Tutorial Status Teaching

Tutorial Status Teaching

Owner: Joel Zhan (@Joel9368), Team 2
Sprint: 4
Task: #448, under #439
Implementation: #501, delivered through #531.
Reviewed: 21 October 2026 against main 80a33a33.

Player flow

The active tutorial now teaches a real status effect after the highlighted Strike and Enemy Health explanation. One existing Poison Dagger is placed immediately to the right of the demonstration Strike in the opening hand. This arrangement applies to the tutorial's temporary deck; normal battle shuffle and persistent card ownership are preserved.

flowchart LR
    A[Enemy Health] --> B[PLAY_POISON_CARD]
    B -->|Successful designated card play| C[POISON_ANIMATION]
    C -->|Poison active and visuals settled| D[STATUS_EFFECTS]
    D --> E[Enemy Armour and remaining lessons]

Loading

The designated card, enemy and drag direction use the existing dimming and highlights. Playing another card, rejecting a drop or tapping the prompt does not complete the Poison action gate. The next lesson highlights the actual enemy status row after the effect exists and its animations finish. The status hover panel remains readable above the teaching overlay.

The status-row prompt is deliberately general. Per-effect details come from the existing live hover UI and card descriptions: the icon number shows stacks, while remaining turns are shown separately; expired applications disappear. Poison deals damage at enemy turn start and bypasses Block and Armour. The tutorial demonstrates production rules rather than granting a scripted replacement effect.

Implementation and ownership

The reviewed tutorial sources and screens/BattleScreen.java provide the implementation.

Component	Sprint 4 integration
BattleScreen.setupTutorialGuidance	Passes exact Strike/Poison instance IDs and observations of HP, active Poison and settled visuals.
BattleTutorialController / BattleTutorialComponent	Gate the lesson on the exact successful play, then status/animation readiness; connect to existing event/lifecycle handling.
BattleTutorialPrompt / BattleTutorialGuidanceView	Provide the new prompts, designated-card input gate, drag cues and live status-row target.
TutorialStatusTeachingIntegrationTest	Plays real configured cards and checks effect damage, duration/expiry, survival and source-deck preservation.

Joel owns this teaching extension and its integration. Zixuan owns the original progression module, Jun the original guidance UI, and Yihan the shared wording foundation. Team 1 owns enemy/status behaviour and the Votive Attendant tutorial AI. See Team 1's integration page; the older ordinary-Bone-Crawler descriptions belong to the Sprint 3 snapshots.

Verification

PR #501, head 1e1b2820, records successful Core tests, Spotless and Desktop classes, plus in-game status-lesson and tutorial pause-menu checks. Controller/component tests cover rejected/wrong-card plays and readiness gates; view tests cover the exact card, fixed prompt and moving status target. The live battle test checks Poison countdown/expiry and preservation of the source deck.

These are retained results, not a new full manual run for this documentation update. No separately retained Poison screenshot is published here; #501 and the named tests are the evidence for this lesson. The shared acceptance plan separates these results from final combined-flow manual verification.

Changes from plan and reflection

Dedicated Status teaching was deferred in Sprint 3. Sprint 4 connects an existing representative effect to an actual playable card and the live status display. A text-only explanation could advance without demonstrating an effect, so the implementation requires successful play, active Poison and completed animations. This makes the lesson observable and testable. Keeping detailed effect rules in shared hover descriptions avoids competing copies of balance values in tutorial text. Drawing and a full dedicated win/loss lesson are not implied by this Status delivery.

Related documentation

• Battle Tutorial Steps and Progression
• Battle Tutorial Guidance UI
• Card Keyword Tooltips
• Tutorial Victory Screen

Codex assisted with implementation/documentation work, as disclosed in the achievement form. This page distinguishes Joel's extension from the shared systems and retained verification evidence.