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

0002. Half-scale voxel grid

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

Context

The world is entirely built from voxels. The physical edge length we choose for a voxel directly impacts nearly every system: collision resolution, mesh chunking, level-of-detail thresholds, network bandwidth, and in-memory data layout all scale directly with voxel density. While a finer grid allows for much more expressive terrain and building, it comes at a steep cost in total voxel count per unit volume.

Compared to a conventional coarse voxel grid with a 1-meter edge, halving the edge to 0.5 meters doubles the linear resolution but multiplies the voxel count per unit volume by roughly 8x.

Decision

We are setting the voxel edge to exactly 0.5 meters. Inside the engine, the base world unit is the block itself (1 unit = 1 block). We count in blocks rather than meters. Because of this, a standard player occupies 3 units tall by 2 units wide (3 blocks by 2 blocks).

Consequences

• The density is roughly 8x that of a 1-meter grid world per unit volume. We absolutely must design chunk dimensions and voxel data layouts with this multiplier in mind; a data layout that feels comfortable on a coarse grid might be completely unviable here.
• Collision, meshing, LOD selection, and network bandwidth budgets all inherit this 8x factor and have to be designed against it from day one.
• The motivating benefit is that we can support much finer terrain and construction detail.
• This is a load-bearing choice that will be incredibly expensive to revisit later, mainly because persisted worlds and save formats fundamentally encode the block scale.