security-game/MEMORY.md

MEMORY

Session memory for durable decisions, state, and gotchas. Keep concise, remove obsolete entries.

Decisions

• Engine: Godot 4.3 stable (official editor build, ~/.local/bin/godot). The system's preinstalled godot-runner (4.7.2, Fedora) cannot load projects from arbitrary paths because it was compiled without path overrides; use the official editor binary instead.
• Language: GDScript. All cross-file references use explicit preload() constants (not class_name globals) so scripts compile in headless --script runs without the editor's class cache.
• Test framework deviation: the project uses a custom minimal headless test runner (src/test/test_runner.gd) instead of GUT, because GUT needs the editor plugin. CI runs it with --headless.
• Eventing: no autoload signal bus. ShiftCoordinator owns an EventBus instance (src/core/event_bus.gd) passed to subsystems; subsystems emit only when a bus is assigned. Autoloads at parse time are unreliable under --script.
• Static signals are not available in Godot 4.3 GDScript ("Expected func or var after static") — do not use them.
• GDScript lambdas capture local variables by value; mutating a captured local inside a lambda does not affect the outer variable. Use member functions for accumulators in tests.
• Prototype shift duration defaults to 300 s for testing; production targets 10-15 minutes per PLAN.md.
• RNG: NPC reactions and event scheduling are seedable for deterministic tests.

Current State

• Core simulation, three scenarios, headless tests (25 passing), and a first-person prototype with interaction HUD, access inspection, radio (assist + emergency hold-to-confirm), debug overlay, and shift review are implemented and green.
• Run tests: godot --headless --path . --script res://src/test/test_runner.gd
• Boot check: godot --headless --path . --quit-after 120
• Screenshot tool: godot --path . --script res://src/test/take_screenshot.gd (writes to user://screenshot.png).

Known Issues / Notes

• RefCounted reference cycle: NPCController holds an FSM that holds a back-reference to its owner, so test suites report "resources still in use at exit". Benign (process exit), but worth breaking later (e.g. WeakRef or explicit dispose()).
• Headless (dummy renderer) logs "Parameter m is null" from mesh_get_surface_count; it does not occur with a real GL driver and does not affect logic.
• NPC avatars all walk to the entrance and idle; per-intent waypoints are not implemented yet (see TODO).
• Wand screening (Joke Shop) is policy-only; the interaction is not yet in the prototype (see TODO).

Open Questions

• Tone picker UI design and whether tones should be selectable per interaction.
• Whether the responder avatar should be playable/controllable or purely scripted.
• Localization target languages.