If you’ve decided to contribute to Forge, you’ll have to take some special steps to get started with developing. A simple mod development environment won’t suffice to work with Forge’s codebase directly. Instead, you can use the following guide to help you with your setup and get you started with improving Forge!
Like most major open source projects you’ll find, Forge is hosted on GitHub. If you’ve contributed to another project before, you’ll know this process already and you can skip right ahead to the next section.
For those who are beginners when it comes to collaboration via Git, here are only two easy to steps to get you started.
This guide assumes that you already have a GitHub account set up. If you don’t, visit their registration page to create an account. Furthermore, this guide is not a tutorial for git’s usage, please consult different sources first if you’re struggling with getting it working.
First of all, you have to “fork” the MinecraftForge repository by clicking the “Fork” button in the upper right hand corner. If you are in an organization, select the account you want your fork to be hosted on.
Forking the repository is necessary since not every GitHub user can have free access to every repository. Instead, you create a copy of the original repository to later contribute your changes via a so called Pull Request, which you will learn more about later.
After forking the repository, it is time to get local access to it and to actually make some changes. For this, you need to clone the repository onto your local machine.
Using your favourite git client, simply clone your fork into a directory of your choice. As general example, here is a command line snippet that should work on all correctly configured systems and clones the repository into a directory called “Forge” under the current directory (note that you have to replace
<User> with your username):
git clone https://github.com/<User>/MinecraftForge Forge
Forking and cloning the repository are the only mandatory steps to develop for Forge. However, to ease the process of creating Pull Requests for you, it is best to work with branches.
It is recommended to create and check out a branch for each PR you plan to submit. This way, you can always keep around the latest changes of Forge for new PRs while you still work on older patches.
After completing this step, you’re ready to go and set up your development environment.
Depending on your favourite IDE, there is a different set of recommended steps you have to follow to successfully set up a development environment.
Due to the way eclipse workspaces work, ForgeGradle can do most of the work involved in getting you started with a Forge workspace for you.
- Open a terminal/command prompt and navigate it to the directory of your cloned fork.
./gradlew setupand hit enter. Wait until ForgeGradle is done.
- Open your eclipse workspace and go to
File -> Import -> General -> Existing Projects into workspace.
- Browse to the
<repo>/projects/directory for the root directory in the dialog that opens.
- Make sure both “Forge” and “Clean” are checked and adjust the other settings to your liking.
- Complete the import by clicking the “Finish” button.
That’s all it takes to get you up and running with Eclipse, there’s no extra steps required to get test mods running. Simply hit Run like in any other project and select the appropriate run configuration.
JetBrains’ flagship IDE comes with great integrated support for Gradle, Forge’s build system of choice. Due to some peculiarities of Minecraft mod development, however, there are additional steps required to get everything to work properly.
If you’re more of a visual person, cpw has uploaded a video explaining very similar steps which will also lead to a working setup.
- Import Forge’s
build.gradleas an IDEA project. For this, simply click
Import Projectfrom the
Welcome to IntelliJ IDEAsplash screen, then select the
- After IDEA is done importing the project and indexing the files, run the Gradle setup task. Either:
- open the Gradle sidebar on the right hand side of your screen, then open the
forgeproject tree, select
otherand double-click the
setuptask (may also appear as
MinecraftForge[Setup]. Or alternatively:
- tap the CTRL key twice, and type
gradle setupin the
Runcommand window that pops up.
You can then run Forge using the
forge_client gradle task (
Tasks -> fg_runs -> forge_client): right-click the task and select either
Debug as desired.
Versions older than 2016 will not work because they didn’t have the appropriate Gradle support and did not support Forge development multiproject workspaces. IDEA 2016 - 2018 will work with extra manual steps required, but it is strongly recommended to update to IntelliJ 2019+ instead.
That’s all there is to creating a Forge development environment in IntelliJ IDEA. However, you won’t be able to run the tests and debug mods included in Forge straight away. This takes some extra effort.
To enable the test mods coming with Forge, you will need to add the compiler output to the classpath. Again, cpw has put up a video explaining these steps.
- Build the test classes by selecting the
src/main/testdirectory in your project view and then run
Build -> Build module 'Forge_test'from the menu bar.
- Open the “Project Structure” Window under
File -> Project Structure.
- Head to the “Modules” section and expand the
- Select the
Forge_testsubmodule and head to the “Paths” tab.
- Remember the path listed under the “Test output path” label and select the
Forge_mainsubmodule from the tree.
- Open the “Dependencies” tab, hit the green plus button on the right-hand side and select “JARs or directories”.
- Navigate to the path previously displayed as the
Forge_testoutput path and confirm your selection.
- For the “Scope” of this newly added dependency (currently “Compile”) choose “Runtime”, since the main code doesn’t rely on the test code for compilation.
Now that you’ve added the test mods to the classpath, you need to rebuild them each time you make a change as they will not be built automatically. To do so, repeat step 1 from the above list or, in case you make changes to a single test mod file and want them to get rebuild, simply hit
Build -> Rebuild project or the corresponding keyboard shortcut (CTRL+F9 by default).
You might want to test changes in Forge with an existing project. The video by cpw linked in the test mods section also covers this. Getting the mod to run requires similar steps to the test mod, but getting your project added to the workspace requires some additional work.
- Open the “Project Structure” Window under
File -> Project Structure.
- Head to the “Modules” section and press the green plus icon above the tree view.
- Select “Import Module”, navigate to your project’s
build.gradlefile and confirm your selection as well as the import settings.
- Close the “Project Structure” window by clicking the “OK” button.
- Reopen the window after IDEA is done importing the project and select your project’s
_mainmodule from the tree.
- Open the “Dependencies” tab, click the green plus icon on the right-hand side and select “Module dependency”.
- In the window that just opened, select the
- From here on, reproduce the steps from the test mods section, just with your project’s
_mainmodule instead of the
You might need to remove existing dependencies from a normal development environment (mainly references to a
forgeSrc JAR) or move the Forge module higher up in the dependency list.
You should now be able to work with your mod using the changes you introduce to the Forge and Vanilla codebase.
Once you’ve set up your development environment, it’s time to make some changes to Forge’s codebase. There are, however, some pitfalls you have to avoid when editing the project’s code.
The most important thing to note is that if you wish to edit Minecraft source code, you must only do so in the “Forge” sub-project. Any changes in the “Clean” project will mess with ForgeGradle and generating the patches. This can have disastrous consequences and might render your environment completely useless. If you wish to have a flawless experience, make sure you only edit code in the “Forge” project!
After you’ve made changes to the code base and once you’ve tested them thoroughly, you may go ahead and generate patches. This is only necessary if you work on the Minecraft code base (i.e. in the “Forge” project), but this step is vital for your changes to work elsewhere. Forge works by injecting only changed things into Vanilla Minecraft and hence needs those changes available in an appopriate format. Thankfully, ForgeGradle is capable of generating the changeset for you and all you have to do is commit it.
To initiate the patch generation, simply run the
genPatches Gradle task from your IDE or the command line. After its completion, you can commit all your changes (make sure you do not add any unnecessary files) and submit your Pull Request!
The last step before your contribution is added to Forge is a Pull Request (PR in short). This is a formal request to incorporate your fork’s changes into the live code base. Creating a PR is easy, simply go to this GitHub page and follow the proposed steps. It is now that a good setup with branches pays off, since you’re able to select precisely the changes you want to submit.