Dependencies

A dependency is the reliance of a piece of software on another piece of software. In the context of Minecraft Forge, it is a mod or library which another mod relies or depends on.

Dependencies are declared in three ways:

• The dependencies block in a Gradle buildscript defines compile-time and runtime dependencies, which are used by the build system and compiler when building or running the mod in the development environment.
• The act of using classes, fields, and methods from a library creates a dependency on the library in the compiled binaries. The library may be an explicitly declared dependency, or a dependency of an explicitly declared dependency (such as the Guava libraries that Minecraft depends on).
• Dependency configurations are declared in the mods.toml metafile, which is then checked by Forge on runtime on whether they are satisfied.

Hard and Soft Dependencies

There are two types of mod dependencies: hard dependencies, and soft dependencies.

A hard dependency is a dependency where the dependent mod requires that the dependency is present. This may be in the form of a code dependency, wherein the JVM will crash due to the missing class, field, or method from the dependency, or it may be in the form of a dependency configuration which mandates that the dependency is present.

Hard dependencies should be declared using a dependency configuration to allow the Forge Mod Loader to detect the missing dependency and gracefully handle it by showing an error screen to the user, rather than the JVM crashing with a non-user-friendly exception message.

A soft dependency is a dependency where the dependent mod does not require the dependency is present, but extra features or compatibility is added in the case of the dependency being present. This often takes the form of cross-mod compatibility features, where a mod soft-depends on another mod or the mod's API.

Soft dependencies usually take the form of isolated code dependencies, where the code that depends on the soft-dependency is isolated from the rest of the mod until the soft-dependency is detected as being present.

Declaring Dependencies

A mod declares a dependency on a mod or library through Gradle, through the dependencies block.

For example, to declare a dependency on the net:minecraftforge:eventbus:4.0.0 library from the main source set:

dependencies {
    // 'implementation' is for the main source set
    implementation "net.minecraftforge:eventbus:4.0.0"
}

ForgeGradle automatically adds the Forge Maven and Maven Central repositories to projects. If a dependency is not present in these (such as dependencies on other mods), the repository containing the dependency must be declared in the repositories block of the Gradle buildscript.

Deobfuscating Dependencies

Mods (and libraries which use Minecraft code) are usually released as an SRG-obfuscated JAR, which prevents their direct use in development environments due to mismatch between SRG names from the mod/library and the MCP/mapped names in the development environment.

These mods/libraries must be deobfuscated to the development environment's mappings first. This is done using the fg.deobf function, which creates a dependency which is dynamically remapped to the local environment's mappings.

For example, to declare a dependency on the mezz.jei:jei-1.16.5:7.6.1.75 library (which is obfuscated):

dependencies {
    implementation fg.deobf("mezz.jei:jei-1.16.5:7.6.1.75")
}

Flat Directory Repositories

There are occasions where it is needed to temporarily add a dependency on a JAR file that is not present in a Maven repository, such as to add a mod which adds some developer tools during runtime. Gradle allows declaring flat directory repositories, which use a local directory as a simplified repository.

A flat directory repository is declared using a flatDir block within the repositories block, and specifying directories using dirs:

repositories {
    flatDir {
        dirs 'lib'
    }
}

When a dependency artifact is searched for in a flat directory repository, it will look for the following files in order (ext defaults to jar):

• <artifact>-<version>.<ext>
• <artifact>-<version>-<classifier>.<ext>
• <artifact>.<ext>
• <artifact>-<classifier>.<ext>

For example, for the dependency junit:junit:4.8.1, it will first search for junit-4.8.1.jar then junit.jar. The group ID in the dependency descriptor must be present (due to the presence of non-flat directory repositories as added by ForgeGradle), but it will always be ignored.

Warning

Flat directory repositories should only be used temporarily in a local environment, and not used to include a required dependency for your project. For a actual dependency used by your mod, use a remote Maven repository holding the artifact.