0xrsydn/sts2-bot
1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add design doc and research notes

Browse source 
DESIGN.md covers the three-layer architecture (facts in code, Jev for
tactics, gated escalation for macro). research/ documents the engine and
mod surface, the Jev classifier's measured behavior, the STS2MCP HTTP
interface, state shapes, failure modes, decision architecture, and a
run log of the first four sessions.
This commit is contained in:
0xrsydn 2026-09-21 17:09:43 +07:00
commit fb32822468
9 changed files with 2341 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

74
docs/research/README.md Normal file
View file

@ -0,0 +1,74 @@
# STS2 Bot — Research Notes
Living notes on reverse-engineering Slay the Spire 2 and driving it with a
TypeSafe System One (Jev) decision model.
These documents record **what was measured**, not what was assumed. Where a
claim comes from a live test, the evidence is quoted. Where something is a
guess, it says so.
## Contents
| # | Document | Covers |
|---|---|---|
| 01 | [Game engine and mod surface](01-game-engine-and-mod-surface.md) | Engine, assemblies, the official mod loader, manifest schema |
| 02 | [System One / Jev](02-system-one-jev.md) | What Jev is, measured latency and cost, the arithmetic failure |
| 03 | [STS2MCP interface](03-sts2mcp-interface.md) | The community mod, version drift, rebuilding from source |
| 04 | [State shapes](04-state-shapes.md) | Every verified JSON shape, per `state_type` |
| 05 | [Failure modes](05-failure-modes.md) | Every infinite loop found live, with its fix |
| 06 | [Decision architecture](06-decision-architecture.md) | The three-layer design and why the split is where it is |
| 07 | [Run log](07-run-log.md) | Results per run, with seeds and outcomes |
Architecture summary lives in [`../DESIGN.md`](../DESIGN.md).
## How to add a finding
1. Prefer a measurement over an inference. Quote the command and the output.
2. Put game facts in 01/03/04, model facts in 02, bugs in 05.
3. Record the **date** and the **game build** (`v0.107.1` today). Both move.
4. When a finding is later disproved, do not delete it. Mark it superseded
and say what replaced it. The wrong turn is often the useful part.
## Environment these notes were taken on
| Item | Value |
|---|---|
| Game build | `v0.107.1`, commit `59260271` |
| Platform | macOS (arm64), Steam |
| Engine | Godot 4.5.1 (.NET), runtime .NET 9.0.7 |
| Mod | STS2MCP, rebuilt from upstream `main` @ `55e0648` |
| Model | `jev-latest` resolving to `jev-1.13.0` |
## Rebuilding the mod
`STS2MCP` release `0.4.0` is **broken on this game build**. See
[03](03-sts2mcp-interface.md). To rebuild:
```bash
cd ~/sts2-bot/vendor/STS2MCP
nix shell nixpkgs#dotnet-sdk_9 --command bash -c '
dotnet build STS2_MCP.csproj -c Release -o out/STS2_MCP \
-p:STS2GameDir="$HOME/Library/Application Support/Steam/steamapps/common/Slay the Spire 2"'
cp out/STS2_MCP/STS2_MCP.dll \
"$HOME/Library/Application Support/Steam/steamapps/common/Slay the Spire 2/SlayTheSpire2.app/Contents/MacOS/mods/"
```
Then restart the game. Mods load only at process start.
## Testing
Two suites, both offline. Run them before every session.
```bash
python3 test_brain.py # 54 assertions — structural / programmatic
python3 test_facts.py # 29 assertions — arithmetic and parsing
```
`test_brain.py` is the important one for catching usage bugs. It asserts that
every `state_type` produces an action **legal for that state**, that every
action the decision layer can emit is declared somewhere, and that every
fallback respects its own inputs. It needs no model and no running game.
It was added after a session in which four separate infinite loops and three
hardcoded fallbacks were found by hand. Most of them would have been caught
here.