ECS Architecture Guide for Roguelike Games

If your roguelike is growing into a mess of enemy types, projectiles, status effects, items, and temporary world entities, ECS is worth considering not because it is fashionable, but because it can keep complexity manageable at scale.

Who This Helps

• Developers managing hundreds or thousands of live entities
• Teams whose inheritance tree keeps getting harder to extend
• Projects that need better performance, data clarity, or serialization discipline

The Problem

Traditional object hierarchies often start clean and become rigid:

• every new hybrid entity asks for another subclass
• shared logic leaks into unrelated classes
• serialization gets messy
• performance tuning becomes harder because data is fragmented

Roguelikes amplify these problems because they rely on lots of composable systems:

• enemies
• projectiles
• status effects
• loot
• traps
• particles
• temporary map objects

Why It Matters

Roguelikes benefit from architectures that reward composition over special cases.

ECS helps because it separates:

• identity
• data
• behavior

That makes it easier to:

• build unusual entity combinations
• batch or optimize systems
• save and load state
• reason about gameplay logic without giant inheritance chains

Core Principles

1. Entities should stay lightweight

An entity is usually just an ID. Its meaning comes from the components attached to it.

2. Components should stay close to pure data

Position, health, attack power, sprite references, AI settings, and collision data should mostly describe state rather than own large chunks of gameplay behavior.

3. Systems should own the actual behavior

Movement, combat resolution, rendering, AI updates, and cleanup all become easier to reason about when they operate on groups of entities with known component requirements.

4. Composition beats hierarchy for roguelike variety

Want a boss that drops items, teleports, burns tiles, and phases through walls? ECS handles that more naturally with composition than with subclass stacking.

How To Apply It

1. Start with a small ECS surface

Do not convert the whole game overnight. A good first slice is:

• Position
• Velocity
• Health
• AttackPower
• Sprite or RenderData
• Collider
• PlayerControlled
• EnemyAI

Then write a few core systems:

• movement
• combat
• render sync
• enemy update
• cleanup or despawn

2. Use ECS where density or variation is high

ECS tends to pay off most when:

• entity count is high
• combinations of behavior matter
• systems read the same fields repeatedly
• you want cleaner data for save/load or tooling

It may be overkill for every single subsystem. Some UI or meta-progression layers can remain outside ECS if that keeps the codebase simpler.

3. Think engine-agnostic first, then map to tools

Phaser

• treat ECS as a gameplay data layer that drives Phaser objects
• avoid coupling engine scene objects too tightly to component logic
• keep render sync separate from simulation data

Unity

• small custom ECS patterns and DOTS are very different choices
• decide early whether you need full DOTS complexity or just composition discipline
• keep authoring workflows in mind, not just runtime speed

Godot

• use ECS ideas carefully if your project already leans on scene composition
• ECS can still be useful for combat simulation or data-heavy runtime logic

Unreal

• data-oriented thinking is useful even if you do not adopt a pure ECS stack
• focus on clear ownership between gameplay data, world actors, and update systems

4. Plan for serialization early

One hidden advantage of ECS is that save/load can become cleaner when entity IDs and component data are explicit. If the game relies on procedural state, floor history, or persistent modifiers, this can be a major win.

Common Mistakes

1. Rebuilding the whole project around ECS too early

An ECS rewrite can stall progress if the project does not yet have enough complexity to justify it.

2. Letting components accumulate behavior

If components turn into mini-objects with lots of logic, you lose much of the architectural benefit.

3. Treating ECS as a performance guarantee

ECS can improve performance, but only when data layout, access patterns, and system design are actually disciplined.

4. Forcing every subsystem into the same model

Roguelike combat or simulation may benefit from ECS sooner than menus, progression UIs, or editorial tooling.

Checklist

• [ ] Entities are mostly IDs or lightweight references
• [ ] Components primarily describe data
• [ ] Systems own the gameplay behavior
• [ ] Hybrid gameplay objects are built through composition rather than subclass chains
• [ ] Rendering and simulation responsibilities are clearly separated
• [ ] Save/load strategy is compatible with entity and component data
• [ ] The team understands where ECS helps and where it would be unnecessary

References

• EnTT
• Entitas
• Unity DOTS documentation
• Phaser 3 documentation
• Game Programming Patterns and related architecture references