zomboid-modding

Zomboid Modding

Use this skill for Project Zomboid mod work. Prefer the layout already used by nearby mods over generic assumptions.

First Checks

• Inspect the current folder and nearby mods before creating files: pwd, find . -maxdepth 3 -type f -iname mod.info | sort, and one or two similar cjs* mods.
• Preserve existing user edits and existing mod IDs. Do not rename IDs, folders, or version folders unless the user asks or the current layout is broken.
• For existing third-party or Workshop-backed mods, check the local Workshop copy before importing, forking, or patching locally. Inspect /media/cjstorrs/windows/Program Files (x86)/Steam/steamapps/workshop/content/108600 and match by mod.info id=, active version folder, and relevant files to see whether the fix or update already exists upstream.
• If the Workshop copy already contains the needed fix or a newer compatible update, prefer refreshing/replacing the live copy from Workshop over maintaining a local project patch. Do not import or fork a Workshop mod just to fix an issue already fixed upstream.
• When adding CJS-only behavior to an existing third-party or Workshop-backed mod, prefer a separate CJS patch/tweaks mod over overwriting upstream files. Overwrite the upstream/live copy only when a patch cannot safely layer the behavior, when the user explicitly asks, or when replacing stale local files with a verified current Workshop payload.
• For new or forked CJS mods, work in ~/projects/game-mods/zomboid/<modName> first. Install into the live Zomboid mods folder only after project validation.
• In the live Zomboid/mods workspace, mods must be direct children of mods/, not under Contents/mods/.
• Project-backed mods live under ~/projects/game-mods/zomboid/<modName>. Their live installs are symlinks back to those project folders, not copied folders.
• For every new or imported mod project, initialize the project repo and GitHub remote using the GitHub repo setup rules below before editing.
• Before making changes, create an initial baseline commit containing only the copied/imported mod files unless the user explicitly asks not to commit, then push it.

GitHub Repo Setup And Push Discipline

Use these rules for Project Zomboid mod repos in ~/projects/game-mods/zomboid.

• Keep the local mod folder name and mod.info id= stable unless the user explicitly asks to rename them.
• Local repos use main as the default branch. If initializing, run git init -b main; if a repo already exists without main, create main from master or current HEAD before the first push.
• GitHub repo names must start with pz- and be lowercase kebab-case from the project folder name, e.g. cjsQuickZoom -> pz-cjs-quick-zoom. Remove apostrophes, convert & to and, + to plus, split camel case and digit/letter boundaries, collapse repeated separators, and do not rename the local mod folder to match the repo.
• For CJS patch/tweaks mods for existing mods, use the CJS patch mod convention below instead of deriving the repo name from the local folder.
• Create or update the GitHub repo under mrStorrs. Make clearly new, non-forked CJ-authored mods public only when mod.info or project context shows author=CJ Storrs and no fork/source-derived wording such as fork, based on, or repack; make forks, imports, third-party mods, Workshop-backed mods, helpers, and ambiguous repos private.
• After the first push of a public repo, protect main: set it as the default branch, disallow force pushes and deletions, and enforce protection for admins. Do not require status checks or reviews unless the repo already has that policy.
• Set origin to [email protected]:mrStorrs/<repo>.git. Push main, all local branches, and tags after repo creation.
• After every commit made by this skill, immediately run a normal git push for the committed branch. Do not force-push. If the repo has no remote yet, create/configure it with these rules first, then push.
• If GitHub hits a secondary content-creation limit while creating repos, back off and retry the same missing repo set; do not create alternate names.

CJS Patch Mods For Existing Mods

When CJS needs local fixes or quality-of-life tweaks for an existing third-party or Workshop mod and the upstream mod can remain the source of truth, create a separate patch/tweaks mod instead of editing or importing the upstream payload.

• Prefer a patch/tweaks mod over overwriting the target mod. Overwrite the target only when the behavior cannot safely be layered, when replacing stale local files with a verified current Workshop payload, or when the user explicitly asks for an overwrite.
• Derive <mod-name> from the target mod display name, folder name, or stable id= by lowercasing, splitting camel case and word boundaries, removing punctuation, converting & to and, converting + to plus, and collapsing separators into kebab-case.
• GitHub repo names must be pz-<mod-name>-cjs-tweaks, e.g. CleanUI -> pz-clean-ui-cjs-tweaks.
• Project folder names and mod.info id= values should use the same words without pz-, converted to lower camelCase, e.g. CleanUI -> cleanUiCjsTweaks.
• Set mod.info name= to CJS <Target Mod Name> Tweaks.
• Add require=\<TargetModId> in mod.info, and enable the patch immediately after the target mod in active load lists.
• Keep patch mods narrow and namespaced. Do not copy upstream files unless overriding a specific Lua, script, asset, or load path is required.
• Make these repos private unless project context proves the patch is clearly CJ-authored, non-forked, and safe to publish.

Root-Cause Fixes

• Do not build defensively by default. Fix the proven cause instead of adding broad nil guards, pcall fallbacks, catch-all skips, silent cleanup, or code that deletes broken state to make an error disappear.
• If an invariant is broken and the bad state should not be possible, surface a clear error or targeted log with enough context to find the source. Do not silently drop items, entities, save records, loot entries, or user data unless the user explicitly approves that behavior.
• Defensive handling is only acceptable when it is an absolute must: untrusted persisted save/modData, sandbox values, client/server command payloads, optional dependencies, real Workshop/API version drift, or a PZ API that is proven nullable. Keep those guards narrow and close to the boundary.
• When a boundary guard is required, preserve data where possible and log the exact malformed value or missing dependency. The guard must not hide the root cause from later debugging.

Loot Work

• If the task touches loot distribution, EasyDistro, spawn rates, zombie/container loot, capsules, packs, boxes, wrappers, or contained item definitions that may affect spawning, read and apply /home/cjstorrs/projects/game-mods/zomboid/.codex/instructions/easy-distributions.md before editing.
• If that workspace instruction file is missing, continue with this skill and inspect the relevant mod's current loot path before changing code.

Post-Change Review Gate

• After any code, script, asset-reference, packaging, sandbox, mod-list, or live-install change, read and apply /home/cjstorrs/projects/game-mods/zomboid/.codex/skills/zomboid-review/SKILL.md before final closeout.
• Scope the review to the touched mod and changed domains, but do not skip it for small edits. The review must at least cover changed files, active B42 layout, live-install drift when applicable, latest relevant logs when available, syntax/line-ending checks, and any domain probes that match the change.
• If the review finds issues and the user asked for implementation, apply focused fixes, rerun the relevant validation, relink the project-backed live mod if needed, and rerun the affected review checks before finishing.
• If the change cannot be proven outside Project Zomboid, state the exact in-game validation still required after the review gate passes.

Mod List Updates

When enabling, disabling, adding, or removing mods from a loadout, update all active load points unless the user explicitly narrows the scope:

• Save-specific lists: /media/cjstorrs/windows/Users/cjsto/Zomboid/Saves/*/*/mods.txt. Add or remove mod = \ModId, entries inside the mods {} block.
• Main game/default list: /media/cjstorrs/windows/Users/cjsto/Zomboid/mods/default.txt. Keep the same mod = \ModId, block format.
• Saved preset list: /media/cjstorrs/windows/Users/cjsto/Zomboid/Lua/pz_modlist_settings.cfg. Update the named preset line such as b42-4: with \ModId; entries.

Rules:

• Use the actual id= from the relevant mod.info, not the display name or folder name.
• Search for existing entries before editing; do not duplicate an ID.
• Preserve the existing load order. For additions, append near the matching tail of the active list or preset instead of alphabetizing.
• Treat Lua/saved_builds.txt as character occupation/trait builds, not a mod load list.
• Treat legacy B41/mod-manager files such as Lua/saved_modlists.txt, Lua/modmanager-mods.txt, and Lua/saved_modlists_server.txt as stale unless the user specifically names them.
• After editing, verify the ID appears exactly once in each intended load point with rg -n "ModId" ... or an equivalent count.

Project-Backed Live Links

Project-backed mods in this workspace are installed into /media/cjstorrs/windows/Users/cjsto/Zomboid/mods as symlinks back to ~/projects/game-mods/zomboid/<modName>. The live symlink name should match the project folder casing exactly.

Do not replace a project-backed live symlink with a copied folder. If a real live folder has a matching project folder, treat it as stale live drift and replace it with a symlink after verifying the match by folder name or mod.info id.

Exception: if the user explicitly asks or approves abandoning a project-backed copy because the Workshop version is now the source of truth, remove the pro

Content truncated.