213
edits
Changes
mLine 37:
Line 37: − + + + + + + + − The <code>mods.toml</code> 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 <code>mods.toml</code> file is formatted in [https://toml.io/en/ Tom's Obvious Minimal Language], or TOML for short. The example <code>mods.toml</code> file in the MDK provides comments explaining the contents of the file. It should be stored under the <code>META-INF</code> folder in your resources directory (<code>src/main/resources/META-INF/mods.toml</code>). − <div class="mw-collapsible mw-collapsed" style="border: solid 2px; padding: 2px 5px; margin-top: 3px">+ − <div style="font-weight:bold;line-height:1.6;">Example <code>mods.toml</code> file</div> − <div class="mw-collapsible-content"> Line 81:
Line 83: − </div> − </div> − The default Gradle configuration replaces <code>${file.jarVersion}</code> with the project version, but only within <code>mods.toml</code>, so you should use those instead of directly writing them out. Here is a table of attributes that may be given to a mod, where <code>mandatory</code> means there is no default and the absence of the property causes an error. − The <code>mods.toml</code> 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.+ − + + − ! Property !! Type !! Defaults − ! Description − ! Example − + − + − + + + − + − + − + + + − + − + − | <code>"GNU GPL v3, https://www.gnu.org/licenses/gpl-3.0.en.html"</code>+ + + − + − + − + + + − + − + − + + + − + − + − + + + + + + + + + − === Mod Properties === + − − ! Property !! Type !! Defaults − ! Description − ! Example − + − + − + + + − + − | An override namespace. <inline info> Currently, there is no use for this property </inline> + − + + + − + − + − + + + − + − + − + + + − + − + − + + + − + − + − + + + − + − + − + + + − + − + − + + + − + − + − + + + − + − + − + + + − + − + − + + + − + − + − + + + + + + + + + − === Dependency Configurations === + − + − − ! Property !! Type !! Defaults − ! Description − ! Example − + − + − + + + − + − + − + + + − + − + − + + + − + − + − + + + − + − + − + + + + + + + + + +
Fix the information about file.jarVersion, thanks Ater
The <code>@Mod</code> annotation indicates to the mod loader that this class is the entry point of your mod. Each <code>@Mod</code> annotation and their value should be paired with a mod id entry in your <code>mods.toml</code> file.
The <code>@Mod</code> annotation indicates to the mod loader that this class is the entry point of your mod. Each <code>@Mod</code> annotation and their value should be paired with a mod id entry in your <code>mods.toml</code> file.
== The <code>mods.toml</code> file ==
==The <code>mods.toml</code> file==
The <code>mods.toml</code> 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 <code>mods.toml</code> file is formatted in [https://toml.io/en/ Tom's Obvious Minimal Language]
, or TOML for short. The example <code>mods.toml</code> file in the MDK provides comments explaining the contents of the file. It should be stored under the <code>META-INF</code> folder in your resources directory (<code>src/main/resources/META-INF/mods.toml</code>).
Example <code>mods.toml</code> file
<syntaxhighlight lang="TOML">
<syntaxhighlight lang="TOML">
modLoader="javafml"
modLoader="javafml"
side="BOTH"
side="BOTH"
</syntaxhighlight>
</syntaxhighlight>
If the <code>version</code> is specified as<code>${file.jarVersion}</code>, 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 <code>NONE</code> instead. As such, it is usually recommended to leave this field alone.
=== Non-Mod-Specific Properties ===
The <code>mods.toml</code> 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<code>mandatory</code>means there is no default and the absence of the property causes an error.
===Non-Mod-Specific Properties===
{| class="wikitable"
{| class="wikitable"
|-
|-
| <code>modLoader</code> || string || '''mandatory'''
!|Property
| 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 <code>javafml</code>.
!|Type
| <code>"javafml"</code>
!|Defaults
!|Description
!|Example
|-
|-
| <code>loaderVersion</code> || string || '''mandatory'''
|<code>modLoader</code>
| The acceptable version range of the language loader, expressed as a [https://maven.apache.org/enforcer/enforcer-rules/versionRanges.html Maven version spec]. For the Forge-provided Java loader, the version is the major version of the Forge version.
|string
| <code>"[34,)"</code>
|'''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 <code>javafml</code>.
|<code>"javafml"</code>
|-
|-
| <code>license</code> || string || '''mandatory'''
|<code>loaderVersion</code>
| 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.
|string
|'''mandatory'''
|The acceptable version range of the language loader, expressed as a [https://maven.apache.org/enforcer/enforcer-rules/versionRanges.html Maven version spec]. For the Forge-provided Java loader, the version is the major version of the Forge version.
|<code>"[34,)"</code>
|-
|-
| <code>showAsResourcePack</code> || boolean || <code>false</code>
|<code>license</code>
| 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.
|string
| <code>true</code>
|'''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.
|<code>"GNU GPL v3, https://www.gnu.org/licenses/gpl-3.0.en.html"</code>
|-
|-
| <code>properties</code> || table || <code>{}</code>
|<code>showAsResourcePack</code>
| A table of custom substitution properties. This is used by <code>StringSubstitutor</code> to replace values, using <code>${file.*}</code>.
|boolean
| <code>{ "thingy" = 1 }</code>, used in <code>${file.thingy}</code>
|<code>false</code>
|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.
|<code>true</code>
|-
|-
| <code>issueTrackerURL</code> || string || ''nothing''
|<code>properties</code>
| A URL for an issues tracker. <inline alert> This should never be a blank string, as that will cause an error. </inline>
|table
| <code><nowiki>"http://my.issue.tracker/"</nowiki></code>
|<code>{}</code>
|A table of custom substitution properties. This is used by <code>StringSubstitutor</code> to replace values, using <code>${file.*}</code>.
|<code>{ "thingy" = 1 }</code>, used in <code>${file.thingy}</code>
|-
|<code>issueTrackerURL</code>
|string
|''nothing''
|A URL for an issues tracker. This should never be a blank string, as that will cause an error.
|<code><nowiki>"http://my.issue.tracker/"</nowiki></code>
|}
|}
===Mod Properties===
A mod entry is defined by a new section starting with a <code><nowiki>[[mods]]</nowiki></code> header (In TOML, the <code><nowiki>[[mods]]</nowiki></code> defines an [https://toml.io/en/v1.0.0-rc.2#array-of-tables array of tables]). All properties from that line until the next header will become the properties for that mod.
A mod entry is defined by a new section starting with a <code><nowiki>[[mods]]</nowiki></code> header (In TOML, the <code><nowiki>[[mods]]</nowiki></code> defines an [https://toml.io/en/v1.0.0-rc.2#array-of-tables array of tables]). All properties from that line until the next header will become the properties for that mod.
{| class="wikitable"
{| class="wikitable"
|-
|-
| <code>modId</code> || string || '''mandatory'''
!|Property
| The mod's identifier (modid). This must match the following regex: <code>^[a-z][a-z0-9_-]{1,63}$</code> (starts with a lowercase letter; other characters must be a lowercase letter, number, underscore or hyphen; must be 2-64 characters long).
!|Type
| <code>"examplemod"</code>
!|Defaults
!|Description
!|Example
|-
|-
| <code>namespace</code> || string || value of <code>modId</code>
|<code>modId</code>
|string
| <code>example</code>
|'''mandatory'''
|The mod's identifier (modid). This must match the following regex: <code>^[a-z][a-z0-9_-]{1,63}$</code> (starts with a lowercase letter; other characters must be a lowercase letter, number, underscore or hyphen; must be 2-64 characters long).
|<code>"examplemod"</code>
|-
|-
| <code>version</code> || string || <code>"1"</code>
|<code>namespace</code>
| The version of the mod jar, used when the mod is a dependency of another mod, expressed as numbers seperated by dots (<code>.</code>), ideally conforming to [[Semantic_Versioning|Semantic Versioning]]. The default value in the MDK for this is <code>${file.jarVersion}</code>, which is replaced at runtime with the <code>Implementation-Version</code> found in the jar's manifest file.
|string
| <code>"0.2.4-beta1"</code>
|value of <code>modId</code>
|An override namespace. Currently, there is no use for this property
|<code>example</code>
|-
|-
| <code>displayName</code> || string || value of <code>modId</code>
|<code>version</code>
| The display name of the mod, for use in the Mods listing screen
|string
| <code>"Example Mod"</code>
|<code>"1"</code>
|.), ideally conforming to [[Semantic_Versioning>Semantic Versioning]]. The default value in the MDK for this is <code>${file.jarVersion}</code>, which is replaced at runtime with the <code>Implementation-Version</code> found in the jar's manifest file.
|<code>"0.2.4-beta1"</code>
|-
|-
| <code>description</code> || string || <code>"MISSING DESCRIPTION"</code>
|<code>displayName</code>
| The description of the mod, for use in the Mods listing screen. It's recommended to use a multiline string (surrounded by <code>'''<code>)
|string
| <code>"Adds things and stuff. "</code>
|value of <code>modId</code>
|The display name of the mod, for use in the Mods listing screen
|<code>"Example Mod"</code>
|-
|-
| <code>logoFile</code> || string || ''nothing''
|<code>description</code>
| 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 <code>src/main/resources</code>)
|string
| <code>"myAwesomeLogo.png"</code>
|<code>"MISSING DESCRIPTION"</code>
|The description of the mod, for use in the Mods listing screen. It's recommended to use a multiline string (surrounded by <code>'''<code>)</code></code>
|<code>"Adds things and stuff. "</code>
|-
|-
| <code>logoBlur</code> || boolean || <code>true</code>
|<code>logoFile</code>
| Whether to do some blurring on the mod's logo in the Mods listing screen. Has no effect if <code>logoFile</code> is not set.
|string
| <code>false</code>
|''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 <code>src/main/resources</code>)
|<code>"myAwesomeLogo.png"</code>
|-
|-
| <code>updateJSONURL</code> || string || ''nothing''
|<code>logoBlur</code>
| The update JSON URL, used by the [Update_Checker update checker]. <inline alert> This should never be a blank string, as that will cause an error. </inline>
|boolean
| <code><nowiki>"http://myurl.me/path/to/update.json"</nowiki></code>
|<code>true</code>
|Whether to do some blurring on the mod's logo in the Mods listing screen. Has no effect if <code>logoFile</code> is not set.
|<code>false</code>
|-
|-
| <code>modproperties</code> || table || <code>{}</code>
|<code>updateJSONURL</code>
| A table of custom mod properties; this is not used for Forge, but is mainly for use by mods.
|string
| <code>{ "useThing" = true }</code>
|''nothing''
|The update JSON URL, used by the [Update_Checker update checker]. This should never be a blank string, as that will cause an error.
|<code><nowiki>"http://myurl.me/path/to/update.json"</nowiki></code>
|-
|-
| <code>credits</code> || string || ''nothing''
|<code>modproperties</code>
| Credits and acknowledgements for the mod, for use in the Mods listing screen. Can be any string.
|table
| <code>"This person and that guy"</code>
|<code>{}</code>
|A table of custom mod properties; this is not used for Forge, but is mainly for use by mods.
|<code>{ "useThing" = true }</code>
|-
|-
| <code>authors</code> || string || ''nothing''
|<code>credits</code>
| Authors for the mod, for use in the Mods listing screen. Can be any string.
|string
| <code>"ExampleDude"</code>
|''nothing''
|Credits and acknowledgements for the mod, for use in the Mods listing screen. Can be any string.
|<code>"This person and that guy"</code>
|-
|-
| <code>displayURL</code> || string || ''nothing''
|<code>authors</code>
| A URL, displayed on the Mods listing screen. Can be any string.
|string
| <code><nowiki>"http://example.com/"</nowiki></code>
|''nothing''
|Authors for the mod, for use in the Mods listing screen. Can be any string.
|<code>"ExampleDude"</code>
|-
|<code>displayURL</code>
|string
|''nothing''
|A URL, displayed on the Mods listing screen. Can be any string.
|<code><nowiki>"http://example.com/"</nowiki></code>
|}
|}
===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.
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 <code>[[dependencies.<modid>]]</code>, with <code><modid></code> 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.
These dependency configurations, like the mod properties, are defined by a new section starting with <code>[[dependencies.]]</code>, with <code></code> 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.
{| class="wikitable"
{| class="wikitable"
|-
|-
| <code>modId</code> || string || '''mandatory'''
!|Property
| The mod id of the dependency.
!|Type
| <code>examplelibrary</code>
!|Defaults
!|Description
!|Example
|-
|-
| <code>mandatory</code> || boolean || '''mandatory'''
|<code>modId</code>
| Whether to crash if this dependency is not met.
|string
| <code>true</code>
|'''mandatory'''
|The mod id of the dependency.
|<code>examplelibrary</code>
|-
|-
| <code>versionRange</code> || string || <code>""</code>
|<code>mandatory</code>
| The acceptable version range of the dependency, expressed as a [https://maven.apache.org/enforcer/enforcer-rules/versionRanges.html Maven version spec]. An empty string is an unbounded version range, which matches any version.
|boolean
| <code>"[1.0,2.0)"</code>
|'''mandatory'''
|Whether to crash if this dependency is not met.
|<code>true</code>
|-
|-
| <code>ordering</code> || string || <code>"NONE"</code>
|<code>versionRange</code>
| Defines if the mod must load before or after this dependency. The valid values are <code>BEFORE</code> (must load before), <code>AFTER</code> (must load after), and <code>NONE</code> (does not care about order).
|string
| <code>"AFTER"</code>
|<code>""</code>
|The acceptable version range of the dependency, expressed as a [https://maven.apache.org/enforcer/enforcer-rules/versionRanges.html Maven version spec]. An empty string is an unbounded version range, which matches any version.
|<code>"[1.0,2.0)"</code>
|-
|-
| <code>side</code> || string || <code>"BOTH"</code>
|<code>ordering</code>
| Defines if this dependency needs only to be met on a specfic [[Sides|physical side]]. The valid values are <code>CLIENT</code> (present on the client), <code>SERVER</code> (present on the dedicated server), and <code>BOTH</code> (present on both sides).
|string
| <code>"CLIENT"</code>
|<code>"NONE"</code>
|Defines if the mod must load before or after this dependency. The valid values are <code>BEFORE</code> (must load before), <code>AFTER</code> (must load after), and <code>NONE</code> (does not care about order).
|<code>"AFTER"</code>
|-
|<code>side</code>
|string
|<code>"BOTH"</code>
|physical side]]. The valid values are <code>CLIENT</code> (present on the client), <code>SERVER</code> (present on the dedicated server), and <code>BOTH</code> (present on both sides).
|<code>"CLIENT"</code>
|}
|}
{{Tip/Warning|When specifying dependency ordering between two or more mods, beware of cyclic order!
{{Tip/Warning|When specifying dependency ordering between two or more mods, beware of cyclic order!