Files
aevolution/docs/architecture/SPATIAL_CONTRACT.md
T

64 lines
3.4 KiB
Markdown

# Local spatial contract
M1.7 implements [ADR-0023](../adr/0023-local-neighborhood-queries.md).
```cpp
// include/evo/simulation/spatial.hpp
auto ids = evo::query_neighbors(world, center, evo::Millimetres{16});
```
| Input/result | Contract |
|---|---|
| Frame | Existing synthetic 2D torus, coordinates 0 through 1023 mm per axis |
| Center | Out-of-domain coordinates return `Error::invalid_position`, even for an empty world |
| Radius | Unsigned millimetres, zero through UINT32_MAX; no silent clamp or rejected large radius |
| Geometry | Shortest periodic Euclidean distance; equality with radius is included |
| Identity | Ascending unique IDs; coincident entities all included; caller explicitly excludes self if needed |
| Lifetime | Returned vector owns IDs, not entity references; later removal may invalidate an identity |
| Mutation | No state, tick, PRNG, snapshot or input changes; no clock/I/O/dependency |
| Concurrency | Owner provides a stable world for the duration of the call |
For each axis, `d = min(abs(a-b), 1024-abs(a-b))`; membership is
`dx*dx + dy*dy <= radius*radius`, evaluated in u64. Maximum squared distance is
524,288. Thus radius 725 includes the entire domain; radius 724 can exclude the
diagonal antipode. Exactly opposite points have an ambiguous direction but a
unique distance; this API deliberately does not return displacement vectors.
The scan observes current rows on each call, so scheduled creates/removals,
movement and restored state need no invalidation hook. Snapshots serialize only
authoritative state. Future indexes must preserve this query contract and measure
update/rebuild costs, not just warm query timings. Cross-region ghosts and senses
require separate ownership/perception contracts before integration.
`evo-spatial-benchmark` reports seeded uniform and clustered worlds, 1k/10k/100k
entities, 128 queries, radii 0/16/128/725, one warmup and three measured samples.
Every result contributes to a checksum. Timing includes allocation/destruction,
excludes world/query construction, and has no portable pass/fail threshold.
Timing also includes result checksumming. This is a baseline measurement, not an
index comparison or an MMO capacity claim.
Windows MSVC 19.44 Release on Ryzen 7 9800X3D (uncontrolled desktop, 2026-09-19):
median milliseconds for 128 queries over 100,000 entities:
| Radius (mm) | Uniform | Clustered |
|---|---:|---:|
| 0 | 13.60 | 14.18 |
| 16 | 17.73 | 59.31 |
| 128 | 19.48 | 48.53 |
| 725 | 53.35 | 48.36 |
Raw three-sample results and compiler metadata are in
[spatial-msvc1944.jsonl](../engineering/results/spatial-msvc1944.jsonl).
Clustered query centers are inside the same 32 mm patch as the entities; uniform
centers span the entire domain. Dense result allocation/checksumming matters as
well as scanning. This does not justify querying all 100,000 entities every tick;
measure an index against this baseline when interaction frequency is known.
GCC 14.2 Release in Gitea run 1409 produced identical checksums and match counts
for all 72 samples; raw output is retained in
[spatial-gcc142.jsonl](../engineering/results/spatial-gcc142.jsonl).
At 100,000 entities the corresponding Linux medians were 62.22/48.97/61.35/90.19 ms
for uniform and 36.42/139.94/77.52/76.47 ms for clustered scenarios (radii in the
table's order). Runner CPU allocation was not captured; these are within-runner
observations, not a cross-platform performance comparison.