Voxel Query Core

voxel_query_core is a standalone C++20 library for deterministic voxel query algorithms and replay-oriented data validation.

It is best thought of as a small domain algorithm library, not a renderer or a full engine runtime.

What it includes:

• local voxel narrow phase and bounded sweep traversal
• object-space and batched query orchestration
• compact material-return helpers
• promoted pure-data shadow and solver slices
• snapshot schema, binary I/O, compare, and replay support
• offline replay dispatch through engine_skeleton

What it deliberately does not include:

• renderer backends
• process injection or live capture hooks
• editor UI
• platform-specific engine glue

Status

Current package version:

• 0.1.0

API stability policy:

• pre-1.0 semantic versioning
• public API is useful now, but still settling
• snapshot binary compatibility is tracked separately by per-format file header versions

More detail:

• VERSIONING.md
• NAMING.md
• TOOLS.md

Library Layout

• include/voxel_query_core public headers
• src implementation
• tests deterministic library coverage
• tools optional offline utilities and seed generators
• examples/minimal_cast minimal integration example

Public Surface

The versioned public API consists of:

• headers under include/voxel_query_core
• CMake target vqc::voxel_query_core
• generated header voxel_query_core/version.h available from the build tree after configure and from the installed include tree after cmake --install

The most useful entry points are usually:

• narrow_phase.h
• window_cast.h
• grid_cast.h
• object_cast.h
• batched_cast.h

Replay/data-path users will also want:

• snapshot_schema.h
• snapshot_io.h
• compare.h
• replay_runner.h
• engine_skeleton.h

Build

cmake -S . -B build
cmake --build build --config Release

To also build the offline utilities under tools/:

cmake -S . -B build -DVOXEL_QUERY_CORE_BUILD_TOOLS=ON
cmake --build build --config Release

Install

cmake -S . -B build
cmake --build build --config Release
cmake --install build --config Release --prefix .local/install

Installed consumers can use:

• package name voxel_query_core
• target name vqc::voxel_query_core

If VOXEL_QUERY_CORE_BUILD_TOOLS=ON is enabled, the offline tool executables are also installed into the package bin/ directory.

Test

.\build\Release\voxel_query_core_tests.exe

Minimal Integration

Source:

#include <voxel_query_core/grid_cast.h>

vqc::GridView grid{};
grid.dims = {8, 8, 8};
grid.cell_size = 1.0f;
grid.occupancy_faces.assign(grid.CellCount(), 0u);
grid.material_indices.assign(grid.CellCount(), 0u);
grid.occupancy_faces[grid.LinearIndex(3, 4, 4)] = 0xBFu;

vqc::SphereSweepInputs inputs{};
inputs.start_local = {-2.0f, 4.5f, 4.5f};
inputs.direction = {1.0f, 0.0f, 0.0f};
inputs.max_distance = 16.0f;

vqc::LocalHitResult result{};
const bool hit = vqc::CastSphere(grid, inputs, &result);

Installed-package CMake:

cmake_minimum_required(VERSION 3.20)
project(my_app LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
find_package(voxel_query_core CONFIG REQUIRED)

add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE vqc::voxel_query_core)

Working example files live in:

• examples/minimal_cast/main.cpp
• examples/minimal_cast/CMakeLists.txt

Data Model Notes

GridView uses dense X-major arrays:

• occupancy_faces per-cell occupancy and optional face-mask bits
• material_indices per-cell lookup into material_rows
• material_rows compact fixed-size material payload table

This design keeps the query path easy to serialize, replay, diff, and embed in offline tooling.