ADR-001: Archetype-Based ECS Storage

Status: Accepted Date: 2026-01-25

Context

When implementing an Entity Component System, the two main storage approaches are:

1. Sparse Sets -- Each component type stored separately, entities indexed by ID
2. Archetypes -- Entities grouped by component signature, data stored in tables

Performance is critical for a game engine targeting 60+ FPS with thousands of entities.

Decision

We chose archetype-based storage for the ECS implementation.

Entities with the same set of components are stored together in archetype tables, enabling:

• Cache-friendly iteration over entities with matching component signatures
• Efficient query execution by iterating entire archetype tables
• Predictable memory layout for better prefetching

Consequences

Positive

• Cache efficiency -- Components of matching entities are contiguous in memory
• Fast iteration -- Queries iterate dense arrays without indirection
• Predictable performance -- Linear memory access patterns
• Parallel-friendly -- Different archetypes can be processed independently

Negative

• Component add/remove overhead -- Entity moves to new archetype table
• Memory fragmentation -- Many unique archetypes can fragment memory
• Complex implementation -- Archetype graph management adds complexity

Alternatives Considered

• Sparse Sets (bitECS-style) -- Simpler implementation, faster component add/remove, but slower iteration due to indirection. Rejected because iteration performance is more critical for typical game systems.

• Hybrid Approach -- Use sparse sets for frequently-added components and archetypes for stable components. Rejected for complexity; pure archetype approach is sufficient with archetype caching.

Related

• ADR-007: Data-Oriented Design -- The architectural principle this storage model implements
• Data-Oriented Design -- Detailed explanation of SoA and archetype storage