• Forums

Navigation

  • Home
  • Contributing to the Docs
  • Getting Started
    • Introduction
      • Prerequisites
      • From Zero to Modding
      • Customizing Your Mod Information
      • Building and Testing Your Mod
    • The Mod Files
    • Structuring Your Mod
    • Versioning
  • Core Concepts
    • Registries
    • Sides
    • Events
    • Mod Lifecycle
    • Resources
    • Internationalization
  • Blocks
    • Introduction
    • Block States
  • Items
    • Introduction
    • BlockEntityWithoutLevelRenderer
  • Networking
    • Introduction
    • SimpleImpl
    • Synchronizing Entities
  • Block Entities
    • Introduction
    • BlockEntityRenderer
  • Game Effects
    • Particles
    • Sounds
  • Data Storage
    • Capabilities
    • Saved Data
    • Codecs
  • Graphical User Interfaces
    • Menus
    • Screens
  • Rendering
    • Model Extensions
      • Introduction
      • Root Transforms
      • Render Types
      • Part Visibility
      • Face Data
    • Model Loaders
      • Introduction
      • Baked Model
      • Transform
      • Item Overrides
  • Resources
    • Client Assets
      • Introduction
      • Models
        • Introduction
        • Texture Tinting
        • Item Properties
    • Server Data
      • Introduction
      • Recipes
        • Introduction
        • Custom Recipes
        • Ingredients
        • Non-Datapack Recipes
      • Loot Tables
      • Global Loot Modifiers
      • Tags
      • Advancements
      • Conditionally-Loaded Data
      • Tags List
  • Data Generation
    • Introduction
    • Client Assets
      • Model Providers
      • Language Providers
      • Sound Providers
    • Server Data
      • Recipe Providers
      • Loot Table Providers
      • Tag Providers
      • Advancement Providers
      • Global Loot Modifier Providers
      • Datapack Registry Object Providers
  • Miscellaneous Features
    • Configuration
    • Key Mappings
    • Game Tests
    • Forge Update Checker
    • Debug Profiler
  • Advanced Topics
    • Access Transformers
  • Contributing to Forge
    • Introduction
    • Pull Request Guidelines
  • Legacy Versions
    • Introduction
    • Porting to This Version

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

Important

Do not edit the settings.gradle unless you know what you are doing. The file specifies the repository that ForgeGradle is uploaded to.

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:

Type Value Top-Level Package
Domain example.com com.example
Subdomain example.github.io io.github.example
Email [email protected] com.gmail.example
// 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.

Note

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.

Built with MkDocs using a custom theme. Hosted by Read the Docs.
Enable Dark Theme