Combat‐Stats‐System - UQcsse3200/2026-studio-3 GitHub Wiki

Team 7 | Health/Death: stable, Armour/Block: stable, Status Effects: framework stable, turn-wiring pending | Issues: #47

This page describes how other teams interact with the player's combat stats. The component is CombatStatsComponent — health, max health, death, armour, and status effects all live here for both the player and enemies. Method signatures below are stable; you may call your code against them.

Unlike the enemy system, there's no separate stats class for the player — the player entity gets a CombatStatsComponent attached directly by PlayerFactory, the same class NPCs use.

In the real game, the player is created through PlayerFactory.createPlayer(), which requires engine services to be running — don't call it from a unit test. For tests or isolated logic, construct the component directly:

Real game (inside a GameArea)

Entity player = PlayerFactory.createPlayer();

CombatStatsComponent stats = player.getComponent(CombatStatsComponent.class);

Tests / isolated usage — no factory needed

Entity entity = new Entity();

CombatStatsComponent stats = new CombatStatsComponent(/* health */ 100, /* baseAttack */ 10, /* maxHealth */ 100);

entity.addComponent(stats);

stats.takeDamage(15); // health drops, block/armour absorb first

stats.heal(5); // heal cannot exceed max health

boolean dead = stats.isDead(); // check whether the player is dead or not. Return true if player is dead.

CombatStatsComponent stats = entity.getComponent(CombatStatsComponent.class);

stats.takeDamage(8); // a card deals 8 damage — routes through armour/status first

if (stats.isDead()) { // handle death }

Armour and Block are two damage-reduction pools stored in CombatStatsComponent. The same component is used by both the player and enemies, so the rules below apply to both, unless stated otherwise.

Note: Earlier versions of this page described Armour as "permanent". This was misleading. Armour persists across turns within a battle, but does not carry over to the next battle.

// A FORTIFY card (e.g. Iron Oath) resolves
stats.addArmour(5);
// 20 health, 5 armour, takes 8 damage -> armour absorbs 5, remaining 3 reduces health to 17

// A BLOCK card (e.g. Defend) resolves
stats.addBlock(5);
// 20 health, 5 block, takes 8 damage -> block absorbs 5, remaining 3 reduces health to 17

// Both together
stats.addBlock(3);
stats.addArmour(4);
stats.takeDamage(10);
// block absorbs 3, remaining 7 -> armour absorbs 4, remaining 3 -> health -3

flowchart TD
    A[Incoming damage] --> B{Pierce damage?}
    B -- Yes --> H[Reduce Health]
    B -- No --> C{Block > 0?}
    C -- Yes --> D[Block absorbs as much as it can]
    C -- No --> E{Armour > 0?}
    D --> E
    E -- Yes --> F[Armour absorbs as much as it can]
    E -- No --> G{Damage left?}
    F --> G
    G -- Yes --> H
    G -- No --> I[Health unchanged]

Example: an entity with 20 Health, 2 Block and 5 Armour takes 10 damage. Block absorbs 2 → Armour absorbs 5 → the remaining 3 reduces Health to 17.

flowchart LR
    S[Battle starts<br/>Player: Block 0, Armour 0<br/>Enemies: Armour from config] --> T1
    T1[Player turn<br/>Block reset to 0<br/>Cards can add Block / Armour] --> E1
    E1[Enemy turn<br/>Enemy attacks hit Block first, then Armour<br/>Enemy Defend adds Armour] --> T2
    T2[Next player turn<br/>Block reset to 0<br/>Armour stays] --> E2[...]
    E2 --> N[Battle ends<br/>Next battle starts with player Armour 0]

Example across two turns:

Player

flowchart LR
    C1["BLOCK card effect<br/>e.g. Defend"] -->|adds| PB["Player Block"]
    C2["FORTIFY card effect<br/>e.g. Iron Oath"] -->|adds| PA["Player Armour"]
    I1["Iron Aegis item<br/>+5 per copy"] -->|adds| PA

Enemy

flowchart LR
    E1["Enemy config<br/>armour field"] -->|starting value| EA["Enemy Armour"]
    E2["Enemy Defend intent"] -->|adds| EA
    C3["SUNDER card effect"] -.->|reduces| EA

Enemy starting Armour (from the enemy config):

Enemies use Armour rather than Block because several enemy behaviours depend on it building up across turns (e.g. Bone Crawler's defensive stance, Dark Acolyte's armour scaling, Tomb Guardian's shield-break retaliation).

sequenceDiagram
    participant BC as BattleController
    participant CEH as CardEffectHandler
    participant CS as CombatStatsComponent
    participant UI as PlayerStatsDisplay
    BC->>CEH: applyPlayerEffects(effects, player)
    CEH->>CS: addArmour(value)
    CS-->>UI: "updateArmour" event
    UI->>UI: show Armour icon + number, health bar turns blue

On the player's health bar, the colour is: blue if Armour > 0, otherwise red if Health ≤ 40%, otherwise green. The player's Armour icon is only shown while Armour > 0.

• To give an entity Armour or Block: call addArmour(amount) or addBlock(amount) on its CombatStatsComponent. Do not call setArmour with a computed negative value; it is clamped to 0.
• To display Armour or Block: listen to the updateArmour or updateBlock event on the entity, and read the current value with getArmour() or getBlock().
• Block resets automatically at the start of each player turn. No extra code is needed.
• Pierce damage should use takePiercingDamage, which skips both pools.

StatusEffect fields are named type (String), value (int) and duration (int), aligned with Team 6's EffectConfig naming.

stats.applyStatusEffect(new StatusEffect("VULNERABLE", 2, 2));

stats.applyStatusEffect("VULNERABLE", 2, 2); // three-arg overload

stats.applyStatusEffect("STRENGTH", 2, 0); // duration 0 = permanent

Concrete Status Effect calculations are handled separately by StatusEffectCalculator. It reads the active Status Effects stored in CombatStatsComponent and provides the corresponding calculation values for other combat systems.

Feeble
Feeble reduces outgoing damage by 25% while active. The current implementation uses a fixed 0.75 modifier.

Vulnerable
Vulnerable increases incoming damage while active. The current implementation uses a fixed 1.5 modifier.

Poison
Poison returns its current stored value as the damage value when queried.

Resolves the player's attack and defend actions against CombatStatsComponent. Lives in PlayerBehaviourComponent, attached by PlayerFactory, so every player entity has one. Self-contained — no dependency on components.combat; the battle controller calls into it, not the reverse.

PlayerBehaviourComponent behaviour = player.getComponent(PlayerBehaviourComponent.class);

behaviour.attack(enemyEntity, 5); // a 5-damage card resolves // player baseAttack 5, no status effects -> 10 damage to the enemy

behaviour.defend(5); // a defend card resolves -> player gains 5 armour

attack() computes cardDamage + baseAttack, then applies the attacker's outgoing modifier (FEEBLE → 0.75×) and the target's incoming modifier (VULNERABLE → 1.5×), rounds to the nearest int, and passes the result to takeDamage() — so block and armour still absorb as normal.

playerStats.applyStatusEffect("FEEBLE", 1, 2); enemyStats.applyStatusEffect("VULNERABLE", 1, 2); behaviour.attack(enemyEntity, 5); // (5 card + 5 baseAttack) x 0.75 feeble x 1.5 vulnerable = 11.25 -> rounds to 11

Entities broadcast state changes through the event system. Listen rather than poll.

entity.getEvents().addListener("updateHealth", (Integer h) -> updateHealthBar(h));

entity.getEvents().addListener("entityIsDead", this::onDeath);

Currently no — addMaxHealth only raises the ceiling, it doesn't add current health. Card effects that want both call addMaxHealth and heal separately. Confirm with the cards owner if a single combined effect is expected.

They live on the shared CombatStatsComponent base class, so EnemyStatsComponent inherits them automatically — functionally shared already. Needs Qi Ding to confirm this is the intended design.

Currently on: main Contact: <Jay> (Team 7)

• Enemy System — Interface Contract
• Event System
• Components