Engine Features

Everything built from the ground up — no game engine, no shortcuts.

Voxel Global Illumination

Real-time GI in a 256³ voxel volume using DDA ray marching. Hard and soft shadows via voxel tracing — no shadow maps. Per-vertex AO baked with DDA hemisphere tracing using Amanatides & Woo traversal.

Binary Greedy Meshing

Reduces triangle count 10-20x versus naive cubes. Multi-draw indirect rendering batches ~2,200 chunks into a single draw call. 4 LOD levels by distance with compute shader frustum culling on GPU.

Volumetric Lighting

God rays via a 3-pass pipeline: half-res DDA ray march, bilateral blur, and composite. Temporal dithering with Henyey-Greenstein phase function, adjustable 24-72 sample steps.

Water System

Heightfield rendering with pipe-model flow simulation. Ray-marched fullscreen water pass with wave animation, Fresnel reflections, refraction, and underwater fog.

Procedural Worlds

8 biomes (grasslands, desert, jungle, tundra, mountains, ocean, swamp, cavernous highlands) with 3D Perlin caves, ore veins, procedural trees, vegetation, and ruins. Region file persistence with zstd compression at 3:1 ratio.

Spatial Audio

3D positional audio with material-based sound categories. DDA raycast occlusion crossfades ambience between environments. Convolution reverb in caves, footstep material detection, and music system with crossfade transitions.

Character System

3rd-person camera with skeletal animation and FBX model loading via ufbx. Character customization for outfits, hair, and heads. Body part editor with bone-driven skinned meshes lit by the voxel GI system.

Post-Processing

Hybrid morphological-temporal AA with depth edge detection, pattern matching, temporal accumulation, and sharpening. Depth of field with near/far blur layers. Bloom, SSAO, and greedy-meshed voxel clouds with terrain shadows.

Under the Hood

Some of the implementation details.

Rendering Pipeline

Sky pass — procedural atmosphere
Opaque geometry — MDI mega-buffer batching
Characters — skinned meshes + voxel GI shadows
Water pass — ray-marched heightfield
SSAO — screen-space ambient occlusion
Volumetrics — DDA ray march + blur + composite
Post-process — DoF, AA, bloom
UI — hotbar, debug overlay, menus

Architecture

wgpu — Vulkan/DX12/Metal abstraction
19 WGSL shaders — compute + graphics
8 worker threads — generation, meshing, lighting
Lock-free channels — crossbeam MPSC queues
Region files — 32x32 chunk sectors, zstd compressed
SlotMap ECS — generational arena, O(1) lookup
Priority task system — player actions bypass gen queue
Criterion benchmarks — meshing, shadows, generation

What is Mosaic?

Mosaic is an open-source voxel engine written from scratch in Rust and wgpu. It is not a game engine plugin or a wrapper around an existing renderer — every system (rendering pipeline, world generation, meshing, lighting, audio, ECS) was built ground-up across approximately 32,000 lines of code.

The primary technical focus is real-time voxel global illumination: light is propagated through a 256³ voxel volume each frame using DDA ray marching, enabling hard and soft shadows without shadow maps. The engine targets graphics and game-engine developers interested in low-level rendering techniques rather than end users.

The source is available on GitHub under an open-source license. It runs on Windows, macOS, and Linux via wgpu’s Vulkan, DirectX 12, and Metal backends.

How does Mosaic implement real-time global illumination?

Light propagation

DDA ray marching — Amanatides & Woo traversal steps through a 256³ voxel volume to trace rays from the sun and sky into the scene each frame
No shadow maps — hard and soft shadows are computed entirely by voxel ray tracing, avoiding the resolution and aliasing limitations of depth-map approaches
Per-vertex AO — ambient occlusion is baked per vertex at mesh-build time via DDA hemisphere tracing, then stored in the vertex buffer for zero runtime cost
GPU compute — shadow and AO passes run in WGSL compute shaders via wgpu; 8 background worker threads keep the GI volume in sync with player edits

Volumetric lighting

God rays — 3-pass pipeline: half-resolution DDA ray march into the GI volume, bilateral blur, then full-res composite
Phase function — Henyey-Greenstein scattering with 24–72 adjustable sample steps and temporal dithering to avoid banding
Greedy-meshed clouds — volumetric clouds are voxel geometry processed through the same greedy meshing pipeline as terrain, casting terrain shadows
Character integration — skinned mesh characters receive GI shadows from the voxel volume, so lighting is consistent between geometry types

What is Mosaic built with?

Core dependencies

wgpu — portable GPU abstraction targeting Vulkan, DirectX 12, and Metal from a single codebase
19 WGSL shaders — mix of compute and graphics passes; no third-party shader library
crossbeam — lock-free MPSC channels between 8 worker threads for generation, meshing, and lighting
SlotMap — generational arena backing the custom ECS; O(1) entity lookup with safe slot reuse
zstd — region file compression at a 3:1 ratio
ufbx — FBX loader for skeletal animation and character models

Architecture decisions

No game engine — Mosaic does not use Bevy, Godot, Unity, or any existing engine; the ECS, renderer, and world systems are all first-party
Multi-draw indirect — ~2,200 chunks batched into a single GPU draw call via MDI mega-buffer; compute shader frustum culling on GPU
Binary greedy meshing — face-merging reduces triangle count 10–20× over naive cubes; 4 LOD levels by view distance
Priority task queue — player block edits bypass the generation queue so edits feel instant
Criterion benchmarks — meshing, shadow propagation, and world generation are all benchmarked; regressions surface before commit

Building a voxel renderer from scratch vs. using a game engine

When each approach makes sense — an honest look.

Engines like Bevy or Unity with a voxel plugin are the right starting point for most projects. You get a scene hierarchy, input handling, asset pipeline, editor tooling, and an ecosystem of plugins from day one. A voxel terrain plugin in Bevy, for instance, can have procedural chunks rendering in a few hundred lines.

Building from scratch makes sense when the rendering technique is the point. Mosaic exists to explore what real-time voxel GI looks like in practice at the system level: how a 256³ GI volume integrates with chunk streaming, how DDA traversal budgets interact with frame time, how greedy meshing must be structured to keep per-vertex AO correct across chunk boundaries. None of these questions are answerable inside an engine abstraction that hides the GPU pipeline.

The tradeoff is real: ~32k lines of Rust to reach parity with features an engine gives you for free. If you need a voxel game shipped, use an engine. If you need to understand the renderer at the instruction level — or want a clean reference implementation of DDA voxel GI in wgpu — Mosaic is that reference.