Minecraft Forge is the Minecraft modding API. It is an open-source project that provides tools and libraries for Minecraft mods. The Minecraft Forge 1.12.2 Documentation will help you learn how to use Minecraft Forge to make mods for Minecraft.
Table of Contents
From Zero to Modding
- Obtain a source distribution from forge’s files site. (Look for the Mdk file type, or Src in older 1.8/1.7 versions).
- Extract the downloaded source distribution to an empty directory. You should see a bunch of files, and an example mod is placed in
src/main/java
for you to look at. Only a few of these files are strictly necessary for mod development, and you may reuse these files for all your projects These files are:build.gradle
gradlew.bat
gradlew
- the
gradle
folder
- Move the files listed above to a new folder, this will be your mod project folder.
- Open up a command prompt in the folder you created in step (3), then run
gradlew setupDecompWorkspace
. This will download a bunch of artifacts from the internet needed to decompile and build Minecraft and forge. This might take some time, as it will download stuff and then decompile Minecraft. Note that, in general, these things will only need to be downloaded and decompiled once, unless you delete the gradle artifact cache. - Choose your IDE: Forge explicitly supports developing with Eclipse or IntelliJ environments, but any environment, from Netbeans to vi/emacs, can be made to work.
- For Eclipse, you should run
gradlew eclipse
– this will download some more artifacts for building eclipse projects and then place the eclipse project artifacts in your current directory. - For IntelliJ, simply import the build.gradle file.
- For Eclipse, you should run
- Load your project into your IDE.
- For Eclipse, create a workspace anywhere (though the easiest location is one level above your project folder). Then simply import your project folder as a project, everything will be done automatically.
- For IntelliJ, you only need to create run configs. You can run
gradlew genIntellijRuns
to do this.
Terminal-free IntelliJ IDEA configuration
These instructions assume that you have created the project folder as described in the steps 1 to 3 of the section above. Because of that, the numbering starts at 4.
- Launch IDEA and choose to open/import the
build.gradle
file, using the default gradle wrapper choice. While you wait for this process to finish, you can open the gradle panel, which will get filled with the gradle tasks once importing is completed. - Run the
setupDecompWorkspace
task (inside theforgegradle
task group). It will take a few minutes, and use quite a bit of RAM. If it fails, you can add-Xmx3G
to theGradle VM options
in IDEA’s gradle settings window, or edit your global gradle properties. - Once the setup task is done, you will want to run the
genIntellijRuns
task, which will configure the project’s run/debug targets. - After it’s done, you should click the blue refresh icon on the gradle panel (there’s another refresh icon on the main toolbar, but that’s not it). This will re-synchronize the IDEA project with the Gradle data, making sure that all the dependencies and settings are up to date.
- Finally, assuming you use IDEA 2016 or newer, you will have to fix the classpath module. Go to
Edit configurations
and in bothMinecraft Client
andMinecraft Server
, changeUse classpath of module
to point to the task with a name like<project>_main
.
If all the steps worked correctly, you should now be able to choose the Minecraft run tasks from the dropdown, and then click the Run/Debug buttons to test your setup.
Customizing Your Mod Information
Almost anything underneath apply project: forge
and the // EDITS GO BELOW HERE
marker can be changed, many things can be removed and customized there as well.
There is a whole site dedicated to customizing the forge build.gradle
files – the ForgeGradle cookbook. Once you’re comfortable with your mod setup, you’ll find many useful recipes there.
Simple build.gradle
Customizations
These customizations are highly recommended for all projects.
- To change the name of the file you build – edit the value of
archivesBaseName
to suit. - To change your “maven coordinates” – edit the value of
group
as well. - To change the version number – edit the value of
version
.
Building and Testing Your Mod
- To build your mod, run
gradlew build
. This will output a file inbuild/libs
with the name[archivesBaseName]-[version].jar
. This file can be placed in themods
folder of a forge enabled Minecraft setup, and distributed. - To test run with your mod, the easiest way is to use the run configs that were generated when you set up your project. Otherwise, you can run
gradlew runClient
. This will launch Minecraft from the<runDir>
location, including your mod code. There are various customizations to this command. Consult the ForgeGradle cookbook for more information. - You can also run a dedicated server using the server run config, or
gradlew runServer
. This will launch the Minecraft server with its GUI.