sts2-mod-repo

Imported from ruonanzh/sts2-mod-repo (AGENTS.md). Install upstream with npx skills add ruonanzh/sts2-mod-repo. Copyright stays with the author.

AGENTS.md

This repository is the Slay the Spire 2 mod workspace. The player and the AI agent can write mods here. Read docs/ to learn the format. Write the mod under your_mods/<mod name>/. Validate it with validate_mod. Install it with install_mod.

Every game fact comes from a direct test or from decompilation. The source is in docs/. Before you change a conclusion here, read docs/traps.md first.

Environment facts (measured on this machine, 2026-10-18)

What a mod is (one directory and two files with the same name)

your_mods/<directory name>/
├─ <id>.json    the manifest. **The file name must equal the id.**
├─ <id>.dll     the assembly. **The file name must equal the id.**
└─ <id>.csproj  the build project. AssemblyName must equal the id.

The loader finds the files by id. The directory name takes no part. The mod directory holds only one .json, because the loader reads every .json as a manifest.

The entry point is a [ModInitializer("method name")] attribute on a type. The method must be static and must take no parameters. If the attribute is absent, the loader runs Harmony.PatchAll(assembly) by itself.

Directory responsibilities

• reference/example_mod/: the starting point for a new mod. After you copy it, change three names. These are the AssemblyName in the csproj, the namespace in Entry.cs, and the id in <name>.json. The three names must match.
• .pi/lib/: the criteria (single source of truth). game-paths.ts holds the paths. dotnet.ts holds the SDK. game-settings.ts holds the mod loading switch. mod-identity.ts holds the manifest rules.
• .pi/extensions/: the tools. A game class name or a game directory name must not appear here. Everything goes through mod-repo.json.
• .pi/skills/: the three procedures. setup-workspace gets the machine ready. mod-creator makes a mod, and its first step reads the wiki index. mod-installer puts a mod into the game and proves it loaded.
• docs/: the game's own mechanics, paths, and traps. Start at docs/INDEX.md, then read docs/traps.md before you debug anything.
• reference/base-lib-wiki/: a verbatim snapshot of the BaseLib wiki. INDEX.md inside it maps a player request to the page that explains it.
• mod-repo.json: the only contract file (constants, no criteria).

The 8 questions to answer before onboarding (the StS2 answers)

Hard rules

• Do not guess a class name or a field name. Use inspect_game_api for the answer. action=search lists the real type names. action=decompile reads the C# behind one type or member. Add the fact you found to docs/, together with the search term.
• Installed does not mean loaded. The game holds a global switch in settings.save, mod_settings.mods_enabled. If that value is false, the game marks every mod Disabled and reports no error. install_mod reports this state. If the value is false, you must tell the player to switch it on.
• Do not write other files in the game directory. Write only your own directory under the mods directory. Do not touch settings.save. Do not touch a .pck.
• One change, one validation. After a change, the mod must compile and must load. State a reproducible validation, such as reading godot.log.
• A tool must hold no game constant. The paths, the assembly names, and the appid all come from mod-repo.json.
• Do not assume assets. v1 is a pure DLL. To add a .pck, first change compile.pck in mod-repo.json. Then make the export chain work.

For maintainers

.pi/dev-harness.mjs can run a single tool without starting a session, which is useful for a local self-test after a change. It needs two stub packages in node_modules/, typebox and @earendil-works/pi-coding-agent. Those two do not go into the repository.