Tutorial lesson track (2026-09-24)

Tutorial lesson track — design

Status: approved by Chris, 2026-09-24 (“yes go ahead”, option A of A/B/C).

Brief

Chris: “do an overhaul on the tutorial, see if you can make it flow better and make it clearer as to what is happening and who is talking and what needs to be done, adjust the text, everything, and we need to gate all features and weapons properly so that the player is really stepped through it only one thing at a time.”

Findings that drive the design (headless trace + read-only audit, 2026-09-24)

• 12 teaching beats fire in the first 13.6 s of sim time (story_trace.gd, seed 1234), several under a second apart; then a 50 s Warden fight teaches nothing. Two weapons (Pulse, Nova) are gifted ~10 s apart.
• Only movement completion is detected. Aim, warp, decoy are described but never checked; pickups have no “fly over it” prompt.
• radar_intro fires when an enemy exists, but radar V2 only shows OFF-screen threats, so the glow it names is usually absent. crystal_intro says “Those are crystals” but crystals only come from level-up cards and no live HUD shows them.
• Speakers: Echo and the Ember Warden both render initial “E”; The Null renders “T”; Ash’s orange and the Warden’s red are close; Ash and The Null are never introduced; Echo voices all system teaching.
• Ungated in the tutorial: pause Shop/Ship/Bestiary; codex (C) and HUD-toggle (Y/V) hotkeys; controller X debug overlay (no dev check); first-sighting “NEW ENEMY” cards; crystal threshold auto-upgrades and evolutions; the level-up panel’s why-tags / RECOMMENDED / Y stats sheet (never explained); meta ship perk, decoy type and drone loadout (a replaying player’s decoy differs from what is taught).
• Control tokens resolve by PLATFORM, not the device in use (a Mac player on a controller is told “WASD”); controller strings hard-code “(RB)/(LB)”; dialogue says “decoy” while the touch button says DRONE.
• Gates open when a beat is QUEUED, not when it is read (story_director.gd:347).

Design

1. Lessons (one unlock + one checked objective each)

#	Lesson	Unlocks	Objective (detected by the game)
1	Wake up	movement	Fly to Echo
2	Blaster	auto-weapon, weapon dock	Fly over the Blaster to pick it up → Destroy 5 drones
3	Level up	XP, level-up panel (stat cards only)	Collect XP → Pick a card (first-time tag explainer on the panel)
4	Ship stats	Y/Tab stats sheet	Next level-up: open the stats sheet → pick a card
5	Rift Bolt	manual aim weapon	Hit 3 enemies with the Rift Bolt
6	Warp	warp/dash	Warp once while an enemy is close (chargers spawned)
7	Decoy	decoy (meter starts full for the lesson)	Send out a decoy → survive 10 s
8	Crystals	crystal cards + threshold upgrades/evolutions	Pick the (guaranteed, LONG-TERM-tagged) crystal card → see its bar in the stats sheet
9	A found weapon	Nova	Fly over Nova → destroy 30 Mites with Nova (2026-09-27: was 8 Weavers, which showed no Nova edge; now dense Mite bursts the Blaster can’t keep up with)
10	The Warden	nothing new	Defeat the Ember Warden (decoy / still-heal tips only when struggling) → hand-off to Survival

• The Pulse gift is removed from the tutorial. The optional hidden Orbit room stays (optional, no lesson).
• A lesson advances only when its objective completes, then a ~1.5 s “done” beat before the next.
• Enemy spawns are scripted per lesson so each objective is achievable and nothing else competes.
• Surplus level-ups keep the existing hold-back behaviour; the level-up panel stays locked until lesson 3.

2. Objective panel (new)

A small clear-glass bar, top centre, shown in tutorial runs only: LESSON 5 OF 10 · RIFT BOLT / Hit 3 enemies with the Rift Bolt [prompt] 2/3. The control prompt is a ButtonGlyph for the device in use; progress counts where the objective has a count; a tick animation on completion. It never overlaps the dialogue box or the level-up strip.

3. Dialogue and speakers

• Dialogue carries story/flavour only, 1-2 short lines per beat. Instructions live in the objective panel.
• Each speaker has a name, a role subtitle and a drawn emblem (no initials): Echo, gold diamond, “your guide”; Ash, orange flame, “Ember raider”; The Null, purple hollow ring, “the dark”; Ember Warden, red crown, “boss”. Allies speak from the left, enemies from the right.
• Every villain’s first line says who they are.
• Control prompts in any text resolve by the LAST-USED input device and render as drawn glyphs (ButtonPrompt); no hard-coded RB/LB.
• Gates open when the beat’s dialogue is READ (dismissed), not when it is queued.

4. Gates (tutorial runs)

Locked until their lesson: weapon dock, aim, warp, decoy (and Drone Bay), level-up panel, stats sheet, crystal cards, crystal threshold upgrades/evolutions, Nova. Locked for the whole tutorial: pause Shop / Ship / Bestiary entries, codex (C) and HUD-toggle (Y/V) hotkeys, first-sighting NEW ENEMY cards, co-op join, dimension choice (already), shop-unlocked weapons (already). Controller X debug overlay becomes dev-build only everywhere. The tutorial ignores the saved ship perk, decoy type and drone loadout (starter loadout, so the run matches what is taught). The threat radar is explained as a contextual TIP the first time an enemy is actually off-screen, not as a lesson.

5. Text

Every tutorial line rewritten: plain English, short sentences, one idea each, second person, true to the sim. No em dashes.

Testing

• tools/story_auto/story_trace.gd must finish the tutorial and print lessons in order with no two lessons’ unlocks in the same lesson; extend StoryAutoPlayer so it performs each objective (aim, warp, decoy, pick-ups, stats sheet) where needed.
• GUT: each lesson’s objective detection through the real sim path; each gate refuses before its lesson and allows after; beat-read (not queue) gating; speaker emblem/role mapping; device-based prompts.
• Determinism baselines unaffected (story mode is not in them) — verify both still pass.
• Device-scale (1280×720) captures of the objective panel + dialogue per lesson; Chris playtests pacing.

Out of scope

Story mode beyond Ember Reach; new art; changes to Survival balance; voice audio.