ProjectV

A voxel sandbox engine with simulation at its core, written from scratch in C++26 on Vulkan 1.4.

A hole is cut into the glass shell at t = 1.5 s; the fluid automaton empties the sphere onto the floor. Rendered by the engine's normal real-time path in a Debug build: the camera follows a scripted path at a fixed 1/30 s step and every frame is saved, so the clip plays smoothly whatever the frame rate was.

Where it stands

The goal is a sandbox where the world is the simulation: the player reshapes it, builds, fights, wires up logic and writes mods and scenarios. Today ProjectV is the engine underneath, with one test scene (VoxelLab) to work on. The gameplay layers are still ahead.

What works now:

• Voxel world. Sparse storage (Sparse64Tree) mirrored into a NanoVDB-style GPU buffer, runtime edits, CPU raycast.
• Water. A fixed-point cellular automaton: exact mass conservation, deterministic regardless of traversal order, sleeps once at rest, every cell drawn at its fill level. Design: fixed-point Fluid CA.
• Meshing and culling. GPU greedy meshing, an optional mesh-shader path, HZB occlusion culling of chunks.
• Ray tracing, when the GPU has it. Sun shadows via ray query with a voxel-aware procedural intersection, DDGI probes, RT specular and refraction for glass and water. Without VK_KHR_acceleration_structure + VK_KHR_ray_query the engine still starts and these passes switch off.
• Lighting and image. Day–night cycle with sun and moon, sky ambient, contact shadows, MSAA 4× + SMAA, tone mapping and grading, about twenty debug views of the individual lighting terms.
• Physics. Jolt Physics with a CharacterVirtual controller: Creative, Spectator and Walk modes.
• Engine plumbing. Data-oriented layout (SoA by default), an ECS bridge on flecs, world generation on an async compute queue, Tracy instrumentation, input replay, scripted camera paths, a clean Vulkan validation run, unit, property and regression tests under ctest, run in CI for every push to main and every pull request.

Experimental and off by default: the physically based sky, volumetric clouds, height fog, bloom and aerial perspective (PROJECTV_SKY=ON, PROJECTV_CLOUDS=ON, …). They are not ready to show yet, so none of the footage here uses them.

Gallery

Orbit	Morning to sunset in eight seconds

Anatomy of a frame

One frame split into the engine's own debug views: the final image; direct sunlight and sky ambient as separate light terms; the ray-traced sun shadow mask; the greedy mesh (a checkerboard floor cannot merge, the sphere can); the cone directions of the voxel cone-traced diffuse term.

All media is produced by tools/capture/: capture.py flies a .campath and encodes MP4 and WebP with ffmpeg, layers.py renders the debug views and builds the grid.

Building

Windows and Linux are both supported, with Clang and Ninja on each.

Platform	Toolchain
Linux	Clang 22+ with libc++, CMake 3.30+, Ninja, Vulkan SDK 1.4.350+
Windows	clang-cl with Visual Studio Build Tools, CMake 3.30+, Ninja, Vulkan SDK 1.4.350+

git clone --recursive https://github.com/Leeleit/ProjectV.git
cd ProjectV
cmake --preset linux-clang-debug              # or windows-clang-debug
cmake --build --preset linux-clang-debug-build
ctest --preset linux-clang-debug-tests
./build/linux-clang-debug/bin/ProjectV

All third-party code comes in as git submodules. Details and troubleshooting: Linux, Windows.

Controls

Key	Action
W A S D	move
Space	up; double tap switches Creative ↔ Walk
Shift	down; sneak in Walk
Ctrl / Alt	faster / slower
LMB / RMB	remove / place a voxel
F2	cycle the placed material: white, gray, glass, water
`	settings: MSAA, overlays, debug views, editor tools
Tab	release the mouse
F1	hide the UI
Esc	quit

Layout

src/
  app/        main loop, camera, input, replay and camera-path automation
  core/       shared types, math, diagnostics
  voxel/      Sparse64Tree, NanoVDB buffer, chunk streaming, fluid automaton, CPU meshing
  render/     Vulkan renderer: passes, RT, DDGI, culling, post-processing
  shaders/    GLSL
  physics/    Jolt integration and character controller
  sim/        day–night cycle
  ecs/        flecs bridge
  asset/      asset manifest, loading and mesh baking
  ui/         Dear ImGui HUD and settings
  audio/      music playback
  platform/   SDL3 events
  debug/      overlays and profiling hooks
tests/        unit, property and regression tests (ctest)
tools/        lint, capture and profiling scripts
docs/         architecture guides and design notes, see docs/README.md

The design principles behind the code are written up in docs/philosophy/.

License

The code is licensed under the GNU General Public License v3.0 or later. The tracks in music/ are the author's own and are not covered by that license; please ask before reusing them.

Lev Kadochnikov