minecraft modding environment quickstart

This is adapted from something I wrote for the EbXL team, but it applies to any active mod development.

NB: I am assuming a moderate degree of technical ability here. If you don’t understand what I’m talking about and can’t Google the missing pieces for yourself… I’m sorry.

I have been working for ages (read over a year) on a tutorial on fully customizing and massaging a modding environment capable of handling multiple mods at once. But the community shift to backing Gradle has thrown enough kinks into the process that I’m largely unmotivated to work very hard on it any more.

But it has been long enough – I just need to put something out there. So here we go, a quickstart for using Eclipse to compile an existing mod.

While some people recommend IDEA, I can’t get used to it. I used IDEA for the entirety of EbXL’s 1.6 to 1.7 port and hated every minute of the process… so am personally giving up – and going back to Eclipse (a decade of experience trumps all else in this case).

Step 0: Install tools

I’m not in a position to go into details on this right now. But suffice it to say that you need modern versions of:

  • git
  • eclipse – a current version of the Java IDE (Juno or above, anything else is WAY too old; J2EE version is unnecessary)
  • jdk – Oracle’s OpenJDK (others are not guaranteed to work). Ideally, your mod will compile against Java 7 or 8, but it is probably best to use 7 for now as that is what most players should have installed – but you should probably refrain from using anything that doesn’t work in Java 6, just in case.


For Windows, I recommend TortoiseGit, but the command line (via cygwin or the git bash prompt) is also perfectly acceptable.

On OSX and Linux, I have yet to find a graphical git client that I can recommend – so I just use the command line. It’s not terrible, honest.

Step 1: Check out mod source

Using the example of EbXL, we maintain a public clone on github (https://github.com/ExtrabiomesXL/ExtrabiomesXL).

This should create a folder called ExtrabiomesXL, and should point you at the master branch. You can verify this:

I will refer to this folder as {checkout} from here on out.

This should work for any mod that uses the de-facto standard directory structure:

In the case of EbXL, we have our code under src/main/java/extrabiomes and also reference the api’s for other mods (forestry, thaumcraft, etc…) in parallel directories.

Step 2: Download Forge

In theory, gradle should just grab forge for you. But it’s not 100% reliable. So, just to be safe, go to http://files.minecraftforge.net/ and download the latest appropriate src package.

Unzip this file into your checkout, and do not overwrite mcmod.info or build.gradle. If your mod provides them, chances are you want those versions instead of the generic versions that Forge ships.

Step 3: Bootstrap Environment

cd into your dev folder and run the following commands:

On windows cmd:

On linux/osx/cygwin:

This will download mcp/minecraft, decompile, recompile, and generally thrash your cpu for a while. Depending on your machine, you may want to make a sandwich.

If everything goes well, you’re all set.

Step 4: Set up Eclipse

Fire up eclipse.

When it asks you for your workspace, point it at {checkout}/eclipse.

If all goes well, you should have a single project set up – Minecraft. Expand the project and you should see a bunch of files. And if you tell MC to run, it will actually fire up a Minecraft client with your mod (and possibly the empty Example Mod) installed.

You can safely delete the example mod from {checkout}/src/main/java/com/example.

If there are a few scary exclamation points on some apparently empty folders in the package explorer, that is because of how gradle creates the project. It is assuming that you may have any of the following folders in addition to src: jars, lib, common. Some mods use them, some don’t.

If the bangs annoy you enough, you can always just create the directories under {checkout}. If Eclipse doesn’t detect the change immediately, you can right click on the Minecraft project and tell it to refresh.

Step 5: Other Mods

You probably want to use other mods for testing. If nothing else, you probably want NEI. Even if you don’t want NEI, you should probably install CCC as it does some runtime deobfuscation magic that makes it easier to install other mods to test with (like a map mod or something whose api you are using).

Download the universal versions of CCC and NEI like normal (from http://chickenbones.net/Pages/links.html). No need to get the “dev” versions.

If you’ve run the client at least once, you should see a folder at {checkout}/eclipse/mods, plunk things in there. If not, just create the folder.

Step 6: Profit

And that’s it. Provided the mod in question actually compiles, you should be good to go. I don’t recommend ever shipping a jar compiled by an IDE to players – you should usually be using gradle from the command line to package clean builds for shipment (either manually or with the help of something like Jenkins). But, this will let you work.

For now, this system doesn’t work perfectly with multiple mods. You can always copy their compiled jars into your mods folder, or copy their source over – but then you have a cluttered repository unsuitable for committing back upstream to git. So YMMV there.

But that’s what we have to work with now. I’m working on documenting a simplified process for making this sort of situation easier, and will post an update if that ever happens 😉

Leave a Reply

Your email address will not be published. Required fields are marked *