CLAUDE.md — U R M03

Godot 4 game project. Science-fiction rogue-lite: strategy-forward mech auto-battler with a light action layer and a nurturing base-builder meta.

Persistent memory

persistent-memory.md at the repo root captures durable intent and supporting evidence (goals, decisions, foot-gun warnings, in-flight state) across context resets. Read it at session start; treat it as one input alongside this CLAUDE.md and the auto-memory system, not as the single source of truth.

It is a lean index: the dated log sections keep each over-threshold entry's full body in persistent-memory.d/<slug>.md. Pull a detail file only when its index line is relevant to your work — never bulk-read persistent-memory.d/.

When you commit, include any pending persistent-memory.md and persistent-memory.d/ updates in the same commit (stage them alongside whatever else is being committed). Never leave them as a floating uncommitted change while shipping other work — durable memory that lags the code defeats its own purpose.

Design canon (read before designing anything)

The design documents are canonical and live in the advisor repo, NOT here:

Document	Canonical for
`~/development/advisors/game-design/concept/mechatronics/CONCEPT.md`	All systems: loop stack, run skeleton, tag grammar, chemistry table, encounter grammar, base, economy, campaign
`~/development/advisors/game-design/concept/mechatronics/MOE.md`	M03 ("Moe") — character bible, design law, scenes

Where they conflict: MOE.md wins for Moe, CONCEPT.md for systems. Design decisions are made in those documents first, then implemented here. Do not fork design decisions in this repo; propose changes against the advisor repo's docs.

Non-negotiable canon highlights (full rationale in CONCEPT.md):

ONE BOT — the cast is M03, Khoe, and rescued humans. No other friendly mech, ever. Build variety rides in RIGS.
No immunities, no healing enemies, ever (the invincibility laws). Susceptibilities only; damage dealt is progress banked.
Two-solutions rule — every encounter answerable by brute force AND by the read; cleverness pays only in speed, safety, spectacle.
Combos produce verbs, not multipliers. Every chemistry row is a visible event, learnable by seeing it once.
No tutorial, ever. The base's growth order is the curriculum.
Siege/base-defense mode: permanently rejected. Do not build, do not re-propose.

Design questions — where answers live, in order

CONCEPT.md / MOE.md (paths above) — most questions are already settled there; check the decisions log and § Open questions before re-deriving anything.
The advisor repo's persistent memory — ~/development/advisors/game-design/persistent-memory.md — for context, foot-guns, and tried-and-abandoned ideas.
The book, via the KB. Load-bearing design-theory claims ground in Jesse Schell, The Art of Game Design (3rd ed.), retrievable live:
```
cd ~/development/advisors/game-design
source env.sh   # gitignored credentials; if missing, see env.sh.template there
uv run --with httpx python kb_query.py "your query" --title "Art of Game Design"
```
Always pass --title "Art of Game Design" (mixed corpus). Use distinctive tokens (lens names, Schell's coined terms), not broad words. Confidence buckets: high ≥ 0.030, medium ≥ 0.016. Honesty discipline (hard floor): quote what the KB returns; if it doesn't surface the claim, say so — never confabulate "Schell says." An empty result means retrieval missed, not that the book lacks it. Full retrieval guidance: the advisor repo's CLAUDE.md.

Foot-gun: env.sh carries a borrowed Worldtree key (ratatoskr's); HTTP 401 means it rotated — fix documented in env.sh's header.

Engine

Godot 4.7.1-stable, pinned. Both dev machines run 4.7.1.stable.official.a13da4feb (Mac editor: /Applications/ Godot.app + godot shim; nh3-dev headless: ~/bin/godot). Do not upgrade unilaterally — version skew rewrites scene files. An upgrade is an operator decision applied to both machines at once.
Headless verification: godot --headless works on nh3-dev for scripts, tests, and imports. Smoke gate: ~/bin/godot --headless --path . res://tests/smoke.tscn (exit 0 pass / 1 fail; run 3x to catch flakes). After adding scenes/assets, import first: ~/bin/godot --headless --import --path .
Generated sidecars ship with their sources. Run the headless import BEFORE committing new scripts/assets so .uid / .import sidecars land in the same commit — otherwise the other machine's editor mints untracked copies and its next git pull refuses to merge. Enforced on nh3-dev by a local .git/hooks/pre-commit (not versioned — recreate on fresh clones: refuse staged-new .gd without a tracked .uid).
Aseprite headless on nh3-dev: ~/bin/aseprite (1.3.18.2, operator-licensed source build; tree at ~/src/aseprite, skia m124 at ~/deps/skia). Sprite pipeline: aseprite -b --script tools/aseprite/gen_sprites.lua from the repo root; the Pillow previewer tools/aseprite/preview.py renders pixel-identical PNGs from the same maps (verified 2026-08-14).
Two-machine hygiene (Mac editor side): pull BEFORE opening the editor after new commits land. If a pull ever refuses over generated sidecars anyway, they're safe to delete wholesale: git clean -f '*.uid' (add '*.import' if named) — then pull.
GDScript for design iteration; C# reserved for hot paths (none yet).
2D, pixel-first: integer scaling, nearest-neighbor filtering (set in project.godot). Hi-bit mixed-res effects layer comes later — greybox is deliberately art-free.

Current phase: GREYBOX (v1 per ROADMAP.md)

The falsifier slice, specced in CONCEPT.md § Encounter grammar: one arena · one auto-fire KINETIC weapon · two cards (HEAT + KINETIC) · the KINETIC+HEAT chemistry row (knock a heated enemy into others → heat spreads on impact) · two enemy types (untagged grunt swarm + self-heating burster). It exists to falsify three bets: positioning ↔ build interaction, card-freeze rhythm, chemistry delight. Greybox art: primitives and placeholder shapes only — no sprites, no polish.

6.2 KiB Raw Blame History