Mods.toml

From Forge Community Wiki
Revision as of 17:08, 11 December 2021 by N1K-x (talk | contribs) (Update to 1.18.1)

This page is under construction.

This page is incomplete, and needs more work. Feel free to edit and improve this page!

The mods.toml file is read by the mod loader to determine what mods are packaged into your JAR file, and what information to display to the user in the Mods listing screen (accessible by pressing the "Mods" button on the main menu of the game).

The file is formatted in Tom's Obvious Minimal Language, or TOML for short. The example mods.toml file in the MDK provides comments explaining the contents of the file. It should be stored under the META-INF folder in your resources directory (src/main/resources/META-INF/mods.toml).

Example mods.toml file:

modLoader="javafml"
# Forge for 1.18.1 is version 39
loaderVersion="[39,)"
license="All rights reserved"
issueTrackerURL="github.com/MinecraftForge/MinecraftForge/issues"
showAsResourcePack=false

[[mods]]
    modId="examplemod"
    version="1.0.0.0"
    displayName="Example Mod"
    updateJSONURL="minecraftforge.net/versions.json"
    displayURL="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.
    '''

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

[[dependencies.examplemod]]
    modId="minecraft"
    mandatory=true
    versionRange="[1.18.1,1.19)"
    ordering="NONE"
    side="BOTH"

If the version is specified as${file.jarVersion}, Forge will replace the string with the 'Implementation Version' specified in the jar manifest at runtime. Since the userdev environment has no jar manifest to pull from, it will be NONE instead. As such, it is usually recommended to leave this field alone.

The mods.toml is split 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 dependency configurations, with a section for each mod's dependencies. Here is a table of attributes that may be given to a mod, where mandatory means there is no default and the absence of the property causes an error.

Non-Mod-Specific Properties

Property Type Defaults Description Example
modLoader string mandatory The language loader for the mod. Used to specify an alternative language for the mod, such as Kotlin, if one exists. The Forge-provided Java loader is javafml. "javafml"
loaderVersion string mandatory The acceptable version range of the language loader, expressed as a Maven version spec. For the Forge-provided Java loader, the version is the major version of the Forge version. "[39,)"
license string mandatory The license for the mod(s) in this JAR. This string may be any valid string, but it is suggested to set the value to be the name of your license, and/or a link to that license. "GNU GPL v3, https://www.gnu.org/licenses/gpl-3.0.en.html"
showAsResourcePack boolean false Whether to display this mod's resources as a separate option in the resource pack menu. If disabled, the mod's resources will be rolled into the "Mod resources" pack. true
properties table {} A table of custom substitution properties. This is used by StringSubstitutor to replace values, using ${file.*}. { "thingy" = 1 }, used in ${file.thingy}
issueTrackerURL string nothing A URL for an issues tracker. This should never be a blank string, as that will cause an error. "http://my.issue.tracker/"

Mod Properties

A mod entry is defined by a new section starting with a [[mods]] header (In TOML, the [[mods]] defines an array of tables). All properties from that line until the next header will become the properties for that mod.

Property Type Defaults Description Example
modId string mandatory The mod's identifier (modid). This must match the following regex: ^[a-z][a-z0-9_-]{1,63}$ (starts with a lowercase letter; other characters must be a lowercase letter, number, underscore or hyphen; must be 2-64 characters long). "examplemod"
namespace string value of modId An override namespace. Currently, there is no use for this property example
version string "1" The mod's version, ideally conforming to semantic versioning. The default value in the MDK for this is ${file.jarVersion}, which is replaced at runtime with the Implementation-Version found in the jar's manifest file. "0.2.4-beta1"
displayName string value of modId The display name of the mod, for use in the Mods listing screen "Example Mod"
description string "MISSING DESCRIPTION" The description of the mod, for use in the Mods listing screen. It's recommended to use a multiline string (surrounded by ''') "Adds things and stuff. "
logoFile string nothing The path of the logo file image, for use in the Mods listing screen. The image must be in the root of the jar file, not in any subfolder thereof (e.g. the file is directly in src/main/resources) "myAwesomeLogo.png"
logoBlur boolean true Whether to do some blurring on the mod's logo in the Mods listing screen. Has no effect if logoFile is not set. false
updateJSONURL string nothing The update JSON URL, used by the update checker. This should never be a blank string, as that will cause an error. "http://myurl.me/path/to/update.json"
modproperties table {} A table of custom mod properties; this is not used for Forge, but is mainly for use by mods. { "useThing" = true }
credits string nothing Credits and acknowledgements for the mod, for use in the Mods listing screen. Can be any string. "This person and that guy"
authors string nothing Authors for the mod, for use in the Mods listing screen. Can be any string. "ExampleDude"
displayURL string nothing A URL, displayed on the Mods listing screen. Can be any string. "http://example.com/"

Dependency Configurations

Mods can define dependencies for their mods, which are checked by Forge before loading mods. This is used for e.g. ensuring your mod loads after another, or hard-crashing if a mod with a specified version does not exist.

These dependency configurations, like the mod properties, are defined by a new section starting with [[dependencies.modid]], with modid being the mod id that has this dependency. All properties from that line until the next header will become the properties of that dependency configuration.

Property Type Defaults Description Example
modId string mandatory The mod id of the dependency. examplelibrary
mandatory boolean mandatory Whether to crash if this dependency is not met. true
versionRange string "" The acceptable version range of the dependency, expressed as a Maven version spec. An empty string is an unbounded version range, which matches any version. "[1.0,2.0)"
ordering string "NONE" Defines if the mod must load before or after this dependency. The valid values are BEFORE (must load before), AFTER (must load after), and NONE (does not care about order). "AFTER"
side string "BOTH" physical side]]. The valid values are CLIENT (present on the client), SERVER (present on the dedicated server), and BOTH (present on both sides). "CLIENT"


Warning

When specifying dependency ordering between two or more mods, beware of cyclic order!

An example: if mod A must load before mod B, and mod B must load before mod A, the game will crash because of the circular cycle.