cities2-mod-debugging

Cities2 Mod Debugging

Debug CS2 mods with evidence, one focused fix at a time. Use MCP-backed docs for CS2-specific assumptions and record negative constraints that rule out unsafe or misleading shortcuts.

Core principle: Always find root cause before attempting fixes. Plausible source-code guesses are still guesses.

Violating the letter of this process is violating the spirit of debugging.

The Iron Law

NO FIXES WITHOUT ROOT-CAUSE EVIDENCE FIRST

If the failure only appears after the mod is installed, loaded, or run in game, source-code inspection is not enough. Inspect runtime evidence first or state that root cause is unverified and stop before patching.

Debugging Workflow

1. State the failing symptom in one sentence: build, package, launch, runtime, UI, save, or gameplay behavior.
2. Gather the smallest useful evidence before changing code.
3. Classify the failure category and state the likely root cause, or say what remains unknown.
4. Form one hypothesis tied to a file, API, asset, package step, or game log entry.
5. Apply one focused fix.
6. Re-run the narrowest relevant check and compare evidence before/after.
7. After applying a fix for runtime, UI, save, or gameplay behavior, either run the relevant build or install check or tell the user exactly why it could not run. Then provide playtesting steps without waiting for the user to ask.
8. If the fix fails or the symptom changes, return to evidence and hypothesis instead of stacking unrelated edits.
9. After three failed fix attempts, pause and ask whether the architecture, template choice, or modding approach should change.

Runtime And UI Gate

For "build passes but it does not work in game" problems, complete at least one runtime check before editing:

• installed package layout and file timestamps;
• enabled playset/load state;
• Modding.log, Unity/Player logs, launch output, or exception stack traces;
• UI debugger state at localhost:9444 for UI mods.

Source files, package.json, and dist/ui.js can support a hypothesis, but they do not prove why an installed CS2 mod failed at runtime. If those are the only facts available, hand the user a playtesting/log collection step and mark the root cause unverified. Do not patch a likely selector, import, path, timing, or binding issue first and ask for logs only if it fails.