zwitschi/security-game
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity
Files
69484866db93c8122de753e331f159554e3bfabd
security-game/MEMORY.md
T

14 KiB
Raw Blame History

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.
  • Shift length is the scenario's shift_duration_s (900 s in all three venues). Tests and the screenshot tool override elapsed time; they do not change the default.
  • RNG: NPC reactions and event scheduling are seedable for deterministic tests.

Current State

  • Next playable pass (planned, not coded): ADR-0007 locomotion/input layers, ADR-0008 cone focus + head ring, ADR-0009 radial action menu, ADR-0010 procedural NPC presentation. Emergency stays on R. Wand leaves W. Host sign-in follow-up is deferred. PLAN.md has the full pass notes.
  • Release v0.2.1 is LIVE (2026-10-31): CI run 1110 built the NSIS installer + AppImage and published — installers/AppImage are on the releases page. Releasing = bump version → tag → push.
  • NSIS gotchas (validated in a local ubuntu:24.04 docker repro): makensis uses -D defines (never /D), resolves relative -DICON/-DARTIFACT against the script directory so CI passes $PWD-absolute paths; installed exe must be space-free (step-line.exe); ICO must be classic BMP entries (ImageMagick icon:auto-resize=48,32,16; PIL emits PNG-compressed ICOs NSIS cannot load).
  • appimagetool runs system appstreamcli if present (strict, exit 3 on warnings) — project metadata now passes --pedantic.
  • Distribution facts (verified via Gitea API + host creds): repo is public, account is admin; v0.2.1 has all 5 assets; the installers were initially missing from the release because publish_release.sh uploaded only portables — now fixed (uploads installer + AppImage; falls back to ~/.git-credentials when no GITEA_TOKEN).
  • Host sign-in: instance [service] REQUIRE_SIGNIN_VIEW=true blocks anonymous browse/download (not a repo/API setting). ~/.git-credentials holds the Gitea creds (basic-auth usable); .env only holds OPENROUTER_API_KEY.
  • Release v0.2.0 was LIVE: pushing the v0.2.0 tag made Gitea Actions run the build job and publish automatically (host has the GITEA_TOKEN secret). Tag page and /releases are public (HTTP 200). Caveat: anonymous asset downloads redirect to login on this host (host setting — tracked in TODO). Future releases = bump config/version, git tag vX.Y.Z, push. No local token needed.
  • Core simulation, three scenarios, headless tests (57 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.
  • NPC avatars now walk to per-intent waypoints (VenueScenario.waypoint_for_intent): enter/trespass/deliver/arrive → entrance, photo/film/perform/wander/roam → sidewalk, sit → steps_end. NpcAvatar.setup takes an explicit door_position.
  • Returning-trespasser behavior: NpcProfile.return_probability (trespasser 0.6, mental-crisis 0.4, others 0). NPCController._maybe_schedule_return() moves a directed-away NPC to LOITERING_DISTANT; tick_return(delta) fires after 20-60s and transitions back to APPROACH. NpcAvatar._advance_fsm re-targets the door on return.
  • Perception pass: NPCController.perceive_guard(distance) returns {noticed, band, reaction} with bands unaware (>6m), aware (2-6m), near (<2m). Near + temperament ≥0.6 → ARGUE, else COMPLY. GameManager._perception_pass() feeds real guard distance each physics tick and logs first-time notice.
  • Responder dispatch: RadioSystem tracks pending_calls and decrements arrival_delay_s in tick; emits responder_arrived when a call's delay elapses. RadioSystem.responder_outcome(call) maps danger/weapons → command/restraint/evacuation/arrest. GameManager._on_responder_arrived spawns a RESPONDER avatar at the entrance and logs the outcome. HUD shows an emergency-radio cooldown label via _update_radio_cooldown.
  • Wand screening (Joke Shop): WandScreener (new src/core/wand_screener.gd) classifies carried items as prohibited (weapon/knife/gun/blade) vs false-alarm (keys/belt/phone/coins/watch/buckle) vs clear. NpcProfile.carried_items holds guest items. GameManager binds W to _toggle_wand_screening and A/D to decide_wand; decide_access blocks admission at wand venues until controller.screened is true. VenueScenario.door_staff_lines holds venue-specific door-staff dialogue (Joke Shop has id/ticket/wand/refusal/prohibited lines).
  • Design change (2026-10-31): the selectable dialogue tone-of-voice system was removed. Rules.Tone/TONE_NAMES, NpcProfile.tone_modifiers, and the tone param on NPCController.roll_reaction/apply_player_action no longer exist; NpcProfile.dialogue_lines is a flat Array[String]; GameManager uses _apply_interaction(level, action_name); the T key is gone. HUD tone_label removed and hud.tone_prefix string deleted from JSON.
  • Polish/accessibility: venue cycling (V cycles VENUE_ORDER and restarts the shift), aim-free targeting (Tab cycles nearby NPCs within NEARBY_RADIUS), color-coded escalation indicator (Hud.set_escalation), procedural audio (AudioFeedback node generates sine tones for confirm/radio/escalation/deny), and a centralized Strings table (src/core/strings.gd, lookup/fmt) backed by content/strings.en.json. NOTE: Strings.get was renamed to Strings.lookup because get collides with Object.get.
  • Newly added: LATE shift phase (start 700s) with a reachability test; PROTESTER archetype + events + colors; CALL_SOMEONE reaction; DoorState core class + L binding + visual indicator; flashlight (G, SpotLight3D, perception bonus at evening/late); persistence wired (Save.save_shift_result on shift end, history + best score on the review screen); NavigationRegion3D flat navmesh + NavigationAgent3D NPC paths (steps now visual-only); strings moved to res://content/strings.en.json (41 keys, loader keeps lookup/fmt); export_presets.cfg (Linux/Windows/macOS) + tools/build_releases.sh + docs/RELEASING.md; README Downloads section.
  • Run tests: godot --headless --path . --script res://src/test/test_runner.gd
  • Boot check: godot --headless --path . --quit-after 120
  • Screenshot tools: godot --path . -s res://src/test/take_screenshot.gd (single shot to user://screenshot.png); godot --path . -s res://src/test/capture_screenshots.gd (staged README gallery shots to user://screenshots/, copied to docs/screenshots/).
  • Release build verified locally: export templates for 4.3 installed at ~/.local/share/godot/export_templates/4.3.stable/; ./tools/build_releases.sh produced Linux/Windows/macOS artifacts for 0.1.0 in build/ and the Linux binary passed a headless smoke test. Publishing to Gitea still needs a token (see tools/publish_release.sh, docs/RELEASING.md).
  • CI: the repo now carries a Gitea Actions workflow at .gitea/workflows/build.yml (checks on push/PR; full export + artifact upload + optional release publish on tags and workflow_dispatch). A repo secret GITEA_TOKEN is required for tag releases. The old .github/workflows/ci.yml was removed so hosts scanning both paths do not double-run.
  • Venue cycling: V switches Hollywood Blvd → The Joke Shop → TV Studio and restarts the shift.
  • Venue door-staff dialogue: VenueScenario.door_staff_line(context, rng) and GameManager logging (id/ticket/wand-check, refusal, prohibited-item) — Joke Shop flavor.
  • CI cache: .gitea/workflows/build.yml no longer uses actions/cache (the runner can't reach the GitHub cache service; import is fast). GODOT_SILENCE_ROOT_WARNING=1 set on jobs. Logs live in .gitea/logs/ after each run.
  • Visual polish (v0.2.0): phase lighting (GameManager.PHASE_LIGHTING + ProceduralSkyMaterial), street lamps + night mode in WorldBuilder.set_night_mode, marquee Label3D, crosswalk/planters/ trees, NPC per-seed variation. capture_screenshots.gd shoots day + fast-forwarded LATE night (6 shots in docs/screenshots/). Version bumped to 0.2.0; binaries rebuilt.
  • Assets pipeline: python3 tools/generate_textures.py produces all authored PNGs under assets/textures/ (≤1024px, pow2); regenerate after changing the script, then run godot --headless --import before tests. 57 headless tests guard the pipeline.
  • General image pipeline: python3 tools/asset_pipeline.py defaults to openai/gpt-5-image-mini, requests supported 1:1/3:2 sources, then fits each role's target. It provides crop, resize, tile edge blending, alpha-glyph recoloring, and role-aware audits. Screenshot auditing checks 1280x720 minimum, 16:9 aspect, and contrast; visual composition remains a manual check. Python tools require Pillow from requirements-tools.txt.
  • AI texture mode: python3 tools/generate_textures.py --ai generates textures via the OpenRouter image API (POST https://openrouter.ai/api/v1/images, model bytedance-seed/seedream-4.5 by default, base64 PNG in data[].b64_json). Requires OPENROUTER_API_KEY (a gitignored .env in the repo root holds it locally; source it with set -a && . ./.env && set +a). --prompt/--name/--model/--size override the default batch. Output is downscaled to ≤1024px. NOTE: seedream rejects sizes below 3,686,400 px (1920×1920), so the script requests GEN_SIZE=2048 and downscales — do not lower GEN_SIZE below 1920. Verified end-to-end 2026-10-31 (3 textures generated). Legacy --ai remains on Seedream 4.5 and still ignores background: transparent; do not use it for alpha-dependent assets. Gemini 3.1 Flash Image advertised broad ratios but the current provider rejected authentication. The validated role-aware model is GPT-5 Image Mini.
  • Runtime assets: all 15 loaded world/HUD/card textures now live in assets/textures/ai/game_ready/; each passes role audit. Generated tile edges are blended, icon alpha masks are recolored white where needed, and the vignette uses the existing deterministic generator because the API returned an empty transparent image. The six docs/screenshots/ captures were regenerated after wiring and pass screenshot audit.
  • Detailed graphics: textured facade/awning/skyline, humanoid NPC rigs + props + walk bob + attention head-turn, inspection artifact cards, mode icons, escalation vignette, body-cam overlay (REC + shift clock). Screenshot set regenerated (docs/screenshots/, day + night).
  • Polish: wand scan cooldown (WAND_COOLDOWN_S + wand.recharge message).
  • NOTE: collaborators occasionally add uncommitted work to this shared tree (e.g. the radio easter egg); check git status before committing and leave foreign changes untouched unless asked.

Known Issues / Notes

  • Reference cycles are fixed: FSM holds its owner via WeakRef, ShiftCoordinator is RefCounted, and persistence tests free the Save node — the suite exits with no "resources still in use" warnings (was ~13). If a future subsystem introduces a cycle, repeat the WeakRef pattern.
  • Shift length: GameManager uses the scenario's shift_duration_s (900s ≈ 10-15 min); tests and the screenshot tool override elapsed time directly.
  • 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.
  • Steps are visual-only (no collider) so NPCs can path to the entrance; the guard spawns on the landing so it never needs to climb.
  • Persistence tests write into the real user://shift_results.json (harmless local pollution of the demo history).
  • macOS export required rendering/textures/vram_compression/import_etc2_astc=true in project.godot (universal build demands ETC2 ASTC enabled).
  • Joke Shop door_staff_lines are logged through GameManager (inspect / wand / refuse). They are not a separate dialogue UI.
  • GameManager._artifacts_for ignores event override_access and maps artifacts by NpcType. Joke Shop guests currently inspect as recognized staff. Tracked in TODO "Access artifacts actually match the venue".
  • Save.SETTINGS_FILE is declared and unused; no mouse-sensitivity or pause menu yet.

Open Questions

  • Whether the responder avatar should be playable/controllable or purely scripted.
  • Localization target languages beyond English.
  • macOS notarization approach for broad distribution.

Plan vs code (re-evaluated)

Shipped and tested: simulation core, three venues, 57 headless tests, v0.2.1 installers/AppImage, procedural world, HUD inspect/wand/radio, shift review (summary only), Tab targeting, V venue cycle.

Still missing (now in TODO.md, control pass first): ADR-0007–0010 input/focus/radial/NPC face; venue-correct access artifacts (override_access unread); startup/pause/settings; eye contact, recognize-as-verb, body-cam toggle, real blocking, request-reason; crowd rubberneck; emergency aftermath; body-cam replay timeline; sit/photo/film poses; real crowd audio; a few Joke Shop / Studio scripted cases; README test-count drift (says 52).

Reference in new issue View Git Blame Copy Permalink