Modding

The modding section is generated from approved public modding docs. It does not read keys, packaged clients, build folders, SDK binaries, or local save contents.

Start Here

Local mod folder

Quickstart

Create mods/<mod_id>/mod.json, mirror data or asset paths, validate with WardenModKit, then enable the mod from the in-game Mods page.

JSON hooks

Script API

Hook-based runtime scripting actions and event surfaces.

Unsafe advanced path

Native SDK

C ABI plugin requirements, callbacks, validation, and sample SDK location.

How To Create Each Mod Type

Mod type	Where files go	Creation path
Data mod	mods/<id>/data/...	Create mod.json, mirror the base data path, edit JSON, run WardenModKit validate, enable the mod in-game.
Asset mod	mods/<id>/assets/...	Place replacement PNG, GIF, TMX, or other approved assets under the same relative path; validate asset references before enabling.
RPG item mod	mods/<id>/data/rpg/loot.json plus assets/Sprites/Equipment/...	Add merge loot data, reference iconSheet by file name, validate duplicate IDs, then test drops or shop offers.
JSON script mod	mods/<id>/scripts/runtime.json	Declare entrypoints in mod.json, add hooks such as OnRunStart or OnWaveStart, and use supported restricted actions only.
Lua mod	No public Lua runtime in this build	Use JSON hook entrypoints or native plugins instead until a Lua host is added and documented.
Native C++ mod	mods/<id>/native/win64, native/linux64, native/macos	Build against the native SDK, declare nativePlugins and permissions, enable unsafe_native_mods, then validate ABI/API compatibility.

In-Engine Mod Loader

Mods screen

Activation

Mods are opt-in during normal play. The in-game Mods page can enable or disable mods, reorder load order, open the mods folder, and toggle unsafe native mods.

Deterministic

Load Order

Enabled mods, Workshop roots, and base game roots are resolved with dependency and load-before/load-after constraints.

Modded saves

Profile Safety

Loading runtime mods switches play to the shared modded profile and disables Steam achievements and leaderboard submissions for that session.

Digest matching

Multiplayer

Modded multiplayer requires matching build ID, active mod-set hash, and active mod-list digest across host and clients.

Quickstart Details

1. Create a Local Mod

• `mods/template_noop_mod/`
• `mods/template_giant_monsters/` (large enemy size overrides)
• `mods/template_enemy_size_pulse_cpp/` (unsafe mode, enemy size pulsing plugin)
• `mods/template_item_mod/` (Artifact-quality Sunglasses head item, guaranteed INT affix, and equipped screen tint)

3. Verify Load

• Launch the game.
• The first normal launch starts with no mods loaded, even if `mods/` already contains mod folders.
• Open the main-menu **Mods** page and enable your mod.
• Check logs for active mod load order.
• Confirm your overridden content appears in-game.
• Enabling any mod switches play to the shared modded profile at the shared modded profile.
• Steam achievements and leaderboard submissions are disabled after runtime mods have been loaded in the session.

4. Dependency and Ordering Tips

• Use `dependencies` for required mods.
• Use `loadAfter` / `loadBefore` for deterministic conflict control.
• Missing required dependencies disable that mod for safety.

5. In-Game Mod Manager

• Main menu now includes a **Mods** page.
• You can:
• enable/disable mods
• reorder load order
• open the `mods/` folder
• toggle `unsafe_native_mods`
• Footer shows the active profile slot, active mod-set hash, Steam progression state, and dependency warnings.
• The Mods screen stores player choices in local mod selection data; shipped `data/modding/mod_defaults.json` remains the default template.

6. WardenModKit CLI

• `python tools/modkit/warden_modkit.py ...`
• `python modtools/warden_modkit.py ...`
• `init`
• `validate`
• `pack`
• `inspect`
• `diff`
• `map validate`

7. Warden Forge Desktop Tool

• Run with:
• `python tools/warden_forge/warden_forge.py`
• Features:
• live JSON editors for enemies, waves, drops, abilities, and map links
• mod validation panel (`WardenModKit validate`)
• map validation shortcut (`WardenModKit map validate`)
• asset browser with sprite preview for PNG/GIF sheets
• test-in-game launch profile for the selected mod root

9. Native Plugin SDK

• SDK files live in `tools/native_sdk/`.
• Build the sample plugin with:
• `cmake -S tools/native_sdk/sample_plugin -B build-native-sample`
• `cmake --build build-native-sample --config Release`
• Place plugin binaries under your mod root (`native/win64`, `native/linux64`, `native/macos`).
• Native plugins load only when `unsafe_native_mods` is enabled.
• For a shipped C++ template that visibly pulses enemy size, see `mods/template_enemy_size_pulse_cpp/README_mod.md`.
• Root `zeta` builds now auto-build the shipped `template_enemy_size_pulse_cpp` plugin and stage it with runtime mods.

Format Notes

`mod.json` Required Fields

• `id`
• `name`
• `version`
• `apiVersion`
• `author`
• `description`

Supported Optional Fields

• `dependencies`: array of strings or `{ "id", "version", "optional" }` objects
• `loadAfter`: array of mod IDs
• `loadBefore`: array of mod IDs
• `entrypoints`: array of script entry files (reserved for scripting milestone)
• `multiplayerPolicy`
• `nativePlugins`
• `nativeApiVersion`
• `nativePermissions`

Saves and Steam Progression

• Vanilla/no-mod play uses the vanilla profile and the Steam Cloud remote `profile.dat`.
• Any loaded mod switches play to the shared modded save the shared modded profile and Steam Cloud remote `profile_modded.dat`.
• The modded save is intentionally shared across all mod sets, so changing enabled mods does not create another save file.
• Steam achievements and Steam leaderboard submissions are disabled for a session once runtime mods have loaded.

Multiplayer Compatibility

• Modded multiplayer is allowed.
• Hosts and clients must match build ID, active mod-set hash, and active mod-list digest exactly.
• Empty mod metadata is treated as the vanilla state, so a vanilla host rejects a modded client and a modded host rejects a vanilla client.

Workshop Mapping

• Workshop items are mounted first, then scanned for `mod.json` at:
• item root
• `mods/<mod_id>/mod.json`
• Invalid or duplicate workshop manifests are rejected from mod activation and reported through runtime diagnostics.