Welcome to my MinecraftForge modding series! This article will cover the basic environment setup at a high level. The hope is that this article will help clarify ambiguities in the existing resources, as well as provide some (hopefully) useful context about what it is you're doing.

MinecraftForge's documentation clearly-states that it's not for those who are just learning how to code. Which is totally fair - it's up to them to decide the scope of their documentation, and they decided that they don't want to have to help people learn how to code. This may sound "mean" to some, but consider this - teachers are paid simply to do one job; teach. That is to say, teaching someone a skill is basically a full time job. I don't know any of the MinecraftForge team members personally, but I assume they are developers with their own day jobs and are choosing to work on MinecraftForge on their own time and dollar (after all, the Mojang terms forbid profiting from mod/mod framework sales). It's simply too much work to both develop a full-featured framework, document how to use it, and teach people how to code while doing it.

This is where my series is a bit different. I don't want to assume you have any knowledge of coding before getting into this. Personally, I feel as though Minecraft is an excellent way for people to get introduced to coding since most people have great contextual knowledge of the game (which goes a long way when learning a code base). With that in mind, there is a certainly a bit of a disconnect between new coders and the Minecraft codebase. I aim to use this series to bridge that disconnect.

I too am new to the Minecraft codebase, but I am not a new coder. While my expertise is primarily in the Node.js ecosystem, I do have experience coding in Java as well. With that said, my Java experience is certainly not "veteran" status, so the cadence at which I release these series articles may be a bit slow; I am taking the time to really understand each step before I write about it. Bad documentation is worse than no documentation at all, in my opinion, and I'd like to avoid that as much as possible.

With that said, let's get started!

What's covered

• Review what you can and cannot do when making Minecraft mods
• Understanding the MinecraftForge codebase at a high level
• Understanding the MDK
• Learn how to get the MinecraftForge modded client up and running from scratch

In this article, I'll cover some basic steps to getting your development environment setup so that you can explore the MinecraftForge codebase. At the end of this guide, you'll know how to run a modded Minecraft client from within your IDEA (note: I am developing on IntelliJ IDEA 2021.2).

I'll also cover some basic information about the MinecraftForge codebase to help you better explore and level yourself up!

The MinecraftForge codebase

It will help you in the long run to understand what MinecraftForge is and is not. Many people go into Minecraft modding with not much of an idea of where to begin, which is totally normal. The mod-loading frameworks, including MinecraftForge, are all open-source projects maintained by the community.

The Minecraft terms of service strictly forbid profiting directly from modded versions of the game. NEVER FORGET THIS (taken from the Minecraft EULA):

Any Mods you create for the Game from scratch belong to you (including pre-run Mods and in-memory Mods) and you can do whatever you want with them, as long as you don't sell them for money / try to make money from them and so long as you donate distribute Modded Versions of the Game.

In short, this states the two "golden rules" set out by the EULA:

1. Never sell or attempt to make money DIRECTLY from a mod
   1. You can, however, profit from ad revenue if you're hosting a mod on your own platform (like MinecraftForge does with their ad link downloads)
      1. Word of caution - this seems more like a gray area that Mojang/Microsoft simply don't bother pursuing - it's possible they could take issue with it eventually, but doing so would mean they also take issue with MinecraftForge, which seems unlikely - you should be safe to use ads, if you want
2. Always make your mods available to the community as a whole (e.g., no "exclusivity")

"But what about servers that have optional subscription payments?" A good question, no doubt. I believe this also falls within that same gray area that ad revenue falls into. Technically, there is no "sale" of game content, so it seems legally permissible so long as the content is otherwise free for all Minecraft account holders. In short, all players should be able to join a server or use a modpack without paying for anything other than the base Minecraft game. Additional payments can only go towards paying for things completely unrelated to the Minecraft IP ("Intellectual Property", meaning the codebase as a whole).

If all of this is hard to keep in mind, then just do what I do to avoid all confusion - just make your whole mod open source and be sure to upload it once done. That way, there is no need to worry about whether or not your revenue strategies violate Minecraft's EULA. With that being said, it's perfectly okay to keep your code closed-source; there simply isn't much incentive to do so, if any (in my opinion).

The MinecraftForge codebase is undoubtedly a beast to tackle at a single time. So, I'm only going to cover the areas we are going to look at for this guide. This includes the following directories:

1. mdk
2. projects
3. src

This does not mean that the other files are unimportant - far from it, in fact. However, I personally feel that these are the best "starting points" to dig into when starting to explore the MinecraftForge codebase.

The mdk directory is only listed because it's important to note if you were to create a new mod. Technically, when creating a new mod, the MDK ("mod development kit") is all you need. It's simply a small directory that the main repository contains; the developers of MinecraftForge intend for new mods to be made starting with the MDK. You can think of it as something of a "mod starter".

MinecraftForge prefers you to obtain the MDK from their site and NOT the repo - doing so helps them out by generating ad revenue, thus supporting them to keep working on the platform.

projects is probably the most-important directory for exploration. This doesn't contain anything in a clean project, but once you've built it, it will contain four directories - clean, fmlonly, forge, mcp. At the time of writing, I am not quite sure what the difference is between the first three - they all appear to contain the de-obfuscated Minecraft code; mcp is something else entirely. I'll be sure to update this once I am more certain of their purposes. Just know that I've found this section of the code most-useful for exploration.

The next most-important part of the code is the src directory (though, for MinecraftForge developers this is the most-important). This is where you would make changes to the MinecraftForge codebase, but I don't intend to cover that in this article, or even in this series. I'm more interested in modding than developing on the framework, but who knows what time will bring!

First off, know that the Minecraft code is not going to be very easy to explore, even with ample experience coding. The main challenge with the Minecraft codebase is that it's de-obfuscated (see obfuscation). This simply means that the code was once unreadable, but has been converted to a readable format. On the whole, this is a good thing since it's the only way you can read the Minecraft source code. However, this has the unfortunate side effect of making many variables have overly-generic, or completely-unhelpful names such as flag or p_129816_. Unless there is a tool to help with this (which, there may very well be), I consider this a pretty big obstacle for new coders learning the Minecraft codebase.

However, fear not! I intend to explain every step that I cover in as great of detail as possible, including explaining any potentially vague parts of the process.

First time setup

Now, on to the fun part! This section will walk you through getting the MinecraftForge code on your system as well as how to configure your environment so that you can run the modded client through your IDE using Gradle tasks.

The first step in exploring MinecraftForge is to get the actual code. To do this:

1. Open a new terminal window > cd to where you want to clone the repository to
2. Clone the MinecraftForge repository by running git clone git@github.com:MinecraftForge/MinecraftForge.git

That's it! You now have the MinecraftForge code copied to your local system.

MinecraftForge offers documentation on how to properly import the project, depending on the IDE (and version of the IDE) that you're using here. Personally, I am using IntelliJ IDEA 2021.2. The only difference between the IDE versions appears to be how you open the project. From there, it's a matter of making sure your Gradle configuration is using the correct JVM version.

If you run in to unsupportedClassException errors when first building your project, it means that your Gradle configuration is set to use the wrong version JVM. To fix this, you simply need to change your Gradle configuration to use the correct JVM version. In IntelliJ IDEA 2021.2, this is done by:

1. Click IntelliJ Idea > Preferences
2. Build, Execution, Deployment > Build Tools > Gradle
3. Set the Gradle JVM dropdown to the correct JVM version (which will depend on the version of Minecraft you are modding for)
   1. For Minecraft 1.17.x, JVM should be set to version 11

Once you're able to get the Gradle build task to complete (which should simply happen automatically when you open the project), you should now be able to run the setup task. To do this, simply locate and run the Gradle task labeled setup, or, if you're using IntelliJ, double-tap CTRL and type gradle setup and press enter.

Note that the setup task may run into licensing issues. If you encounter this, you should be able to correct the issue by running the updateLicenses task.

Now, it's time to run the modded client from within your IDE! To do this, simply run the Gradle task forge_client. If all went well, you should eventually see a modded version of the Minecraft client start up. This is a fully-playable game client, except that you won't be able to join official servers (because it's not an official game session - it's not tied to any account, so it's technically "unauthorized" and only available for local use). This client is instrumental when developing a mod, in my opinion. It's far better to use the IDE to develop on your mod than having to jump through all of the irritating hoops put forth when using the vanilla client launcher to run the Forge client.