Getting Started with Forge

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.

Prerequisites

• An installation of the Java 21 Development Kit (JDK) and 64-bit Java Virtual Machine (JVM). Forge recommends and officially supports Eclipse Temurin.
• Familiarity with an Integrated Development Environment (IDE).
  • It is recommended to use an IDE with Gradle integration.

From Zero to Modding

1. 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.

2. Extract the downloaded MDK into an empty directory. This will be your mod’s directory, which should now contain some gradle files and a src subdirectory containing the example mod.

   Note

   A number of files can be reused across different mods. These files are:

   • the gradle subdirectory
   • build.gradle
   • gradlew
   • gradlew.bat
   • settings.gradle

   The src subdirectory 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.

3. 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., build.gradle, settings.gradle, etc.). Some IDEs come with ‘Refresh’ buttons to do this; however, it can be done through the terminal via gradlew.
4. Generate run configurations for your selected IDE:
   • Eclipse: Run the genEclipseRuns task.
   • IntelliJ IDEA: Run the genIntellijRuns task. If a “module not specified” error occurs, set the ideaModule property to your ‘main’ module (typically ${project.name}.main).
   • Visual Studio Code: Run the genVSCodeRuns task.
   • Other IDEs: You can run the configurations directly using gradle run* (e.g., runClient, runServer, runData, runGameTestServer). These can also be used with the supported IDEs.

Customizing Your Mod Information

Edit the build.gradle file to customize how your mod is built (e.g., file name, artifact version, etc.).

Recommended build.gradle Customizations

Mod Id Replacement

Replace all occurrences of examplemod, including 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 Id

The 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

Set the version property to the current version of your mod. We recommend using a variation of Maven versioning.

// In some build.gradle
version = '1.21.1-1.0.0.0'

Additional Configurations

Additional configurations can be found on the ForgeGradle docs.

Building and Testing Your Mod

1. To build your mod, run gradlew build. This will output a file in build/libs with the name [archivesBaseName]-[version].jar, by default. This file can be placed in the mods folder of a Forge-enabled Minecraft setup or distributed.
2. 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 main source set, so any code written in src/main/java will be applied.
3. 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.txt file in the run directory. Once accepted, the server will load, which can then be accessed via a direct connect to localhost.