Module addr 

Address math for the world ↔ grid-local ↔ chunk + voxel coordinate spaces.

Three spaces:

1. World (f64). Universe-level positions; one DVec3 per point.
2. Grid-local (f64). Position in a grid’s local frame (origin + rotation already applied). Voxel size is fixed at 1 unit / voxel; integer voxel coordinate v covers grid-local space [v, v+1) on each axis.
3. Chunk + voxel-in-chunk (i32 + u32). A grid-local voxel coordinate v: IVec3 decomposes into a chunk index c: IVec3 and a voxel offset u: UVec3 within that chunk. Chunks are XY = CHUNK_SIZE_XY, Z = CHUNK_SIZE_Z, so u.x, u.y < CHUNK_SIZE_XY and u.z < CHUNK_SIZE_Z.

Negative voxel coords decompose with i32::div_euclid / i32::rem_euclid semantics: voxel -1 lives in chunk -1 at position (CHUNK_SIZE - 1). This matches the natural “voxel slots tile the integer line, chunks tile groups of slots” intuition; using truncating division would put voxel -1 in chunk 0 at position -1, splitting the chunk-0 / chunk-(-1) boundary inconsistently.

All conversions go through these helpers — risk R5 in PORTING-SCENE.md calls out the f64↔i32 boundary as a common off-by-one source, so concentrating the casts here lets the property tests pin them.

Structs

GridLocalPos

Decomposition of a grid-local position into discrete chunk + voxel + sub-voxel coordinates.

Functions

grid_local_to_world

Inverse of world_to_grid_local: reconstruct the world-space position of a grid-local chunk + voxel + sub-voxel.

voxel_global

Inverse of voxel_split: combine a chunk index and a voxel-in-chunk offset back into a grid-local voxel coordinate.

voxel_split

Split a grid-local voxel coordinate into (chunk, voxel-in-chunk).

world_to_grid_local

Project a world-space position into the grid-local frame and decompose into chunk + voxel + sub-voxel.