Battle Tutorial Steps and Progression - UQcsse3200/2026-studio-3 GitHub Wiki

Battle Tutorial Steps and Progression

Team: Team 2 Owner: Zixuan Yang (@yangzixuan840-gif) Sprint: 3 Feature: #339 - New Player Battle Tutorial and Contextual Event Help Related integration task: #365 Integration branch: Feature-2-Sprint3-TutorialTooltips Main integration: PR #418, merged 7 October 2026 Last updated: 7 October 2026

Overview

This module observes real battle actions and connects tutorial steps to prompts; it does not own enemy AI, battle rules, deck mutation or fresh-run navigation.

Zixuan implemented the original controller, prompt mapping, event binding, view contract, component cleanup and focused tests in #399, then applied Yihan's review in #401. Guoqing connected the isolated scene in #402. Jun's #410 added the positioned UI and revised reference sequence now used by that scene. Yihan supplies shared teaching text; Joel owns New Game routing and the fresh-run transition. Later UI updates are in #412 and #414.

The integrated tutorial is now available in main through #418. Publication does not mean that every original teaching requirement, safety guarantee, or manual acceptance scenario is complete.

Scope Change - Next Sprint

The original plan included dedicated Buff/status-effects, drawing/draw-pile and full win/loss-rule lessons. The team has decided to add those lessons in the next Sprint. They are deferred teaching work, not completed Sprint 3 lessons. Prepared shared wording and legacy step definitions do not mean these lessons are connected to the current graphical route.

Existing combat, Buff, drawing and victory/defeat mechanics are unchanged; only the extra teaching is deferred. End Turn is optional in the current route. Team 1's tutorial-safe enemy remains a separate later integration under #365; do not claim that the ordinary enemy prevents player death or guarantees every explanation is visited.

Current Implementation Status

Checked against main merge commit 3c6f656c, which integrates PR #418's head e23f1c2f. The earlier group-build references are historical, not the current publication status.

Area	Status and evidence
Step controller and shared view contract	Implemented in #399/#401; present in main through #418.
Dedicated tutorial battle	Connected by Guoqing in #402; ordinary bone_crawler and disposable RunState.
Positioned guidance	Connected by Jun in #410. The current scene uses BattleTutorialGuidanceView, not the temporary text view.
Active reference route	Four-argument component constructor with the exact demonstration card instance and live observations.
Buff, drawing, full win/loss lessons	Deferred to the next Sprint.
Team 1 tutorial-safe enemy	Not integrated into this checked main build; the current enemy is ordinary bone_crawler.
Latest-build integrated manual acceptance	Shared T1-T12 execution results remain NOT TESTED in the acceptance page at the time of this update.
Publication to main	Completed through #418 on 7 October 2026.
Personal PR review	No formal review submissions found on #399/#401 at the time of this update; independent post-merge checking remains useful.
Scene-level follow-up	Queued outcome navigation and tutorial item-inventory isolation require fixes/verification; see below.

Player Flow and Step Sequence

New Game -> Enter Tutorial -> isolated guided battle. Skip Tutorial starts a fresh normal run through opening narration and then the Map.

Step	Teaching or observation	How it advances
HAND	Welcome and the five-card hand	Continue
CARD_INVENTORY	View/manage battle cards	Continue
ENERGY	Energy used to play cards	Continue
CARD_COST	Highlighted card's energy cost	Continue
PLAY_A_CARD	Drag the highlighted Strike onto the enemy	Successful play of that exact demonstration copy
CARD_ANIMATION	Observe the resolved hit	Enemy HP falls below initial snapshot, visuals settle and phase is PLAYER_TURN
ENEMY_STATS	Enemy health and armour	Continue
USED_CARD	Used-card availability/cooldown	Continue
END_TURN	End-turn instruction	Continue may skip; actual PLAYER_END enters ENEMY_ANIMATION
ENEMY_ANIMATION	Enemy action, when End Turn is chosen	Settled visuals and return to PLAYER_TURN
HEALTH	Player health and incoming damage	Continue
FREE_PLAY	Continue the fight without teaching overlays	Real battle result or Exit Tutorial; Exit remains available

After HEALTH, the normal route goes directly to FREE_PLAY. BUFFS, CARD_DRAW and BATTLE_OUTCOME_RULES remain defined but are not dedicated lessons on this route. Short health prompts do not replace the deferred full outcome lesson.

Progression Rules

Rejected card plays do not satisfy PLAY_A_CARD. A drag/click alone does not count.
The reference route targets the exact demonstration Strike instance. Another card does not satisfy that gate.
Continue cannot bypass PLAY_A_CARD or animation-resolution waits. END_TURN can be skipped in this version.
Battle input is not globally disabled while explanations are displayed. The legacy early-action memory is not the active reference route's teaching contract.
Starting twice does not reset the controller. Its first terminal outcome is retained.
A real battle result can end teaching early. This does not prove every explanation was visited. Final acceptance must check the current route and early outcomes.

Main Classes

Source files are under source/core/src/main/com/csse3200/game/tutorial/ in the published main build. The group branch remains an integration reference.

Class	Responsibility
`BattleTutorialController`	Holds the current step, remembers successful actions, observes battle events, and reports `WON`, `LOST`, or `CANCELLED`.
`BattleTutorialPrompt`	Maps each step to its text, semantic highlight target, and `canContinue` flag.
`BattleTutorialComponent`	Connects the controller to a view and the entity lifecycle; defers completion and cleans up before notifying the scene.
`BattleTutorialView`	Shared interface for the guidance UI.
`BattleTutorialPromptContent`	Yihan's shared battle explanations and the reviewed action instruction.
`BattleTutorialGuidanceView`	Jun's active positioned guidance and highlights.
`BattleTutorialObservation`	Live enemy/player HP and presentation-settled probes supplied by the scene.
`BattleTutorialTextView`	Retained legacy/provisional view; not used by the current scene.

BattleController also provides matching removal methods for card-play, phase-change, and battle-end listeners. Cleanup removes only this tutorial's listeners and leaves other battle observers attached.

UI Interface for Jun

public interface BattleTutorialView {
  void bindActions(Runnable continueAction, Runnable exitAction);
  void show(BattleTutorialPrompt prompt);
  void clear();
}

Prompt field	Meaning for the UI
`step()`	Current tutorial step. Use the current `CARD_DRAW` name, not the old `DRAW_AND_TURNS`.
`text()`	Wording to display. The UI should use this value instead of maintaining a second copy.
`highlight()`	Semantic target to resolve against the live battle UI, not a fixed pixel rectangle.
`canContinue()`	Whether Continue is available. In reference mode END_TURN is skippable; PLAY_A_CARD remains a real-action gate.

The view should update text and highlighting together. Recalculate target bounds when the window resizes or the hand is rebuilt. If a target is not visible, such as an inactive status-effect row, still display the explanation without blocking the tutorial. Prompts must not cover the cards or buttons the player needs to use.

clear() must be safe to call more than once. Remove the tutorial's actors, highlights, and UI handlers, but do not dispose the shared Stage, skins, or ordinary battle controls.

The current scene already uses Jun's BattleTutorialGuidanceView. referenceStep supplies its concise route prompts, while forStep retains the shared/default mapping. FREE_PLAY removes teaching overlays but retains Exit Tutorial. Verify alignment, drag/hover and supported window sizes in the integrated build.

Battle and Scene Integration

The active BattleScreen supplies BattleController, BattleTutorialGuidanceView, its outcome callback and the exact demonstration card ID to the four-argument BattleTutorialComponent constructor. It supplies BattleTutorialObservation before entity registration, then starts combat after guidance is registered. The three-argument constructor retains the older default route; it is not the current scene setup.

The component binds successful-play, phase-change and battle-end listeners. It polls resolved enemy HP, player HP and presentation-settled observations. The view must not report successful play merely because a card was clicked or dragged.

Completion and Cleanup

Path	Current scene behaviour
WON	game.startNewRun(): dispose tutorial, reset run, opening narration, fresh Map.
Exit Tutorial / CANCELLED	Same fresh-run path.
LOST with ordinary enemy	Main menu fallback.
ESC pause-menu exit	Main menu and guidance disposal, without intentionally starting a new run.

In reference mode, victory/defeat clears the view and the scene's separate battle-end listener owns navigation. Voluntary cancellation uses the component's deferred completion path. Component dispose()/controller close() are silent and idempotent, remove only this guide's observers, and cancel this component's own queued completion.

That component protection does not prove every scene callback is guarded. In the checked main build, the separate BattleScreen battle-end listener queues onTutorialFinished without an explicit disposed/transition-once guard. A callback queued before exit can still attempt navigation afterward. Guoqing and Joel should coordinate a screen-level guard and listener cleanup; Zixuan can support the regression tests. This is a static code-review finding, not a manually reproduced failure in this update.

The item-inventory wiring also passes game.getRunState() to InventoryPopupComponent, rather than the screen's temporary runState. This means tutorial isolation must not be claimed for every inventory interaction: an existing run's consumable items can be exposed to the tutorial. The screen owner should use the screen-scoped state and verify that tutorial use/exit leaves persistent inventory unchanged, while normal battles still use the real run.

These findings are recorded in the #418 review. Merging the PR does not resolve them. Follow-up evidence should link the fix commit, tests and actual acceptance results.

The tutorial module does not own map-node completion, rewards, autosave or run reset. Joel and Guoqing own those routes.

Review Changes and Design Decisions

Observe real battle events instead of interpreting rejected plays or UI clicks as successful actions.
Separate controller and presentation, and remove only this guide's listeners during cleanup.
Apply Yihan's review in #401: a separate PLAY_A_CARD instruction and CARD_DRAW naming. This describes the historical shared/default contract.
Jun's later #410 integration introduced the demonstrated-Strike reference route, animation/damage observations and optional End Turn. Its current sequence differs from #399/#401.
Defer dedicated Buff/status, drawing and full win/loss lessons to the next Sprint by the team's scope decision. Preserve prepared content, but do not count it as delivered graphical teaching.
Reuse Joel's shared fresh-run route, including Team 6 opening narration. The step controller itself does not launch the story.

Existing drawing and combat rules remain unchanged.

Testing and Evidence

Evidence	Recorded verification
PR #399	84 focused tests passed locally; Spotless and `git diff --check` passed.
PR #401	85 focused tests passed locally after the prompt/step review changes; Spotless and `git diff --check` passed.
PR #402	Guoqing's scene integration; PR-head unit-test and formatting workflows passed.
PR #410	Jun's reference route, damage gating, optional End Turn and UI tests; PR-head workflows passed.
PR #412 / #414	Later UI integration; PR-head unit-test and formatting workflows passed.
PR #418	Published the integrated tutorial to main. The PR records 2,034 passing core tests and desktop compilation; its checked head has successful Game Unit Tests, Java Format, Javadoc Test Build and SonarCloud workflows. These are retained records, not new local executions for this Wiki update.

The 84/85 counts describe historical focused runs, including related battle and game tests. They are not tutorial-only counts or fresh executions. No tests or manual gameplay were rerun for this Wiki update. Distinguish legacy-sequence coverage from the active reference route. Component queued-callback tests do not automatically cover the separate BattleScreen callback.

Run from source with the project's JDK 21 setup:

.\gradlew.bat :core:test --tests "com.csse3200.game.tutorial.*" --tests "com.csse3200.game.components.combat.BattleControllerTest" --tests "com.csse3200.game.components.battle.BattleActionsTest" --tests "com.csse3200.game.GdxGameTest" spotlessCheck --offline --console plain --max-workers=2

The offline flag assumes dependencies are already cached. Test sources are available in the published tutorial test directory.

Test class	Coverage
`BattleTutorialControllerTest`	Exact step order; unskippable action gates; early-action memory; turn-before-play ordering; repeated outcomes; cancellation; listener removal.
`BattleTutorialPromptTest`	Shared text mapping, highlight keys, Continue availability, and terminal prompts.
`BattleTutorialPromptContentTest`	Eight concept prompts and the separate affordable-card instruction.
`BattleTutorialComponentTest`	View wiring; deferred completion; cleanup before callback; disposal cancelling queued navigation; stale callbacks; duplicate creation.
`BattleTutorialBattleIntegrationTest`	Real `BattleController`/card-play integration: insufficient energy does not advance, valid play and End Turn do, and cleanup preserves other observers.

Manual step-progression and cleanup scenarios are recorded in Tutorial Acceptance Test Plan. That page still has no completed T1-T12 execution record for the published main build. No new manual PASS is claimed by this documentation update. Record the exact tested commit, date/environment, actual result, and screenshots or logs before updating a scenario's status.

In addition to the existing plan, retain focused regressions for:

A victory callback queued before tutorial screen disposal: draining the queue must not navigate from the old screen.
Exit Tutorial and victory occurring together: at most one transition/new run is allowed.
An existing normal run with consumable inventory: entering, using items in, and leaving the tutorial must not consume persistent items; verify normal-battle inventory still works.

Independent Review

#418 has formal approvals from other contributors, including Team 1, and a Comment review identifying the scene-level issues above. This is group integration review evidence, not a substitute for inspecting each personal change. #399/#401 currently have no formal review submissions. Reviewers should check the controller/action gates, prompt mapping, listener cleanup and tests, and describe any later inspection as post-merge review, not a pre-merge approval.

Remaining Integration Work

Zixuan and Guoqing: execute and record the current reference route, rejected actions, optional End Turn, early outcomes, exits and repeat entry against the published main build.
Guoqing and Joel, with Zixuan supporting tests: resolve and verify scene-level stale/duplicate outcome navigation and tutorial item-inventory isolation.
Jun: retain final highlight, drag/hover and window-size checks for the published build.
Zixuan: request independent checking of #399/#401 and update this page with actual review/fix evidence when available.
Team 2: keep documentation, feature/task statuses and acceptance evidence aligned with #418's completed main integration; rerun relevant regressions after follow-up fixes.
Next Sprint: connect Buff/status, drawing/draw-pile and full win/loss lessons with prompts, highlights and progression tests.
Later Team 1 integration: safe tutorial enemy, reachable victory and isolation from ordinary battles.
Do not mark unexecuted manual tests or later work as complete.