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

2.3 KiB

[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, 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.

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.