Getting Your Environment Setup

Before you can start creating your Minecraft mod, you will need to set up a development environment, which will be made up of five different things:

  • JAVA SDK (not the JRE, you will need the compiler)
  • Eclipse – an Integrated Development Environment (IDE)
  • Minecraft Coder Pack (MCP) – a toolkit to compile, decompile, obfuscate, deobfuscate and debug the Minecraft files
  • Minecraft Forge (Forge) – a set of open source APIs that allows for the mods to work in Minecraft
  • Forge Mod Loader (FML) – allows for mods to be loaded into Minecraft from the filesystem as a packaged archive

There is often some confusion about MCP, Forge and FML.  They are often grouped into a single thing, but in truth they are really three separate and distinct components.  But the confusion is understandable, since they are distributed together, work very closely together, and really have no purpose as a separate component.  The collection of these three components will be called the Forge Suite of tools for the rest of this article. 

Eclipse is a very popular development environment.  It is free and there are many tutorials available for it, thus it will not be explained in any details.  There are other IDEs available (NetBeans, IntelliJ, etc…), but the Forge Suite was built around Eclipse, and it will be just easier to use Eclipse, and it will be assumed that Eclipse is being used and that the reader already has an understanding of using Eclipse.  Eclipse can be downloaded from http://www.eclipse.org/downloads/.  You can download either the Java EE or Java package, although I would recommend the Java EE, because it will allow for web application development. 

The first step for your Minecraft mod will be to create a directory for development environment.  The directory should be something easy to find, e.g.: C:/minecraft/mods.  Next, you will need to download the Forge Suite into this directory from http://www.minecraftforge.net.  You will want to get the Source release.  At the time this article was written the latest 1.6.2 was the most stable.  Release 1.6.4 was later tested, and 1.6.3 had been abandoned in favor of 1.6.4. Thus, these intructions will work with both 1.6.2 and 1.6.4.

Once the Forge Suite has been downloaded, it will be a Zip file and will need to be extracted.  Go ahead and extract it into your newly created directory.  After the extraction is complete, it will be extracted as the forge directory.  You will want just need to rename it to your mod, in our case RedDiamond.  I have found it easier to separate your different Minecraft mods by creating an entirely new directory for each.  Although it does require more disk space, it does allow for complete isolate.  All you need to do is just extract a zip file again and rename it to the next mod. 

Next, you will need to complete the installation of your Minecraft mods development environment.  Change your directory to go into the RedDiamond directory and run the install command.  If you are using Windows it will be install.cmd, or if using *nix it will be install.sh.  It is generally better to open a new command window and execute commands something like:

cd C:\minecraft\mods\RedDiamond

install.cmd

This command will do a whole lot of stuff and take a really long time, something like 10 minutes.  Also, it may generate some errors when compiling some of the Minecraft files, but that will be okay.  Generally, you can ignore them and continue on. However, sometimes you will need to make some changes, especially with the 1.6.2 which had some changes to the embedded website information, see the note at the bottom of the page.  

Once the install command has completed, you will be ready to launching your MCP instance.  To do this you will launch your Eclipse and then point the workspace to the one created for you when the Forge Suite was installed.  If you look at the sub-directories below the mcp directory, you will see an eclipse directory.  In this directory is the workspace that MCP has created for you.  What you need to do is use this directory in the Eclipse launch window.  Launch Eclipse and select this directory, as shown below:

Eclipse_launch

Eclipse will come up and it may take a little while for the project to synchronize and finish building.  After Eclipse has settled down, you should see a single project in the workspace, named Minecraft.  If get a Java Build Path error for missing required library, this is a problem with your Java version.  It needs to be Java 6.  Although I have only had this problem with 1.6.2.  From here you will be able launch vanilla Minecraft from inside of Eclipse.  It is a good idea to make sure this basic step will work, before working on your Minecraft Mod.  To this just click on the Run button in the menu bar, shown below:

MC_launch

 

Important Things to Understand

When you use the Forge Suite of tools and set them up as described above you will get a complete instance of Minecraft.  This will have all the Minecraft source code.  You will be able to get an under the covers view of how Minecraft does what it does.  However, you will need to be careful, because you should not edit any of the existing Minecraft code.  You can look at it.  You can extend it with a new subclass.  You can even copy it and drop it into new class.  But never, never edit what is there.  Doing so would be creating a Jar Hack, and Jar Hacks are as bad as they sound.  They are not supported and are in no way supportable. 

Also, the client-server concept is a cornerstone to everything that happens in Minecraft.  There is always a client and a server.  Even in Single player, there is still a server.  It is a local server, but it is a server nonetheless.  When creating your Minecraft mods, you will really need to keep in mind what happens and where it happens.  Some actions need to happen only on the client side and other actions need to only happen on the server side.  Generally speaking, rendering actions should only happen on the client side.  The server side should be reserved for processing type actions, calculating something.  There are two basic techniques to use.  The first is to use the convenient annotations provided by Forge.  The other is to use an if-then statement to test the isRemote property of the World object. 

The core Minecraft classes are under the Java package net.minecraft.  The classes under here will provide a wealth of information about Minecraft itself.  Some of the classes you will probably be referring to very often.  These would be things like Block, Item, Material, etc…  Others you may only need to look at once in a great while.  It would be a good idea to just browse around under this Java package, and just get an idea of what is in here. 

The Forge related classes can be found under the Java packages net.minecraftforge & cpw.mods.  You will be using these classes, but you should not need change them or extend them in any way.  When you are ready to test your mod, you will need to use the Forge Installer to ensure these are present in the Minecraft classpath at runtime.  

Install Changes for 1.6.2

When Mojang changed their website, some of the URLs got changed.  Unfortunately, some of these URLs are hardcoded in the Forge code and will point to the wrong place, and your installation will fail.  It will be necessary for you to manually make some changes in order for the installation to run correctly.  

You will need to open the file RedDiamond/fml/fml.py with your favorite text editor.  I personally like Notepad++, http://notepad-plus-plus.org/, in Windows and gedit on Linux.  Next, you will need to search for and replace the following strings in the file:

default_url = 'http://s3.amazonaws.com/Minecraft.Download/libraries'
to
default_url = 'https://libraries.minecraft.net'

and 

base_url = 'http://s3.amazonaws.com/Minecraft.Resources'
to
base_url = 'http://resources.download.minecraft.net'

Be careful because Python is very particular about indentation, be sure to use spaces and not tabs.  

Also, if you get download error on the lib files with md5 errors, then comment out the code that checks for that error.  

Find the download_file() method in fml.py and comments out by putting a # in front of each line

            if not md5 == None:
                if not get_md5(target) == md5:
                    print '%sDownload of %s failed md5 check, deleting' % (prefix, name)
                    os.remove(target)
                    return False

would then become

            #if not md5 == None:
            #    if not get_md5(target) == md5:
            #        print '%sDownload of %s failed md5 check, deleting' % (prefix, name)
            #        os.remove(target)
            #        return False