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.

Modding: Capabilities

From Shroudforge
Revision as of 12:47, 18 November 2026 by Bonsaibauer (talk | contribs) (Document the export text-reading function)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)


Capabilities are the permissions a mod declares in its mod.json when it needs a specific ShroudForge or EML feature. They tell the loader what the package intends to do. A capability does not enable a disabled mod, choose whether it runs on the client or server, or guarantee that every operation is supported by the current game process.

The four capabilities at a glance

Value in mod.json What the mod is asking to do When the loader uses it
patch Change supported Enshrouded game assets through the asset-writing API. During ShroudForge's preparation step before the game starts.
export Read, create, and manage files inside the configured ShroudForge export directory. In the preparation step for an export-only mod, or in the live runtime when the mod also runs there.
runtime Run Lua in the live game process and use ShroudForge runtime features, such as lifecycle callbacks and supported runtime operations. While the client or Dedicated Server process is running.
runtime-register-dll Register and load a native DLL from the mod package with loader.runtime.register_dll. In the live game process. This capability also schedules the package for the runtime phase.

Declare only the capabilities the mod uses

The optional capabilities field is an array in the root of mod.json. The accepted values are patch, export, runtime, and runtime-register-dll. Each value may appear only once. An unrecognized value or a duplicate makes the manifest invalid.

For example, a mod that edits supported game assets before launch and also runs Lua callbacks during play requests both patch and runtime:

{
  "id": "example.asset-and-runtime-mod",
  "name": "Asset and Runtime Mod",
  "version": "1.0.0",
  "capabilities": [
    "patch",
    "runtime"
  ]
}

If the mod does not use any of these features, omit capabilities or provide an empty array. Do not add all four values as a precaution. Requesting a capability does not make an unsupported feature available.

Capabilities are read from mod.json, not extended.mod.json. They belong to the package that declares them. A dependency does not pass its capabilities to another mod. The separate target field selects the process in which the package runs. It does not grant capabilities, and capabilities do not synchronize a client mod with a server.

How ShroudForge applies a capability

The loader reads and validates each package's manifest, then uses its capability values to build the correct startup and runtime plans. When Lua calls a protected API, ShroudForge checks the owning mod's declaration as well as the current phase and the feature availability of that client or server process.

This means a capability is a request and an access gate, not a success result. For example, runtime makes a package eligible for the live Lua runtime, but a particular native operation can still be unavailable for the current Enshrouded build, process type, or runtime profile. Use the feature checks supplied by the API, such as runtime.has(feature), and handle an unavailable result.

The loader uses two broad phases:

  • Preparation before launch: enabled mods that need patch run through ShroudForge's supported asset-preparation path. A mod that only requests export can also run here to produce files before the game starts, if exporting is enabled.
  • Live runtime: mods that request runtime or runtime-register-dll are scheduled while the game process is running. Runtime access is still checked for each feature and operation.

A mod that requests both patch and runtime can be loaded for both phases. Keep preparation work separate from gameplay callbacks and make top-level code safe for the phase in which it runs. Use the runtime phase information when a behaviour must happen only in one phase.

patch: prepare game assets before launch

patch grants access to game.assets.write in the pre-game preparation phase. A mod uses it when it must change supported Enshrouded asset data before the game loads that data. Examples include changing recipe or other supported asset values that need to be present at startup.

ShroudForge runs the preparation pass before normal gameplay and publishes the resulting asset changes through its managed game-file preparation process. This is for supported game assets. It is not general permission to write arbitrary files, and it is not a way to change live ECS values after a world has loaded.

Use patch when the mod's effect must already be present as the game starts. If the same mod also needs callbacks or live runtime operations, declare runtime separately. These are different jobs: game.assets.write changes prepared asset data, while live operations such as runtime.ecs.write are checked through the runtime API.

Mods that change game files need their preparation step before launch. Follow the mod's instructions. When instructed to prepare manually, close Enshrouded and run this command from the game folder:

./shroudforge/shroudforge.exe launch "."

The patch capability alone does not make the mod run. The mod must also be enabled for the selected client or server installation, and the preparation result must match the installed package set before ShroudForge can use it.

export: write files into the user's export folder

export grants access to the EML file functions such as io.export, io.export_exists, io.read_export_to_string, io.export_list, io.export_copy, io.export_rename, and io.export_delete. A mod can use them for output that the player can keep or inspect, such as generated reports, saved tool output, or files produced by a mod action. io.read_export_to_string reads UTF-8 text from a file in the export folder.

Paths passed to these functions are relative to ShroudForge's configured export directory. By default this is the exports folder in the game installation. The loader can use a different configured folder. Export functions reject paths that escape this directory, so a mod cannot use them to choose an arbitrary system path.

For example:

if loader.features.export then
  io.export("reports/summary.txt", "The report is ready.")
end

If the destination file already exists, io.export replaces it. Choose filenames deliberately, and check before writing when existing player output must be preserved.

Exporting also depends on the loader-wide exports.enabled setting. It is enabled by default. If it is disabled, io.export and the other export functions are unavailable even when the package declares export. The setting is stored at shroudforge/config/modloader-config.json, under /exports/enabled.

An export-only mod can run during pre-game preparation to create files without using the live runtime. If it also declares runtime or runtime-register-dll, ShroudForge schedules it in the live runtime instead, where it can export while the game is running. Add patch as well only if the mod also changes game assets.

runtime: run Lua while the game is running

runtime schedules the mod's Lua entry point for the live client or Dedicated Server process selected by the package target. It allows the mod to use supported ShroudForge runtime features and lifecycle callbacks while the game is running.

Use it for behaviour that needs to react to the current game process, player, world, or supported live game data. Examples include reacting to a lifecycle callback, reading the selected player name, or using a supported runtime operation to change a live value. The standalone Unlimited Flight mod is an example of a runtime mod. Crafting Essentials combines runtime with patch because it needs both live behaviour and prepared asset changes.

The capability does not promise that every runtime function is usable. The API checks the current phase, the mod's lifecycle state, the selected process, the game build, and the operation's supported runtime profile. Check the exact feature before relying on it. For example, runtime.has("runtime.ecs.read") reports whether that operation is available now. Handle false or the reason returned by the corresponding status call instead of assuming that a loaded mod can use every operation.

runtime is not the same as patch. Use patch for supported asset changes before launch. Use runtime for functions that execute in the live game process. If a mod needs both, declare both and keep the two phases' work separate.

runtime-register-dll: load a package DLL

runtime-register-dll is for mods that need native code in addition to Lua. It makes the package eligible for the live runtime so its Lua code can call loader.runtime.register_dll(path). Listing the capability does not load a DLL by itself. The mod must call the function with a path relative to its package root.

if loader.features.runtime.dll then
  loader.runtime.register_dll("bin/example.dll")
end

Keep the DLL inside the mod package and include any files that it needs beside it. The function loads that DLL into the current game process for the process lifetime. ShroudForge may call the DLL's optional ShroudforgeModNativeInit export after loading. When present, that export lets the DLL register functions for the same mod's Lua code through shroudforge.native.

Native DLL loading is available in the Windows game runtime only. A DLL runs as native code inside the Enshrouded process and is not sandboxed like Lua. Request this capability only when the mod genuinely needs native code, and only use DLLs whose source you trust. A regular Lua mod does not need it.

Declare runtime-register-dll for a package that calls loader.runtime.register_dll. This capability schedules a DLL-only package for the live phase. If the mod also uses ordinary ShroudForge runtime features such as runtime.lifecycle or ECS operations, declare runtime as well because it describes a separate need.

Choose the smallest matching set

What the mod does Capabilities to declare
Changes supported asset data before the game starts patch Writes files into the configured ShroudForge export folder export Runs Lua callbacks or supported ShroudForge runtime operations during play runtime Loads a DLL from the mod package with loader.runtime.register_dll runtime-register-dll Changes startup assets and also has in-game behaviour patch and runtime Runs in-game and writes player-facing files runtime and export Runs in-game, uses runtime APIs, and loads its own native DLL runtime and runtime-register-dll

For setup and the other package fields, see the Mod.json guide. For how to write the Lua entry point, see Modding with Lua. The standalone Unlock Blueprints mod is an example of a mod that requests patch for prepared asset changes.