Modding with Lua: Difference between revisions
More actions
Bonsaibauer (talk | contribs) Create English ShroudForge Wiki article |
Bonsaibauer (talk | contribs) Marked this version for translation |
||
| (2 intermediate revisions by the same user not shown) | |||
| Line 10: | Line 10: | ||
<translate> | <translate> | ||
<!--T:1--> | |||
ShroudForge loads each Lua mod as an independent package. A package uses <code>mod.json</code> for its identity, requested capabilities, and process targets. Its <code>src/mod.lua</code> contains the mod logic. An optional <code>extended.mod.json</code> declares player-facing settings, action buttons, and links. | ShroudForge loads each Lua mod as an independent package. A package uses <code>mod.json</code> for its identity, requested capabilities, and process targets. Its <code>src/mod.lua</code> contains the mod logic. An optional <code>extended.mod.json</code> declares player-facing settings, action buttons, and links. | ||
== Start with a working package == | == Start with a working package == <!--T:2--> | ||
<!--T:3--> | |||
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. | 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 == | == Choose the process that owns the behavior == <!--T:4--> | ||
<!--T:5--> | |||
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. | 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. | ||
<!--T:6--> | |||
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. | 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 == | == Add settings and diagnose loading == <!--T:7--> | ||
<!--T:8--> | |||
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. | 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. | ||
<!--T:9--> | |||
Open the ShroudForge Mods window with <kbd>F9</kbd>. Use <kbd>F10</kbd> 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. | Open the ShroudForge Mods window with <kbd>F9</kbd>. Use <kbd>F10</kbd> 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. | ||
== | <!--T:12--> | ||
<span id="eml-migration"></span> | |||
== Migrate an EML mod to ShroudForge == | |||
This article explains the package and runtime concepts. The complete searchable Lua, native, game-type, and resource reference remains on the [https:// | <!--T:13--> | ||
ShroudForge can read many packages that use EML's <code>mod.json</code> 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 === <!--T:14--> | |||
<!--T:15--> | |||
# Make a backup of the complete mod folder before editing or saving it with another tool. | |||
# Keep the existing <code>id</code>, <code>name</code>, <code>version</code>, and dependency declarations. These identify the same package and its requirements. Change a field only when you have confirmed the package needs that change. | |||
# Check every declared capability against code and included files. <code>runtime-register-dll</code> is for registering a DLL shipped inside that EML mod's own folder. It is not a reference to ShroudForge's bundled <code>shroudforge/kfc-runtime.dll</code>. | |||
=== Add ShroudForge settings only when needed === <!--T:16--> | |||
<!--T:17--> | |||
<code>extended.mod.json</code> 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 <code>mod.json</code> manifest or import another mod's Lua modules. | |||
<!--T:18--> | |||
If ShroudForge writes an extension while saving a legacy EML package, it can record <code>"launcher": "EML"</code> 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 === <!--T:19--> | |||
<!--T:20--> | |||
For an EML package without a <code>targets</code> 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. | |||
<!--T:21--> | |||
<pre> | |||
{ | |||
"schemaVersion": 1, | |||
"enabled": true, | |||
"targets": ["client"] | |||
} | |||
</pre> | |||
<!--T:22--> | |||
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 === <!--T:23--> | |||
<!--T:24--> | |||
# Enable the package in the Modloader and check its manifest and dependency status. | |||
# Test it on a matching client or Dedicated Server installation. A successful package scan alone does not prove its runtime features work. | |||
# 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. | |||
# Compare the functions the mod calls with the [https://shroudforge.net/tools/modding/api-reference/ searchable ShroudForge Modding API reference]. EML compatibility functions and ShroudForge functions have distinct support requirements. | |||
<!--T:25--> | |||
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 == <!--T:10--> | |||
<!--T:11--> | |||
This article explains the package and runtime concepts. The complete searchable Lua, native, game-type, and resource reference remains on the [https://shroudforge.net/tools/modding/api-reference/ ShroudForge API reference]. Its function signatures and support data are maintained there. The Wiki does not copy its API-symbol pages. | |||
</translate> | </translate> | ||
[[Category:Modding:Shroudforge]] | [[Category:Modding:Shroudforge]] | ||
Latest revision as of 21:14, 18 November 2026
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
- Make a backup of the complete mod folder before editing or saving it with another tool.
- 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. - Check every declared capability against code and included files.
runtime-register-dllis for registering a DLL shipped inside that EML mod's own folder. It is not a reference to ShroudForge's bundledshroudforge/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
- Enable the package in the Modloader and check its manifest and dependency status.
- Test it on a matching client or Dedicated Server installation. A successful package scan alone does not prove its runtime features work.
- 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.
- 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.