# MRPCI — working notes for Claude

SCI-generation adventure engine (sibling of MRPGI). Rust workspace:
`mrpci-core` (headless sim — **must never depend on macroquad**; that's the
architectural guardrail) and `mrpci` (the macroquad GUI, a thin bus client).

## Build / test / run

```sh
cargo build --workspace
cargo test --workspace          # includes full-playthrough regression tests
cargo run -p mrpci              # play Neon Precinct in a window
target/debug/mrpci-headless --game games/neon-precinct --render-room out.png
```

## Invariants — do not break

- **Everything goes through the bus.** All mutation is a `Command` on
  `GameState::apply`; all output is `Event`s. GUI, stdio, HTTP, MCP and the
  in-engine editor are thin adapters with zero private powers.
- **Determinism.** Fixed 30Hz cycles; timers count ticks; the only RNG is
  the seeded xorshift in `ScriptCtx`. `--script` replays must stay
  byte-identical (the AI parser lane is force-disabled there). Weather
  particles run a separate RNG stream on purpose.
- **Deterministic serialization.** Serde-facing maps are `BTreeMap` so room
  JSON/bundles are diffable and `--sample` output is byte-stable.
- **Scripts can't corrupt the sim.** rhai reads a `ScriptCtx` snapshot,
  writes queue as `Fx` — keep that airlock.
- **Missing resources degrade, never crash** (placeholders + `error` event).

## Gotchas

- `games/neon-precinct/` is **generated** by `mrpci-headless --sample`
  (source: `mrpci-core/src/bin/mrpci-headless/sample.rs`). Edit the
  generator, then regenerate — don't hand-edit the JSON.
- Distant verbs queue a walk-then-act (`pending_verb`); real-time surfaces
  resolve it on later ticks, the MCP adapter calls `GameState::settle()`.
  Raw stdio/HTTP callers must send `tick`.
- Sprites named `<base>-sheet<C>x<R>.png` are sliced into animated actor
  views (rows: front/back/left/right, right falls back to mirrored left).
  Sheets are for egos/NPCs; props/portraits use plain single-cel sprites.
- Solid props stamp CTL_BLOCK footprints; anything that can remove one must
  `rebake()`, not just re-stamp (else invisible walls linger).
- Hit-testing is pixel-accurate with 1px slop (`cel_hit`); typed commands
  "click" mid-sprite via `target_click_pos` (a feet-point click lands
  between an actor's legs).

## Docs

`README.md` (architecture + game-folder format), `docs/CONTROL.md` (bus
reference: every Command, all four surfaces), `docs/EDITOR.md` (F8 editor).