Files
aevolution/docs/adr/0021-ecs-evaluation.md
T

72 lines
3.4 KiB
Markdown

# ADR-0021: Isolated EnTT comparison
## Status
Accepted for M1.5 measurement only. No production ECS adoption or public API change.
## Context
ADR-0005 requires evidence before the bounded sorted-row proof becomes a general
ECS. We need sparse multi-component queries and structural churn measurements,
including deterministic export cost rather than raw iteration alone.
## Decision
Compare a sorted composed-row adapter with EnTT 4.0.0 in an opt-in experiment.
Use EnTT commit 85c6bba014049b5de8fad49d25424df2f1f6a8c1, single header SHA256
eedcb83fedffe640334ef69a0647625a186cf1daeb333b21b0a1445f01e89b6c and MIT license
SHA256 73547f6370ee16ea560665329bb62d4e2d8250f41eaa204b47a6c694ca3286ea.
An explicit preparation command downloads/validates both; configuration is
offline and rejects a mismatched header. Default builds do not use EnTT.
The experiment owns adapters and monotonic external IDs. EnTT handles never enter
simulation contracts or snapshots. Use a tracking memory resource for container
allocation requests; report its scope and limitations. Compare canonical bytes
and independent closed-form counter results before accepting timing samples.
See [protocol](../engineering/ECS_EVALUATION.md).
## Alternatives Considered
Flecs is a maintained MIT C/C++ candidate with relationships and scheduling.
Those features exceed this first storage/query experiment and would confound a
small adoption comparison. It remains an alternative if EnTT's adapter cost or
query model fails later needs; no performance ranking against Flecs is claimed.
Writing an internal sparse-set framework now would prejudge the experiment.
## Benefits
EnTT is C++-native, header-only, and documents views, lifetime and allocator
support. Its July 2026 release supplies current maintenance evidence. The
experimental adapter can be removed without migrating game state.
## Costs
Template compile time, larger experimental executable, an explicit network
preparation step and retained MIT attribution. This single-header experiment
does not select a general package manager; ADR-0003's compiled-dependency gate
still applies. Only the benchmark includes the dependency.
## Risks
Independent updates understate deterministic ordering cost for interacting
organisms. Small synthetic components may misrepresent real genome/phenotype
layouts. Allocator counts exclude process RSS, stack, allocator bookkeeping and
snapshot scratch buffers. Seven samples on a shared host are descriptive, not
statistical capacity promises. EnTT's native handle reuse is not persistent ID
reuse; the adapter must enforce the distinction.
## Consequences
Run release correctness checks, sanitizers and both supported compiler families.
Record raw samples, toolchain, binary/build observations, canonical equivalence
and limitations. Make no production adoption from one fast loop. Foundation
maintainers own updates/removal; keep third-party warnings outside owned code.
MIT notices remain in the prepared dependency directory and any redistributed
experimental binary's accompanying materials. No known-vulnerability absence is
asserted merely from version selection.
Sources: [EnTT release](https://github.com/skypjack/entt/releases/tag/v4.0.0),
[pinned source](https://github.com/skypjack/entt/tree/85c6bba014049b5de8fad49d25424df2f1f6a8c1),
[ECS contracts](https://github.com/skypjack/entt/wiki/Entity-Component-System),
[Flecs](https://github.com/SanderMertens/flecs).