acdream/docs/research/2026-07-25-slice-i3-prepared-collision-package.md

Slice I3 — prepared flat-collision package

Date: 2026-07-25 Scope: Modern Runtime Slice I3 only Behavioral boundary: storage, serialization, bake, and prepared lookup; production collision traversal remains on the parsed-DAT graph oracle.

Result

The existing format-1 acdream.pak now carries four appended asset types:

Numeric type	Payload
4	GfxObj collision BSP, polygon table, bounding sphere, and visual bounds
5	Setup cylinders, spheres, and movement dimensions
6	reusable CellStruct physics BSP, containment BSP, and portal polygons
7	independently keyed EnvCell portals, visibility, and seen_outside

The existing mesh type values 1–3 did not change. Bake-tool identity advanced from 3 to 4; the package binary container remains format 1.

FlatCollisionAssetSerializer is a strict little-endian codec. It:

• writes every float through SingleToInt32Bits;
• retains node, polygon, vertex, Setup-shape, portal, and visible-cell order;
• checks counts before allocation and validates combined byte requirements;
• checks cancellation during large rows;
• rejects wrong payload kinds, unsupported schema versions, non-zero reserved bits, invalid enum/tree/range contracts, truncation, and trailing bytes;
• remains behind the package entry CRC, so a CRC or structural fault marks only that typed entry corrupt.

IPreparedCollisionSource is separate from the render-only IPreparedAssetSource API. PakPreparedAssetSource implements both over the same PakReader and therefore maps the 29.9 GB immutable package once, not once per subsystem. Render and collision counters are independent.

CellStruct collision geometry is addressed by every EnvCell source key. The bake emits ordinary TOC aliases within the same source group and across groups only after comparing the complete serialized payload bytes. Per-cell topology is always written under its own key and is never inferred from shared render geometry.

Complete installed-DAT bake

Two independent full bakes used 16 and 7 workers:

Metric	Result
GfxObj mesh keys	15,318
Setup mesh keys	5,935
EnvCell mesh keys	729,888
GfxObj collision keys	15,318
Setup collision keys	5,935
CellStruct collision keys	729,888
EnvCell topology keys	729,888
Total typed keys	2,232,170
Physical blobs	781,196
Failures	0
File bytes	29,908,271,024
SHA-256	FEE8595D512DCB119C98B3D9911CDF9A905C97B624BCB826CEAF8DFD3F67269C

Both complete files have identical length and SHA-256. Exact-byte deduplication produced:

• 9,363 physical GfxObj collision blobs behind 15,318 keys;
• 979 physical Setup collision blobs behind 5,935 keys;
• 2,596 physical CellStruct collision blobs behind 729,888 keys.

The 16-worker bake completed and validated in 107.5 seconds; the 7-worker bake completed and validated in 80.5 seconds. Peak bake-process memory was 4.43–4.89 GB working set and 3.81–4.21 GB private. This is offline extraction state and is not mapped as committed client memory; the production source memory-maps the immutable file and pages only accessed ranges.

The validated bake-tool-4 package was installed at the machine-local DAT location for subsequent Slice I gates.

Verification

• strict codec round-trip and exact-float-bit tests for all four payloads;
• every truncation of a representative payload rejected;
• wrong-kind, negative/impossible count, trailing-byte, CRC, and valid-CRC structural-corruption tests;
• concurrent prepared reads and separate render/collision accounting;
• raw-DAT versus current cached-source preparation on representative installed GfxObjs, Setups, and EnvCells;
• filtered 1/8- and 8/3-worker bake equivalence and exact alias tests;
• complete installed package reads for representative GfxObj, Setup, CellStruct, and EnvCell topology keys;
• failed validation and timed cancellation preserve the last published file;
• Release build: zero warnings;
• complete Release suite: 8,371 passed / 5 skipped.

No divergence-register row changes: no gameplay decision or traversal route changed. Slice I4 adds the flat traversal referee while the graph path remains authoritative.