Tutorial Battle Setup and Enemy Integration - UQcsse3200/2026-studio-3 GitHub Wiki

Overview

Owner: Guoqing Sun (@Sunqing050114)
Team: Team 2
Sprint: Sprint 3
Feature: #339 — New Player Battle Tutorial and Contextual Event Help
Cross-team integration: #365 — Tutorial Battle Setup and Safe Enemy Integration
Implementation PR: #402 — Connect teaching battle to New Game
Integration branch: Feature-2-Sprint3-TutorialTooltips

This component connects the New Game tutorial choice to a dedicated teaching battle. The tutorial runs in an isolated, disposable state so tutorial health loss, cards, currency, rewards, map progression and autosave do not affect the player's normal run. PR #402 has been merged into the Team 2 Sprint 3 integration branch, and the post-fix graphical tutorial playthrough passed. Team 1's tutorial-only safe enemy behaviour and Jun's final positioned guidance UI remain cross-team integration dependencies before the complete feature branch can be merged into main.

Responsibility and Scope

Guoqing's responsibility is to initialise the tutorial battle, spawn the agreed ordinary enemy, connect the existing tutorial controller to real battle actions, coordinate the safe-enemy interface with Team 1, and handle tutorial completion, interruption and exit. The work deliberately reuses production battle, player and card systems while keeping tutorial-only routing separate from ordinary encounters.

The implementation does not claim ownership of Joel's New Game dialog and fresh-run UI, Jun's final highlighted guidance UI, Zixuan's tutorial-step definitions, Yihan's tutorial wording, or Team 1's safe-enemy behaviour.

Implementation

Tutorial entry and screen routing

  • MainMenuActions listens for MainMenuDisplay.ENTER_TUTORIAL_EVENT and calls GdxGame.startTutorialBattle().
  • GdxGame.ScreenType.TUTORIAL_BATTLE opens new BattleScreen(game, true).
  • Skip Tutorial continues to use the normal startNewRun() path.
  • Starting the tutorial does not complete or alter the active normal map node.

Isolated tutorial battle

  • BattleScreen creates a disposable RunState for tutorial mode instead of using the persistent normal-run state.
  • The current integration creates one ordinary bone_crawler with the dungeon background.
  • BattleTutorialComponent is registered through the normal entity lifecycle before combat starts.
  • BattleTutorialTextView provides a usable temporary prompt, Continue control and Exit Tutorial control until the final positioned highlights are integrated.
  • BattleActions retains normal card-play and turn events but does not install ordinary victory/defeat navigation for tutorial mode.
  • The tutorial path does not complete a map node, grant encounter rewards, request an autosave or open the normal end-battle screen.

Outcome and cleanup

  • WON and voluntary CANCELLED outcomes call Joel's shared startNewRun() path, which creates a clean normal run.
  • LOST currently returns to the main menu while Team 1's no-player-death behaviour is pending.
  • Exiting from the tutorial pause menu does not abandon a normal map encounter.
  • Tutorial observers and prompt UI are removed during cleanup, and normal battles retain their existing behaviour.

Mapless RunState regression fix

The first graphical launch of Enter Tutorial exposed a NullPointerException: the tutorial's isolated RunState has no mapGraph, while PlayerStatsTopDisplay requests map progression during player UI creation. RunState.getMapProgression() now checks mapGraph and activeNodeId before calling getNode(), returning 0 for mapless states. A regression test covers this case.

Integration Boundaries

Contributor Interface / dependency Current status
Joel / Team 2 New Game choice and clean startNewRun() transition Connected through ENTER_TUTORIAL_EVENT and startTutorialBattle()
Zixuan / Team 2 Tutorial progression and action-based completion Connected through BattleTutorialComponent and real battle events
Jun / Team 2 Positioned prompt and highlight view Temporary text view is connected; final graphical view remains to be integrated
Yihan / Team 2 Accurate tutorial prompt content Consumed by the existing tutorial controller/content boundary
Team 1 Tutorial-only safe enemy behaviour Still required; the ordinary Bone Crawler alone does not satisfy the no-player-death criterion

Team 1's special behaviour must apply only in the tutorial battle. The same enemy must retain normal behaviour in ordinary battles, remain defeatable with the tutorial setup, and be unable to kill a player who follows the tutorial.

Automated Testing

The implementation and formatting checks passed on Java 21:

./gradlew test spotlessCheck --console plain --max-workers=2

Result recorded for PR #402: 1,771 tests passed, 0 failures or skips, and all four GitHub checks passed.

Focused regression coverage includes:

  • MainMenuActionsTest.enterTutorialStartsTheDedicatedBattleOnly — Enter Tutorial launches the dedicated path without starting a normal run.
  • GdxGameTest.tutorialLaunchUsesItsOwnScreenWithoutCompletingAMapNode — the tutorial opens its own screen and leaves normal map progress unchanged.
  • BattleActionsTest.tutorialKeepsTheBattleActionsButDoesNotInstallOrdinaryOutcomeNavigation — normal actions remain available without ordinary battle-end routing.
  • RunStateTest.returnsZeroWhenMapIsMissing — a mapless tutorial state safely reports zero progression.

Manual Validation Record

Build / commit Scenario Result Evidence and follow-up
7fba831 New Game → Enter Tutorial FAIL Tutorial event routing worked, but player UI creation crashed because RunState.getMapProgression() dereferenced a missing mapGraph.
b44814d + 8102ad7 Mapless RunState fix and regression PASS (automated) Added null-safe progression handling and a focused regression test. PR CI subsequently passed.
Merged PR #402 Post-fix graphical tutorial flow: Enter Tutorial, battle actions, completion/exit and transition to a clean normal run PASS (manual) Manually verified after the mapless RunState fix on the merged PR #402 integration. The tutorial launches without the previous crash and the tested flow completes successfully.

The passing manual playthrough is recorded separately from the automated CI result.

Remaining Work Before main

  • Integrate Team 1's tutorial-only safe enemy behaviour and verify that ordinary enemy behaviour is unchanged.
  • Replace the provisional text view with Jun's final positioned prompts and highlights.
  • Retain screenshots or a short recording of the passing post-fix playthrough in the shared Tutorial Acceptance Test Plan.
  • Repeat final end-to-end acceptance after Team 1's safe-enemy behaviour and Jun's final guidance UI are integrated.

Evidence and References