If you have never made a Forge mod before, this section will provide the minimum amount of information needed to setup a Forge development environment. The rest of the documentation is about where to go from here.
An installation of the Java 17 Development Kit (JDK) and 64-bit Java Virtual Machine (JVM). Forge recommends and officially supports Eclipse Temurin.
Make sure you are using a 64-bit JVM. One way of checking is to run
java -versionin a terminal. Using a 32-bit JVM will cause some problems when using ForgeGradle.
Familiarity with an Integrated Development Environment (IDE).
- It is recommended to use an IDE with Gradle integration.
- Download the Mod Developer Kit (MDK) from the Forge file site by clicking ‘Mdk’ followed by the ‘Skip’ button in the top right after waiting for a period of time. It is recommended to download the latest version of Forge whenever possible.
Extract the downloaded MDK into an empty directory. This will be your mod’s directory, which should now contain some gradle files and a
srcsubdirectory containing the example mod.
A number of files can be reused across different mods. These files are:
srcsubdirectory does not need to be copied across workspaces; however, you may need to refresh the Gradle project if the java (
src/main/java) and resource (
src/main/resources) are created later.
Open your selected IDE:
- Forge only explicitly supports development on Eclipse and IntelliJ IDEA, but there are additional run configurations for Visual Studio Code. Regardless, any environment, from Apache NetBeans to Vim / Emacs, can be used.
- Eclipse and IntelliJ IDEA’s Gradle integration, both installed and enabled by default, will handle the rest of the initial workspace setup on import or open. This includes downloading the necessary packages from Mojang, MinecraftForge, etc. The ‘Gradle for Java’ plugin is needed for Visual Studio Code to do the same.
- Gradle will need to be invoked to re-evaluate the project for almost all changes to its associated files (e.g.,
settings.gradle, etc.). Some IDEs come with ‘Refresh’ buttons to do this; however, it can be done through the terminal via
- Generate run configurations for your selected IDE:
- Eclipse: Run the
- IntelliJ IDEA: Run the
genIntellijRunstask. If a “module not specified” error occurs, set the
ideaModuleproperty to your ‘main’ module (typically
- Visual Studio Code: Run the
- Other IDEs: You can run the configurations directly using
runGameTestServer). These can also be used with the supported IDEs.
- Eclipse: Run the
build.gradle file to customize how your mod is built (e.g., file name, artifact version, etc.).
Do not edit the
settings.gradle unless you know what you are doing. The file specifies the repository that ForgeGradle is uploaded to.
Replace all occurrences of
mods.toml and the main mod file with the mod id of your mod. This also includes changing the name of the file you build by setting
base.archivesName (this is typically set to your mod id).
// In some build.gradle base.archivesName = 'mymod'
group property should be set to your top-level package, which should either be a domain you own or your email address:
// In some build.gradle group = 'com.example'
The packages within your java source (
src/main/java) should also now conform to this structure, with an inner package representing the mod id:
com - example (top-level package specified in group property) - mymod (the mod id) - MyMod.java (renamed ExampleMod.java)
version property to the current version of your mod. We recommend using a variation of Maven versioning.
// In some build.gradle version = '1.20-22.214.171.124'
Additional configurations can be found on the ForgeGradle docs.
- To build your mod, run
gradlew build. This will output a file in
build/libswith the name
[archivesBaseName]-[version].jar, by default. This file can be placed in the
modsfolder of a Forge-enabled Minecraft setup or distributed.
- To run your mod in a test environment, you can either use the generated run configurations or use the associated tasks (e.g.
gradlew runClient). This will launch Minecraft from the run directory (default ‘run’) along with any source sets specified. The default MDK includes the
mainsource set, so any code written in
src/main/javawill be applied.
- If you are running a dedicated server, whether through the run configuration or
gradlew runServer, the server will initially shut down immediately. You will need to accept the Minecraft EULA by editing the
eula.txtfile in the run directory. Once accepted, the server will load, which can then be accessed via a direct connect to
You should always test your mod in a dedicated server environment. This includes client-only mods as they should not do anything when loaded on the server.