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.

Modloader settings: Difference between revisions

From Shroudforge
Publish English migration guide
 
Marked this version for translation
 
Line 10: Line 10:
<translate>
<translate>


<!--T:1-->
This guide covers settings for ShroudForge itself. It is separate from the player-facing settings that a mod declares in [[Extended.mod.json]]. The documented preferences are stored in <code>shroudforge/config/modloader-config.json</code> beside the game installation. The Modloader's Settings page is the easiest way to change them because it validates and saves each value for you.
This guide covers settings for ShroudForge itself. It is separate from the player-facing settings that a mod declares in [[Extended.mod.json]]. The documented preferences are stored in <code>shroudforge/config/modloader-config.json</code> beside the game installation. The Modloader's Settings page is the easiest way to change them because it validates and saves each value for you.


== Find and edit the configuration ==
== Find and edit the configuration == <!--T:2-->


<!--T:3-->
The file is inside the <code>shroudforge/config</code> folder beside the Enshrouded executable. For example, if the game is installed in <code>D:\Games\Enshrouded</code>, the file is <code>D:\Games\Enshrouded\shroudforge\config\modloader-config.json</code>.
The file is inside the <code>shroudforge/config</code> folder beside the Enshrouded executable. For example, if the game is installed in <code>D:\Games\Enshrouded</code>, the file is <code>D:\Games\Enshrouded\shroudforge\config\modloader-config.json</code>.


<!--T:4-->
Prefer the Modloader's Settings page for ordinary changes. If you edit the JSON file yourself, close the game and Modloader first, make a backup, preserve the rest of the file, and keep the JSON valid. JSON does not allow comments or a comma after the final item. The configuration contains internal state as well as user preferences, so do not replace the entire file with a short example.
Prefer the Modloader's Settings page for ordinary changes. If you edit the JSON file yourself, close the game and Modloader first, make a backup, preserve the rest of the file, and keep the JSON valid. JSON does not allow comments or a comma after the final item. The configuration contains internal state as well as user preferences, so do not replace the entire file with a short example.


<!--T:5-->
Settings use JSON values. A boolean is <code>true</code> or <code>false</code>. A string is in double quotes. A path can be a string or <code>null</code>. Use <code>null</code> to restore the automatic path for a storage location.
Settings use JSON values. A boolean is <code>true</code> or <code>false</code>. A string is in double quotes. A path can be a string or <code>null</code>. Use <code>null</code> to restore the automatic path for a storage location.


== General settings ==
== General settings == <!--T:6-->


<!--T:7-->
<span id="general-compactmode"></span>
<span id="general-compactmode"></span>
=== Compact Modloader layout: <code>general.compactMode</code> ===
=== Compact Modloader layout: <code>general.compactMode</code> ===


<!--T:8-->
This boolean controls whether the Modloader uses a denser layout. The shipped defaults leave it unset, which keeps the standard layout. Set it to <code>true</code> to use the compact layout or <code>false</code> to keep the standard layout.
This boolean controls whether the Modloader uses a denser layout. The shipped defaults leave it unset, which keeps the standard layout. Set it to <code>true</code> to use the compact layout or <code>false</code> to keep the standard layout.


<!--T:9-->
<pre>
<pre>
{
{
Line 35: Line 42:
</pre>
</pre>


<!--T:10-->
<span id="general-locale"></span>
<span id="general-locale"></span>
=== Interface language: <code>general.locale</code> ===
=== Interface language: <code>general.locale</code> ===


<!--T:11-->
This string selects the language used by the Modloader interface. The shipped default is <code>en-GB</code>. Choose a language in the Settings page when possible. The schema accepts language-tag-shaped values matching <code>^[A-Za-z0-9]+(-[A-Za-z0-9]+)*$</code>, but a value that matches the pattern is not necessarily a language supplied by the installed Modloader.
This string selects the language used by the Modloader interface. The shipped default is <code>en-GB</code>. Choose a language in the Settings page when possible. The schema accepts language-tag-shaped values matching <code>^[A-Za-z0-9]+(-[A-Za-z0-9]+)*$</code>, but a value that matches the pattern is not necessarily a language supplied by the installed Modloader.


<!--T:12-->
<pre>
<pre>
{
{
Line 48: Line 58:
</pre>
</pre>


<!--T:13-->
<span id="general-messagenamefallback"></span>
<span id="general-messagenamefallback"></span>
=== Fallback name for notices: <code>general.messageNameFallback</code> ===
=== Fallback name for notices: <code>general.messageNameFallback</code> ===


<!--T:14-->
This string is the name used in a notice when automatic character-name detection cannot supply one. It is also the name used when <code>general.usernameMode</code> is set to <code>manual</code>. The shipped default is <code>Flameborn</code>. The value must contain 1–40 characters. The Settings page trims surrounding whitespace and uses <code>Flameborn</code> if the field is left empty.
This string is the name used in a notice when automatic character-name detection cannot supply one. It is also the name used when <code>general.usernameMode</code> is set to <code>manual</code>. The shipped default is <code>Flameborn</code>. The value must contain 1–40 characters. The Settings page trims surrounding whitespace and uses <code>Flameborn</code> if the field is left empty.


<!--T:15-->
<pre>
<pre>
{
{
Line 61: Line 74:
</pre>
</pre>


<!--T:16-->
<span id="general-reducedmotion"></span>
<span id="general-reducedmotion"></span>
=== Reduce motion: <code>general.reducedMotion</code> ===
=== Reduce motion: <code>general.reducedMotion</code> ===


<!--T:17-->
This boolean reduces interface motion and transition effects. The shipped defaults leave the setting unset, so the normal interface motion is used. Set it to <code>true</code> to reduce motion or <code>false</code> to keep normal transitions.
This boolean reduces interface motion and transition effects. The shipped defaults leave the setting unset, so the normal interface motion is used. Set it to <code>true</code> to reduce motion or <code>false</code> to keep normal transitions.


<!--T:18-->
<span id="general-usernamemode"></span>
<span id="general-usernamemode"></span>
=== Choose how notices get a player name: <code>general.usernameMode</code> ===
=== Choose how notices get a player name: <code>general.usernameMode</code> ===


<!--T:19-->
This string accepts <code>"auto"</code> or <code>"manual"</code>. The shipped default is <code>"auto"</code>.
This string accepts <code>"auto"</code> or <code>"manual"</code>. The shipped default is <code>"auto"</code>.


<!--T:20-->
* <code>"auto"</code> uses the local character name captured by the current game process. ShroudForge captures it when a valid character is first available and again when the character selection or name changes. If capture fails, notices use <code>general.messageNameFallback</code>. A name cached by a previous game process is not restored.
* <code>"auto"</code> uses the local character name captured by the current game process. ShroudForge captures it when a valid character is first available and again when the character selection or name changes. If capture fails, notices use <code>general.messageNameFallback</code>. A name cached by a previous game process is not restored.
* <code>"manual"</code> always uses <code>general.messageNameFallback</code>.
* <code>"manual"</code> always uses <code>general.messageNameFallback</code>.


<!--T:21-->
This affects names shown in notices. It does not identify remote players or change a mod's own fallback text.
This affects names shown in notices. It does not identify remote players or change a mod's own fallback text.


<!--T:22-->
<pre>
<pre>
{
{
Line 84: Line 104:
</pre>
</pre>


== Logging ==
== Logging == <!--T:23-->


<!--T:24-->
<span id="logging-minimumlevel"></span>
<span id="logging-minimumlevel"></span>
=== Minimum saved log level: <code>logging.minimumLevel</code> ===
=== Minimum saved log level: <code>logging.minimumLevel</code> ===


<!--T:25-->
This string sets the lowest severity that ShroudForge writes to log files. The accepted values, from most detailed to most restrictive, are <code>TRACE</code>, <code>DEBUG</code>, <code>INFO</code>, <code>WARN</code>, and <code>ERROR</code>. The shipped default is <code>INFO</code>. Entries below the selected level are not saved to the regular log file.
This string sets the lowest severity that ShroudForge writes to log files. The accepted values, from most detailed to most restrictive, are <code>TRACE</code>, <code>DEBUG</code>, <code>INFO</code>, <code>WARN</code>, and <code>ERROR</code>. The shipped default is <code>INFO</code>. Entries below the selected level are not saved to the regular log file.


<!--T:26-->
The Debug Console has its own display filter. Changing that filter only changes which entries are shown in the console. It does not change what the log file saves. The saved-file threshold is the setting documented here.
The Debug Console has its own display filter. Changing that filter only changes which entries are shown in the console. It does not change what the log file saves. The saved-file threshold is the setting documented here.


<!--T:27-->
<pre>
<pre>
{
{
Line 101: Line 125:
</pre>
</pre>


== Export functions ==
== Export functions == <!--T:28-->


<!--T:29-->
<span id="exports-enabled"></span>
<span id="exports-enabled"></span>
=== Enable mod export functions: <code>exports.enabled</code> ===
=== Enable mod export functions: <code>exports.enabled</code> ===


<!--T:30-->
This boolean enables or disables mod export functions. The shipped default is <code>true</code>. Set it to <code>false</code> to disable those functions for the installation.
This boolean enables or disables mod export functions. The shipped default is <code>true</code>. Set it to <code>false</code> to disable those functions for the installation.


<!--T:31-->
<pre>
<pre>
{
{
Line 116: Line 143:
</pre>
</pre>


<!--T:32-->
This loader preference is different from the <code>export</code> capability requested by an individual mod in <code>mod.json</code>. A mod still has to declare and use the capability it needs. See [[Modding: Capabilities]].
This loader preference is different from the <code>export</code> capability requested by an individual mod in <code>mod.json</code>. A mod still has to declare and use the capability it needs. See [[Modding: Capabilities]].


== Module settings ==
== Module settings == <!--T:33-->


<!--T:34-->
<span id="module-settings"></span>
<span id="module-settings"></span>
The <code>modules</code> value is an object with separate sections for the built-in modules. There is no <code>modules.modules</code> option or shared module list. Each section is named for its owner. The shipped defaults currently contain these sections:
The <code>modules</code> value is an object with separate sections for the built-in modules. There is no <code>modules.modules</code> option or shared module list. Each section is named for its owner. The shipped defaults currently contain these sections:


<!--T:35-->
{| class="wikitable"
{| class="wikitable"
! Section !! What it configures
! Section !! What it configures
Line 147: Line 177:
|}
|}


<!--T:36-->
The exact fields and allowed values belong to the schema. Some saved fields are runtime state rather than preferences. For example, window positions and diagnostic request or session values are managed by ShroudForge. Do not copy those values into a mod's <code>extended.mod.json</code> or treat them as mod settings.
The exact fields and allowed values belong to the schema. Some saved fields are runtime state rather than preferences. For example, window positions and diagnostic request or session values are managed by ShroudForge. Do not copy those values into a mod's <code>extended.mod.json</code> or treat them as mod settings.


<!--T:37-->
<pre>
<pre>
{
{
Line 164: Line 196:
</pre>
</pre>


<!--T:38-->
This is a partial example. Keep other module sections and settings already present in the configuration.
This is a partial example. Keep other module sections and settings already present in the configuration.


== Storage paths ==
== Storage paths == <!--T:39-->


<!--T:40-->
<span id="paths-cache"></span>
<span id="paths-cache"></span>
=== Reusable cache: <code>paths.cache</code> ===
=== Reusable cache: <code>paths.cache</code> ===


<!--T:41-->
Stores reusable cached data. The default value is <code>null</code>, which resolves to <code>&lt;game folder&gt;\shroudforge\cache</code>.
Stores reusable cached data. The default value is <code>null</code>, which resolves to <code>&lt;game folder&gt;\shroudforge\cache</code>.


<!--T:42-->
<span id="paths-exports"></span>
<span id="paths-exports"></span>
=== Mod export destination: <code>paths.exports</code> ===
=== Mod export destination: <code>paths.exports</code> ===


<!--T:43-->
Folder where files produced by mod export functions are written. The default value is <code>null</code>, which resolves to <code>&lt;game folder&gt;\shroudforge\exports</code>.
Folder where files produced by mod export functions are written. The default value is <code>null</code>, which resolves to <code>&lt;game folder&gt;\shroudforge\exports</code>.


<!--T:44-->
<span id="paths-logs"></span>
<span id="paths-logs"></span>
=== Log files: <code>paths.logs</code> ===
=== Log files: <code>paths.logs</code> ===


<!--T:45-->
Folder for ShroudForge and mod log files. The client and Dedicated Server write separate log files there. The default value is <code>null</code>, which resolves to <code>&lt;game folder&gt;\shroudforge\logs</code>.
Folder for ShroudForge and mod log files. The client and Dedicated Server write separate log files there. The default value is <code>null</code>, which resolves to <code>&lt;game folder&gt;\shroudforge\logs</code>.


<!--T:46-->
<span id="paths-mods"></span>
<span id="paths-mods"></span>
=== Installed mod packages: <code>paths.mods</code> ===
=== Installed mod packages: <code>paths.mods</code> ===


<!--T:47-->
Folder where ShroudForge searches for installed mod packages. The default value is <code>null</code>, which resolves to <code>&lt;game folder&gt;\mods</code>. This is a sibling of the <code>shroudforge</code> data folder.
Folder where ShroudForge searches for installed mod packages. The default value is <code>null</code>, which resolves to <code>&lt;game folder&gt;\mods</code>. This is a sibling of the <code>shroudforge</code> data folder.


<!--T:48-->
<span id="paths-runtime"></span>
<span id="paths-runtime"></span>
=== Runtime files and profiles: <code>paths.runtime</code> ===
=== Runtime files and profiles: <code>paths.runtime</code> ===


<!--T:49-->
Folder for Lua and native runtime data and detected game profiles. The default value is <code>null</code>, which resolves to <code>&lt;game folder&gt;\shroudforge\runtime</code>.
Folder for Lua and native runtime data and detected game profiles. The default value is <code>null</code>, which resolves to <code>&lt;game folder&gt;\shroudforge\runtime</code>.


<!--T:50-->
<span id="paths-state"></span>
<span id="paths-state"></span>
=== Persistent loader state: <code>paths.state</code> ===
=== Persistent loader state: <code>paths.state</code> ===


<!--T:51-->
Folder for persistent Modloader state, including saved enablement and runtime status. The default value is <code>null</code>, which resolves to <code>&lt;game folder&gt;\shroudforge</code>.
Folder for persistent Modloader state, including saved enablement and runtime status. The default value is <code>null</code>, which resolves to <code>&lt;game folder&gt;\shroudforge</code>.


<!--T:52-->
<span id="paths-ui"></span>
<span id="paths-ui"></span>
=== Interface data: <code>paths.ui</code> ===
=== Interface data: <code>paths.ui</code> ===


<!--T:53-->
Folder for persistent interface data and the Modloader WebView profile. The default value is <code>null</code>, which resolves to <code>&lt;game folder&gt;\shroudforge\ui</code>.
Folder for persistent interface data and the Modloader WebView profile. The default value is <code>null</code>, which resolves to <code>&lt;game folder&gt;\shroudforge\ui</code>.


<!--T:54-->
<span id="paths-updates"></span>
<span id="paths-updates"></span>
=== Downloaded updates: <code>paths.updates</code> ===
=== Downloaded updates: <code>paths.updates</code> ===


<!--T:55-->
Folder for downloaded or staged updates. The default value is <code>null</code>, which resolves to <code>&lt;game folder&gt;\shroudforge\updates</code>.
Folder for downloaded or staged updates. The default value is <code>null</code>, which resolves to <code>&lt;game folder&gt;\shroudforge\updates</code>.


<!--T:56-->
All eight path fields accept a non-empty string or <code>null</code>. With <code>null</code>, ShroudForge chooses the path described above. An absolute path is kept as the selected location. A relative path is resolved from the game folder at startup, then stored as an absolute path. For example, <code>"paths": { "cache": "ShroudForgeCache" }</code> selects a folder named <code>ShroudForgeCache</code> beside the game executable. The selected installation and its client or server process must be able to read and write the chosen folders.
All eight path fields accept a non-empty string or <code>null</code>. With <code>null</code>, ShroudForge chooses the path described above. An absolute path is kept as the selected location. A relative path is resolved from the game folder at startup, then stored as an absolute path. For example, <code>"paths": { "cache": "ShroudForgeCache" }</code> selects a folder named <code>ShroudForgeCache</code> beside the game executable. The selected installation and its client or server process must be able to read and write the chosen folders.


<!--T:57-->
To restore one path to its default, set its value back to <code>null</code>. This does not move data from the old folder. Copy files yourself only when a feature needs existing data at the new location.
To restore one path to its default, set its value back to <code>null</code>. This does not move data from the old folder. Copy files yourself only when a feature needs existing data at the new location.


== Where the values come from ==
== Where the values come from == <!--T:58-->


<!--T:59-->
The shipped defaults and accepted fields are defined by the [https://github.com/bonsaibauer/shroudforge/blob/1.8.1/modules/loader-config/loader.schema.json loader configuration schema] and [https://github.com/bonsaibauer/shroudforge/blob/1.8.1/modules/loader-config/loader.default.json default configuration]. Use the Modloader Settings page for regular changes. If a field is not described here, check the matching schema instead of guessing its name or value.
The shipped defaults and accepted fields are defined by the [https://github.com/bonsaibauer/shroudforge/blob/1.8.1/modules/loader-config/loader.schema.json loader configuration schema] and [https://github.com/bonsaibauer/shroudforge/blob/1.8.1/modules/loader-config/loader.default.json default configuration]. Use the Modloader Settings page for regular changes. If a field is not described here, check the matching schema instead of guessing its name or value.



Latest revision as of 21:14, 18 November 2026


This guide covers settings for ShroudForge itself. It is separate from the player-facing settings that a mod declares in Extended.mod.json. The documented preferences are stored in shroudforge/config/modloader-config.json beside the game installation. The Modloader's Settings page is the easiest way to change them because it validates and saves each value for you.

Find and edit the configuration

The file is inside the shroudforge/config folder beside the Enshrouded executable. For example, if the game is installed in D:\Games\Enshrouded, the file is D:\Games\Enshrouded\shroudforge\config\modloader-config.json.

Prefer the Modloader's Settings page for ordinary changes. If you edit the JSON file yourself, close the game and Modloader first, make a backup, preserve the rest of the file, and keep the JSON valid. JSON does not allow comments or a comma after the final item. The configuration contains internal state as well as user preferences, so do not replace the entire file with a short example.

Settings use JSON values. A boolean is true or false. A string is in double quotes. A path can be a string or null. Use null to restore the automatic path for a storage location.

General settings

Compact Modloader layout: general.compactMode

This boolean controls whether the Modloader uses a denser layout. The shipped defaults leave it unset, which keeps the standard layout. Set it to true to use the compact layout or false to keep the standard layout.

{
  "general": {
    "compactMode": true
  }
}

Interface language: general.locale

This string selects the language used by the Modloader interface. The shipped default is en-GB. Choose a language in the Settings page when possible. The schema accepts language-tag-shaped values matching ^[A-Za-z0-9]+(-[A-Za-z0-9]+)*$, but a value that matches the pattern is not necessarily a language supplied by the installed Modloader.

{
  "general": {
    "locale": "de"
  }
}

Fallback name for notices: general.messageNameFallback

This string is the name used in a notice when automatic character-name detection cannot supply one. It is also the name used when general.usernameMode is set to manual. The shipped default is Flameborn. The value must contain 1–40 characters. The Settings page trims surrounding whitespace and uses Flameborn if the field is left empty.

{
  "general": {
    "messageNameFallback": "Flameborn"
  }
}

Reduce motion: general.reducedMotion

This boolean reduces interface motion and transition effects. The shipped defaults leave the setting unset, so the normal interface motion is used. Set it to true to reduce motion or false to keep normal transitions.

Choose how notices get a player name: general.usernameMode

This string accepts "auto" or "manual". The shipped default is "auto".

  • "auto" uses the local character name captured by the current game process. ShroudForge captures it when a valid character is first available and again when the character selection or name changes. If capture fails, notices use general.messageNameFallback. A name cached by a previous game process is not restored.
  • "manual" always uses general.messageNameFallback.

This affects names shown in notices. It does not identify remote players or change a mod's own fallback text.

{
  "general": {
    "usernameMode": "auto"
  }
}

Logging

Minimum saved log level: logging.minimumLevel

This string sets the lowest severity that ShroudForge writes to log files. The accepted values, from most detailed to most restrictive, are TRACE, DEBUG, INFO, WARN, and ERROR. The shipped default is INFO. Entries below the selected level are not saved to the regular log file.

The Debug Console has its own display filter. Changing that filter only changes which entries are shown in the console. It does not change what the log file saves. The saved-file threshold is the setting documented here.

{
  "logging": {
    "minimumLevel": "INFO"
  }
}

Export functions

Enable mod export functions: exports.enabled

This boolean enables or disables mod export functions. The shipped default is true. Set it to false to disable those functions for the installation.

{
  "exports": {
    "enabled": true
  }
}

This loader preference is different from the export capability requested by an individual mod in mod.json. A mod still has to declare and use the capability it needs. See Modding: Capabilities.

Module settings

The modules value is an object with separate sections for the built-in modules. There is no modules.modules option or shared module list. Each section is named for its owner. The shipped defaults currently contain these sections:

Section What it configures
modDetection Mod package discovery and how unknown manifest fields are handled.
dllManager DLL discovery and compatibility profiles.
debugConsole Debug Console behavior, including log source, display filter, refresh rate, and shortcut.
worldEditor World Editor enablement, refresh rate, and shortcut.
modloaderUi Modloader interface behavior, including its starting page, remote target, and shortcut.
wiki In-Modloader Wiki availability, paging, and refresh interval.
network Network module availability and dedicated-server or client allowlist settings.
runtimeDiagnostics Runtime diagnostic collection, job selection, timing, and slow-callback threshold.
gameProfileDiscovery Automatic discovery of game profiles.
updates System and mod update behavior and recycle-bin retention.

The exact fields and allowed values belong to the schema. Some saved fields are runtime state rather than preferences. For example, window positions and diagnostic request or session values are managed by ShroudForge. Do not copy those values into a mod's extended.mod.json or treat them as mod settings.

{
  "modules": {
    "debugConsole": {
      "enabled": true,
      "defaultSource": "game",
      "levelFilter": "ALL"
    },
    "worldEditor": {
      "enabled": true
    }
  }
}

This is a partial example. Keep other module sections and settings already present in the configuration.

Storage paths

Reusable cache: paths.cache

Stores reusable cached data. The default value is null, which resolves to <game folder>\shroudforge\cache.

Mod export destination: paths.exports

Folder where files produced by mod export functions are written. The default value is null, which resolves to <game folder>\shroudforge\exports.

Log files: paths.logs

Folder for ShroudForge and mod log files. The client and Dedicated Server write separate log files there. The default value is null, which resolves to <game folder>\shroudforge\logs.

Installed mod packages: paths.mods

Folder where ShroudForge searches for installed mod packages. The default value is null, which resolves to <game folder>\mods. This is a sibling of the shroudforge data folder.

Runtime files and profiles: paths.runtime

Folder for Lua and native runtime data and detected game profiles. The default value is null, which resolves to <game folder>\shroudforge\runtime.

Persistent loader state: paths.state

Folder for persistent Modloader state, including saved enablement and runtime status. The default value is null, which resolves to <game folder>\shroudforge.

Interface data: paths.ui

Folder for persistent interface data and the Modloader WebView profile. The default value is null, which resolves to <game folder>\shroudforge\ui.

Downloaded updates: paths.updates

Folder for downloaded or staged updates. The default value is null, which resolves to <game folder>\shroudforge\updates.

All eight path fields accept a non-empty string or null. With null, ShroudForge chooses the path described above. An absolute path is kept as the selected location. A relative path is resolved from the game folder at startup, then stored as an absolute path. For example, "paths": { "cache": "ShroudForgeCache" } selects a folder named ShroudForgeCache beside the game executable. The selected installation and its client or server process must be able to read and write the chosen folders.

To restore one path to its default, set its value back to null. This does not move data from the old folder. Copy files yourself only when a feature needs existing data at the new location.

Where the values come from

The shipped defaults and accepted fields are defined by the loader configuration schema and default configuration. Use the Modloader Settings page for regular changes. If a field is not described here, check the matching schema instead of guessing its name or value.