Chinese Dragon

Current implementation: checked against main at 77e0b9b2 on 21 October 2026. Values below are defaults before room difficulty scaling unless stated otherwise.

Overview

The Chinese Dragon is a two-phase mini-boss built around three abilities: Thunder Orb, Cloud Dash, and Storm Zone. The encounter combines tracking projectiles, directional movement, and delayed area attacks to encourage players to reposition and respond to visible warnings.

Unlike Cerberus, which has three independently damageable heads, the dragon uses a single health pool and health bar. When its health reaches 50% of its maximum health or below, it enters Phase 2.

The implementation separates attack logic, movement, damage detection, and visual effects into dedicated components. An attack coordinator controls how the abilities are used during each phase.

Default Statistics

Parameter	Default value
Health	200
Base attack	20
Width	2 world units
Height	Approximately 2.17 world units
Health bar scale	2
Phase 2 threshold	100 HP with default maximum health

These values are defined in DragonConfig. Room difficulty scales maximum/current health together: the default 200 HP becomes 300, 400 or 500 after one, two or three completed dungeons. Phase 2 always uses 50% of the actual maximum. A newly scaled, full-health dragon must remain in Phase 1.

The three skills currently define their own damage values. Changing DragonConfig.baseAttack does not automatically change Thunder Orb, Cloud Dash, or Storm Zone damage.

Main Classes

Class	Responsibility
DragonConfig	Defines default health, base attack, display size, and health bar scale.
DragonFactory	Creates the dragon and attaches its combat, movement, rendering, and lifecycle components.
DragonPhaseComponent	Detects the health threshold and permanently activates Phase 2.
DragonAttackCoordinatorComponent	Controls sequential attacks in Phase 1 and attack combinations in Phase 2.
DragonThunderOrbComponent	Controls firing requests, burst timing, cooldown, deferred spawning, and owned-projectile cleanup.
ThunderOrbFactory	Creates thunder orb entities with movement, hit detection, and animation.
ThunderOrbMovementComponent	Implements tracking with a limited turn speed and projectile lifetime.
ThunderOrbHitComponent	Applies a single damage attempt, plays the impact animation, and schedules removal.
DragonCloudDashComponent	Controls warning, direction locking, dash state, and recovery.
DragonCloudDashMovementComponent	Moves the dragon along the locked direction while limiting distance and checking obstacles.
DragonCloudDashDamageComponent	Detects whether the dash crosses the player and limits damage to one attempt per dash.
DragonCloudDashVisualComponent	Renders the dash warning and distance-based smoke trail.
DragonStormZoneComponent	Creates fixed warning areas, schedules delayed strikes, and checks damage overlap.
DragonStormZoneVisualComponent	Renders storm warning circles and strike feedback.
DragonAnimationController	Selects idle, casting, and directional dash animations.
DragonEnrageVisualComponent	Displays the dragon’s pulsing enrage aura.

Dragon-specific components are grouped in the com.csse3200.game.components.miniboss.dragon package.

Health and Death

The dragon uses one CombatStatsComponent and one EnemyStatDisplay.

Unlike Cerberus, it does not have independently damageable head entities. All damage reduces the dragon’s single health pool.

When the dragon dies:

• The attack coordinator stops scheduling attacks.
• Cloud Dash is cancelled.
• Storm warnings and active zones are cleared.
• Queued thunder orb creation is prevented, and owned orbs are cancelled.
• The animation controller stops playback.
• The enrage aura becomes inactive.
• EnemyDeathComponent(false) handles the dragon’s death lifecycle.

Target death also causes the attack logic to stop and clean up its active skills.

Movement

The dragon’s combat movement is controlled by Cloud Dash. The full factory does not attach a separate continuous pursuit component.

A dash locks its direction towards the player when the warning begins. Moving the player during the warning does not redirect that dash.

Movement is restricted to a maximum distance per dash. Unlike Cerberus, the dragon is not tethered to a fixed anchor.

Obstacle checks use the dragon’s polygon collider and small movement steps. The checks are conservative around corners, so the dragon may stop slightly early rather than clip through an obstacle.

Immobilising status effects pause dash movement. This does not mean that every attack timer or skill is globally paused.

Attacks

Thunder Orb

Before moving, the orb raycasts between its current and proposed centre positions against the OBSTACLE layer. A blocked path or obstacle collision stops movement and triggers the impact animation without damaging the player. This checks existing obstacle geometry; it does not guarantee blocking across gaps without colliders.

Thunder Orbs spawn at the dragon’s centre and track the player with a limited turning speed.

Parameter	Value
Cooldown	2.5 seconds
Phase 1 projectiles per cast	1
Phase 2 projectiles per cast	2
Phase 2 burst interval	0.35 seconds
Movement speed	3 world units per second
Maximum turning speed	90 degrees per second
Flight lifetime	3 seconds
Damage	10

Projectile creation is deferred through EntityService.schedule(). Before creating a queued projectile, the skill checks whether the dragon and target are still alive and whether firing has been stopped.

The number of shots is selected when the attack starts. Entering Phase 2 during an existing Phase 1 cast does not add another shot to that cast.

On a valid player collision:

1. The projectile records that it has impacted.
2. Tracking movement stops.
3. One damage attempt is made through CombatStatsComponent.takeDamage(...).
4. The impact animation plays before removal.

An orb cannot repeatedly damage the player. A collision with an invulnerable player still consumes the orb, even if the damage is prevented.

The skill remains busy while shots are queued, the burst is incomplete, or owned projectiles remain active. The coordinator therefore waits for projectile disposal before completing the attack.

Cloud Dash

Cloud Dash follows these states:

READY → WARNING → DASHING → RECOVERING → READY

Cancellation moves the skill to STOPPED.

Parameter	Value
Warning duration	0.8 seconds
Dash speed	6 world units per second
Maximum dash distance	3 world units
Maximum movement step	0.05 world units
Phase 1 recovery	1 second
Phase 2 recovery	0.75 seconds
Damage	20
Damage attempts	At most one per dash

The direction is locked at the start of the warning. The dash finishes when it reaches its distance limit or encounters an obstacle.

Damage detection checks the swept movement against the player’s hitbox bounds. This helps detect hits when the dragon moves across the player between updates.

The warning is visible before movement begins. During the dash, smoke puffs are emitted at distance intervals and expire independently.

Smoke parameter	Value
Puff spacing	0.25 world units
Animation frames	21
Frame duration	0.04 seconds
Puff lifetime	0.84 seconds

Storm Zone

Storm Zone creates a warning circle at the player’s centre position. Once created, that zone remains fixed and does not follow the player.

Zone radius	1 world unit
Damage per zone	10
Strike flash duration	0.2 seconds
Phase 1 zones per cast	1
Phase 2 zones per cast	2
Delay before creating the second zone	0.35 seconds
Warning duration	1 second
Cooldown	2.5 seconds

In Phase 2, the second zone samples the player’s position when it is created. It receives its own full warning duration.

Each zone makes one damage attempt when its warning finishes. Damage detection checks overlap between the circle and the player’s axis-aligned bounds, calculated from the entity’s position and scale.

Two overlapping zones may each make a damage attempt. Final damage is handled by the shared combat and status-effect systems.

The cooldown begins when the cast is accepted. Another cast requires both the cooldown to finish and the existing zones to clear.

Phase Behaviour

Phase 1: Sequential Attacks

After an initial delay of 1 second, the coordinator follows this order: Thunder Orb → Cloud Dash → Storm Zone → Thunder Orb

The coordinator waits for the active attack to finish:

• Thunder Orb finishes after queued shots, burst timing, and active projectiles have cleared.
• Cloud Dash finishes after its recovery state returns to READY.
• Storm Zone finishes after all zones and any pending second zone have cleared.

Thunder Orb and Storm Zone are followed by a 1-second coordinator recovery window.

Cloud Dash already includes its own recovery. The coordinator does not add another recovery period after it.

If the next skill cannot start, the coordinator waits and retries that skill.

Phase 2: Attack Combinations

The phase threshold is:

Current health / Maximum health ≤ 0.5

The dragon must still be alive. Killing it directly from Phase 1 does not trigger enrage.

The transition occurs only once. Healing does not return the dragon to Phase 1. Changes to maximum health also cause the threshold to be re-evaluated.

The coordinator finishes the current attack before switching to the Phase 2 plan: Thunder Orb + Storm Zone → Cloud Dash → Repeat

During Phase 2:

• Thunder Orb fires two shots per cast.
• Storm Zone creates two separately warned areas.
• The coordinator attempts to start Thunder Orb and Storm Zone together.
• If one combination skill is temporarily unavailable, only that skill is retried.
• Cloud Dash waits until both combination skills have finished.
• Recovery after the combination is 0.75 seconds.
• Cloud Dash uses its own 0.75-second recovery.
• The dragon displays a pulsing enrage aura.

The combination skills are therefore allowed to overlap, but are not guaranteed to start on exactly the same update.

Animation and Visuals

The dragon uses images/dragon/dragon.atlas.

Animation	Current use
idle	Default animation and dash recovery.
wave	Thunder Orb casting, Storm Zone casting, and dash warning.
moveLeft	Leftward dash movement.
moveRight	Rightward dash movement.
jump	Registered by the factory, but not selected by the current attack controller.
collapse	Registered by the factory, but not connected to a delayed death-animation sequence.

For a vertical dash, the animation controller retains its previous horizontal facing direction.

The controller avoids restarting an animation every update when the selected animation has not changed.

Additional visual resources include:

• images/dragon/thunder-orb.atlas for projectile flight and impact.
• images/dragon/smoke_sheet.png for dash smoke.

Storm warnings and the enrage aura use dedicated render components. The implementation does not require changes to the shared AnimationRenderComponent.

Usage and Main Methods

Factory

The current room integration creates the complete combat-enabled dragon with:

Entity dragon = DragonFactory.createDragon(target);

The returned entity is not registered automatically. Before registration, the owner must listen for NPCFactory.PROJECTILE_SPAWNED (enemyProjectileSpawned) on the dragon and register the emitted Thunder Orbs through its spawning system. EnemyManagerComponent.track(...) connects this listener in normal gameplay; the room then positions and registers the dragon.

The compatibility overload DragonFactory.createDragon(target, projectileSpawner) remains available. It creates the same combat-ready entity and connects the supplied callback to that event for the caller.

The factory also provides:

Entity dragon = DragonFactory.createDragon();

DragonConfig config = new DragonConfig(); config.health = 600;

Entity dragon = DragonFactory.createDragon(config);

These overloads create the base dragon with health, phase logic, animations, a health bar, and death handling. They do not attach the target-dependent attacks or attack coordinator.

The current combat-enabled overload uses the default configuration.

Resources must be loaded before the relevant rendering components use them. Normal gameplay also requires the project’s entity, physics, rendering, resource, and time services.

Attack Control and State Queries

Method	Purpose
DragonPhaseComponent.getCurrentPhase()	Returns Phase 1 or Phase 2.
DragonPhaseComponent.isEnraged()	Reports whether Phase 2 has started.
DragonThunderOrbComponent.tryAttack()	Requests a projectile cast.
DragonThunderOrbComponent.isBusy()	Reports queued shots, remaining burst shots, or active projectiles.
DragonCloudDashComponent.tryAttack()	Starts the warning and locks the direction.
DragonCloudDashComponent.getState()	Returns the current dash state.
DragonCloudDashComponent.getLockedDirection()	Returns a copy of the locked direction.
DragonCloudDashComponent.finishDash()	Ends movement and starts recovery.
DragonStormZoneComponent.tryAttack()	Starts a storm cast if available.
DragonStormZoneComponent.getZones()	Returns immutable zone snapshots for rendering.
DragonAttackCoordinatorComponent.stop()	Permanently stops scheduling and cancels the three skills.
DragonEnrageVisualComponent.isAuraActive()	Reports whether the enrage aura is active.

Events

Event	Source	Purpose
updateHealth / updateMaxHealth	Dragon combat stats	Re-evaluates the phase threshold.
entityDied	Dragon	Stops attacks and initiates death handling.
dragonEnrageStarted	Phase component	Announces the one-way transition to Phase 2.
dragonThunderOrbStarted	Thunder Orb skill	Announces an accepted cast and triggers casting feedback.
dragonCloudDashStarted	Cloud Dash skill	Announces the warning and resets per-dash damage tracking.
dragonCloudDashStep	Dash movement component	Supplies movement endpoints for damage and smoke processing.
dragonStormZoneStarted	Storm Zone skill	Announces a storm cast and triggers casting feedback.
collisionStart	Projectile physics events	Allows the orb hit component to process player contact.

Room Integration

EnemyManagerComponent supports the DRAGON enemy type:

case DRAGON:
  return DragonFactory.createDragon(target);

Its shared projectile-event listener routes Thunder Orbs through spawnEntity, matching the ordinary flying-enemy integration.

The dragon is tracked as a room enemy and currently appears in dungeonFourEnd (Chinese dungeon). Defeating it reports the DRAGON kill used by Dragon Slayer. The shared achievement service owns unlock persistence and UI.

Thunder Orbs are room-owned projectiles and are not added to the active-enemy count.

The room configuration determines where the dragon appears. Adding the factory case does not automatically add the dragon to every room.

The room can clear after the dragon and all other tracked enemies have died.

Testing

Automated Tests

Test class	Main coverage
DragonTest	Factory setup, combat statistics, attached components, and health-phase integration.
DragonPhaseComponentTest	Half-health boundary, direct death, healing, and maximum-health changes.
DragonAttackCoordinatorComponentTest	Initial delay, sequential attacks, combination completion, phase-plan changes, and cancellation.
DragonThunderOrbComponentTest	Deferred spawning, cooldown, two-shot bursts, active-projectile tracking, and cleanup.
ThunderOrbFactoryTest	Projectile setup, collision layer, spawn settings, and invalid arguments.
ThunderOrbMovementComponentTest	Tracking, turn-rate limits, lifetime, stopping, obstacle blocking and one-time blocked notification, and invalid elapsed time.
ThunderOrbHitComponentTest	Single-hit behaviour, impact playback, expiry, invulnerability, blocked-event and obstacle-contact impact handling, and cancellation during damage callbacks.
DragonCloudDashComponentTest	Warning, locked direction, recovery, single-hit swept damage, targets behind walls and immobilisatio, and cancellation.
DragonCloudDashMovementComponentTest	Locked-direction movement, distance limits, and obstacle handling.
DragonCloudDashVisualComponentTest	Warning visibility, smoke emission, expiry, and cleanup.
DragonStormZoneComponentTest	Delayed damage, fixed targeting, overlap, second-zone timing, cooldown, and cancellation.
DragonStormZoneVisualComponentTest	Warning and strike visibility, cancellation, and renderer lifecycle.
DragonAnimationControllerTest	Idle, casting, directional dash animations, and death handling.
DragonEnrageVisualComponentTest	Phase activation, persistence after healing, pulsing, and cleanup.

From the source directory on Windows PowerShell: .\gradlew.bat :core:test --tests "com.csse3200.game.components.miniboss.dragon.*" --tests "com.csse3200.game.entities.enemy.DragonTest" --tests "com.csse3200.game.entities.factories.ThunderOrbFactoryTest"

Run the complete core test suite with: .\gradlew.bat :core:test

Visual-component tests cover state and lifecycle behaviour. They do not replace in-game verification of appearance, alignment, animation quality, or readability.

Manual Verification

Launch Desktop and enter a room configured to spawn DRAGON.

1. Confirm that the dragon appears with its idle animation and health bar.
2. Verify the Phase 1 order: Thunder Orb, Cloud Dash, then Storm Zone.
3. Move around an orb and confirm that its turning is limited and its flight expires.
4. Confirm that one orb cannot repeatedly damage the player.
5. Move sideways during a dash warning and verify that the dash retains its locked direction.
6. Verify that the dash stops at obstacles or its maximum distance.
7. Confirm that smoke follows the dash and disappears afterwards.
8. Leave a storm warning circle and confirm that the delayed strike can be avoided.
9. Reduce health to 50% of the actual maximum (100 HP with the unscaled default configuration).
10. Confirm the enrage aura, two-shot burst, and two storm warnings.
11. Verify that Cloud Dash waits for the combination to finish.
12. Defeat the dragon and confirm that projectiles, storm zones, and attack visuals are cleaned up.
13. Verify room completion after all tracked enemies have died.

UML Overview

Factory and Phase Structure

Attack Coordination

Cloud Dash Components

Current revision and related work

Dragon implementation #206; default-health and scaling integration #291; factory and shared projectile-event integration #371. Current integration sources: DragonFactory.java and EnemyManagerComponent.java. Configuration sources: DragonConfig.java, DragonPhaseComponent.java, CombatStatsComponent.java. See the Team 1 Test Plan for scaling, death cleanup and achievement checks.