Energy System - UQcsse3200/2026-studio-3 GitHub Wiki

Team 7 | Core API: stable, Turn lifecycle | Issues: #2, #23

Overview

This page describes how other teams interact with the player's energy resource. The component is EnergyComponent — it tracks current and max energy, exposes safe spend/restore methods for the card system, and provides turn lifecycle hooks intended to be called by the turn/battle system.

There's no separate energy class for enemies — EnergyComponent is player-only, attached directly by PlayerFactory.

Quick Start

Real game (inside a GameArea)

Entity player = PlayerFactory.createPlayer();
EnergyComponent energy = player.getComponent(EnergyComponent.class);

Tests / isolated usage — no factory needed

Entity entity = new Entity();
EnergyComponent energy = new EnergyComponent(/* maxEnergy */ 3);
entity.addComponent(energy);

energy.spendEnergy(2);      // deducts energy if affordable
energy.restoreEnergy(1);    // restores energy, capped at max
energy.onTurnStart();       // resets current energy to max

Core Energy API

Method Description
EnergyComponent(int maxEnergy) Initializes with current energy equal to max
int getCurrentEnergy() Current energy
int getMaxEnergy() Max energy
void setCurrentEnergy(int) Sets current energy directly, clamped to [0, maxEnergy]
void setMaxEnergy(int) Sets max energy directly, floored at a minimum of 1
boolean canAfford(int amount) Read-only check for whether current energy covers amount. Does not modify state
boolean spendEnergy(int amount) Deducts energy if affordable. Fails safely (no state change, returns false) if insufficient or amount is negative
void restoreEnergy(int amount) Restores energy, capped at max. Non-positive amounts ignored

Usage

EnergyComponent energy = entity.getComponent(EnergyComponent.class);

if (energy.canAfford(cardCost)) {
    energy.spendEnergy(cardCost); // a card is played
}

Turn Lifecycle

Method Description
void onTurnStart() Resets currentEnergy to maxEnergy. Intended to be called by the turn/battle system at the start of the player's turn
void onTurnEnd() Turn-end hook. Currently a stub — no logic implemented yet, pending confirmation with Team 3 on required behaviour

Usage

// called by the turn manager once it exists
energy.onTurnStart();

Events

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

Event Payload Fired when
updateEnergy int current energy Every current-energy write
updateMaxEnergy int max energy Every max-energy write

Usage

entity.getEvents().addListener("updateEnergy", (Integer e) -> updateEnergyBar(e));

Current Limitations

Item Current state
onTurnEnd() Not implemented — behaviour (does unused energy carry over / reset / anything?) needs confirmation from Team 3
Turn manager Doesn't exist yet — onTurnStart()/onTurnEnd() are not wired to anything and won't fire in a real game until Team 3's turn manager calls them
spendEnergy() return type Currently boolean. Team 5 has asked whether a more detailed failure reason (exception/enum) is needed — under discussion
Max energy per-combat reset Ticket calls for resetting max energy after combat; not yet implemented

Open Questions

Does spendEnergy() need a more detailed failure reason?

Confirmed with Team 5 — boolean return on spendEnergy() is sufficient for now. canAfford() isn't required for the initial integration but is planned for future UI use (e.g. greying out unplayable cards).

Who calls onTurnStart()/onTurnEnd(), and when?

Confirmed with Team 3 — no specific onTurnEnd() behaviour is required for now; this may be revisited pending a decision from the design committee. onTurnStart() remains ready for Team 3 to call once the turn manager exists.

Where to Get It

Currently on: Feature-7 Contact: Celeste116 (Team 7)

Related Pages

  • Combat-Stats-System
  • Card Library API
  • Enemy System — Interface Contract
  • Event System
  • Components