Files
aevolution/schemas/world-fields-v1.md
T

1.9 KiB

Environmental field snapshot v1

All integers explicit little endian; signed coordinates use two's-complement u64 encoding. No struct padding. Unknown formats/units/material versions reject.

Offset Type Meaning
0 8 bytes ASCII AEVOFLD1
8 u32 format=1
12 u32 total length including checksum
16,24 u64 each nonzero world, frame
32,36 u32 each environmental units=1, material table=1
40,48 u64 each nonzero opening provenance, last transfer command (initially 0)
56 u32 sites, 1..4096
60 u32 presence bits 0..9 only, enum order in fields.hpp
64 3*u64 water capacities in fg for material 0,1,2
88 site_count*74 bytes sorted site records
following present_countsite_countu64 scalar logical arrays, increasing channel order
final 8 u64 FNV-1a of all preceding bytes; corruption detection only

Each site: signed X/Y/Z (24 bytes), box origin X/Y/Z and width/height/depth in um (48 bytes), material ID u16. Strictly increasing voxel addresses; valid one-voxel box and material 0..2. No duplicate habitat in a voxel. Field arrays contain finite per-site quantities, including repeated uniform values; absent differs from zero. Water capacity and global per-energy/element sums are validated on restore.

Length must equal 96 + sites*(74 + 8*present) (maximum 630880), also bounded by the API's 1 MiB envelope. All structural counts/lengths are checked before staging allocations. Canonical encoding omits storage layout, byte budget and pointers. No rates/residuals exist in v1: incident energy is finite stock only. Adding rate sources requires explicit versioned persistence, not default construction on restore. M5 world snapshots are a distinct format and cannot stand in for missing fields.

Codec buffers do not publish durable state. Field/terrain/biology consistency and recovery bundles remain later gates; LocalWorldFiles handles M5 terrain only.