synvael/docs/adr/0002-half-scale-voxel-grid.md

0002. Half-scale voxel grid

• Status: Accepted
• Date: 2026-06-27

Context

The world is built from voxels. The physical edge length chosen for a voxel propagates into nearly every system: collision resolution, mesh chunking, level-of-detail thresholds, network bandwidth, and in-memory data layout all scale with voxel density. A finer grid yields more expressive terrain and building at a direct cost in voxel count per unit volume.

Relative to a conventional coarse voxel grid with a 1 m edge, halving the edge to 0.5 m doubles the linear resolution and multiplies the voxel count per unit volume by roughly 8×.

Decision

A voxel edge is 0.5 m. Inside the engine the world unit is the block itself: 1 unit = 1 block, counted in blocks rather than metres. A player therefore occupies 3 units tall × 2 units wide (3 blocks × 2 blocks).

Consequences

• Density is ~8× that of a 1 m-grid world per unit volume. Chunk dimensions and voxel data layouts must be chosen with that multiplier in mind; a layout that is comfortable on a coarse grid may not be here.
• Collision, meshing, LOD selection, and network bandwidth budgets all inherit the 8× factor and must be designed against it from the start.
• Finer terrain and construction detail become possible, this is the motivating benefit.
• The choice is load-bearing and expensive to revisit later, since persisted worlds and save formats encode the block scale.