Sunday, 28 August 2016

Getting Started with Minecraft Modding

Greetings, fellow Minecraft players! So you've finally decided to try your hand at some mod dev stuff? Great, you will not regret it, I promise. Modding is difficult, takes a lot of time and energy, but is definitely worth it.

Welcome to modding minecraft! We modders have a lot of control over Minecraft, but there's a lot of code and beginning can be overwhelming. But still, creating your own blocks and adding your own functionality to Minecraft is quite a liberating experience! If you don't like a facet of the game, change it! If you want more content, you can add it!"

This article is a guide or tutorial of some sort that is intent on showing you how to get started developing your first very own Minecraft mod. Once you're done reading this article you should be able to set up your development environment, install Forge, interact with Git repositories, import your mod in Eclipse as an independent project and run your mod directly from Eclipse with relative ease.

This article was written for version 1.10, however I believe that you will have no problem applying it to other recent versions including 1.8 and 1.9. Also, many of the concepts you'll learn here will be very useful to you for modding in general.

Table of Contents

This guide is divided into the following sections:

Use the links to easily navigate through the article and bookmark individual sections.


Okay, let's get started. Before we can go into writing the actual code you will have to download and install some software. Here is a list of prerequisites with descriptions and download links:

  • Java SE Development Kit (JDK) - Includes the Java Run Environment, plus tools for developing, debugging, and monitoring Java applications.
  • Eclipse IDE (for Java Developers) - The development environment we will be using in this tutorial. If you're using another IDE, you might have to configure things differently.
  • Minecraft Forge MDK - Minecraft modding API that is used to interact with Minecraft code, develop and package our mod. Always choose the recommended version.

First off, you should create a new folder where all your mod development files will be located, you can call it something descriptive like "MinecraftModDev". Inside that folder create a subfolder called  "Installation Files" and move all the files you've downloaded (JDK, Eclipse and Forge) here. The reason we are creating this subfolder is to have an offline backup of these files in case you need to repeat this whole process from scratch.

Now, onto the first point of the list, installing the JDK which should be a fairly simple job (remember to write down the installation path). After the installation is complete we need to set the JAVA_HOME variable to the installation path of our JDK. This will let Forge (and other applications) know where our Java is located. This is a short and simple how-to on how to accomplish this task.

Note: you might need to restart your computer to finalize this step.

Second step is to locate the Eclipse package you downloaded (make sure you downloaded an offline installation package for Java Developers). From the link I provided you the package should be a zip file containing the full program without the need for installation. Just extract the zip file and move the extracted folder wherever you see fit. Since the program is not installed in Windows registry, a useful thing to do would be to create a shortcut of the program and maybe even pin it to Start Menu for ease of access, however you don't have to do this.

Setting up Forge

Now that we have our IDE it's time to set up Forge, so first and foremost it's important to understand what Forge really is. Minecraft Forge is a modding API (Application Programming Interface), which makes it easier to create mods, and also make sure mods are compatible with each other. You can imagine it as a bridge between us and Minecraft's source code, it helps us interact with it. Now we can set it up, and the best place to find out how to do that is the official Forge documentation. Here is the link to the instructions on their website. The instructions are fairly simple and you should be looking at your Forge project in Eclipse in less then few minutes. Once Forge is done installing move it's folder into the root development folder we created earlier.

One of the steps in Forge's documentations tells you to “open up a command prompt in the folder you created”. To do that with ease, right-click that folder while holding shift and select the open command window here context entry.

About GitHub

What is GitHub? GitHub is a web-based public hosting service for Git repositories. Now what is Git you might be asking yourselves. Git is the most popular version control system used for software development. Version control System (VCS) is most simply put, management of changes to documents. They are commonly used by word processors (e.g Microsoft Word) and spreadsheet software (e.g. Microsoft Excel) as well as most bigger collaborative projects today.

Every time you make any changes (however small they might be) to your project, you are given an option to create a new version of your project, a version that contains those new changes. That version is stored in your repository both offline and online so all members of your development team always have a secure backup of the whole project. In addition to this, you are able to view the changes made in each revision in detail as well as revert your active code to an earlier project version. Not to mention such features as branching, stashing, forking and pull requests which are immensely useful. If you've been an active developer for some time and have never heard about this concept then this will change they way you look at code forever. Here are some good reasons why you should use version control system in your development environment.

For more information about GitHub, what it can do for you, and how to use it, read a dedicated article I wrote about this: Learning to GitHub: For Minecraft Modders.

Although it's not strictly necessary to set up your project in an online repository on GitHub, I would strongly recommend it. It's a great way to make your development effort more organized and efficient, and I've already mentioned the collaborative element in all this. It might be important to add that most other Minecraft mod developers use GitHub as well, which makes working there that more interesting for us.

To set up your project in a repository, visit GitHub and create a free your account. Next thing you have to do is download and install a Git GUI client. The most simple one I know of is GitHub Desktop (for Windows 7 or later) so I would recommend going with that. If you're interested in something more advanced you can take a look at this list.

For the purpose of this guide I've decided to create a new generic mod (the name was borrowed from Havvy's generic mod) and hosted it in a repository on GitHub. You can find the repository here.  What I want you to do now is visit that repository and clone (create a local copy) it to your computer using GitHub Desktop you installed earlier. I usually keep all my repositories in Documents\GitHub, but you can store yours wherever you want. If you are not sure exactly how to do, that don't worry, you can watch the instructional GIFs linked in the end of the article.

External Project Dependencies

One more thing we need to do before we can import the generic mod project in our Eclipse workspace. The following steps will explain how to do an independent mod setup. For this setup we only need Forge for it's two meta files, after that we can freely delete it. There are three files that we need to move to your mod root folder. The first file is called .classpath. Eclipse uses this "meta"file to locate all project external dependencies, which are basically all Minecraft and Forge classes you are going to be interacting with. Without them your mod is completely blind. The second file is called .project, which is used by Eclipse as a project description file that describes that project. The third and last file is called build.gradle, which is essentially a set of instructions for building a gradle project. Now, go to your Forge root folder, copy the those three files and paste them in your mod root file. Now open the build.gradle file with your favourite text editor (I use Notepad++ because it's just awesome) and edit the following lines to look like this:

version = "1.0.0"
group = "user.genericmod"
archivesBaseName = "genericmod"

Now we're all set to import the mod with Eclipse. Fire up your Eclipse IDE and import a new gradle project File → Import → Gradle - Gradle Project, then click Next. Enter your project root directory as the root directory of your mod (where your mod project is located on your hard drive), click through Next until the end, then click Finish. Eclipse will then start synchronizing our gradle build with workspace and ask you if you want to "Overwrite existing Eclipse project descriptors", always choose overwrite here. In case your JRE System Library is not set to the latest version of Java SE you're using (that would be "JavaSE-1.8" in my case), make sure to edit your Java build path by right-clicking on your project in package explorer and navigate to Build Path → Configure Build Path and edit the execution environment of the mentioned system library under "Libraries" tab. Congratulations, you've just successfully set up your first mod with Forge! If you had problems completing this step you can watch the instructional GIFs linked in the end of the article.

The reason I did not go into explaining what Gradle is and how to fully use it, is because I lack the knowledge to do so. I searched a long time before I could find some relevant information on how pull this setup off. This is the 'how-to' article I used to accomplish this.

Run Configurations

There are two amazing things I didn't know when I just started modding Minecraft. Amazing thing #1: with the use of Gradle we're able to run an instance of a Minecraft client and server directly from Eclipse with both Forge and our mod loaded inside. Amazing thing #2: is that we can actually run Minecraft interactively while watching the source code and the variables during the execution. This allows us to write our code 'on the fly' when trying to correct problems. Without debugging, mod development would be a long and tedious process that only few would have the patience and dedication of doing. Code debugging is unfortunately out of the scope of this article, so feel free to read more about Java debugging with Eclipse here. Meanwhile we should concentrate on trying to figure out how to set up run configurations.

In order to run our mod from Eclipse, we need to create a new run configuration. To do that, right-click your project in the package explorer and navigate to Run As → Run Configurations..., then select "Java Application". Right-click the category and choose New. Name the new configuration something like "Client_Launcher" (make sure it's not "Launch_Client" as Forge uses that name) and enter GradleStart in the Main class field. Click Apply, and after that Run. Eclipse should start booting up the new Minecraft instance and you should be seeing the console log start to fill up.

If you get an error, please let me know in the comment section and I will try to help to the best of my abilities. Again, if you had problems completing this step or you are more of a visual learner, you can watch the instructional GIFs linked in the end of the article.

Pro Tip
After running build.gradle and the Java application from Eclipse you will end up with a lot of files in your root mod directory that are cluttering our package explorer window. To remove these files from view left-click the small arrow (pointing down) located in the upper right corner of your package explorer, select "Filters..." option and check the "Non-Java elements" checkbox.

The Conclusion

If you followed this article properly you should now be left with a fairly good understanding of how to set up your Minecraft development environment from scratch.

One last suggestion; join your fellow developers on the official Minecraft Forge forum and take a look around, there is much to learn from there and the community is very helpful and kind... most of the times.

Keep in mind that I am not an expert of any kind on this topic, so suggestions and corrections are most welcome. If this article helped you in any way please leave me a comment with your impression, it helps keep me motivated when I see my writing is actually helping people out there. Also don't feel shy to share this article with people you think might benefit from it.

Here is the album of instructional GIF's as I promised, although I apologise for the GIF sizes. To increase their size so that the instructions will be more visible, right-click the GIF and select "view video".


  1. This was a great post! Thanks so much for putting this together for us newbies.

  2. You're very welcome, thanks for taking the time to comment =)

  3. If you import your custom prject with 'archivesBaseName = "genericmod"' elipse throws an error that 'archivesBaseName' is unknown or 'undefined'. If you remove that line no error is thrown.

    1. That's strange. Did you import the project as a Gradle project, and is the Gradle version 2.13? You can see the version in the import preview.

  4. When I click run at the run configs windows with everything inserted correctly, is sais that the MainClass GradleStart could not be found or load.

    Sorry for the mistakes, english isn´t my mother tongue

    1. Have you taken a look at the album of instructional GIF's linked at the very end of the article? The GIF named "How to Set up your Run Configuration" should sufficiently explain how to do this. If that however does not work for you, please provide a screenshot of your error, and we will take it from there.

      Hope you manage to fix your error, let me know if you did.

  5. Hello, I cant find Import > Gradle - Gradle Project.
    I have File > Import > General, but not File > Import > Gradle - Gradle Project.

    1. Hey, are you sure you're using Eclipse as your IDE? If so, did you check if it's the newest version publicly available? With that being said, you can find clear visual instructions on how to import a Gradle project for Eclipse in the GIF album I linked at the bottom of the guide. It's the second image in the album, called "How to import Gradle project to Eclipse".

  6. For the very first mod, will you simultaneously develop a project named *whatever*-core to encapsulate your basic functionality such as proxy, key binding or whatever else?
    Actually I really don't know what others do in their Core mod, have you ever develop a mod based on cores developed by others?

    1. The practice of developing core mods is not encouraged or supported by the Forge community, this guide is not about core modding.

    2. Thanks for pointing that out. I'll focus on forge modding rather than core mod.

  7. This comment has been removed by the author.

  8. Great Article... worked perfectly. Thank you.

  9. Thank you for this article! I hope I will now have the time time to make use of it!

  10. This comment has been removed by the author.

  11. Whenever I get to step 4 on the "Getting Started With Forge" article, and I run the command "gradlew setupDecompWorkspace", I get this error log:

    > Could not resolve all dependencies for configuration ':classpath'.
    > Could not resolve net.minecraftforge.gradle:ForgeGradle:2.2-SNAPSHOT.
    Required by:
    :Mod Project Folder:unspecified
    > Could not resolve net.minecraftforge.gradle:ForgeGradle:2.2-SNAPSHOT.
    > Unable to load Maven meta-data from
    > Could not GET ''.
    > Address family not supported by protocol family: connect

    Does anyone know how to fix this? I am not an experienced coder

  12. Hello there, I'm Ekas Wonder.
    I want to thank you for this redaction, as it has greatly helped me to progress in my project.
    Thank you again for taking the time to do this.

  13. I’m going to read this. I’ll be sure to come back. thanks for sharing. and also This article gives the light in which we can observe the reality. this is very nice one and gives indepth information. thanks for this nice article...