RubyCore
Minecraft modding has always felt like a Java-only club. You learn Java, you wrestle with Gradle, and you pray the Forge version matches. But what if you could write your next mod in Ruby? That is exactly what RubyCore brings to the table. It is a lightweight loader that lets you create mods and plugins using Ruby, while still tapping into the full power of Minecraft and Forge APIs.
Instead of fighting annotations and boilerplate, RubyCore lets you focus on the fun part: building blocks, items, and mechanics. Whether you are a seasoned Ruby developer or just curious about a different workflow, this add-on opens a new door. Let us break down what it does, how to get it running, and why you might want to give it a shot.
What Is RubyCore for Minecraft?
RubyCore is an updated and maintained fork of an earlier project by btripoloni. It acts as a bridge between the Java-based Forge environment and the Ruby scripting language. The core idea is simple: you write your mod logic in .rb files, and RubyCore handles the heavy lifting of loading and executing them inside Minecraft.
This is not a toy. You can access all Java, Minecraft, and Forge APIs from Ruby. That means you can create custom blocks, items, entities, and even complex gameplay systems. The project includes helper classes that wrap common Forge APIs, so you are not always writing raw Java interop code. For example, registering a block in Ruby looks like this:
@rubyblock = Block.new(AbstractBlock::Properties.create(Material::ROCK).hardnessandresistance(3, 10).harvestlevel(2))Clean, readable, and Ruby-flavored. The add-on is built for Minecraft 1.16.5 and requires Java 15. It uses JRuby 9.2.17 (pre-included in the repo) to interpret your Ruby code. While it targets Forge, the developer is working on making the loader generic, which could open doors for Fabric or Spigot later.
Key Features and Caveats
Before you jump in, there are a few things to understand about how RubyCore works under the hood.
What Works Great
- Write mods in Ruby with minimal Java code
- Use all Java classes via
java_import - DeferredRegister makes block and item registration much easier
- Mojmaps are used, with generated Ruby versions of mappings included
- Both internal and external mods are supported
What to Watch Out For
- JRuby does not support annotations on Ruby functions, so your mod annotation must stay on the Java side
@SubscribeEventannotations do not work from Ruby; use aprocess_event(event)function instead- External mods are copied to a
cachefolder before loading, which is a current limitation - Avoid
system,exec, or backtick calls to prevent sub-ruby performance issues
These are not deal-breakers. They simply mean you need to structure your mod slightly differently than a pure Java one. The trade-off is worth it if you prefer Ruby's syntax and speed of iteration.
Getting Started with RubyCore
There are three main ways to create a mod with RubyCore. Pick the one that fits your workflow.
1. External Mod in Your Mods Folder
Create a standard Forge project in IntelliJ, set up your mods.toml and main class annotation, then add a file named mod_yourmodname.rb in src/main/resources. When you place this jar in your mods folder alongside RubyCore, the loader scans for mod_*.rb files, copies them to rubycore/cache, and loads them.
2. Direct Script in the Scripts Folder
Drop a Ruby script directly into rubycore/scripts. RubyCore loads it straight from there. This is the fastest way to test small ideas without building a full project.
3. Build from the RubyCore Base
Clone the repo, change the mod ID in RubyCoreApi.java and mods.toml, then add your Ruby code in src/main/resources/mod. Run gradle build to get your jar. Note that this method disables loading external mods.
Whichever route you choose, the process is straightforward. For examples, check the src/resources/examples folder or the GitLab repository mentioned in the project docs.
How to Install RubyCore for Minecraft
Installing RubyCore is similar to any Forge mod. Here is the simple version of how to install it:
- Install Minecraft 1.16.5 and the matching Forge version
- Download RubyCore and place the jar in your
modsfolder - Add your Ruby scripts or external mod jars
- Launch the game
If you want a more streamlined experience, the foxygame.net launcher includes a built-in add-on catalog where you can find RubyCore for Minecraft with a one-click install. It also handles version compatibility checks and auto-updates, so you do not have to track new releases manually. Just search for RubyCore in the launcher, hit install, and you are ready to script.
Supported Versions and Loaders
Currently, RubyCore targets Minecraft 1.16.5 with the Forge loader. The project uses Mojmaps, which makes mapping names more intuitive. While Java 15 is the stated requirement, the lightweight nature of RubyCore means it might work on other versions, but those are untested. The developer is actively working on making the loader generic, so future support for Fabric or Spigot is a real possibility.
Can You Use Gems and Java Libraries?
Yes, with some caveats. You can include Ruby gems by using the built-in gem processing line in loader.rb. The project already bundles rubyzip for its own functionality. To add your own gems, you would need to build from the RubyCore base and follow the documented process of injecting gems into the JRuby jar.
For Java libraries, it is even easier. Add them to your build.gradle and use java_import in your Ruby code. This means you are not limited to what RubyCore provides; the entire Java ecosystem is at your disposal.
Why Choose Ruby for Minecraft Modding?
Ruby was designed for developer happiness. It reads like English, has a gentle learning curve, and is incredibly expressive. If you already know Ruby from web development or scripting, you can transfer those skills directly to Minecraft. The fact that GitHub and GitLab are built with Ruby on Rails shows how scalable and robust the language is. RubyCore brings that same joy to your game.
There is also a practical benefit: faster iteration. Writing a quick script in rubycore/scripts and reloading is much quicker than rebuilding a Java project. For prototyping mechanics or testing ideas, this is a huge win.
Final Thoughts
RubyCore is a clever bridge between two worlds. It is not a full replacement for Java modding, but it does not need to be. It is an easy way to create mods and plugins for Minecraft using Ruby, with enough flexibility to handle serious projects. The caveats around annotations and event handling are manageable, especially if you structure your code with the provided process_event pattern.
If you are a Ruby enthusiast looking to break into Minecraft modding, or a Java modder curious about a different approach, RubyCore is worth a download. The project is actively maintained, the community is small but helpful, and the potential is significant. Start with a simple block, then build up from there. You might just find that Ruby is the modding language you have been waiting for.