Entity Component System (ECS) - UQcsse3200/2026-studio-3 GitHub Wiki

Introduction

Almost everything that exists in the game is an entity, from the player and NPCs to the map terrain and UI. An entity doesn't do much on it's own, but acts as a container to add components to. This is a common pattern in game development called an Entity Component System (ECS). Each component is responsible for one piece of functionality. We can make an entity do something interesting with the right combination of components.

Example: Tree Entity

For example, to create a tree:

public static Entity createTree() {
    Entity tree = new Entity()
        .addComponent(new TextureRenderComponent("images/tree.png"))
        .addComponent(new PhysicsComponent())
        .addComponent(new ColliderComponent());
    return tree;
}
  1. We start with a new entity
  2. We add a TextureRenderComponent which draws the tree texture on screen
  3. We add a PhysicsComponent which lets the tree use game physics
  4. We add a ColliderComponent which adds a rectangular collider around the tree, so other physics entities can't walk through it.

The tree would look like this in the game (green border indicates physics collider):

Example: Player Entity

A simple player entity might look like:

public static Entity createPlayer() {
  return new Entity()
    .addComponent(new TextureRenderComponent("images/player.png"))
    .addComponent(new PlayerMovementComponent())
    .addComponent(new InventoryComponent())
    .addComponent(new CombatComponent());
}

We can reuse the same texture render component that we used for the tree, but also add player-specific components to control movement, give the player an inventory, and give them combat capabilities (e.g. health and attack damage).

Example: Status Effect Visualisation

Status effects use several components and data objects to separate combat logic from rendering.

An enemy's planned action is represented by an EnemyIntent. It records:

  • the general intent type, such as ATTACK, DEFEND or DEBUFF;
  • the specific status effect, if any;
  • the effect value;
  • the effect duration.

Enemy Intent Icons

EnemyIntentDisplay is a render component attached to an enemy entity. It listens for the enemy's intentChanged event and draws the current intent above that enemy.

IntentIcons selects the appropriate texture for each intent:

IntentIcons.pathFor(IntentType type, IntentEffectType effectType)

Debuffs can use effect-specific icons:

Effect Icon path
Silence images/enemies/intents/silence.png
Damage on card play images/enemies/intents/damage_on_card_play.png
Taunt images/enemies/intents/taunt.png
Generic or unspecified debuff images/enemies/intents/debuff.png

Only DEBUFF intents are separated by effect type. Other intent types continue to use their standard icons.

If the effect type is null, the generic debuff icon is used.

All icon paths must be returned by:

IntentIcons.all()

EnemyFactory.loadAssets() uses this collection to preload intent textures before they are displayed.

Intent Duration

When an enemy intent has a positive duration, EnemyIntentDisplay draws the number of turns beside the intent icon.

For example:

[Silence icon] 2

This means the enemy intends to apply Silence for two turns.

Intents with a duration of zero or less do not display a duration number.

The duration is provided by:

EnemyIntent.getDuration()

Player Status Query

The player's active status effects are stored in CombatStatsComponent.

CombatStatsComponent provides an immutable snapshot of the current effects:

Map<String, Integer> getStatusEffectDurations()

BattleController exposes this information to UI and integration code:

Map<String, Integer> getPlayerStatusEffectDurations()

The returned map associates each status-effect type with its remaining duration. For example:

SILENCE -> 2
DAMAGE_ON_CARD_PLAY -> 1

The returned map is read-only and detached from the internal status-effect collection. External code cannot use it to modify the player's combat state.

If the player has no active effects, or does not have a CombatStatsComponent, the method returns an empty map rather than null.

A positive value represents the number of turns remaining. A value of zero or less represents an effect without a finite duration.

Status Expiration

Silence and damage-on-card-play durations are reduced at the end of the player's turn.

Attempting to play a card does not reduce a status effect's duration. For example, repeatedly attempting to play cards while silenced does not cause Silence to expire early.

When an effect expires, it is removed from CombatStatsComponent and no longer appears in the player status snapshot.

Card-Play Integration

Team3CardPlayAdapter checks whether the player is silenced before submitting a card-play request.

When the player is silenced:

  • the card-play request is rejected;
  • energy is not spent;
  • the card remains in the player's hand;
  • the card is not moved to the discard pile;
  • card effects are not resolved;
  • damage-on-card-play is not triggered;
  • a battle-log message explains why the card was rejected.

Card-play integration uses each card's instanceId rather than its definition-level cardId. This allows individual copies of the same card to be tracked independently.

UI Integration

The player status query provides the data required for a persistent status row beneath the player's health and energy display.

A UI component can iterate over the returned map to display:

  • one icon for each active status effect;
  • the number of turns remaining;
  • no duration number for effects without a finite duration.

The status row should refresh when effects are applied, reduced or removed.

Read Next

Behind the Scenes

Why use ECS over inheritance?

Inheritance has some strong limitations, both in game development and general software development. Inheritance only allows for change along one axis. This explanation of the bridge pattern has a great explanation of how this leads to problems. For an example that relates to game development, consider this inheritance tree for enemies:

If the scope of the project changes, and we now want to add a FlyingRangedEnemy, we are in trouble. The flying code exists in an entirely different part of the inheritance tree! In this case, composition (e.g. the bridge pattern) can be used to extract the flight code into a separate class, which both FlyingRangedEnemy and FlyingMeleeEnemy can use.

ECS can be considered as simply the bridge pattern taken one step further, where entity behaviour is defined completely by composition. The core entity class only contains functionality that is required for every entity in the game, and is never extended from. In general, it is recommended to keep inheritance trees wide rather than deep, and use composition where possible.

Further Reading