Troubleshooting
Start with a fresh load
Section titled “Start with a fresh load”After editing files, save them and fully exit and relaunch Eclipse. Changing the selection in the mod menu uses Apply & Restart; saving a Lua file does not hot-reload the current session. Work on one error or change at a time.
The file name looks right, but nothing loads
Section titled “The file name looks right, but nothing loads”Show file extensions in your file manager and check for accidental .txt
suffixes. Use UTF-8 text files. Make sure there is no extra folder between the
mod folder and mod.toml. In Lua tables, check commas, quotes, braces, and end.
TOML lists in the manifest must be on one line. See
manifest fields and
Lua basics.
The mod is missing or cannot be enabled
Section titled “The mod is missing or cannot be enabled”Check that Mods/<folder>/mod.toml exists, the manifest ID is unique, and the
entrypoint path points to your Lua file. Inspect Details in the title-screen
mod menu for unmet requirements. Every declared dependency must be available at a compatible version.
Choose Apply & Restart after changing the selection, then enter Campaign. See installing and enabling mods.
Registration fails
Section titled “Registration fails”Read the error tagged with your mod ID. Check duplicate IDs, missing handles, required capabilities, references to undeclared dependencies, and field types. Fix the first registration error before investigating missing content: a failed registration does not commit part of the mod’s definitions.
Two mods cannot independently replace the same asset or the same semantic localization field. Resolve the conflicting claims; changing folder order does not choose a winner.
A sprite does not load
Section titled “A sprite does not load”Check the descriptor’s type=sprite and its texture path relative to assets/.
The texture path includes .png; the logical sprite ID used from Lua omits
.asset. Keep PNGs in textures/ and descriptors in sprites/.
Rectangles and borders must fit the image. For core atlas sprites, verify both the atlas address and member name. See sprite descriptors.
A combat callback does not run
Section titled “A combat callback does not run”Register a supported callback and attach the behavior through an active perk or enchantment. Verify its capability requirements and whether it dispatches for the player, an NPC, or both. The dojo punchbag does not use the normal fight lifecycle. See combat callbacks for the exact boundaries and event fields.
Turn on the F3 performance overlay, reproduce the issue and press F4 to save the active versions, callback timings and recent execution failures. See Debug callbacks in game for nested provider attribution and the limits of this evidence. An absent timed row can also mean the overlay was off or that the callback was never dispatched.
Content is unavailable after disabling a mod
Section titled “Content is unavailable after disabling a mod”Missing mod-owned save records are preserved. Re-enable the mod and reload the profile to restore access. Do not delete the save as a troubleshooting step. Keep the original namespace and published IDs, or provide the documented compatibility mappings. See save compatibility.