Storyline Mode — Build Plan & Progress Tracker

Storyline Mode — Build Plan & Progress Tracker

Spec: docs/superpowers/specs/2026-06-25-storyline-mode-design.md Started: 2026-06-25 ~00:49 BST. Loop budget: 4h (stop scheduling wakeups after epoch 1782359365 ≈ 04:49 BST). Mode: autonomous 10-min loop. User asleep ~7h from start; make all decisions, no questions.

The per-chunk ritual (every iteration — see skill bh-dev-chunk)

1. Build + TDD in ~/Claude/bullet-heaven (main). Keep /sim pure (no Node/Engine/File APIs; extends RefCounted).
2. If a new class_name file was added: godot --headless --path . --import BEFORE testing (stale class cache).
3. Boot-check: godot --headless --path . --quit-after 90 2>&1 | grep "SCRIPT ERROR" must be empty. (timeout is NOT on macOS PATH — never wrap with it.)
4. Full suite: godot --headless --path . -s res://addons/gut/gut_cmdln.gd -gdir=res://tests -ginclude_subdirs -gexit then bash scripts/check-test-count.sh. Trust the COUNT, not just “passed”.
5. Survival determinism baseline must stay 4152236597 / 1267954985 (story defaults off → byte-identical). Story mode gets its OWN determinism test, not these numbers.
6. Commit to main with the Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> line.
7. Shippable feature → sync gameplay files to ~/Claude/bullet-heaven-tvos/ (NOT project.godot/icon.png/builds/export_presets.cfg; copy the WHOLE tests/ dir), bump Sim_Const.BUILD, deploy.

Skill reflection (standing instruction from Chris)

Each iteration, ask: did I just repeat a multi-step ritual a 2nd/3rd time? If so, capture it as a project skill in .claude/skills/<name>/SKILL.md. Skills created so far:

• bh-dev-chunk — the per-chunk ritual above (created chunk 1).
• (add bh-new-weapon, bh-new-enemy, bh-deploy when first executed — battle-tested, not speculative)

Chunks (check off as completed; keep notes)

• 1. Spec + plan + tracker + loop + first skill — design spec written; this tracker; bh-dev-chunk skill; caffeinate safeguard; loop scheduled.
• 2. Map model + StoryState skeleton — sim/story_data.gd (rooms/doors/auto-walls/gates) + sim/story_state.gd (gates/rooms/dialogue-once). +7 tests. DONE C2.
• 3. StoryLoader + StoryData + story.json (Ember skeleton) — content/story_loader.gd fail-loud validate; StoryData.from_dict; data/story.json 3-room Ember slice. +9 tests. DONE C3.
• 4. Wall collision — Sim.story/enable_story/_resolve_walls (circle-vs-AABB), guarded tick branches; survival baseline byte-identical. +5 tests. DONE C4.
• 5+6. StoryDirector — room tracking, gate seal/open, scripted timed waves, clear detection, reward grant; spawn_story_enemy/grant_story_reward. +5 tests. DONE.
• [~] 7. Dialogue events + triggers (sim) — CORE DONE in the director (say events, fire-once, on_enter + encounter triggers). Remaining triggers (on_low_hp, boss-phase taunts, on_secret_found, enemy on_spawn/on_death) fold into their feature chunks (boss/secret), not a standalone chunk.
• 8. Dialogue render box — ui/dialogue_box.gd typewriter speaker box from story.events. +4 tests. DONE.
• 9. Map renderer — render/story_map_renderer.gd region-tinted rooms + neon walls + pulsing sealed gates. +3 tests. DONE.
• 10. NPCs — _check_npcs talk-radius dialogue+reward (Echo grants nova); diamond+nametag render. +5 tests. DONE.
• [~] 11. Talking enemies — encounter dialogue (captain/Warden taunts) + clear_dialogue wired; the Null/Ash/Warden all taunt in Ember. Per-enemy on_spawn/on_death triggers still optional polish.
• 12. Secret areas — false-wall doors (gate “”, secret:true → passable + faux-wall render); discovery grants a hidden ORBIT weapon in Ember. +3 tests. DONE.
• 13. Weapon/ability story gating — reward→grant + weapon picker suppressed in story. DONE.
• 14. Region 1 content (Ember Reach) — 8 rooms, 5 escalating encounters, Echo nova gift, Warden boss, full dialogue; clamp_arena + spawn_story_boss enablers. +1 test. DONE C14.
• 15. Mode select — ui/start_menu.gd (Story/Survival) + main wiring + objective HUD; story PLAYABLE. +5 tests. DONE C15.
• DEPLOY (tvOS) — BUILD 33 synced + built + installed to the Apple TV (runs on next wake). bh-deploy skill captured. WEB demo + site changelog DEFERRED (the start menu changes the public demo from auto-attract → menu; flag for Chris before pushing the live landing page).
• Region 2 — The Hush (cold): 6 rooms, spider/shooter/tank/brute, Rime ally → beam, Hush Warden. story.json 15 rooms/2 regions. DONE.
• Region 3 — Live Wire (lightning): Vex rival (hostile encounter → ally NPC grants scatter), chaotic arenas, Warden. DONE.
• Region 4 — The Null Core (void finale): the Null made flesh, final Warden, ending dialogue. DONE — 27 rooms / 4 regions.
• Warden HP scaling — per-region hp_mult (Ember 750 → Null 1725); BossState.max_hp so enrage stays relative. +1 test.
• DEPLOY BUILD 34 — full campaign synced + built + installed to the Apple TV (runs on next wake). tvOS gameplay is gitignored (build shell), so no tvos gameplay commit — source is in main.
• Victory state — is_end room → StoryState.complete → ResultsPanel.show_victory (“ASCENT COMPLETE”). +1 test. DONE.
• CLAUDE.md docs — full “## Storyline mode” section (seam, types, authoring, skills). DONE.
• DEPLOY BUILD 35 — full campaign + victory state built + installed to the TV.
• Polish: give_pulse early (ranged from room 1), 2 more secrets (Hush/Live Wire heals), extra taunts, region TITLE CARDS (cinematic domain intros). DEPLOYED BUILD 36 + 37.
• STORYLINE MODE FEATURE-COMPLETE & DEPLOYED (BUILD 37). Stopped here — remaining ideas need Chris’s playtesting feel, not blind autonomous work.

Deferred / next steps (need playtesting — for Chris)

• Per-Warden attack variety — all 4 Wardens share one BossState attack set (swing/barrage/missiles/spiral). Bias per region for distinct fights. Risky-blind; do WITH playtesting.
• Checkpoints — a 4-domain run that restarts from the menu on death is punishing. Resume at the current domain’s entry (or last safe room) would help. Moderate code; feel-dependent.
• Survive/escort/timed encounter types — the director only does “kill all waves”; a survive N seconds clear variant would add locked-room variety. Testable, low-risk — a good next chunk.
• Encounter difficulty tuning — Warden HP (750→1725) + wave counts are first-guess; tune by feel on the TV.
• WEB demo — NOT redeployed: the start menu changes the public landing-page demo from auto-attract → menu (a UX decision for Chris). When ready: scripts/deploy-demo.sh + update the site changelog to BUILD 37.
• turret weapon — the one weapon not story-granted (6-weapon cap reached by pulse/nova/orbit/beam/scatter). Could swap into a region or raise the story cap.

Running log (newest last)

• C1 (00:49): Spec + plan + bh-dev-chunk skill + caffeinate(pid 69378) + loop scheduled. Survival baseline untouched (no sim change yet).
• C2 (~00:55): map model — StoryData/StoryState, auto-generated walls + gates, +7 tests. 65 scripts/330. Baseline intact.
• C3 (~01:05): loader — StoryLoader fail-loud validate + StoryData.from_dict + data/story.json Ember slice, +9 tests. 66 scripts/339. Baseline intact.
• C4 (~01:18): wall collision + Sim story seam (enable_story/_resolve_walls), all guarded by story null-check. +5 tests. 67 scripts/344. Survival baseline VERIFIED byte-identical.
• C5+6 (~01:23): StoryDirector — room tracking/gating/scripted waves/clear/reward. +5 tests. 68 scripts/349. Baseline intact. Chunk 7 (dialogue) mostly absorbed.
• Skill reflection: no new ritual repeated 3×+ yet; bh-dev-chunk still the only skill. Next: render chunks (8 dialogue box, 9 map) toward a visible/playable slice.
• C8+9 (~01:39): render layer — DialogueBox (typewriter) + StoryMapRenderer (rooms/walls/sealed gates), wired into main inert-when-off. +7 tests. 70 scripts/356. Baseline intact.
• C15 (~01:44): mode select StartMenu (Story/Survival) + main wiring (enable_story, human-plays, headless auto-survival) + HUD objective. +5 tests. 71 scripts/361. STORY MODE PLAYABLE. Baseline intact.
• Skill reflection: the upcoming tvOS+web DEPLOY dance is the next ritual to capture as bh-deploy. Render-wiring-into-main is light, not skill-worthy yet.
• C10+13 (~02:00): NPCs (meet-to-talk reward, Echo→nova) + story weapons reward-only. +5 tests. 72 scripts/366. Baseline intact.
• C14 (~02:06): rich Ember Reach — 8 rooms, 5 escalating encounters → Warden; clamp_arena + spawn_story_boss. +1 test. 72/367. Baseline intact.
• DEPLOY (~02:10): BUILD 33 synced to tvOS (whole tests/ dir) + verified (72/367) + export-pack + xcodebuild SUCCEEDED + devicectl install OK (TV asleep, runs on wake). tvOS repo committed (6796e46). bh-deploy skill written. WEB deferred (menu vs attract UX — flag for Chris).
• Skill reflection: captured bh-deploy (2nd skill). Now: C12 secret areas (false-wall non-colliding doors → secret weapon), then regions 2-4 + per-Warden attack variety + polish.
• C12 + Region 2 (~02:24): secret areas (false-wall → bonus orbit) + The Hush (cold domain, Rime ally→beam, 2nd Warden). +3 tests, story.json 15 rooms/2 regions. 73 scripts/370. Baseline intact. NOT yet deployed (batching regions for one deploy).
• Regions 3+4 + tuning + DEPLOY (~02:43): Live Wire (Vex) + Null Core (finale) → 27 rooms/4 regions; per-region Warden HP scaling. 73 scripts/371. BUILD 34 (full campaign) BUILT + INSTALLED to the Apple TV. tvOS gameplay gitignored (build shell) → no tvos commit, source in main. caffeinate pid 69378 still holding.
• The CORE GOAL IS DELIVERED: a complete, playable 4-domain storyline mode is live on the TV. Remaining time → polish: VICTORY state, document storyline mode in the project CLAUDE.md, maybe per-Warden variety / more secrets.
• Victory + docs + BUILD 35 (~02:58): ASCENT COMPLETE victory screen on campaign completion (+1 test, 73/372); full storyline-mode docs in CLAUDE.md; BUILD 35 built+installed to TV. caffeinate pid 69378 still holding.
• Polish + title cards + BUILD 36/37 (~03:16): pulse from room 1, 2 more secrets, region title cards (cinematic domain intros). 74 scripts/375. Deployed BUILD 36 then 37 to TV. STORYLINE MODE COMPLETE — stopped here (further work needs playtesting).