Files
aevolution/docs/adr/0005-ecs-strategy.md
T
2026-10-08 12:08:53 -04:00

55 lines
2.3 KiB
Markdown

[Reviewed]
# ADR-0005: Component storage before a general ECS
## Status
Adopted for proof as bounded experiment; production ECS deferred to M1 measurements.
## Context
Composition is locked; taxonomy inheritance is prohibited. The proof needs identity/state, not dynamic queries.
## Decision
Use sorted component-composed rows with monotonic non-reused u64 IDs, capped at100,000. Public values expose no third-party handles. lower_bound lookup is O(log n); erase is O(n).
## Alternatives Considered
EnTT is MIT, header-only C++ with documented uses. Flecs offers C/C++, relationships, queries/scheduling under MIT. Relative workload performance is unmeasured.
## Benefits
Small lifecycle/replay surface, stable order, easy diagnostics.
## Costs
Less flexible than archetypes or independent pools; erase moves rows.
## Risks
Prototype grows into homemade ECS, ID exhaustion, view invalidation, structural-order drift.
## Consequences
Compare churn/query/memory/order/diagnostics on sparse/dense workloads before adoption. Defer structural edits to stable phases. Reject exhausted/stale IDs; generational reuse needs separate design. [EnTT](https://github.com/skypjack/entt), [Flecs](https://github.com/SanderMertens/flecs).
## M1.5 measurement update (2026-09-19)
ADR-0021 adds an isolated EnTT4 comparison, with full byte-equivalence,
closed-form arithmetic, retired-ID and restore tests. See the
[protocol and results](../engineering/ECS_EVALUATION.md).
Windows and Linux evidence supports **retaining sorted rows for the bounded
proof and upcoming scheduler contract**, not adopting a general ECS yet. At
10000 entities, EnTT substantially reduces individual removal/replacement cost;
the row adapter uses less live container memory and has cheaper updates/export
in the Windows workloads. Linux sparse updates favor EnTT (~2.4x), while dense
updates/export still favor rows. These are tradeoffs, not a universal ranking.
Both compiler families' results and sanitizer evidence are recorded with the
experiment; native container growth differs between standard libraries.
The production decision remains deferred until variable component sizes,
capability add/remove, high churn over long lifetimes, interacting systems and
bounded external-ID mapping are measured. Compare EnTT groups and batched row
structural updates then. No public EnTT handles or dependency enter libevo.