Extended.mod.json: Difference between revisions
More actions
Bonsaibauer (talk | contribs) Marked this version for translation |
Bonsaibauer (talk | contribs) Add guidance and link for searchable large multi-select settings. |
||
| (One intermediate revision by the same user not shown) | |||
| Line 3: | Line 3: | ||
<!-- ShroudForge Modloader Wiki Post | <!-- ShroudForge Modloader Wiki Post | ||
title: extended.mod.json | title: extended.mod.json | ||
description: Configure mod | description: Configure player-facing mod settings, controls, groups, actions, links, input reservations, and presets. | ||
language: en-GB | language: en-GB | ||
creator: Bonsaibauer | creator: Bonsaibauer | ||
| Line 11: | Line 11: | ||
<!--T:1--> | <!--T:1--> | ||
<code>extended.mod.json</code> is | <code>extended.mod.json</code> is the ShroudForge extension file beside <code>mod.json</code>. Use it to define what players can configure in the Modloader, organize those controls, add buttons and links, and store whether the mod is enabled. It complements <code>mod.json</code>. It does not replace the package ID, version, dependencies, or capability declarations in that file. | ||
<!--T:2--> | |||
The basic flow is: you declare a setting and its starting value, the Modloader builds the matching control, the player changes it, and the Modloader saves the chosen value in <code>extended.mod.json</code>. Your Lua code reads the current value with the exact setting key, for example <code>shroudforge.settings.get("greeting", "Hello")</code>. A setting only affects gameplay when the mod's Lua code reads and uses it. | |||
<!--T:3--> | == Start with this small example == <!--T:3--> | ||
<!--T:4--> | |||
This is a valid starting point with one visible text setting. The <code>schemaVersion</code> and <code>enabled</code> fields are required. Other fields can be added as needed. | |||
<!--T:5--> | <!--T:5--> | ||
| Line 30: | Line 26: | ||
"$schema": "https://shroudforge.net/schemas/1.8.0/extended.mod.schema.json", | "$schema": "https://shroudforge.net/schemas/1.8.0/extended.mod.schema.json", | ||
"schemaVersion": 1, | "schemaVersion": 1, | ||
"enabled": | "enabled": true, | ||
"targets": ["client"], | "targets": ["client"], | ||
"settings": { | "settings": { | ||
| Line 36: | Line 32: | ||
"value": "Hello from my mod", | "value": "Hello from my mod", | ||
"label": "Greeting", | "label": "Greeting", | ||
"description": "Text shown by this mod.", | |||
"control": "text" | "control": "text" | ||
} | } | ||
| Line 42: | Line 39: | ||
{ | { | ||
"label": "Messages", | "label": "Messages", | ||
"description": "Text used by the mod.", | |||
"settings": ["greeting"] | "settings": ["greeting"] | ||
} | } | ||
| Line 49: | Line 47: | ||
<!--T:6--> | <!--T:6--> | ||
Here the setting key is <code>greeting</code>. The label is what the player sees. Lua still looks up the stable key <code>greeting</code>, not the label. Keep keys stable when you change the wording players see. | |||
<!--T:7--> | == Root fields == <!--T:7--> | ||
The [https://shroudforge.net/schemas/1.8.0/extended.mod.schema.json canonical | |||
<!--T:8--> | |||
These fields go at the top level of the JSON object. The schema rejects unknown top-level fields, so do not invent new root properties. | |||
<!--T:9--> | |||
{| class="wikitable" | |||
! Field !! Required? !! Accepted value and purpose | |||
|- | |||
| <code>$schema</code> || No || A string containing the versioned schema URL. It helps JSON editors validate and complete the file. It is not a replacement for <code>schemaVersion</code>. | |||
|- | |||
| <code>schemaVersion</code> || Yes || The number <code>1</code>. This describes the extension format version. It is a number, not an object and not the string <code>"1"</code>. | |||
|- | |||
| <code>enabled</code> || Yes || <code>true</code> or <code>false</code>. This is the mod's enabled state in the Modloader. Use a JSON boolean, without quotation marks. | |||
|- | |||
| <code>targets</code> || No || A non-empty array containing <code>"client"</code>, <code>"server"</code>, or both. It selects where the mod is loaded. It does not synchronize setting values or gameplay over a multiplayer connection. | |||
|- | |||
| <code>launcher</code> || No || <code>"EML"</code> or <code>"SF"</code>. Preserve this only when package provenance needs to be recorded. ShroudForge-authored packages should normally omit it. Use <code>"EML"</code> for an EML package that retains its original launcher identity. | |||
|- | |||
| <code>settings</code> || No || An object keyed by stable setting IDs. Each entry supplies a starting value and can include its label, control, limits, options, and update behavior. | |||
|- | |||
| <code>groups</code> || No || An array that arranges setting IDs and action buttons into named Modloader sections. | |||
|- | |||
| <code>links</code> || No || An object of supported link IDs and HTTPS URLs. The IDs must come from the list in [[#Links|Links]]. | |||
|- | |||
| <code>changelog</code> || No || An array of up to 50 short version notes, each 1–500 characters. | |||
|- | |||
| <code>inputReservations</code> || No || Declares when the game may need to ignore an input because your mod is using it. See [[#Input_reservations|Input reservations]]. | |||
|- | |||
| <code>presets</code> || No || Connects a choice setting to coordinated values for several other settings. See [[#Presets|Presets]]. | |||
|} | |||
=== Schema version and activation === <!--T:10--> | |||
<!--T:11--> | |||
Always write <code>"schemaVersion": 1</code> as a JSON number. The current extension schema requires both <code>schemaVersion</code> and <code>enabled</code>. The Modloader may supply a default for some older or incomplete data while reading it, but new package files should follow the schema exactly. | |||
== Targets and launcher == <!--T:12--> | |||
<!--T:13--> | |||
Use <code>targets</code> to say which process should load the mod. The accepted values are <code>"client"</code> and <code>"server"</code>. Provide at least one value, and do not repeat a value. | |||
<!--T:14--> | |||
ShroudForge packages default to the client when <code>targets</code> is omitted. Older EML packages without this field default to both client and server to preserve their previous behavior. State the target explicitly when the mod is intended for a dedicated server or for both processes. | |||
<!--T:15--> | |||
For example, a client-only mod can use <code>"targets": ["client"]</code>. A mod intended to load in both processes can use <code>"targets": ["client", "server"]</code>. This only controls where code loads. It does not replicate settings or mod actions between players and the server. | |||
<!--T:16--> | |||
The optional <code>launcher</code> field preserves package origin. Omit it for a normal ShroudForge-authored mod. An imported EML package can use <code>"launcher": "EML"</code> when its EML provenance should remain visible. The only accepted values are <code>"EML"</code> and <code>"SF"</code>. | |||
== Settings and controls == <!--T:17--> | |||
<!--T:18--> | |||
Settings are the main reason to add <code>extended.mod.json</code>. Each setting has a key that Lua uses, an initial <code>value</code>, and optional information that tells the Modloader how to display and validate it. Use the object form when authoring a setting. It makes the control and its limits explicit. | |||
=== Setting keys and values === <!--T:19--> | |||
<!--T:20--> | |||
<code>settings</code> is a JSON object. Its property names are setting keys. A key must contain 1–80 letters, digits, dots, underscores, or hyphens. The key is used in Lua, conditions, groups, input reservations, and presets, so treat it like a stable program identifier. For example, use <code>showHints</code> in the file and keep reading that same key from Lua even if its player-facing label later changes. | |||
<!--T:21--> | |||
Every setting object must have a <code>value</code>. It must be a JSON boolean, string, number, or array. Do not use <code>null</code>. Choose a value type that matches the control and the kind of data your Lua code expects. | |||
<!--T:22--> | |||
The Modloader can also read a bare boolean, string, number, or array as a shorthand setting value. That form cannot carry the setting's label, description, control, or other rules. For a package other modders and players need to understand, use the object form. | |||
<!--T:23--> | |||
{| class="wikitable" | |||
! Setting field !! Accepted value !! What it is for | |||
|- | |||
| <code>value</code> || Boolean, string, number, or array || Required starting value and value type for this setting. An array must have <code>options</code>. | |||
|- | |||
| <code>label</code> || Non-empty string, up to 120 characters || Human-readable name shown to players. If omitted, the Modloader derives a display label from the key, but an explicit label is easier to understand. | |||
|- | |||
| <code>description</code> || String, up to 500 characters || A short explanation of what this setting changes. Describe the effect in player terms. | |||
|- | |||
| <code>control</code> || One of the 12 values in [[#Setting_controls|Setting controls]] || Chooses the control shown in the Modloader. Its value must fit the control, for example a boolean for a toggle or a list for a multi-select. | |||
|- | |||
| <code>min</code> and <code>max</code> || Numbers || Lower and upper bounds for a numeric setting. The minimum cannot be greater than the maximum. | |||
|- | |||
| <code>step</code> || Number greater than zero || Suggested increment for a numeric control. For example, a step of <code>5</code> makes a slider move in increments of five. | |||
|- | |||
| <code>minLength</code> and <code>maxLength</code> || Whole numbers greater than or equal to zero || Minimum and maximum text length for a string value. | |||
|- | |||
| <code>options</code> || Non-empty object of option keys and labels || Defines the allowed choices for <code>select</code>, <code>radio</code>, <code>segmented</code>, and <code>multiselect</code> controls. | |||
|- | |||
| <code>enabledWhen</code> || Object with a setting key and an equal value || Makes this control available only when another setting has the specified value. See [[#Conditional_settings|Conditional settings]]. | |||
|- | |||
| <code>applyAt</code> || <code>"live"</code> or <code>"restart"</code> || Says when a changed value can take effect. If omitted, the Modloader infers this from the mod's Lua APIs. Set it explicitly when you know the correct behavior. Mark a setting live only when your mod can safely use the changed value without restarting. | |||
|- | |||
| <code>restartRequired</code> || <code>true</code> or <code>false</code> || Older or simpler form of the same timing choice. If you provide both fields, they must agree: <code>true</code> means restart and <code>false</code> means live. | |||
|- | |||
| <code>assetPreparation</code> || <code>true</code> or <code>false</code> || Accepted and stored as setting metadata. The current settings reader has no user-visible behavior documented for this flag, so leave it out unless the ShroudForge version you target documents a specific use. | |||
|} | |||
=== How Lua receives a setting === <!--T:24--> | |||
<!--T:25--> | |||
The JSON setting key and the key in your Lua call must match exactly. With the example key <code>greeting</code>, Lua can call <code>shroudforge.settings.get("greeting", "Hello")</code>. The fallback value is useful if the setting is unavailable. Read settings through the ShroudForge API instead of parsing <code>extended.mod.json</code> yourself. | |||
<!--T:26--> | |||
For a live setting, your code must read the current value when it needs it or subscribe to the relevant update behavior. Reading a value once during startup does not make later player edits affect a Lua variable you copied earlier. If a change can only be applied during mod initialization or asset preparation, use <code>"applyAt": "restart"</code> so the Modloader can tell the player that a restart is needed. When both timing fields are omitted, the loader infers a live schedule for recognized runtime-only code and a restart schedule otherwise. | |||
=== Setting controls === <!--T:27--> | |||
<!--T:28--> | |||
The control determines what the player sees. Use a matching JSON value type and provide <code>options</code> for every choice control. | |||
<!--T:29--> | |||
{| class="wikitable" | |||
! Control !! Value type !! Use it for | |||
|- | |||
| <code>toggle</code> || Boolean || A compact on/off switch for a setting. | |||
|- | |||
| <code>checkbox</code> || Boolean || A checkable on/off choice. It represents the same basic true/false kind of value as a toggle. | |||
|- | |||
| <code>text</code> || String || A short, single-line text value. | |||
|- | |||
| <code>textarea</code> || String || Longer or multi-line text. | |||
|- | |||
| <code>number</code> || Number || A numeric value entered directly. Add <code>min</code>, <code>max</code>, and, if useful, <code>step</code> to constrain it. | |||
|- | |||
| <code>slider</code> || Number || A value selected along a numeric range. Give it useful <code>min</code>, <code>max</code>, and optionally <code>step</code> bounds. | |||
|- | |||
| <code>select</code> || One option value || A compact menu where the player chooses one option. | |||
|- | |||
| <code>radio</code> || One option value || A visible list of mutually exclusive choices. | |||
|- | |||
| <code>segmented</code> || One option value || A compact row of mutually exclusive choices, best for a small number of short options. | |||
|- | |||
| <code>multiselect</code> || Array of option values || A list where the player may choose more than one option. The initial value is an array, even if it contains only one choice. | |||
|- | |||
| <code>keybind</code> || Shortcut string || A keyboard shortcut, mouse button, or keyboard and mouse alternative. Leave the value empty to make the shortcut unassigned. | |||
|- | |||
| <code>color</code> || String || A color selected with the Modloader's color input. Use a six-digit hexadecimal value such as <code>"#d0ae6d"</code>. | |||
|} | |||
=== Keybind value format === <!--T:30--> | |||
<!--T:31--> | |||
Keyboard keys use an SDL scancode such as <code>SDL:44</code>. Mouse buttons use <code>Mouse:1</code> through <code>Mouse:99</code>. A keyboard scancode can be from <code>SDL:1</code> through <code>SDL:999</code>. Prefix a chord with modifiers in this order when needed: <code>Ctrl</code>, <code>Alt</code>, <code>Shift</code>, then <code>Meta</code>. For example, <code>"Ctrl+Shift+SDL:44"</code>. | |||
<!--T:32--> | |||
To offer a keyboard and mouse alternative, put one keyboard chord first, then a vertical bar, then one mouse chord, for example <code>"SDL:44|Mouse:1"</code>. A mouse-only shortcut such as <code>"Alt+Mouse:2"</code> is also valid. Use the empty string <code>""</code> when no shortcut should be assigned. The complete string can be at most 96 characters. | |||
=== Numeric and text limits === <!--T:33--> | |||
<!--T:34--> | |||
For numeric settings, <code>min</code> and <code>max</code> describe the allowed range. For example, a volume value could start at <code>0.5</code>, have a minimum of <code>0</code>, a maximum of <code>1</code>, and a step of <code>0.1</code>. Set limits that your Lua code can actually handle. | |||
<!--T:35--> | |||
For strings, <code>minLength</code> and <code>maxLength</code> describe how many characters the value may contain. These are different from numeric <code>min</code> and <code>max</code>. Add only limits that your mod needs. | |||
=== Choice options === <!--T:36--> | |||
<!--T:37--> | |||
Write option keys as JSON object keys and use their labels for display text. The key is the value stored by the control. The label is what players read. Keep keys stable and make labels understandable without requiring players to know your Lua code. | |||
<!--T:38--> | |||
<pre> | |||
"settings": { | |||
"messageStyle": { | |||
"value": "short", | |||
"label": "Message style", | |||
"control": "select", | |||
"options": { | |||
"short": "Short messages", | |||
"detailed": "Detailed messages" | |||
} | |||
} | |||
} | |||
</pre> | |||
<!--T:39--> | |||
Each setting needs at least one option. Option labels must contain 1–120 characters. An option can instead use an object with a required <code>label</code> and an optional <code>group</code> label of 1–60 characters. Groups help organize a long choice list. | |||
<!--T:40--> | |||
Option keys are converted to the setting's value type. For a string setting, the option key remains a string. For a boolean setting, use keys <code>"true"</code> and <code>"false"</code>. For a numeric setting, use numeric text such as <code>"1"</code> and <code>"2"</code>. The initial value must match one of the available choices. | |||
=== Large multi-select lists === <!--T:41--> | |||
<!--T:42--> | |||
Use <code>multiselect</code> when players can choose several entries from one setting. Its <code>value</code> remains an array and <code>options</code> defines the available choices. When there are more than 12 choices, the Modloader adds search controls automatically. You can group choices with each option's <code>group</code> and put the setting group on its own tab with <code>"tab": true</code>. For a complete example, localization details, and compatibility notes, see [[Search and organize large mod settings]]. | |||
=== Conditional settings === <!--T:43--> | |||
<!--T:44--> | |||
Use <code>enabledWhen</code> to disable or enable a control based on another setting. Its <code>setting</code> is the other setting's key and <code>equals</code> is the value that turns this setting on. The comparison value must have the same type as the other setting. If the other setting has options, the value must be one of them. | |||
<!--T:45--> | |||
<pre> | |||
"settings": { | |||
"showHints": { | |||
"value": true, | |||
"label": "Show hints", | |||
"control": "toggle" | |||
}, | |||
"hintDelay": { | |||
"value": 3, | |||
"label": "Hint delay in seconds", | |||
"control": "number", | |||
"min": 0, | |||
"max": 30, | |||
"enabledWhen": { | |||
"setting": "showHints", | |||
"equals": true | |||
} | |||
} | |||
} | |||
</pre> | |||
<!--T:46--> | |||
The referenced setting must exist. A setting cannot depend on itself, and conditional settings cannot form a cycle. An array cannot be used as the value in <code>equals</code>. | |||
== Groups and actions == <!--T:47--> | |||
<!--T:48--> | |||
Use <code>groups</code> to make a long settings page easier to scan. Each group can contain settings, action buttons, or both. A setting can appear in at most one group. Any setting you do not list still appears in the Modloader's default group. | |||
=== Group fields === <!--T:49--> | |||
<!--T:50--> | |||
{| class="wikitable" | |||
! Field !! Accepted value !! What it changes | |||
|- | |||
| <code>label</code> || Required non-empty string, up to 120 characters || Name shown for the group. Use a short label that tells players what the settings in it have in common. | |||
|- | |||
| <code>description</code> || Optional string, up to 500 characters || Explains the purpose of the group. | |||
|- | |||
| <code>settings</code> || Optional array of unique setting keys || Places the referenced settings in this group. Every key must exist in <code>settings</code> and cannot be placed in another group too. | |||
|- | |||
| <code>actions</code> || Optional array of action objects || Adds buttons to the group. See [[#Action_fields|Action fields]]. | |||
|- | |||
| <code>tab</code> || Optional boolean || Requests that this group be shown as its own tab. Omit it when ordinary grouping is enough. | |||
|} | |||
=== Action fields === <!--T:51--> | |||
<!--T:52--> | |||
{| class="wikitable" | |||
! Field !! Accepted value !! What it changes | |||
|- | |||
| <code>id</code> || Required identifier, 1–80 letters, digits, dots, underscores, or hyphens || Connects the button to your Lua action handler. This exact ID must match the ID passed to <code>shroudforge.ui.on_action</code>. | |||
|- | |||
| <code>label</code> || Required non-empty string, up to 120 characters || Text shown on the button. Name the action clearly, for example <code>"Reset progress"</code>. | |||
|- | |||
| <code>style</code> || <code>"primary"</code>, <code>"secondary"</code>, or <code>"danger"</code> || Visual emphasis. Use <code>danger</code> for an action with a destructive or hard-to-reverse effect. | |||
|- | |||
| <code>confirm</code> || Optional confirmation text, up to 500 characters || Asks the player to confirm before the action runs. Explain the consequence, especially for destructive actions. | |||
|} | |||
=== Connect a button to Lua === <!--T:53--> | |||
<!--T:54--> | |||
An action declaration only creates the button. Your mod's Lua code must register a handler for the same action ID. UI actions use the ShroudForge runtime, so a mod that uses them must request the <code>runtime</code> capability in its <code>mod.json</code>. See [[Modding: Capabilities|Modding: Capabilities]] for the capability rules. | |||
== Links == <!--T:55--> | |||
<!--T:56--> | |||
Use <code>links</code> to add useful destinations to the mod's details. The key must be one of the exact supported IDs below, and its value must be an HTTPS URL no longer than 2,048 characters. An ID that looks reasonable but is not registered is rejected by the Modloader. | |||
<!--T:57--> | |||
{| class="wikitable" | |||
! ID !! Destination | |||
|- | |||
| <code>source</code> || General source-code or project source page. | |||
|- | |||
| <code>source-github</code> || Source repository hosted on GitHub. | |||
|- | |||
| <code>source-gitlab</code> || Source repository hosted on GitLab. | |||
|- | |||
| <code>source-codeberg</code> || Source repository hosted on Codeberg. | |||
|- | |||
| <code>issues</code> || Bug reports or issue tracker. | |||
|- | |||
| <code>wiki</code> || Documentation or wiki for the mod. | |||
|- | |||
| <code>website</code> || The mod's website. | |||
|- | |||
| <code>store</code> || Store or download page. | |||
|- | |||
| <code>community-discord</code> || Discord community or support server. | |||
|- | |||
| <code>video-youtube</code> || Related YouTube channel or video page. | |||
|- | |||
| <code>support-bmac</code> || Buy Me a Coffee support page. | |||
|- | |||
| <code>support-patreon</code> || Patreon support page. | |||
|- | |||
| <code>support-paypal</code> || PayPal support page. | |||
|- | |||
| <code>support-github</code> || GitHub Sponsors support page. | |||
|- | |||
| <code>support-ko-fi</code> || Ko-fi support page. | |||
|- | |||
| <code>support-open-collective</code> || Open Collective support page. | |||
|- | |||
| <code>support-other</code> || Another support destination. | |||
|} | |||
<!--T:58--> | |||
For example, use <code>"source-github": "https://github.com/example/ember-tools"</code>. Do not use <code>http://</code>, a bare domain, or an invented link key. | |||
== Input reservations == <!--T:59--> | |||
<!--T:60--> | |||
An input reservation tells the game when one of your mod's controls is using a key or mouse input, so the game can avoid handling the same input at the same time. It does not assign a shortcut by itself. Declare the setting as a <code>keybind</code>, define a named context, then refer to that context from <code>inputReservations</code>. | |||
<!--T:61--> | |||
The main parts are: | |||
<!--T:62--> | |||
* <code>contexts</code> maps a stable context key to a player-readable label. Context keys use 1–80 letters, digits, dots, underscores, or hyphens. Labels contain 1–120 characters. | |||
* <code>keys</code> maps a keybind setting to the context in which the game may need to ignore it. Each entry needs <code>when</code>, which names a declared context. Optional <code>keyboard</code> and <code>mouse</code> booleans say which input sources are involved. | |||
* <code>wheels</code> maps a boolean setting to a declared context when a mod needs the mouse wheel reserved. | |||
* <code>choices</code> stores the player's keyboard and mouse padlock choices. The Modloader writes this data. Do not include player-specific choices as package defaults. | |||
<!--T:63--> | |||
For this feature to have an effect, the mod must report when one of its contexts is active through the ShroudForge input-reservation API. A ShroudForge version without input-reservation support ignores this block. Check that the exact setting keys and context IDs match throughout the file. | |||
== Presets == <!--T:64--> | |||
<!--T:65--> | |||
Presets let one choice control a coordinated set of settings. For example, a player can choose a quality preset and have the mod update range and detail together. The preset object is keyed by its controller setting. The controller must be a string choice using <code>select</code>, <code>radio</code>, or <code>segmented</code>. | |||
<!--T:66--> | |||
<pre> | |||
"settings": { | |||
"quality": { | |||
"value": "medium", | |||
"label": "Quality preset", | |||
"control": "select", | |||
"options": { | |||
"low": "Low", | |||
"medium": "Medium", | |||
"high": "High", | |||
"custom": "Custom" | |||
} | |||
}, | |||
"range": { | |||
"value": 128, | |||
"label": "View range", | |||
"control": "number", | |||
"min": 32, | |||
"max": 512 | |||
} | |||
}, | |||
"presets": { | |||
"quality": { | |||
"custom": "custom", | |||
"settings": ["range"], | |||
"values": { | |||
"low": { "range": 64 }, | |||
"medium": { "range": 128 }, | |||
"high": { "range": 256 } | |||
} | |||
} | |||
} | |||
</pre> | |||
<!--T:67--> | |||
The <code>custom</code> option defaults to the string <code>"custom"</code> and must exist among the controller's options. Every other controller option needs a value map for every setting named by <code>settings</code>. Values must match the declared setting types and limits. Do not list the controller itself, a keybind setting, or another preset controller in the preset's settings. A setting can belong to only one preset. | |||
<!--T:68--> | |||
When a player selects a preset, the Modloader applies its values to the listed settings. When the player edits one of those settings manually, the controller changes to the custom choice. This keeps the displayed preset from claiming a configuration that the player has already adjusted. | |||
== Changelog == <!--T:69--> | |||
<!--T:70--> | |||
The optional <code>changelog</code> is a list of short version notes shown with the mod's details. It accepts at most 50 strings. Each note must contain 1–500 characters. Keep entries concise and use one string per change or release note. | |||
<!--T:71--> | |||
<pre> | |||
"changelog": [ | |||
"1.2.0: Added a configurable hint delay.", | |||
"1.1.1: Fixed the saved message style." | |||
] | |||
</pre> | |||
== Validate the file == <!--T:72--> | |||
<!--T:73--> | |||
The [https://shroudforge.net/schemas/1.8.0/extended.mod.schema.json canonical extension schema] defines accepted field names, JSON types, and basic limits. The Modloader also checks relationships that a JSON schema cannot fully describe, such as whether a group refers to an existing setting, whether a link ID is supported, whether a preset is complete, and whether input-reservation contexts exist. | |||
<!--T:74--> | |||
Use the [https://shroudforge.net/tools/modding/mod-settings/ Mod Settings editor] to build a sample and preview its controls. Before packaging, check that: | |||
<!--T:75--> | |||
* The JSON is valid and includes <code>"schemaVersion": 1</code> and a boolean <code>enabled</code>. | |||
* Every setting has a value of the right type. Array settings have options. | |||
* Choice controls have options, and their starting value is one of those options. | |||
* Setting keys, group references, action IDs, preset references, and input-reservation references match exactly. | |||
* Link IDs come from the supported list and every URL uses HTTPS. | |||
* <code>applyAt</code> and <code>restartRequired</code> agree if both are present. | |||
== Related pages == <!--T:76--> | |||
<!--T:77--> | |||
* [[Mod.json]] describes package identity, dependencies, icon metadata, and requested capabilities. | |||
* [[Build your first mod]] walks through a complete small package. | |||
* [[Modding: Capabilities|Modding: Capabilities]] explains the capabilities needed by runtime actions. | |||
* [https://shroudforge.net/schemas/ Browse the versioned manifest schemas]. | |||
* [https://shroudforge.net/tools/modding/mod-settings/ Open the Mod Settings editor]. | |||
</translate> | </translate> | ||
Latest revision as of 16:15, 18 November 2026
extended.mod.json is the ShroudForge extension file beside mod.json. Use it to define what players can configure in the Modloader, organize those controls, add buttons and links, and store whether the mod is enabled. It complements mod.json. It does not replace the package ID, version, dependencies, or capability declarations in that file.
The basic flow is: you declare a setting and its starting value, the Modloader builds the matching control, the player changes it, and the Modloader saves the chosen value in extended.mod.json. Your Lua code reads the current value with the exact setting key, for example shroudforge.settings.get("greeting", "Hello"). A setting only affects gameplay when the mod's Lua code reads and uses it.
Start with this small example
This is a valid starting point with one visible text setting. The schemaVersion and enabled fields are required. Other fields can be added as needed.
{
"$schema": "https://shroudforge.net/schemas/1.8.0/extended.mod.schema.json",
"schemaVersion": 1,
"enabled": true,
"targets": ["client"],
"settings": {
"greeting": {
"value": "Hello from my mod",
"label": "Greeting",
"description": "Text shown by this mod.",
"control": "text"
}
},
"groups": [
{
"label": "Messages",
"description": "Text used by the mod.",
"settings": ["greeting"]
}
]
}
Here the setting key is greeting. The label is what the player sees. Lua still looks up the stable key greeting, not the label. Keep keys stable when you change the wording players see.
Root fields
These fields go at the top level of the JSON object. The schema rejects unknown top-level fields, so do not invent new root properties.
| Field | Required? | Accepted value and purpose |
|---|---|---|
$schema |
No | A string containing the versioned schema URL. It helps JSON editors validate and complete the file. It is not a replacement for schemaVersion.
|
schemaVersion |
Yes | The number 1. This describes the extension format version. It is a number, not an object and not the string "1".
|
enabled |
Yes | true or false. This is the mod's enabled state in the Modloader. Use a JSON boolean, without quotation marks.
|
targets |
No | A non-empty array containing "client", "server", or both. It selects where the mod is loaded. It does not synchronize setting values or gameplay over a multiplayer connection.
|
launcher |
No | "EML" or "SF". Preserve this only when package provenance needs to be recorded. ShroudForge-authored packages should normally omit it. Use "EML" for an EML package that retains its original launcher identity.
|
settings |
No | An object keyed by stable setting IDs. Each entry supplies a starting value and can include its label, control, limits, options, and update behavior. |
groups |
No | An array that arranges setting IDs and action buttons into named Modloader sections. |
links |
No | An object of supported link IDs and HTTPS URLs. The IDs must come from the list in Links. |
changelog |
No | An array of up to 50 short version notes, each 1–500 characters. |
inputReservations |
No | Declares when the game may need to ignore an input because your mod is using it. See Input reservations. |
presets |
No | Connects a choice setting to coordinated values for several other settings. See Presets. |
Schema version and activation
Always write "schemaVersion": 1 as a JSON number. The current extension schema requires both schemaVersion and enabled. The Modloader may supply a default for some older or incomplete data while reading it, but new package files should follow the schema exactly.
Targets and launcher
Use targets to say which process should load the mod. The accepted values are "client" and "server". Provide at least one value, and do not repeat a value.
ShroudForge packages default to the client when targets is omitted. Older EML packages without this field default to both client and server to preserve their previous behavior. State the target explicitly when the mod is intended for a dedicated server or for both processes.
For example, a client-only mod can use "targets": ["client"]. A mod intended to load in both processes can use "targets": ["client", "server"]. This only controls where code loads. It does not replicate settings or mod actions between players and the server.
The optional launcher field preserves package origin. Omit it for a normal ShroudForge-authored mod. An imported EML package can use "launcher": "EML" when its EML provenance should remain visible. The only accepted values are "EML" and "SF".
Settings and controls
Settings are the main reason to add extended.mod.json. Each setting has a key that Lua uses, an initial value, and optional information that tells the Modloader how to display and validate it. Use the object form when authoring a setting. It makes the control and its limits explicit.
Setting keys and values
settings is a JSON object. Its property names are setting keys. A key must contain 1–80 letters, digits, dots, underscores, or hyphens. The key is used in Lua, conditions, groups, input reservations, and presets, so treat it like a stable program identifier. For example, use showHints in the file and keep reading that same key from Lua even if its player-facing label later changes.
Every setting object must have a value. It must be a JSON boolean, string, number, or array. Do not use null. Choose a value type that matches the control and the kind of data your Lua code expects.
The Modloader can also read a bare boolean, string, number, or array as a shorthand setting value. That form cannot carry the setting's label, description, control, or other rules. For a package other modders and players need to understand, use the object form.
| Setting field | Accepted value | What it is for |
|---|---|---|
value |
Boolean, string, number, or array | Required starting value and value type for this setting. An array must have options.
|
label |
Non-empty string, up to 120 characters | Human-readable name shown to players. If omitted, the Modloader derives a display label from the key, but an explicit label is easier to understand. |
description |
String, up to 500 characters | A short explanation of what this setting changes. Describe the effect in player terms. |
control |
One of the 12 values in Setting controls | Chooses the control shown in the Modloader. Its value must fit the control, for example a boolean for a toggle or a list for a multi-select. |
min and max |
Numbers | Lower and upper bounds for a numeric setting. The minimum cannot be greater than the maximum. |
step |
Number greater than zero | Suggested increment for a numeric control. For example, a step of 5 makes a slider move in increments of five.
|
minLength and maxLength |
Whole numbers greater than or equal to zero | Minimum and maximum text length for a string value. |
options |
Non-empty object of option keys and labels | Defines the allowed choices for select, radio, segmented, and multiselect controls.
|
enabledWhen |
Object with a setting key and an equal value | Makes this control available only when another setting has the specified value. See Conditional settings. |
applyAt |
"live" or "restart" |
Says when a changed value can take effect. If omitted, the Modloader infers this from the mod's Lua APIs. Set it explicitly when you know the correct behavior. Mark a setting live only when your mod can safely use the changed value without restarting. |
restartRequired |
true or false |
Older or simpler form of the same timing choice. If you provide both fields, they must agree: true means restart and false means live.
|
assetPreparation |
true or false |
Accepted and stored as setting metadata. The current settings reader has no user-visible behavior documented for this flag, so leave it out unless the ShroudForge version you target documents a specific use. |
How Lua receives a setting
The JSON setting key and the key in your Lua call must match exactly. With the example key greeting, Lua can call shroudforge.settings.get("greeting", "Hello"). The fallback value is useful if the setting is unavailable. Read settings through the ShroudForge API instead of parsing extended.mod.json yourself.
For a live setting, your code must read the current value when it needs it or subscribe to the relevant update behavior. Reading a value once during startup does not make later player edits affect a Lua variable you copied earlier. If a change can only be applied during mod initialization or asset preparation, use "applyAt": "restart" so the Modloader can tell the player that a restart is needed. When both timing fields are omitted, the loader infers a live schedule for recognized runtime-only code and a restart schedule otherwise.
Setting controls
The control determines what the player sees. Use a matching JSON value type and provide options for every choice control.
| Control | Value type | Use it for |
|---|---|---|
toggle |
Boolean | A compact on/off switch for a setting. |
checkbox |
Boolean | A checkable on/off choice. It represents the same basic true/false kind of value as a toggle. |
text |
String | A short, single-line text value. |
textarea |
String | Longer or multi-line text. |
number |
Number | A numeric value entered directly. Add min, max, and, if useful, step to constrain it.
|
slider |
Number | A value selected along a numeric range. Give it useful min, max, and optionally step bounds.
|
select |
One option value | A compact menu where the player chooses one option. |
radio |
One option value | A visible list of mutually exclusive choices. |
segmented |
One option value | A compact row of mutually exclusive choices, best for a small number of short options. |
multiselect |
Array of option values | A list where the player may choose more than one option. The initial value is an array, even if it contains only one choice. |
keybind |
Shortcut string | A keyboard shortcut, mouse button, or keyboard and mouse alternative. Leave the value empty to make the shortcut unassigned. |
color |
String | A color selected with the Modloader's color input. Use a six-digit hexadecimal value such as "#d0ae6d".
|
Keybind value format
Keyboard keys use an SDL scancode such as SDL:44. Mouse buttons use Mouse:1 through Mouse:99. A keyboard scancode can be from SDL:1 through SDL:999. Prefix a chord with modifiers in this order when needed: Ctrl, Alt, Shift, then Meta. For example, "Ctrl+Shift+SDL:44".
To offer a keyboard and mouse alternative, put one keyboard chord first, then a vertical bar, then one mouse chord, for example "SDL:44|Mouse:1". A mouse-only shortcut such as "Alt+Mouse:2" is also valid. Use the empty string "" when no shortcut should be assigned. The complete string can be at most 96 characters.
Numeric and text limits
For numeric settings, min and max describe the allowed range. For example, a volume value could start at 0.5, have a minimum of 0, a maximum of 1, and a step of 0.1. Set limits that your Lua code can actually handle.
For strings, minLength and maxLength describe how many characters the value may contain. These are different from numeric min and max. Add only limits that your mod needs.
Choice options
Write option keys as JSON object keys and use their labels for display text. The key is the value stored by the control. The label is what players read. Keep keys stable and make labels understandable without requiring players to know your Lua code.
"settings": {
"messageStyle": {
"value": "short",
"label": "Message style",
"control": "select",
"options": {
"short": "Short messages",
"detailed": "Detailed messages"
}
}
}
Each setting needs at least one option. Option labels must contain 1–120 characters. An option can instead use an object with a required label and an optional group label of 1–60 characters. Groups help organize a long choice list.
Option keys are converted to the setting's value type. For a string setting, the option key remains a string. For a boolean setting, use keys "true" and "false". For a numeric setting, use numeric text such as "1" and "2". The initial value must match one of the available choices.
Large multi-select lists
Use multiselect when players can choose several entries from one setting. Its value remains an array and options defines the available choices. When there are more than 12 choices, the Modloader adds search controls automatically. You can group choices with each option's group and put the setting group on its own tab with "tab": true. For a complete example, localization details, and compatibility notes, see Search and organize large mod settings.
Conditional settings
Use enabledWhen to disable or enable a control based on another setting. Its setting is the other setting's key and equals is the value that turns this setting on. The comparison value must have the same type as the other setting. If the other setting has options, the value must be one of them.
"settings": {
"showHints": {
"value": true,
"label": "Show hints",
"control": "toggle"
},
"hintDelay": {
"value": 3,
"label": "Hint delay in seconds",
"control": "number",
"min": 0,
"max": 30,
"enabledWhen": {
"setting": "showHints",
"equals": true
}
}
}
The referenced setting must exist. A setting cannot depend on itself, and conditional settings cannot form a cycle. An array cannot be used as the value in equals.
Groups and actions
Use groups to make a long settings page easier to scan. Each group can contain settings, action buttons, or both. A setting can appear in at most one group. Any setting you do not list still appears in the Modloader's default group.
Group fields
| Field | Accepted value | What it changes |
|---|---|---|
label |
Required non-empty string, up to 120 characters | Name shown for the group. Use a short label that tells players what the settings in it have in common. |
description |
Optional string, up to 500 characters | Explains the purpose of the group. |
settings |
Optional array of unique setting keys | Places the referenced settings in this group. Every key must exist in settings and cannot be placed in another group too.
|
actions |
Optional array of action objects | Adds buttons to the group. See Action fields. |
tab |
Optional boolean | Requests that this group be shown as its own tab. Omit it when ordinary grouping is enough. |
Action fields
| Field | Accepted value | What it changes |
|---|---|---|
id |
Required identifier, 1–80 letters, digits, dots, underscores, or hyphens | Connects the button to your Lua action handler. This exact ID must match the ID passed to shroudforge.ui.on_action.
|
label |
Required non-empty string, up to 120 characters | Text shown on the button. Name the action clearly, for example "Reset progress".
|
style |
"primary", "secondary", or "danger" |
Visual emphasis. Use danger for an action with a destructive or hard-to-reverse effect.
|
confirm |
Optional confirmation text, up to 500 characters | Asks the player to confirm before the action runs. Explain the consequence, especially for destructive actions. |
Connect a button to Lua
An action declaration only creates the button. Your mod's Lua code must register a handler for the same action ID. UI actions use the ShroudForge runtime, so a mod that uses them must request the runtime capability in its mod.json. See Modding: Capabilities for the capability rules.
Links
Use links to add useful destinations to the mod's details. The key must be one of the exact supported IDs below, and its value must be an HTTPS URL no longer than 2,048 characters. An ID that looks reasonable but is not registered is rejected by the Modloader.
| ID | Destination |
|---|---|
source |
General source-code or project source page. |
source-github |
Source repository hosted on GitHub. |
source-gitlab |
Source repository hosted on GitLab. |
source-codeberg |
Source repository hosted on Codeberg. |
issues |
Bug reports or issue tracker. |
wiki |
Documentation or wiki for the mod. |
website |
The mod's website. |
store |
Store or download page. |
community-discord |
Discord community or support server. |
video-youtube |
Related YouTube channel or video page. |
support-bmac |
Buy Me a Coffee support page. |
support-patreon |
Patreon support page. |
support-paypal |
PayPal support page. |
support-github |
GitHub Sponsors support page. |
support-ko-fi |
Ko-fi support page. |
support-open-collective |
Open Collective support page. |
support-other |
Another support destination. |
For example, use "source-github": "https://github.com/example/ember-tools". Do not use http://, a bare domain, or an invented link key.
Input reservations
An input reservation tells the game when one of your mod's controls is using a key or mouse input, so the game can avoid handling the same input at the same time. It does not assign a shortcut by itself. Declare the setting as a keybind, define a named context, then refer to that context from inputReservations.
The main parts are:
contextsmaps a stable context key to a player-readable label. Context keys use 1–80 letters, digits, dots, underscores, or hyphens. Labels contain 1–120 characters.keysmaps a keybind setting to the context in which the game may need to ignore it. Each entry needswhen, which names a declared context. Optionalkeyboardandmousebooleans say which input sources are involved.wheelsmaps a boolean setting to a declared context when a mod needs the mouse wheel reserved.choicesstores the player's keyboard and mouse padlock choices. The Modloader writes this data. Do not include player-specific choices as package defaults.
For this feature to have an effect, the mod must report when one of its contexts is active through the ShroudForge input-reservation API. A ShroudForge version without input-reservation support ignores this block. Check that the exact setting keys and context IDs match throughout the file.
Presets
Presets let one choice control a coordinated set of settings. For example, a player can choose a quality preset and have the mod update range and detail together. The preset object is keyed by its controller setting. The controller must be a string choice using select, radio, or segmented.
"settings": {
"quality": {
"value": "medium",
"label": "Quality preset",
"control": "select",
"options": {
"low": "Low",
"medium": "Medium",
"high": "High",
"custom": "Custom"
}
},
"range": {
"value": 128,
"label": "View range",
"control": "number",
"min": 32,
"max": 512
}
},
"presets": {
"quality": {
"custom": "custom",
"settings": ["range"],
"values": {
"low": { "range": 64 },
"medium": { "range": 128 },
"high": { "range": 256 }
}
}
}
The custom option defaults to the string "custom" and must exist among the controller's options. Every other controller option needs a value map for every setting named by settings. Values must match the declared setting types and limits. Do not list the controller itself, a keybind setting, or another preset controller in the preset's settings. A setting can belong to only one preset.
When a player selects a preset, the Modloader applies its values to the listed settings. When the player edits one of those settings manually, the controller changes to the custom choice. This keeps the displayed preset from claiming a configuration that the player has already adjusted.
Changelog
The optional changelog is a list of short version notes shown with the mod's details. It accepts at most 50 strings. Each note must contain 1–500 characters. Keep entries concise and use one string per change or release note.
"changelog": [ "1.2.0: Added a configurable hint delay.", "1.1.1: Fixed the saved message style." ]
Validate the file
The canonical extension schema defines accepted field names, JSON types, and basic limits. The Modloader also checks relationships that a JSON schema cannot fully describe, such as whether a group refers to an existing setting, whether a link ID is supported, whether a preset is complete, and whether input-reservation contexts exist.
Use the Mod Settings editor to build a sample and preview its controls. Before packaging, check that:
- The JSON is valid and includes
"schemaVersion": 1and a booleanenabled. - Every setting has a value of the right type. Array settings have options.
- Choice controls have options, and their starting value is one of those options.
- Setting keys, group references, action IDs, preset references, and input-reservation references match exactly.
- Link IDs come from the supported list and every URL uses HTTPS.
applyAtandrestartRequiredagree if both are present.
Related pages
- Mod.json describes package identity, dependencies, icon metadata, and requested capabilities.
- Build your first mod walks through a complete small package.
- Modding: Capabilities explains the capabilities needed by runtime actions.
- Browse the versioned manifest schemas.
- Open the Mod Settings editor.