| # Snapshot area-mask lifecycle and message arguments |
|
|
| Reproduce with `python3 scripts/analyze_snapshot_areas.py`; validate with `python3 scripts/test_snapshot_areas.py`. Evidence: [snapshot-areas.json](snapshot-areas.json), retaining five hash-verified graphs per Linux ELF64 engine. This connects [area-bit output](AREA_FLOODING.md) to server snapshot callers. |
|
|
| The collector evaluates bounded native instruction slices with supplied client/frame pointers, sequence words, area labels and cluster returns. It composes CM_WriteAreaBits instructions across stopped caller boundaries and supplies memset effects. Point/leaf/cluster/PVS services, entity visibility, qsort, real recursive viewpoint selection, message encoders and original processes never execute. Caller register restoration is explicit; ABI/clobber/lifetime and original-runtime conformance remain open. |
| |
| ## SNAP-001 — Ring selection and mask initialization (RE-333) |
| |
| Sixteen paired initialization probes cover sequence words -1/0/1/31/32/33/0x7fffffff/0x80000000. The selected record address is: |
| |
| `client + 0x20d40 + 524 * (sequence_word & 31)` |
|
|
| These are Linux ELF64 client offsets, not a portable Rust ABI or on-disk record layout. The selected frame pointer passed into visibility is record +8; the mask pointer is record +12. Four eight-byte stores clear exactly 32 mask bytes, and a four-byte store clears record +512 (the entity-count word used by the retained snapshot loop). Canaries outside the record are preserved. |
|
|
| The length word at record +8 is **not cleared by this slice**: it retains the supplied 0xa5a5a5a5 sentinel. Later successful area-bit calls overwrite it. Initialization/bypass paths outside this slice must be recovered before making any stale-length or whole-frame correctness claim. Global snapshot stamp updates, player-state copies and entity collection are not composed here. |
|
|
| ## SNAP-002 — Viewpoint union and final complement (RE-334) |
|
|
| The visible-from-point caller receives area and cluster returns from separate services. Its bounded argument slice forwards the area to CM_WriteAreaBits with frame +4 as the mask destination. It then stores the returned byte length at frame +0 and requests CM_ClusterPVS with the supplied cluster value. The collector supplies cluster 5; actual cluster/PVS selection is not executed. |
|
|
| One hundred eighty paired compositions cover area counts 0/1/7/8/9/16/17/255/256, viewpoint-area sequences `[0]`, `[0,1]`, `[1,0]`, `[-1]`, `[0,-1]`, and cm_noAreas words 0/1. Labels are explicitly supplied as `i % 3 + 1`. Each sequence begins with the native 32-byte clear and calls the native area-bit instruction slice repeatedly into that same buffer. Since the helper ORs bits, multiple viewpoints form a union. The two ordinary viewpoint orders agree in these fixtures. A -1 viewpoint or the bypass flag fills the used byte span with ones. |
| |
| The send function's eight NOTL instructions complement **all 32 bytes**, independently of returned length. Thus areas selected by the union become zero bits in the complemented buffer; previously zero bits become ones. Rendering interpretation requires client/renderer evidence and is not inferred here. For an all-area fill, the used bytes become zero while the unused trailing bytes become 0xff. The collector preserves the exact native inversion instructions and buffer canaries. |
| |
| A separate paired recursive-argument slice forwards the same frame pointer and entity-list pointer into another SV_AddEntitiesVisibleFromPoint request, with an alternate point pointer at supplied object +0x68 and fourth argument one. This connects the union mechanism to the retained portal recursion call site. The geometry/distance/flags/reentrancy gates selecting that call, and actual recursive entity/PVS collection, remain open. |
|
|
| The fixtures supply label records even for requested area 1 with count zero/one. Those deliberately supplied out-of-range records characterize local unguarded helper behavior, not valid map states. Counts up to 256 fit the observed buffer; this does not establish native map limits or complete count/capacity validation. |
|
|
| ## SNAP-003 — Length and mask message requests (RE-335) |
|
|
| Twelve paired serialization probes cover lengths 0/1/2/3/31/32. The server first requests: |
|
|
| 1. `MSG_WriteByte(message, frame.length)`. |
| 2. `MSG_WriteData(message, frame + 4, frame.length)`. |
|
|
| The second request excludes unused tail bytes when length is below 32. The collector captures the pointer/count and exact supplied bytes in the requested span. It stops before both writers; no encoded packet is produced or sent. The retained MSG_WriteByte/MSG_WriteData graphs are static evidence for subsequent bit/Huffman/overflow analysis, not executed encoders. |
|
|
| Snapshot flags, server time/delta headers, reliable commands, entity/player deltas, packet overflow/rate/download behavior, client parse bounds and renderer consumption remain separate work. The area-mask requests observed here are part of the snapshot message, not a complete network protocol specification. |
|
|
| ## Validation and next work |
|
|
| Eight independent tests check ring arithmetic and exact resets, retained length, union/complement/tail bytes, native caller arguments and length storage, supplied fill requests, order agreement, message pointer/count/payload spans, recursive argument sharing, paired outcomes and absence of executed CALL instructions in recorded traces. Full masks are retained for larger compositions with trace counts/hashes; small traces retain addresses. |
|
|
| RE-336: compose snapshot initialization/bypasses and real point/leaf/cluster/PVS/entity/portal selection; establish valid area/index/capacity and frame/client lifecycle; recover message encoding/overflow and client snapshot parse bounds/copy behavior; connect renderer mask semantics and full snapshot/delta/reliable protocol; validate actual maps and original-runtime/all-platform fixtures. Rust/Bevy/Solari integration remains open. |
|
|
| Client follow-up: [client parsing](CLIENT_MASKS.md) recovers Linux reset/length guard/copy boundaries (RE-337–339). Message encoding/decoding and complete snapshot/runtime/renderer behavior remain open. |
|
|
