Tutorial Entry and Fresh Run Transition - UQcsse3200/2026-studio-3 GitHub Wiki
Overview
Contributor: Joel Zhan (@Joel9368)
Team: Team 2
Sprint: 3
Task: #364 — New Game Tutorial Entry, Fresh Run Transition and Help UI Polish
Feature: #339 — New Player Battle Tutorial and Contextual Event Help
Integration branch: Feature-2-Sprint3-TutorialTooltips
Last updated: 9 October 2026
My contribution provides the New Game tutorial choice, the shared transition into a fresh normal run, and pixel-art polish for the tutorial-choice dialog and Dice/Card Fusion Help controls. The entry/reset work was integrated through PR #377 and PR #398. The visual polish was merged from tutorial-help-ui in PR #412.
The tutorial/tooltips group branch was merged into main on 7 October 2026 through PR #418, with merge commit 3c6f656c. Earlier verification records below refer to their original PRs/builds. Joel's entry and fresh-run acceptance checks were completed on 9 October 2026 against the frozen submission commit. Results, screenshots and the selected reset-test output are linked under Final Integrated Acceptance. Team 1 safety acceptance remains separate.
Ownership and Integration
| Contributor | Responsibility |
|---|---|
| Joel | New Game choice, shared fresh-run reset/transition, tutorial-choice styling, and Dice/Fusion Help visual polish. |
| Guoqing | Dedicated tutorial battle, isolated battle state, outcome handling, and safe-enemy integration under #365. |
| Yihan | Reusable contextual Help behaviour, Event rule text, and shared tutorial wording under #392. |
| Jun | In-battle guidance presentation and later scene UI changes. |
| Zixuan | Tutorial step progression and battle-event integration. |
| Team 1 | Tutorial-specific safe enemy behaviour. |
The live teaching scope follows the 7 October revision in #339. Dedicated Buff/status, drawing/draw-pile and full win/loss lessons are deferred to the next Sprint. The current ordinary Bone Crawler does not establish the planned no-player-death guarantee.
Player Flow
flowchart TD
M[Main Menu] --> N[New Game choice]
N -->|Skip Tutorial| R[Shared fresh-run reset]
N -->|Enter Tutorial| B[Isolated tutorial battle]
B -->|Victory or voluntary Exit Tutorial| R
B -->|Loss or ESC exit| M
R --> O[Opening narration]
O --> P[Fresh Map]
New Game shows Enter Tutorial and Skip Tutorial before a normal run starts. Enter launches the teaching battle without selecting a Map node. Skip uses the existing normal-run path. Tutorial victory and voluntary Exit Tutorial call the same fresh-run method.
In the frozen build, Health is followed by End Turn guidance. Dismissing the End Turn explanation allows free play without ending the actual turn or starting a normal run. The battle may continue until victory, loss, or a supported exit.
Entry and Fresh-Run Implementation
| Component | Interface or behaviour |
|---|---|
| MainMenuDisplay | Builds the choice dialog and emits separate normal-start and ENTER_TUTORIAL_EVENT events. |
| MainMenuActions | Routes Skip to game.startNewRun() and Enter to game.startTutorialBattle(). |
| GdxGame | Provides the shared fresh-run method and the dedicated tutorial screen entry. |
| BattleScreen | Guoqing's outcome route calls the shared fresh-run method for victory or voluntary exit; loss returns to the main menu. |
startNewRun() disposes the outgoing screen before resetting state. This order matters because a battle screen captures its final player values when disposed: disposing after reset could write old tutorial values into the new run.
The method clears the screen reference, calls RunState.endRun(), and plays the opening narration with Map as its destination. The reset discards the previous player/deck state, active Map state, pending rewards, pending Temple reward and per-run Fusion allowance. The normal Map path then creates the standard starting state.
The GdxGame reset regression modifies the old player, deck, items and pending rewards, and simulates another state capture during screen disposal. It verifies that disposal happens before reset, the opening story appears before Map, and the new player/deck use the normal defaults.
Tutorial Choice and Contextual Help UI Polish
The original placeholder controls were replaced with matching pixel-art assets:
| Asset | Use |
|---|---|
images/context_help_icon.png |
Shared question-mark control for Dice and both Fusion Help entry points. |
images/context_help_rules_frame.png |
Dice and Fusion rules-dialog frame. |
images/tutorial_choice_frame.png |
New Game tutorial-choice frame. |
Existing images/ancient_temple_choice_button.png |
Close, Enter Tutorial and Skip Tutorial button backgrounds. |
The rules dialog uses a separate title/body layout and a styled Close button. The same Help styling is used in the Dice Event, Fusion introduction, and Fusion card-selection view.
PixelButtonStyles supplies shared feedback with nearest-neighbour texture filtering. Hover brightens and enlarges the artwork; pressing darkens it, slightly shrinks it and shifts it down. These changes affect drawing while preserving the control's layout and click area.
ContextualHelpDialog centralises the rules frame, Close styling and Help-button creation. ChanceEncounterDisplay and CardFusionSelectionView reuse it.
This visual work preserves Yihan's Help behaviour and rule text. Opening or closing Help must preserve the active Dice interaction and Fusion selections, deck, allowance and delegated session. Ordinary Chance Events do not gain this contextual Help control.
Recorded Verification
The table below summarises historical PR verification records. The separate 9 October 2026 acceptance run, including one re-executed reset regression, is documented under Final Integrated Acceptance.
| Evidence | Recorded result | Coverage and limit |
|---|---|---|
| PR #377 | Automated suite and manual menu/Skip checks passed. | Choice events, menu routing, disposal-before-reset, initial state and deck. Tutorial battle launch was not connected at that earlier stage. |
| PR #398 | Automated tests, formatting and manual checks passed. | Opening narration -> Map, repeated fresh runs, story skip, and normal card/reward/Event Help regression. |
| PR #402 | Tutorial routing and battle integration checks recorded by Guoqing. | Dedicated tutorial entry, isolated state and outcome wiring; final Team 1 safety is separate. |
PR #412, authored commit 2d7f9b5 |
24 existing Help-related tests passed; formatting/diff and manual UI checks passed. | Dice Help, Fusion introduction/selection Help, closing and state preservation, tutorial-choice styling, hover and pressed feedback. |
| PR #414, Jun's later integration | The PR reports 1,778 core tests, desktop compilation and formatting checks passed. | Later group scene integration retains #412; its final graphical acceptance remains required. |
| PR #418 | Merged into main on 7 October 2026. The PR reports 2,034 passing core tests, desktop compilation, Spotless and whitespace checks on source commit e23f1c2f. |
Group integration evidence; final manual entry, completion, exit and fresh-run acceptance is recorded separately. |
The 24-test figure in #412 consists of ChanceEncounterDisplayTest, CardFusionContextualHelpTest and CardFusionSelectionViewTest. It is contextual Help regression evidence, not a complete tutorial acceptance count.
Manual UI Record for #412
Environment: Windows, Git Bash, Java 21; Gradle cache at C:/gradle-cache.
Recorded date: 7 October 2026.
| Scenario | Recorded result |
|---|---|
| New Game tutorial-choice UI and buttons | PASS |
| Dice Help opening and closing | PASS |
| Fusion introduction Help opening and closing | PASS |
| Fusion selection Help closing with selections retained | PASS |
| Hover and pressed feedback on the styled controls | PASS |
Re-running Relevant Checks
Run project checks from Git Bash with the established Java and cache paths:
cd /e/UQ/CSSE3200/2026-studio-3/source
export JAVA_HOME="/e/Java"
export PATH="$JAVA_HOME/bin:$PATH"
./gradlew -g C:/gradle-cache :core:test --tests 'com.csse3200.game.components.mainmenu.MainMenuDisplayTest' --tests 'com.csse3200.game.components.mainmenu.MainMenuActionsTest' --tests 'com.csse3200.game.GdxGameTest'
./gradlew -g C:/gradle-cache :core:test --tests 'com.csse3200.game.components.chance.ChanceEncounterDisplayTest' --tests 'com.csse3200.game.components.chance.CardFusionContextualHelpTest' --tests 'com.csse3200.game.components.chance.CardFusionSelectionViewTest'
./gradlew -g C:/gradle-cache format
./gradlew -g C:/gradle-cache formatCheck
git diff --check
When recording another run, retain its actual commit, results and test count; newer group changes can change the count.
Final Integrated Acceptance
Executed by: Joel Zhan (@Joel9368)
Execution date: 9 October 2026 (AEST)
Environment: Windows, Git Bash, Java 21.0.4
Tested commit: ff81a12a587472d2a90df0ae922e2d698975cfb6
The Sprint 3 code cutoff was 8 October 2026 at 15:00 AEST. These checks were executed after the cutoff against the frozen main-branch submission commit, including PR #424.
Full execution record, screenshots, automated command and terminal output
| ID | Check | Observed result | Status |
|---|---|---|---|
| J1 | Skip Tutorial → opening narration → Map | Map opened at 100 HP/50 gold; an available node could be entered. No tutorial UI remained. | PASS |
| J2 | Tutorial victory → opening narration → fresh Map | Normal combat victory progressed to Map. HP/gold changed from 95/50 before victory to 100/50. No normal reward screen, stale guidance or duplicate transition appeared. | PASS |
| J3 | Voluntary Exit Tutorial → opening narration → fresh Map | Map opened at 100 HP/50 gold. Tutorial guidance and Exit button were removed; no duplicate transition appeared. | PASS |
| J4 | Re-entry and normal-battle regression | Teaching restarted at the first step without duplicate UI. Normal-battle card dragging, energy changes and turn switching worked; continued play was reported without anomalies. | PASS |
| J5 | Post-transition deck and item comparison | Skip and tutorial-exit paths produced matching 11-card starter decks and empty item inventories. No extra reward screen appeared. | PASS for the tested post-transition state |
| A1 | Existing fresh-run reset regression | One selected test was re-executed and passed; BUILD SUCCESSFUL in 34 seconds. | PASS |
A1 checks disposal before reset, default player state, starter-deck restoration, empty new-run inventory, and clearing of pending rewards, the Temple reward flag and the Fusion allowance. Its evidence is the command and terminal output retained in the linked execution record.
Validation Limits
- These results cover the tested entry, victory, voluntary-exit, re-entry and fresh-run paths. They do not establish complete acceptance of every tutorial requirement.
- Access to an existing normal run's items during the tutorial, rapid exit/victory callback races, ESC interruption and window resizing were not tested in this session.
- One successful playthrough does not establish the planned no-player-death or guaranteed-completion behaviour. These remain separate acceptance requirements under #365.
- Deferred Buff/status, drawing and full win/loss lessons are outside this execution record.
Reflection and Extension Points
Using one fresh-run method keeps Skip and tutorial completion aligned with the game's normal start path. Disposing before reset prevents outgoing screens from restoring old state. Integrating Team 6's opening story through that same method retained the story flow without adding a second run-initialisation path.
Centralising the Help frame and button feedback keeps the supported views visually consistent. Future presentation changes should reuse these shared styles and preserve the existing Help callbacks and state ownership.
Related Documentation
- Tutorial feature overview.
- Tutorial Battle Setup and Enemy Integration.
- Contextual Event Help and Tutorial Content.
- Battle Tutorial Steps and Progression.
- Tutorial Acceptance Test Plan.
- Repository integration contract.
AI Assistance Disclosure
ChatGPT/Codex assisted with drafting and reviewing this documentation. Descriptions were checked against the linked issues, PR evidence, and source. Individual implementation ownership and the limits of recorded verification are identified above.