Mod Files

The mod files are responsible for determining what mods are packaged into your JAR, what information to display within the ‘Mods’ menu, and how your mod should be loaded in the game.

mods.toml

The mods.toml file defines the metadata of your mod(s). It also contains additional information that is displayed within the ‘Mods’ menu and how your mod(s) should be loaded into the game.

The file uses the Tom’s Obvious Minimal Language, or TOML, format. The file must be stored under the META-INF folder in the resource directory of the source set you are using (src/main/resources/META-INF/mods.toml for the main source set). A mods.toml file may look something like this:

modLoader="javafml"
loaderVersion="[45,)"

license="All Rights Reserved"
issueTrackerURL="https://github.com/MinecraftForge/MinecraftForge/issues"
showAsResourcePack=false

[[mods]]
  modId="examplemod"
  version="1.0.0.0"
  displayName="Example Mod"
  updateJSONURL="https://files.minecraftforge.net/net/minecraftforge/forge/promotions_slim.json"
  displayURL="https://minecraftforge.net"
  logoFile="logo.png"
  credits="I'd like to thank my mother and father."
  authors="Author"
  description='''
  Lets you craft dirt into diamonds. This is a traditional mod that has existed for eons. It is ancient. The holy Notch created it. Jeb rainbowfied it. Dinnerbone made it upside down. Etc.
  '''
  displayTest="MATCH_VERSION"

[[dependencies.examplemod]]
  modId="forge"
  mandatory=true
  versionRange="[45,)"
  ordering="NONE"
  side="BOTH"

[[dependencies.examplemod]]
  modId="minecraft"
  mandatory=true
  versionRange="[1.19.4]"
  ordering="NONE"
  side="BOTH"

mods.toml is broken into three parts: the non-mod-specific properties, which are linked to the mod file; the mod properties, with a section for each mod; and the dependency configurations, with a section for each mod’s or mods’ dependencies. Each of the properties associated with the mods.toml file will be explained below, where required means that a value must be specified or an exception will be thrown.

Non-Mod-Specific Properties

Non-mod-specific properties are properties associated with the JAR itself, indicating how to load the mod(s) and any additional global metadata.

Mod-Specific Properties

Mod-specific properties are tied to the specified mod using the [[mods]] header. This is an array of tables; all key/value properties will be attached to that mod until the next header.

# Properties for examplemod1
[[mods]]
modId = "examplemod1"

# Properties for examplemod2
[[mods]]
modId = "examplemod2"

Features

The features system allows mods to demand that certain settings, software, or hardware are available when loading the system. When a feature is not satisfied, mod loading will fail, informing the user about the requirement. Currently, Forge provides the following features:

Dependency Configurations

Mods can specify their dependencies, which are checked by Forge before loading the mods. These configurations are created using the array of tables [[dependencies.<modid>]] where modid is the identifier of the mod the dependency is for.

Mod Entrypoints

Now that the mods.toml is filled out, we need to provide an entrypoint to being programming the mod. Entrypoints are essentially the starting point for executing the mod. The entrypoint itself is determined by the language loader used in the mods.toml.

javafml and @Mod

javafml is a language loader provided by Forge for the Java programming language. The entrypoint is defined using a public class with the @Mod annotation. The value of @Mod must contain one of the mod ids specified within the mods.toml. From there, all initialization logic (e.g., registering events, adding DeferredRegisters) can be specified within the constructor of the class. The mod bus can be obtained from FMLJavaModLoadingContext.

@Mod("examplemod") // Must match mods.toml
public class Example {

  public Example() {
    // Initialize logic here
    var modBus = FMLJavaModLoadingContext.get().getModEventBus();

    // ...
  }
}

lowcodefml

lowcodefml is a language loader used as a way to distribute datapacks and resource packs as mods without the need of an in-code entrypoint. It is specified as lowcodefml rather than nocodefml for minor additions in the future that might require minimal coding.