Skip to content

Mod troubleshooting

Start with Mod Prep → Validate. Keep the source project open so paths and errors refer to the files you are actually editing.

The mod is not listed

  • Confirm the folder containing modinfo.json is directly under Documents/My Games/Signs of Life/Mods/, or use Install / Refresh Test Copy.
  • Put a mod zip directly in the Mods folder. Do not put a zip inside an otherwise empty folder. It can contain modinfo.json at the archive root or in one enclosed pack folder, even if the zip has a different name. Split ambiguous archives containing several packs.
  • A broken archive is skipped while other packs load. Check Main.log for the failed archive path, then rebuild or replace that zip.
  • Use Local Mods Folder in the game's Mods menu or Open Mods Folder in Mod Prep to verify the exact path.

The mod says Pending

Pending means the pack has yet to load in this session.

  • For a Workshop mod, wait for Steam to finish downloading it and reopen Mods.
  • If the pack is Disabled, click Enable. If it stays Pending after installation, click Load Now from the main menu or restart.
  • Global gameplay configuration requires a restart; Load Now skips it. Newly loaded world profiles appear when you reopen the Sandbox creation menu. After Load Now, ambient wildlife rules can add encounters when you reopen an existing single-player world.

My edits do not appear

Install / Refresh Test Copy updates the files in your Mods folder. It does not reload a running game. If the pack is already Loaded, validate and refresh the test copy if needed, then restart Signs of Life. Load Now is for Pending packs and cannot replace a pack already loaded this session.

My replacement loads as a separate item

Check that your game build supports BaseGameOverride. In the item body, set "BaseGameOverride": true and copy the base item's exact UniqueIdentifier. Mod Prep should show the effective sol.* ID. If another pack replaces the same item, search Main.log for that ID to see which pack loaded last. See Replacing a base-game item.

I only want to translate an item

Use Mod Prep's Translate Existing Item… action with the shipped item JSON. Edit the generated Config/InventoryItemData.json row's Name and Description, leaving its ItemID unchanged. This keeps the existing weapon's animations and behavior without copying scripts or adding BaseGameOverride. If you already copied an item definition just for its text, remove that replacement yourself. See Translating an existing item.

A scripted item loads but does nothing

  • Check LuaScriptPath against the folder containing your mod's modinfo.json. A path such as Items/HeldItems/MeleeWeapons/Clubs/Club.lua needs that file inside your mod.
  • To reuse shipped behavior, use an explicit Content/LoadedContent/VanillaContent/.../Club.lua reference. The loader checks your pack first, then the shipped file. Its imports and held-item sound assets use the root that owns the resolved script. Shared Content/Lua/... script references are also supported; arbitrary game-relative Lua paths are not.
  • When you copy Club.lua into your pack, include its helper Items/HeldItems/MeleeWeapons/ComboMeleeWeapon.lua and referenced sounds too. A bare Items/... Lua reference does not fall through to vanilla or another installed mod.
  • Run Validate after the latest edit. A declared missing script is now reported when loading the pack; check the configured and resolved paths in the error or Main.log. An older game build may silently skip that script.
  • Refresh the installed test copy and restart after editing a loaded pack.

See the complete Copper Club replacement example.

Load Now fails

  • Read the error prompt and copy it if needed.
  • Run Mod Prep Validate again after the latest edit.
  • Check the game log under Documents/My Games/Signs of Life/Logs/ for the source file and error. Mod Prep's Open Game Logs button opens that folder.
  • Restore the last working edit, then add changes back one at a time.
  • Load Now is blocked during multiplayer. Leave the session or restart offline.

A pack is rejected during startup

The game skips a mod whose crafting or grinding recipes fail validation and continues loading other packs. The rejected pack's items, settings changes and translations are rolled back together. Check Main.log for the pack path and recipe error, correct the source in Mod Prep, and validate again. Install the corrected files, then use Load Now in single-player or restart.

If an older game build cannot reach the menu, temporarily move the offending pack outside the Mods folder and restart. Keep the pack and saved content IDs so it can be restored after correction.

The item exists but its sprite is missing

  • Keep the picture path relative to the mod folder (for the starter item, Sprites/sample_widget.png).
  • Match filename spelling and extension exactly.
  • Keep inventory art inside the mod. Do not point at a file elsewhere on your computer.

Gameplay configuration changes do nothing

Put gameplay overrides at Config/playerConfig.json or Config/worldConfig.json, with that exact spelling, inside your pack. Copies at the pack root are ignored. Run Validate, then restart the game: Load Now skips these overrides.

Saved mod content is missing

An inert Item from missing mod means its definition was unavailable when the save loaded. Reinstall and enable the original pack, keep its content IDs unchanged, and reload the save. Placed mod creatures, plants, and structures can also be absent from simulation until their definitions return. Do not delete placeholders you want to recover. See Removing and reinstalling a mod.

A Lua helper is missing or has the wrong state

  • Check the path from the pack root, beside modinfo.json, then from the importing script's folder. require("helpers") looks for helpers.lua; require("Tools.helpers") looks for Tools/helpers.lua in that order. A helper's own imports use its directory for the fallback.
  • Ship the helper with your pack. A missing module never searches another installed mod.
  • Return a table from the helper and keep the import in a local variable. Arbitrary global variables remain shared between scripts and mods.
  • Repeated imports within your pack return the same cached helper. Keep per-item or per-creature state on that entity's script table, and restart or fully reload content after editing a loaded helper.
  • The private helper cache is separate from package.loaded. Use loadfile with a literal filename, including .lua, when you need a fresh compiled chunk rather than a cached module.

See Lua modules for the full contract.

A staged package is not listed

  • Stage it with Mod Prep's Stage for in-game button instead of zipping by hand.
  • In the game, open Mods → Staged Mods, or Open Staging Folder. A ready package needs workshop.json, a preview image, and the inner mod zip in the same folder.
  • Stage again after moving the source project or the staging folder.

To play the mod locally, use Install / Refresh Test Copy and look for it under Installed Mods. Staging prepares the Workshop upload.

Steam upload fails

  • Steam must be running, logged in, and started with the game.
  • Read the upload error; staged files stay available for another attempt.
  • Accept the Steam Workshop legal agreement if Steam asks for it.
  • Leave the first upload private until its page, preview, and download have been checked.

An update would create the wrong item

Cancel. Open the original project in Mod Prep and stage it again. That project remembers its Workshop identity in .solmodproject.json next to modinfo.json. Do not rely on matching titles when two published items have the same name.