Jump to content
Toggle menu
  • 64 articles
  • 37 files
  • 9 users
  • 4.6K edits
Shroudforge
Toggle preferences menu
Toggle personal menu
Not logged in
Your IP address will be publicly visible if you make any edits.

Extended.mod.json

From Shroudforge


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.

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:

  • contexts 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.
  • keys maps a keybind setting to the context in which the game may need to ignore it. Each entry needs when, which names a declared context. Optional keyboard and mouse booleans say which input sources are involved.
  • wheels maps a boolean setting to a declared context when a mod needs the mouse wheel reserved.
  • choices stores 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": 1 and a boolean enabled.
  • 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.
  • applyAt and restartRequired agree if both are present.