New Player Battle Tutorial and Contextual Event Help - UQcsse3200/2026-studio-3 GitHub Wiki

Overview

Team: Team 2
Sprint: Sprint 3
Feature issue: #339 — New Player Battle Tutorial and Contextual Event Help
Integration branch: Feature-2-Sprint3-TutorialTooltips

This feature introduces an optional tutorial battle for new players and contextual help for selected non-battle encounters. This page provides the overall scope, player flow, documentation ownership, and integration responsibilities. Each contributor maintains the implementation details and test evidence in their own linked page.

Scope Update - 7 October 2026

The original plan included dedicated Buff/status, drawing/draw-pile and full battle win/loss-rule teaching. The team has decided to add these lessons in the next Sprint. Prepared shared text and legacy step definitions do not mean those lessons are delivered in the current player-facing route. Existing combat mechanics remain unchanged.

The current route covers the hand, Card Inventory, energy, cost, the highlighted Strike, resolved damage/enemy stats, used-card cooldown, optional End Turn and health, followed by free play. Jun's positioned guidance is now integrated (#410, #412); #414 adds later scene polish. The steps page and acceptance plan describe this active reference route.

The checked group build is 3f880bd8. Final latest-build manual acceptance, independent review and publication of this tutorial feature to main remain pending. Team 1's safe-enemy behaviour is separate later integration under #365; the current ordinary enemy does not establish the no-player-death guarantee.

Intended Player Flow

New Game and Tutorial Choice

  1. The player selects New Game from the main menu.
  2. A dialog offers Enter Tutorial and Skip Tutorial.
  3. Skip Tutorial starts a fresh normal run, including the opening narration and map.
  4. Enter Tutorial opens a dedicated tutorial battle without requiring the player to select a map node.
  5. Winning the tutorial or selecting Exit Tutorial transitions into a fresh normal run through opening narration and then the Map. ESC exit returns to the main menu; loss against the current ordinary enemy also returns to the main menu. Early victory can end teaching before every explanation is visited.

The tutorial battle should remain separate from normal map progression, battle rewards, and run state.

Battle Tutorial

The current tutorial explains the hand, Card Inventory, costs, energy, resolved attacks, used-card availability, optional End Turn and health. Dedicated status-effect, drawing and full outcome lessons are deferred as described above.

The play-card step responds to a successful play of the highlighted demonstration Strike. End Turn may be performed or skipped in this version. The guidance interface displays the current instruction and highlights relevant battle elements.

Contextual Event Help

Optional help is provided for the Dice Event and Card Fusion Event. Players can open and close the help without changing the encounter outcome or interrupting its normal interaction.

Documentation and Ownership

Documentation page Owner Main responsibility
Tutorial Entry and Fresh Run Transition Joel New Game choice dialog, entry events, Skip Tutorial, and fresh-run transition
Tutorial Battle Setup and Enemy Integration Guoqing Dedicated tutorial battle, enemy setup, battle outcomes, and Team 1 integration
Battle Tutorial Guidance UI Jun Instruction display, highlights, Continue and Exit controls, and UI integration
Battle Tutorial Steps and Progression Zixuan Tutorial step sequence, gameplay event handling, and progression conditions
Contextual Event Help and Tutorial Content Yihan Tutorial wording and optional help for Dice and Card Fusion encounters
Tutorial Acceptance Test Plan Team 2 Integrated manual test scenarios, actual results, screenshots, and regression checks

The owners listed above follow the current task allocation. Update this table if responsibilities change.

Cross-Team Integration

Team 2

Team 2 implements the tutorial entry, battle setup, instruction flow, guidance UI, contextual help, and transitions back into a normal run.

The initial integrated tutorial uses an existing ordinary enemy so that the complete player flow can be developed and tested.

Team 1

After the Team 2 flow is ready for integration, Team 1 adds the agreed tutorial enemy behaviour to prevent player death and ensure the tutorial can be completed.

Tutorial-specific enemy behaviour should not change the behaviour of enemies in normal battles.

Record the final enemy configuration and activation method in Tutorial Battle Setup and Enemy Integration.

Integration Documentation

Each implementation page should describe:

  • Relevant classes, methods, and events.
  • Interfaces used by other contributors.
  • Dependencies and integration assumptions.
  • Current implementation status and remaining work.
  • Related issues and pull requests.

Update the documentation when an interface changes so that other contributors can integrate against the current implementation.

Testing and Evidence

Maintain shared manual test scenarios and execution records in Tutorial Acceptance Test Plan.

Each execution record should include:

  • The tested branch and commit.
  • The test date and environment.
  • The steps performed.
  • Expected and actual behaviour.
  • Screenshots or relevant logs.
  • A status of PASS, FAIL, NOT TESTED, or BLOCKED.

Only mark a scenario as PASS after it has actually been tested. Successful compilation or CI alone does not confirm that the gameplay flow works correctly.

Related Work