Meshing

The hierarchical greedy mesher's three passes and cross-level coalescing, face classes, built surfaces' microvoxel stairs, foliage edges, the watertight guarantee, and what a chunk mesh holds.

Ragnavoxel turns voxels into a small number of large rectangles. voxel/Mesher.hpp, rv::voxel::Mesher.

rv::voxel::Mesher mesher(palette);
rv::voxel::ChunkNeighborhood hood{&chunk, {&px, &nx, &py, &ny, &pz, &nz}, rv::voxel::kAir};
rv::voxel::ChunkMesh mesh;
mesher.mesh(hood, mesh);

A chunk is meshed with its six face neighbours, so faces on its border are culled against the chunk next door. A null neighbour lies outside the world and reads as boundary (air by default; an opaque id seals the world’s edge).

Three passes and a coalescing

The hierarchy of the storage is the hierarchy of the mesher:

Block pass (16³ per chunk). Faces between uniform blocks are merged on the block grid. Faces touching a non-uniform block are passed down.
Brick pass (128³ per chunk). Inside and around non-uniform blocks, faces between uniform bricks are merged on the chunk-wide brick grid, so terraces and canopies merge across block borders. Faces touching detail bricks are passed down.
Microvoxel pass (64³ per block). Faces of detail bricks, and faces next to them, are merged at full voxel resolution.
Cross-level coalescing. Coplanar rectangles from any level that share a full edge and the same coarse class are joined.

So a hillside of solid rock is a handful of block-sized quads, a terrace edge is brick quads, and only where real detail lives (a carved stone, a leaf, a hand-placed microvoxel) does the mesher work at full resolution.

Face classes

Faces merge only when they are similar. A face class is a material plus its face parameters, quantized for one level of the hierarchy: coarser at the block level, finer at the microvoxel level. Two faces merge at a level when their voxel types fall in the same class there. Similar voxels therefore share large quads, while the heightfield pattern, evaluated per face in world space on the GPU, keeps the surface varied (see Rendering).

palette.faceClass(id, level, dir) gives the class of a voxel type’s face at a level.

What a quad carries

A MeshQuad is one greedy-merged rectangle in chunk-local voxel units: its minimum corner, its size along the two axes of its face plane, its direction and its face class. Two extras ride along:

Stair slopes. Solid, non-foliage faces that are the steps of a microvoxel stair (a pitched roof, a ramp, a turned column) carry the stair’s slope in two signed 6-bit angles, one per axis. The shader rebuilds a smooth normal from them, so a roof built of tiny steps shades as one sloping plane. dressed materials (built surfaces) use this.
Leaf edges. Leaf faces mark which stretches of their border are open silhouette edges: the foliage surface turns away there instead of carrying on into a coplanar neighbour or folding into a concave corner. Leaves are grown inside the face and never clipped by such an edge.

What a chunk mesh holds

ChunkMesh keeps three lists, one per pass that draws them: opaque, water and glass. Its stats record the quads each level’s greedy pass emitted, how many coalescing removed, the raw unit faces before any merging, and the time spent in each pass.

Watertight by test

The engine’s tests check the mesher against a brute-force face count: the output covers every visible face exactly once, with no gaps and no overlaps, at every level of the hierarchy. Physics builds its colliders from the same quads (see Physics, audio and input).

Meshing models

Actors and props are meshed the same way from their own voxel grids, at any cell size (see Content as text). Each cell of a model grid carries the joint it rides on, so one grid can hold a whole articulated body, and skinned meshing keeps such bodies closed under any pose.

Written from the engine's headers and source as of commit 02e81b2 (2026-11-01).