2.9 KiB
Local spatial contract
M1.7 implements ADR-0023.
// 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. 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.