Mod.json: Difference between revisions
More actions
Bonsaibauer (talk | contribs) Marked this version for translation |
Bonsaibauer (talk | contribs) Expand mod.json guide with field rules, dependency behavior, and supported icon formats. |
||
| (One intermediate revision by the same user not shown) | |||
| Line 3: | Line 3: | ||
<!-- ShroudForge Modloader Wiki Post | <!-- ShroudForge Modloader Wiki Post | ||
title: mod.json | title: mod.json | ||
description: | description: Create a valid mod.json package manifest, choose supported values, define dependencies, and add a Modloader icon. | ||
language: en-GB | language: en-GB | ||
creator: Bonsaibauer | creator: Bonsaibauer | ||
| Line 11: | Line 11: | ||
<!--T:1--> | <!--T:1--> | ||
Every ShroudForge mod package needs a <code>mod.json</code> | Every ShroudForge mod package needs a file named <code>mod.json</code> in the package's top-level folder. The Modloader reads this file to identify the package, check its version and dependencies, and determine which capabilities it requests. It is the package manifest, not the place for player-facing settings. Put those in [[Extended.mod.json|<code>extended.mod.json</code>]]. | ||
== | == Start with a valid file == <!--T:2--> | ||
<!--T:3--> | <!--T:3--> | ||
The | <code>mod.json</code> uses JSON. Put field names and text values in double quotes, separate entries with commas, and do not add a comma after the last entry. The fields <code>id</code>, <code>name</code>, and <code>version</code> are required. The other fields are optional. | ||
== | === Required fields === <!--T:4--> | ||
<!--T:5--> | <!--T:5--> | ||
{| class="wikitable" | |||
! Field !! Value to provide !! Rules and purpose | |||
|- | |||
| <code>id</code> || A stable package identifier, such as <code>com.example.ember-tools</code> || Required. Use 1–80 letters, digits, dots, underscores, or hyphens. Keep it unchanged between releases. The Modloader and other mods use this exact value to identify this package. | |||
|- | |||
| <code>name</code> || The name players should see, such as <code>Ember Tools</code> || Required. It must contain 1–120 characters. | |||
|- | |||
| <code>version</code> || This release's version, such as <code>1.2.0</code> || Required. Use a semantic version with three numeric parts: major, minor, and patch. A prerelease such as <code>1.2.0-beta.1</code> is also valid. Increase it when publishing a new release so dependencies and update tools can compare versions. | |||
|} | |||
== Optional information for players == <!--T:6--> | |||
<!--T:7--> | |||
{| class="wikitable" | |||
! Field !! Value to provide !! How it is used | |||
|- | |||
| <code>description</code> || A short plain-text summary, up to 2,000 characters || Helps players understand what the mod does. Keep it useful in the Modloader's mod details. | |||
|- | |||
| <code>authors</code> || An array of non-empty names, for example <code>["Alex", "Sam"]</code> || Credits the people who made the mod. Do not repeat the same name in the array. | |||
|- | |||
| <code>license</code> || A license name or identifier, for example <code>"MIT"</code>, or <code>null</code> || Tells users what terms apply to the mod. The schema accepts a string or <code>null</code>. It does not check that a string is a recognized SPDX license identifier, so choose a real license and state its terms in the package where appropriate. | |||
|- | |||
| <code>icon</code> || A package-root filename, a path under <code>assets/</code>, or <code>null</code> || Adds a small identifying image to the mod's details. See [[#Icon_files|Icon files]] for supported formats and limits. | |||
|- | |||
| <code>$schema</code> || The URL of the manifest schema || Helps editors provide validation and completion. For this release, use the versioned [https://shroudforge.net/schemas/1.8.0/manifest.schema.json manifest schema]. It does not replace the required manifest fields. | |||
|} | |||
=== Icon files === <!--T:8--> | |||
<!--T:9--> | |||
The <code>icon</code> value is the path to an image file that is included in the mod package. You can put the image directly beside <code>mod.json</code>, or place it in the package's <code>assets/</code> folder. The path uses forward slashes. | |||
<!--T:10--> | |||
The Modloader recognizes these filename extensions, without regard to letter case: | |||
<!--T:11--> | |||
* <code>.png</code> | |||
* <code>.jpg</code> and <code>.jpeg</code> | |||
* <code>.webp</code> | |||
* <code>.svg</code> | |||
<!--T:12--> | |||
For example, <code>"icon": "icon.png"</code> refers to <code>icon.png</code> beside <code>mod.json</code>. <code>"icon": "assets/ember-tools.svg"</code> refers to a file inside the package's <code>assets</code> folder. Use <code>"icon": null</code> when the mod has no icon. | |||
<!--T:13--> | |||
The file must be present in the installed package and must be no larger than 2 MiB. <code>.gif</code> is not supported. An unsupported extension, missing file, or oversized file makes the Modloader use its default icon. The manifest does not require a particular pixel size. A square image is a practical choice for a consistent appearance. | |||
== Dependencies == <!--T:14--> | |||
<!--T:15--> | |||
Use <code>dependencies</code> when your mod needs another installed mod to be available before it starts. Each list entry names the dependency's exact <code>id</code> from that mod's own <code>mod.json</code> and gives a semantic-version requirement. A dependency declaration helps the Modloader check availability and startup order. It does not download the other mod and does not replace Lua's normal module-loading rules. | |||
=== Dependency fields === <!--T:16--> | |||
<!--T:17--> | |||
{| class="wikitable" | |||
! Field !! Value to provide !! What happens | |||
|- | |||
| <code>id</code> || The exact, case-sensitive package ID from the other mod's <code>mod.json</code> || The Modloader looks for that installed mod. It accepts letters, digits, dots, underscores, and hyphens, up to 80 characters. | |||
|- | |||
| <code>version</code> || A semantic-version requirement, such as <code>"^1.2.0"</code> or <code>">=1.2.0, <2.0.0"</code> || The dependency must have a version that matches this requirement. Use a real version range, not a placeholder such as <code>"example"</code>. | |||
|- | |||
| <code>optional</code> || <code>true</code> or <code>false</code> || Optional and defaults to <code>false</code>. A missing, disabled, or version-mismatched required dependency blocks this mod from starting. Setting <code>optional</code> to <code>true</code> means its absence does not block startup. | |||
|} | |||
=== Dependency example === <!--T:18--> | |||
<!--T:19--> | |||
<pre> | |||
"dependencies": [ | |||
{ | |||
"id": "com.example.shared-library", | |||
"version": "^1.2.0" | |||
}, | |||
{ | |||
"id": "com.example.optional-integration", | |||
"version": ">=2.0.0, <3.0.0", | |||
"optional": true | |||
} | |||
] | |||
</pre> | |||
<!--T:20--> | |||
The first dependency is required because <code>optional</code> is omitted. The second is optional. Include only dependencies your code actually needs. If you do not depend on another mod, use an empty list such as <code>"dependencies": []</code> or omit the field. | |||
== Capabilities == <!--T:21--> | |||
<!--T:22--> | |||
<code>capabilities</code> is an optional array that declares which protected ShroudForge features the package needs. Its accepted values are <code>patch</code>, <code>export</code>, <code>runtime</code>, and <code>runtime-register-dll</code>. Declare only capabilities used by your mod. Declaring one is a request, not proof that the operation is available or successful. The existing [[Modding: Capabilities|Modding: Capabilities article]] explains what each capability does, when a mod needs it, and what the loader checks. | |||
== A complete small example == <!--T:23--> | |||
<!--T:24--> | |||
This example has all three required fields, credits its authors, supplies an icon, requests the runtime capability, and has no mod dependencies. Make sure every referenced file is included in the package. | |||
<!--T:25--> | |||
<pre> | <pre> | ||
{ | { | ||
"$schema": "https://shroudforge.net/schemas/1.8.0/manifest.schema.json", | "$schema": "https://shroudforge.net/schemas/1.8.0/manifest.schema.json", | ||
"id": "example. | "id": "com.example.ember-tools", | ||
"name": " | "name": "Ember Tools", | ||
"version": "1.0.0", | "version": "1.0.0", | ||
"description": "Small quality-of-life tools for Enshrouded.", | |||
"authors": ["Your Name"], | "authors": ["Your Name"], | ||
"license": "MIT", | |||
"icon": "assets/ember-tools.png", | |||
"capabilities": ["runtime"], | "capabilities": ["runtime"], | ||
"dependencies": [] | "dependencies": [] | ||
| Line 33: | Line 132: | ||
</pre> | </pre> | ||
<!--T: | == Check the manifest before packaging == <!--T:26--> | ||
<!--T: | <!--T:27--> | ||
The [https://shroudforge.net/schemas/1.8.0/manifest.schema.json | Use a JSON-aware editor or the [https://shroudforge.net/tools/modding/mod-settings/ Mod Settings editor] to catch missing commas, misspelled fields, and invalid value types. The versioned [https://shroudforge.net/schemas/1.8.0/manifest.schema.json manifest schema] is the exact field contract. The manifest format does not define arbitrary extra fields. Do not depend on a loader's compatibility handling of unknown fields as a way to add mod settings. | ||
== Related pages == <!--T: | == Related pages == <!--T:28--> | ||
<!--T: | <!--T:29--> | ||
* [[Build your first mod]] | * [[Build your first mod]] shows a small package from start to finish. | ||
* [[extended.mod.json]] | * [[Extended.mod.json|<code>extended.mod.json</code>]] explains player-facing settings, actions, groups, links, and related metadata. | ||
* [[: | * [[Modding: Capabilities|Modding: Capabilities]] covers the four capability values in detail. | ||
* [https://shroudforge.net/schemas/ Browse the versioned manifest schemas]. | |||
* [https://shroudforge.net/schemas/ Browse versioned manifest schemas] | |||
</translate> | </translate> | ||
[[Category:Modding:Shroudforge]] | [[Category:Modding:Shroudforge]] | ||
Latest revision as of 16:02, 18 November 2026
Every ShroudForge mod package needs a file named mod.json in the package's top-level folder. The Modloader reads this file to identify the package, check its version and dependencies, and determine which capabilities it requests. It is the package manifest, not the place for player-facing settings. Put those in extended.mod.json.
Start with a valid file
mod.json uses JSON. Put field names and text values in double quotes, separate entries with commas, and do not add a comma after the last entry. The fields id, name, and version are required. The other fields are optional.
Required fields
| Field | Value to provide | Rules and purpose |
|---|---|---|
id |
A stable package identifier, such as com.example.ember-tools |
Required. Use 1–80 letters, digits, dots, underscores, or hyphens. Keep it unchanged between releases. The Modloader and other mods use this exact value to identify this package. |
name |
The name players should see, such as Ember Tools |
Required. It must contain 1–120 characters. |
version |
This release's version, such as 1.2.0 |
Required. Use a semantic version with three numeric parts: major, minor, and patch. A prerelease such as 1.2.0-beta.1 is also valid. Increase it when publishing a new release so dependencies and update tools can compare versions.
|
Optional information for players
| Field | Value to provide | How it is used |
|---|---|---|
description |
A short plain-text summary, up to 2,000 characters | Helps players understand what the mod does. Keep it useful in the Modloader's mod details. |
authors |
An array of non-empty names, for example ["Alex", "Sam"] |
Credits the people who made the mod. Do not repeat the same name in the array. |
license |
A license name or identifier, for example "MIT", or null |
Tells users what terms apply to the mod. The schema accepts a string or null. It does not check that a string is a recognized SPDX license identifier, so choose a real license and state its terms in the package where appropriate.
|
icon |
A package-root filename, a path under assets/, or null |
Adds a small identifying image to the mod's details. See Icon files for supported formats and limits. |
$schema |
The URL of the manifest schema | Helps editors provide validation and completion. For this release, use the versioned manifest schema. It does not replace the required manifest fields. |
Icon files
The icon value is the path to an image file that is included in the mod package. You can put the image directly beside mod.json, or place it in the package's assets/ folder. The path uses forward slashes.
The Modloader recognizes these filename extensions, without regard to letter case:
.png.jpgand.jpeg.webp.svg
For example, "icon": "icon.png" refers to icon.png beside mod.json. "icon": "assets/ember-tools.svg" refers to a file inside the package's assets folder. Use "icon": null when the mod has no icon.
The file must be present in the installed package and must be no larger than 2 MiB. .gif is not supported. An unsupported extension, missing file, or oversized file makes the Modloader use its default icon. The manifest does not require a particular pixel size. A square image is a practical choice for a consistent appearance.
Dependencies
Use dependencies when your mod needs another installed mod to be available before it starts. Each list entry names the dependency's exact id from that mod's own mod.json and gives a semantic-version requirement. A dependency declaration helps the Modloader check availability and startup order. It does not download the other mod and does not replace Lua's normal module-loading rules.
Dependency fields
| Field | Value to provide | What happens |
|---|---|---|
id |
The exact, case-sensitive package ID from the other mod's mod.json |
The Modloader looks for that installed mod. It accepts letters, digits, dots, underscores, and hyphens, up to 80 characters. |
version |
A semantic-version requirement, such as "^1.2.0" or ">=1.2.0, <2.0.0" |
The dependency must have a version that matches this requirement. Use a real version range, not a placeholder such as "example".
|
optional |
true or false |
Optional and defaults to false. A missing, disabled, or version-mismatched required dependency blocks this mod from starting. Setting optional to true means its absence does not block startup.
|
Dependency example
"dependencies": [
{
"id": "com.example.shared-library",
"version": "^1.2.0"
},
{
"id": "com.example.optional-integration",
"version": ">=2.0.0, <3.0.0",
"optional": true
}
]
The first dependency is required because optional is omitted. The second is optional. Include only dependencies your code actually needs. If you do not depend on another mod, use an empty list such as "dependencies": [] or omit the field.
Capabilities
capabilities is an optional array that declares which protected ShroudForge features the package needs. Its accepted values are patch, export, runtime, and runtime-register-dll. Declare only capabilities used by your mod. Declaring one is a request, not proof that the operation is available or successful. The existing Modding: Capabilities article explains what each capability does, when a mod needs it, and what the loader checks.
A complete small example
This example has all three required fields, credits its authors, supplies an icon, requests the runtime capability, and has no mod dependencies. Make sure every referenced file is included in the package.
{
"$schema": "https://shroudforge.net/schemas/1.8.0/manifest.schema.json",
"id": "com.example.ember-tools",
"name": "Ember Tools",
"version": "1.0.0",
"description": "Small quality-of-life tools for Enshrouded.",
"authors": ["Your Name"],
"license": "MIT",
"icon": "assets/ember-tools.png",
"capabilities": ["runtime"],
"dependencies": []
}
Check the manifest before packaging
Use a JSON-aware editor or the Mod Settings editor to catch missing commas, misspelled fields, and invalid value types. The versioned manifest schema is the exact field contract. The manifest format does not define arbitrary extra fields. Do not depend on a loader's compatibility handling of unknown fields as a way to add mod settings.
Related pages
- Build your first mod shows a small package from start to finish.
extended.mod.jsonexplains player-facing settings, actions, groups, links, and related metadata.- Modding: Capabilities covers the four capability values in detail.
- Browse the versioned manifest schemas.