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 with Lua

From Shroudforge
Revision as of 21:14, 18 November 2026 by Bonsaibauer (talk | contribs) (Add EML migration guidance and current API reference)


ShroudForge loads each Lua mod as an independent package. A package uses mod.json for its identity, requested capabilities, and process targets. Its src/mod.lua contains the mod logic. An optional extended.mod.json declares player-facing settings, action buttons, and links.

Start with a working package

Follow Build your first mod to create the package folders, write a minimal manifest, and confirm that ShroudForge can find the mod. Read mod.json before requesting capabilities. Ask for only what the mod needs and explain why it needs it.

Choose the process that owns the behavior

A mod's target determines which Enshrouded process loads its code. A client mod runs on that player's game. A server-targeted mod runs on the Dedicated Server or the host process. Target selection does not synchronize client changes or grant server authority. A feature that changes shared world state must execute in the process that owns that state.

Install a multiplayer mod in every process required by its design and package declaration. Read Quickstart: Shroudforge and the mod's own installation notes before changing a server installation.

Add settings and diagnose loading

Declare player-facing values in extended.mod.json. Give each setting a stable key, a useful label, a safe starting value, and limits that match the behavior. Keep Modloader preferences separate from settings owned by an individual mod.

Open the ShroudForge Mods window with F9. Use F10 to read loader and mod messages. If a mod does not appear, check its folder, manifest, targets, dependencies, and declared capabilities. Some changes need a game restart. The manifest and settings articles explain those conditions.

Migrate an EML mod to ShroudForge

ShroudForge can read many packages that use EML's mod.json format. Keeping a package readable does not mean that every EML function, native operation, game build, or server setup is compatible. Test the mod in the process and game build where it is meant to run.

Preserve the package before changing it

  1. Make a backup of the complete mod folder before editing or saving it with another tool.
  2. Keep the existing id, name, version, and dependency declarations. These identify the same package and its requirements. Change a field only when you have confirmed the package needs that change.
  3. Check every declared capability against code and included files. runtime-register-dll is for registering a DLL shipped inside that EML mod's own folder. It is not a reference to ShroudForge's bundled shroudforge/kfc-runtime.dll.

Add ShroudForge settings only when needed

extended.mod.json is optional. Add it when the package needs ShroudForge-specific player settings, groups, buttons, links, or process targets. It does not replace the EML-based mod.json manifest or import another mod's Lua modules.

If ShroudForge writes an extension while saving a legacy EML package, it can record "launcher": "EML" to preserve the package's origin. ShroudForge-authored packages normally omit the launcher field. The field records provenance. It does not enable an EML API or improve compatibility.

Choose the process explicitly

For an EML package without a targets value, ShroudForge preserves the legacy client-and-server default. New ShroudForge packages default to the client. Set the targets explicitly when the mod is intended for a particular process. For example, a local interface feature normally belongs to the client, while server-owned world behavior belongs to the Dedicated Server.

{
  "schemaVersion": 1,
  "enabled": true,
  "targets": ["client"]
}

The target determines where the package runs. It does not synchronize state or changes between players. Follow the mod creator's instructions for which processes need the package.

Test the migrated package

  1. Enable the package in the Modloader and check its manifest and dependency status.
  2. Test it on a matching client or Dedicated Server installation. A successful package scan alone does not prove its runtime features work.
  3. Read the client or server log and the Debug Console when the mod reports a problem. Confirm the exact game build and ShroudForge version in any compatibility report.
  4. Compare the functions the mod calls with the searchable ShroudForge Modding API reference. EML compatibility functions and ShroudForge functions have distinct support requirements.

For the allowed manifest fields, see mod.json. For targets, launcher metadata, and settings, see Extended.mod.json. For permission behavior, see Modding: Capabilities.

Look up exact Lua functions separately

This article explains the package and runtime concepts. The complete searchable Lua, native, game-type, and resource reference remains on the ShroudForge API reference. Its function signatures and support data are maintained there. The Wiki does not copy its API-symbol pages.