Final Boss（sprint2 version） - UQcsse3200/2026-studio-4 GitHub Wiki

Historical Sprint 2 implementation: retained for design history and its original evidence. Stage 2 charge attacks and other old tuning below are not the current encounter. Start with Final Boss: Grandpa and Stage 2 Remake and Stage 3 Improvements.

Grandpa is the game's three-stage Final Boss. The encounter combines shielded summon waves, timed opportunities to damage the boss, movement penalties, ice attacks and a statue-based finale. The player must respond to changing attack patterns and visible warnings. The encounter ends with Grandpa returning alive in his peaceful form.

Feature ticket: Final Boss (Grandpa) #93.

According to the feature ticket:

• Eden (@edenyzh): shared Final Boss framework, Stage 1 and Stage 3.
• Chananyu (@MaidOfFire67): Stage 2.

The stages share one Grandpa entity, health pool and phase controller. Gameplay changes between stages without replacing the boss entity.

Health percentages refer to Grandpa's maximum health, which defaults to 100 HP.

A three-second protected handover separates Stage 1 from Stage 2 and Stage 2 from Stage 3. Health floors prevent a powerful hit from skipping the intended combat phases.

Grandpa appears peacefully, transforms into the Wizard and casts before the summon waves.

During Wave 1, eight explosive summons approach the player at the slower movement speed. A proximity-triggered explosion has a one-second warning, giving the player time to leave its area. A ranged hit can trigger earlier detonation. Grandpa moves towards the player in steps with pauses while avoiding summons.

Remaining within 1.5 world units of Grandpa causes five damage every second, subject to normal combat protections. Actual player health loss produces a brief red flash. Grandpa stays shielded while the summons remain.

When all eight summons are removed, Grandpa stops for a seven-second break and takes only 25% of normal incoming damage. Reaching the 90% health floor restores his shield immediately; the remaining break time still runs.

During Wave 2, sixteen faster summons appear and detonate without the first wave's warning delay. Grandpa retreats using the edge-movement mode, stays shielded and no longer applies Wave 1 proximity damage. Petrification adds a separate warning-and-dodge mechanic.

Petrification is a temporary movement slowdown. Its red targeting circle records the player's position once and remains fixed.

1. The red circle flashes for 0.5 seconds. This warning applies no petrification penalty.
2. When the warning ends, the player's current position is checked against the 1.2-world-unit radius.
3. Remaining inside or on the boundary applies a 0.5 movement-speed multiplier for two seconds. Leaving before the check avoids that cast; returning after it has resolved does not cause a hit.
4. The actual penalty displays red blinking and a status indicator. This effect is separate from the brief flash caused by ordinary health loss.
5. A 2.5-second cooldown starts after resolution. The next warning also waits for any previous petrification penalty to end.

The shared status-effect system applies and expires the slowdown. Repeated requests refresh its duration instead of compounding the reduction. Removing the effect preserves unrelated effects and any changes made to base movement speed.

Clearing Wave 2 removes the Boss-owned petrification effect, sets Grandpa to 80% maximum health and completes Stage 1.

Stage 2 uses charge movement and periodic close-range damage. The configured attack and stationary recovery periods are 20 and seven seconds respectively. Contact damage is disabled during recovery.

At 60% maximum health, Stage 2 charge behaviour is cancelled and the protected handover to Stage 3 begins.

Grandpa maintains distance while firing ice fans containing three projectiles: one in the centre and two at ±30 degrees. Static walls block the projectiles.

Two volleys are separated by 1.6 seconds. After the second volley, Grandpa stops for a three-second recovery, including one repositioning teleport after 0.25 seconds. Existing projectiles remain active, and the boss remains vulnerable. The next volley cycle begins when recovery ends.

An ice hit triggers the following sequence:

1. Lock new player movement, dash and attack actions and interrupt the current volley cycle.
2. Grandpa moves for one second, then teleports beside the player.
3. After 0.25 seconds, attempt one strike.
4. An in-range strike applies ten damage through the normal combat rules, releases the Boss-owned freeze and is followed by a retreat teleport.
5. A missed strike does not repeat. The freeze ends after its three-second maximum duration.

This freeze uses a control lock rather than modifying movement-speed buffs. Stage transitions, player defeat and disposal release the Boss-owned lock.

At 20% maximum health, Grandpa becomes shielded and charges for three seconds. Ice projectiles and freeze are cleared. Grandpa and his health display disappear, his collision body is disabled, and five statues appear.

SPACE temporarily performs a jump instead of a dash. An on-screen hint explains the change. The player can move and attack while airborne.

Statues alternate movement and pauses and take turns attacking through a shared scheduler. Each slam has a 0.6-second warning and a 0.9-second jump before landing creates an expanding ring-shaped shockwave.

A sufficiently timed player jump avoids the moving ring edge. Each ring resolves player contact once, including a successful jump over it, so landing inside an already-passed ring is safe.

Each statue requires ten distinct accepted positive weapon hits, independent of weapon damage. Hits 3, 6 and 9 request an evasive teleport without resetting the hit count. A successful evade cancels that statue's current slam and restarts recovery; blocked destinations are retried.

As statues break, survivors gradually gather into a tighter formation and attack more frequently:

These are encounter-wide intervals. Active warnings and jumps retain their full durations; an individual attack can be delayed by recovery or an evade. Movement routes and teleport destinations use wall and actor-clearance checks.

Each of the first four defeated statues leaves one tornado, with a maximum of four visible or pending tornadoes. An obstructed spawn waits for a clear position.

Tornadoes wander slowly, pursue a nearby visible player and resume wandering when the player moves away. Movement uses camera bounds, wall checks and clearance from other tornadoes, statues and reserved statue routes.

Sprint 2 tornadoes do not cause contact damage, knockback or additional status effects.

The final statue spawns no fifth tornado. Existing tornadoes stop and dissolve with grey-white effects, pending spawns are cancelled, and remaining shockwaves and camera shake are cleared. Normal SPACE dash behaviour returns.

A 1.2-second transformation brings peaceful Grandpa back near the player's current position, using camera and obstacle checks. He remains alive and invulnerable. The ending dialogue and encounter-completion event follow the transformation. Continue or Enter advances the dialogue and releases its control lock when finished.

The Final Boss uses the engine's entity-component architecture. One boss entity holds the shared health, protection, movement and stage components. Each stage checks the shared phase and manages its own behaviour.

The three stage configuration classes hold gameplay values and validate them before use. The factory currently creates their default configurations directly. See the [factory assembly][fb-factory] and [Stage 3 controller][fb-stage-three].

The shared phase controller and individual stages use enums, timers and guarded transitions to implement finite-state machines. completeStage(completedPhase) accepts completion only for the current phase. A successful transition advances the phase, applies the handover protection when appropriate, and publishes PHASE_CHANGED.

Stage 1 and Stage 2 request completion through STAGE_COMPLETED. Stage 3 calls the same controller's completeStage(STAGE_THREE) method after the return transformation. Its local state becomes PEACEFUL, while the shared phase becomes DEFEATED. Here, DEFEATED represents encounter completion; Grandpa remains alive. See the [phase controller][fb-phases] and [ending implementation][fb-stage-three].

FinalBossFactory.createFinalBoss(target, summonSpawner) applies the factory approach discussed in Week 5, App 05 - Design Patterns, pages 5-6. It creates the base NPC, validates the stage configurations and adds the required components before returning the entity.

The room manager supplies the player and a spawn callback. This keeps the component assembly in one place, so room code can create a complete Final Boss through one entry point. createExplosiveSummon(...) similarly centralises the shared construction of Stage 1 summons while accepting movement speed and warning duration for each wave.

This is a static factory arrangement. Adding a required Boss component still requires updating the factory, but callers can retain the same creation API. See [FinalBossFactory][fb-factory] and its [room integration][fb-room-manager].

The Final Boss reuses the engine's EventHandler, applying the Observer pattern discussed in Week 5, pages 9 and 14-15:

• addListener(...) registers a listener for a named event, corresponding to attachment.
• trigger(...) notifies the registered listeners and passes the event arguments.
• Registered callbacks, such as PlayerPetrificationComponent.apply(...), perform the receiving component's response.

For example, the Boss publishes a petrification request on the player's event handler. The player component receives it and creates a PetrificationEffect through the shared status-effect controller. Similarly, Stage 3 publishes state changes that the ending dialogue component observes to show the jump hint or peaceful dialogue.

This separates the notification sender from the receiving behaviour. Event names, argument types and the entity carrying the event remain shared contracts, so integration tests must check them. See the existing [event framework][fb-events-engine], [player adapter][fb-player-petrification] and [dialogue listener][fb-dialogue].

The sequence below shows a normal request for a living player with an active status-effect controller. REQUESTED and CLEAR_REQUESTED abbreviate the corresponding FinalBossEvents constants. The participant labels abbreviate FinalBossPetrificationComponent, the player's EventHandler, PlayerPetrificationComponent and StatusEffectsControllerComponent.

sequenceDiagram
    participant B as Boss petrification
    participant E as Player events
    participant P as Player petrification
    participant S as Status effects

    P->>E: addListener(REQUESTED, apply)
    P->>E: addListener(CLEAR_REQUESTED, clear)

    Note over B,P: Warning ends. Check current player position.
    alt Player remains inside the circle
        B->>E: trigger(REQUESTED, multiplier, seconds)
        E->>P: apply(multiplier, seconds)
        P->>S: removeStatusEffect(previous)
        P->>P: Create timed PetrificationEffect
        P->>S: addStatusEffect(next)
    else Player escaped
        Note over B,E: No player effect request
    end

    Note over B,S: When Stage 1 Wave 2 ends
    B->>E: trigger(CLEAR_REQUESTED)
    E->>P: clear()
    P->>S: removeStatusEffect(previous)

Removing the previous Boss-owned effect before adding another refreshes the duration without stacking this penalty. The shared controller manages expiry; the adapter's removal callback notifies effective-stat listeners. Unrelated effects and base movement-speed changes are preserved. The diagram omits rendering and stat-notification calls to focus on the event contract. See the [Boss sender][fb-boss-petrification] and [player receiver][fb-player-petrification].

These interfaces follow the feature ticket; the concrete APIs are listed below.

FinalBossFactory.createFinalBoss(Entity target, Consumer<Entity> summonSpawner) requires non-null arguments and returns an unregistered entity. The caller must arrange registration through the normal game-area lifecycle.

EnemyManagerComponent already handles the FINAL_BOSS spawn type. It passes this::spawnEntity for spawned summons and statues, supplies the room camera to the movement component when available, and tracks the main boss for room completion. Spawned Boss actors use the supplied callback rather than becoming separate entries in the room's activeEnemies set; their progression is managed by the Boss controllers. See [EnemyManagerComponent][fb-room-manager].

Use the correct entity's event handler and preserve argument order. The player factory already adds PlayerPetrificationComponent alongside CombatStatsComponent and StatusEffectsControllerComponent. See [event constants][fb-event-names], [PlayerFactory][fb-player-factory] and [room completion handling][fb-room-manager].

PlayerActions.setControlsLocked(owner, locked) tracks each owner's lock separately. Stage 3 freeze and the ending dialogue therefore release their own locks without cancelling another owner's lock. setJumpEnabled(owner, enabled) uses the same ownership approach for replacing dash with jump during the statue wave. See [PlayerActions][fb-player-actions].

Statue removal can be triggered from a physics contact callback. That path schedules entity disposal so body destruction occurs after the physics world unlocks. Future changes must preserve this ordering; [FinalBossStatueCollisionTest][fb-collision-test] exercises a real weapon contact and checks deferred removal.

The decisions below are supported by the implementation, regression tests and recorded development notes. Gameplay balance and readability still require the recorded manual evaluation described in the test plan.

Testing combines automated component tests, integration tests using real game components and Box2D, and the manual gameplay plan below.

JUnit tests use Mockito to control dependencies while exercising the behaviour under test:

• Controlled time: mocked GameTime supplies specific timestamps and frame durations. Tests can check warning expiry, cooldowns and transitions without waiting for real time.
• Controlled collaborators: phase and movement mocks select the required stage or isolate movement commands. Stage 1 entrance tests also use a scoped static factory mock to create simple summon entities while testing the real stage controller.
• Interaction verification: verify(..., times(1)) checks that completion is submitted once. ArgumentCaptor checks the movement impulses requested during petrification and after recovery; this verifies the commands sent to physics.
• Real physics with observation: spy(new PhysicsEngine()) retains real Box2D behaviour while allowing checks that a collision callback schedules removal and that body destruction occurs after the world unlocks.

The petrification integration tests retain the real Boss petrification component, player adapter, combat stats and shared status-effect controller. Separate collision and movement tests run actual physics steps. See the [petrification tests][test-petrification], [Stage 1 entrance tests][test-entrance] and [statue collision test][test-collision].

The suite includes:

• Boundary cases: updates immediately before and after timing thresholds; health just above a phase threshold and an oversized hit that reaches its floor.
• Negative and repeated inputs: zero or negative statue damage, repeated contacts from the same attack source, and repeated completion or cleanup requests.
• Lifecycle cases: player defeat, disposal, stage changes, interrupted attacks and preservation of effects or control locks owned by another component.
• Spatial cases: camera edges, walls, crossing routes, blocked destinations and long frames. Statue movement tests use fixed seeds, including 7, 31 and 2026, and check movement and separation over multiple physics updates.

For example, [FinalBossHealthProgressionTest][test-health] uses 1,000 maximum HP to check percentage-based progression: Stage 2 remains active at 601 HP, an oversized hit stops at 600, and the later Stage 3 hit stops at 200. This checks that progression scales with maximum health.

The following groups identify the behaviour checked by existing test code. The CI result is recorded separately below.

The [petrification implementation note][test-petrification-notes] records that the overlap regression failed against the earlier implementation and passed after the warning-timing fix. The corrected behaviour waits for the previous penalty to expire before starting another warning.

previousPenaltyShouldExpireBeforeNextWarningStarts() preserves this case with a deliberately shortened cooldown. This protects the design requirement that the player can respond to a new warning without an earlier petrification penalty still active.

Other regression cases protect the related integration decisions: effect removal preserves unrelated buffs, releasing freeze preserves other control locks, and physics callbacks defer unsafe body changes.

The Game Unit Tests run completed successfully on 16 September 2026 for 521e21b69cd6ea1b5d7b6432a7711308fdfa3ad8. Its Run Unit Tests step passed using JDK 21 and ./gradlew test from the source directory. See the [workflow definition][test-workflow].

This is automated-suite evidence for the merged revision. Visual readability, difficulty and complete gameplay interaction are evaluated through the manual plan below. Numerical coverage should be reported from an identified JaCoCo report for the same revision.

Use JDK 21 and run these commands from the repository's source directory.

Run the full suite, as in CI:

./gradlew test

For focused work on the Final Boss and affected player behaviour:

./gradlew :core:test \
  --tests '*FinalBoss*' \
  --tests '*PlayerPetrificationFlashTest' \
  --tests '*PlayerDamageFlashComponentTest' \
  --tests '*PlayerJumpTest' \
  --tests '*PlayerActionsTest'

The merged implementation includes all three stages, shared status-effect integration, the statue and tornado finale, player feedback and ending dialogue functionality.

Tornado damage and further combat balance tuning are deferred to a later sprint. The ending dialogue currently uses draft story text.

• Balance changes: edit the relevant stage configuration and retain its validation rules. Check phase thresholds together with the damage controller's health floors, and update timing tests when defaults change.
• Additional feedback: subscribe to the existing warning, shield or state events where suitable. Keep targeting and damage decisions in the gameplay components.
• Additional player effects: use the shared status-effect controller and remove only the effect owned by the mechanic. Preserve base stats and unrelated effects during expiry and cleanup.
• Further Stage 3 work: keep tornado behaviour in FinalBossTornadoController where appropriate. Adding tornado damage remains future work and requires its own combat rules and tests.

Stage 3 still coordinates several mechanics in one controller, so changes to its timings or cleanup can affect multiple behaviours. Further extraction should preserve the existing state and lifecycle contracts and their regression tests.

• Pixel Holy Spell Effect 32x32 Pack 3
• Frostmere Depths — Pixel Art Ice Tiles & Enemies Asset Pack (32x32)
• Ice Spell Effect 01
• Simple Wizard
• Wizard Platformer — Pixel Art 2D
• Old Man

• Stage 1 configuration.
• Stage 2 configuration.
• Stage 3 configuration.
• Petrification timing and integration.
• Current statue escalation, tornado lifecycle and Grandpa return placement.

Earlier implementation notes include intermediate tuning and validation results. The documented code revision and the later tornado-finale note take precedence for current statue intervals and Grandpa's return location. Historical local test counts are not presented as the final merged-main CI count.

ChatGPT (Codex) assisted with parts of the Final Boss implementation and regression tests, and with comparing code, feature-ticket content, PRs and CI evidence to draft and organise this wiki.