Skip to content

mod.toml

A metadata file which references an external file from a URL. This allows for side-only mods, optional mods and stores metadata to allow finding updates from Modrinth and CurseForge. The "mod" terminology is used a lot here, but this should work for any file.

Example:

name = "Demagnetize"
filename = "demagnetize-1.12.2-1.1.1.jar"
side = "both"

[download]
url = "https://edge.forgecdn.net/files/2834/566/demagnetize-1.12.2-1.1.1.jar"
hash-format = "murmur2"
hash = "2953308073"

[update]
[update.curseforge]
file-id = 2834566
project-id = 301356
release-channel = "beta"

Properties

Property Type Required Description
download object Yes Information about how to download this mod.
filename string Yes The destination path of the mod file, relative to this file.
name string Yes The name of the mod, which can be displayed in user interfaces to identify the mod. It does not need to be unique between mods, although this may cause confusion.
option object No Information about the optional state of this mod. When excluded, this indicates that the mod is not optional.
side string No The side on which this mod should be installed. Defaults to "both". Possible values are: both, client, server.
update object No Information about how to update the download details of this mod with tools. The information stored is specific to the update interface.
If this value does not exist or there are no defined update values, the mod will not be automatically updated.
If there are multiple defined update values, one of them will be chosen. The value that is chosen is not defined, so it is therefore dependant on the implementation of the tool (may not be deterministic, so do not rely on one value being chosen over another).

download

Information about how to download this mod.

Properties

Property Type Required Description
hash-format string Yes A hashing format used to detect if a file has changed. You may use your own hash format, but the valid values here should be supported and expected for most packs, especially SHA-256 and Murmur2. Possible values are: md5, murmur2, sha256, sha512.
hash string Yes The hash of the specified file, as a string. Binary hashes should be stored as hexadecimal, and case should be ignored during parsing. Numeric hashes (e.g. Murmur2) should still be stored as a string, to ensure the value is preserved correctly.
url string Yes The URL to download the mod from.

option

Information about the optional state of this mod. When excluded, this indicates that the mod is not optional.

Properties

Property Type Required Description
default boolean Yes If true, the mod will be enabled by default. If false, the mod will be disabled by default. If a pack format does not support optional mods but it does support disabling mods, the mod will be disabled if it defaults to being disabled.
description string Yes A description displayed to the user when they select optional mods. This should explain why or why not the user should enable the mod.
optional boolean Yes Whether or not the mod is optional. This can be set to false if you want to keep the description but make the mod required.

update

Information about how to update the download details of this mod with tools. The information stored is specific to the update interface.

If this value does not exist or there are no defined update values, the mod will not be automatically updated.

If there are multiple defined update values, one of them will be chosen. The value that is chosen is not defined, so it is therefore dependant on the implementation of the tool (may not be deterministic, so do not rely on one value being chosen over another).

Properties

Property Type Required Description
curseforge object No An update value for updating mods downloaded from CurseForge.
modrinth object No An update value for updating mods downloaded from Modrinth.

curseforge

An update value for updating mods downloaded from CurseForge.

Properties

Property Type Required Description
file-id number Yes An integer representing the unique file ID of this mod file. This can be used if more metadata needs to be obtained relating to the mod.
project-id number Yes An integer representing the unique project ID of this mod. Updating will retrieve the latest file for this project ID that is valid (correct Minecraft version, release channel, modloader, etc.).

modrinth

An update value for updating mods downloaded from Modrinth.

Properties

Property Type Required Description
mod-id string Yes A string representing the unique mod ID of this mod. Updating will retrieve the latest file for this project ID that is valid (correct Minecraft version, release channel, modloader, etc.).
version string Yes A string representing the unique version ID of this file. This can be used if more metadata needs to be obtained relating to the mod.