ForgeGradle Configurations

ForgeGradle has numerous configurations that can change how the development environment is configured. Most configurations are set using the minecraft block; however, some others can be specified within the dependencies block or modify the built jar, such as reobfJar.

Enabling Access Transformers

Access Transformers can widen the visibility or modify the final flag of Minecraft classes, methods, and fields. To enable access transformers in the production environment, you can set accessTransformer to configuration file in question:

minecraft {
    // ...

    // Add an access transformer file relative to the project's directory
    accessTransformer = project.file('src/main/resources/META-INF/accesstransformer.cfg')
}

caution

While the access transformer in the development environment can be read from anywhere the user specifies, in production, the file will only be read from META-INF/accesstransformer.cfg.

Human-Readable Mappings

Minecraft's source code is obfuscated. As such, all classes, methods, and fields have machine-generated names with no package structures. Function-local variable names, meanwhile, are turned into a snowman (☃) due to how the Local Variable Table is stored. It is difficult to create mods using obfuscated names as reverse engineering them is tedious, may change between versions, and may be invalid in the language itself but not in the bytecode.

To address the last two issues, Forge fuzzily maps each class, method, field, and parameter to a unique identifier, known as the SRG name, via the ForgeAutoRenamingTool. SRG mappings are used in production when the game is being run by the user client.

To allow easier development, ForgeGradle allows the user to choose a mapping set to apply on top of SRG mappings, which we will refer to as human-readable mappings. ForgeGradle knows how to convert the mod jar to SRG mappings for use in production via the reobf* task.

The mapping set used can be specified by setting the mappings field in the minecraft block. The mappings field takes in two arguments: channel which is the type of the mapping set, and version which is the version of the mapping set to apply.

Currently, there are three default mapping sets built into ForgeGradle:

• official - This uses the mapping set provided by Mojang. These mappings do not have parameter names and only exist from 1.14 onward.
• stable - This uses a mapping set generated by MCP. These are typically incomplete and no longer exist as of 1.17.
• snapshot - This also is a mapping set generated by MCP, similar to a nightly build of a program. These are also typically incomplete and no longer exist as of 1.17.

info

The class names used in production are from stable prior to 1.17 and from official from 1.17 onwards.

mappings {
    // Sets the mappings to use those from Mojang for Minecraft 1.19.4.
    mappings channel: 'official', version: '1.19.4'

    // ...
}

Parchment

Parchment is an official project maintained by ParchmentMC which provides open, community-sourced parameter names and javadocs on top of the official mapping set. You can learn how setup and use the parchment mapping set on their website.

Preparing Run Tasks

Run tasks (run*) have two separate pipelines depending on whether they are executed through gradlew or a run configuration. By default, there are two tasks that prepare the workspace for execution:

First, there are prepare* tasks which are executed before run* tasks and ensure that mapping files are prepared for the game. The prepare*Compile task is typically only executed as a dependency of run* tasks to make sure that the game is compiled before it is run.

If your IDE is either Eclipse or IntelliJ IDEA, the run configuration can be configured to execute the prepare* tasks before starting the game by setting enableEclipsePrepareRuns or enableIdeaPrepareRuns, respectively, to true. This will allow you to invoke custom Gradle tasks before your IDE launches the game.

minecraft {
    // ...

    // Enable the 'prepare*' task for run configurations
    enableEclipsePrepareRuns true
    enableIdeaPrepareRuns true
}

Copy IDE Resources

The copyIdeResources property can be used to copy resources configured by the processResources task to the IDE's resource output directories. This allows IDE run configurations that do not invoke Gradle (IntelliJ configured to use the IDEA runner or Eclipse) to use buildscript configurable resources. Usually, you need to enable this property when you are replacing values in files like the mods.toml.
This only applies to Eclipse and IntelliJ IDEA via the copyEclipseResources and copyIntellijResources tasks, respectively.

minecraft {
    // ...

    // Copies the files from 'processResources' to the IDE's resource output directories
    copyIdeResources true
}

Run Configuration Folders

Run configurations can be sorted into folders if the generateRunFolders is set to true. This reads the folderName property set in the specific run configuration to determine the organizational structure.

minecraft {
    // ...

    // When true, run configurations will be grouped into folders by their 'folderName'
    generateRunFolders true
}