voxel-framework
A reusable voxel engine framework built on Bevy.
Features
- 16×16×16 voxel chunks with efficient flat-array storage
- Greedy meshing with LOD support and neighbor-aware face culling
- Seam-free borders via neighbor-aware meshing (default in the live system)
- Pluggable
ChunkGeneratortrait — bring your own world generation - Built-in
AsteroidGeneratorwith FBM noise and mineral distribution - World streaming — automatic chunk load/unload based on viewer position
- Save-on-unload — chunks written to disk when streaming out
- PBR rendering via Bevy's
StandardMaterialwith vertex colors - Binary chunk persistence
- Dynamic LOD (2 levels based on viewer distance)
- Auto-save chunk persistence (optional, disk-backed)
- TOML world configuration via
world.toml - Coordinate utilities for world/chunk/voxel space conversions
- Occlusion culling — chunks surrounded by solid neighbors are auto-hidden
- Capsule-voxel collision for player movement
- Mining API — break-time tracking and
VoxelBrokenevents - Block placement API — cooldown tracking and
VoxelPlacedevents - Loading progress —
LoadingProgressmessages and aWorldReadyevent for loading screens
Release Status & Stability
voxel-framework 0.4 is an early public release of a Bevy-first voxel game
framework. It is intended to be usable by real consumer crates, examples, and
experiments, but it is not a 1.0 stability promise yet.
Compatibility target:
| Area | Current status |
|---|---|
| Crate version | 0.4.x |
| Bevy version | 0.18 |
| Rust version | MSRV 1.85 |
| Stability | Public API can still change across 0.x minor releases |
| Distribution | crates.io for released versions; git tags for pinned source installs |
Before each release, the project validates formatting, feature combinations,
doctests, integration tests, documentation, package contents, and cargo publish --dry-run. The CI workflow in .github/workflows/rust.yml mirrors those
release gates without using cargo build.
Known Limitations
- This is a framework/library, not a complete editor or standalone game. Your game crate still owns window setup, input choices, game state, and custom UX.
- The bundled examples are graphical Bevy apps and require a working display to run interactively. Headless tests cover pure logic and selected runtime contracts, but they do not replace manual playtesting.
ViewerPositionmust be kept in sync with your camera/player every frame; it drives chunk streaming. If it never changes, no new chunks stream in.ChunkGenerator::generateruns on background threads. Generators must be deterministic, owned, andSend + Sync; they must not access the BevyWorld,Commands,Res, orQuery.- Mining and placement expose reusable state machines and helper functions. You still decide when to call them from your own input systems unless you opt into the provided input-adapter plugins.
- Persistence is disk-backed chunk persistence for local worlds. The binary
format is suitable for
0.xprojects but should not be treated as a permanent 1.0 save-file compatibility guarantee yet. - Multiplayer, networking, world editing tools, and advanced asset pipelines are outside the current release scope.
Plugin Architecture
voxel-framework is a flat catalog of composable Bevy plugins grouped by
responsibility. Games choose the plugins they need from these official
categories:
| Category | Meaning | Examples |
|---|---|---|
| Engine | Foundation for streamable/renderable voxel worlds | WorldPlugin, RenderPlugin<V>, MeshPlugin<V>, OcclusionPlugin<V>, LoadingPlugin |
| World Data | Chunk sources, generation, persistence, lifecycle data | GeneratorPlugin<V>, MultiGeneratorPlugin<V>, PersistencePlugin<V> |
| Gameplay | Reusable rules and interactions | MiningPlugin, PlacementPlugin, PlayerPlugin<V>, HotbarPlugin, DropsPlugin<I> |
| Default Implementation | Replaceable UI/audio/visual defaults | UiPlugin, SkyboxPlugin, FragmentPlugin, DefaultAudioPlugin |
| Convenience | Bundles, input adapters, compatibility, recipes/prototyping helpers | VoxelCorePlugin<V>, VoxelPlugin<V>, MiningInputPlugin<V, I>, PlacementInputPlugin<V> |
The categories are also exposed as marker traits:
EnginePlugin, WorldDataPlugin, GameplayPlugin,
DefaultImplementationPlugin, and ConveniencePlugin.
VoxelCorePlugin<V> and VoxelPlugin<V> are convenience bundles kept for
compatibility and quick starts. They are useful, but they are not the primary
architecture:
| Bundle | What it composes |
|---|---|
VoxelCorePlugin<V> |
Engine foundation plus the lightweight gameplay primitives MiningPlugin and PlacementPlugin |
VoxelPlugin<V> |
VoxelCorePlugin<V> plus selected defaults: fragments, skybox, SFX events, UI, and hotbar when the items feature is enabled |
GeneratorPlugin<V> and PersistencePlugin<V> are explicit World Data choices
regardless of which convenience bundle you use.
// Compatibility bundle: historical core runtime
new
.add_plugins
.add_plugins
.add_plugins;
// Quick-start bundle for examples/prototypes
new
.add_plugins
.add_plugins
.add_plugins;
Quick Start
Add the dependency to your Cargo.toml. Use crates.io for released versions, or pin the repository when you need an unreleased commit/tag:
[]
# Option A — released crate (recommended for consumers):
= "0.4"
# Option B — local clone side-by-side (development):
= { = "../voxel-framework" }
# Option C — from git, pinned to a stable tag:
= { = "https://github.com/cristhofert/voxel-framework", = "v0.4.0" }
# Option D — follow the dev branch (bleeding-edge):
= { = "https://github.com/cristhofert/voxel-framework", = "dev" }
= "0.18"
To run the bundled examples, clone the repository — the demo
assets/live in the repo and are not pulled in automatically when depending via git.
Choosing the right starting point
| I want to... | Start with | Notes |
|---|---|---|
| See a working voxel world fast | cargo run --example basic_world |
Best first smoke test after cloning the repo |
| Build a prototype with defaults | VoxelPlugin<V> + GeneratorPlugin<V> |
Includes core runtime plus default UI/audio/visual helpers |
| Build my own game UI/audio | VoxelCorePlugin<V> + GeneratorPlugin<V> |
Keeps rendering, streaming, meshing, mining and placement primitives |
| Add procedural generation | GeneratorPlugin<V> + GeneratorResource<V> |
Your generator implements ChunkGenerator<V> |
| Save modified chunks | PersistencePlugin<V>::with_world("world") |
Writes under ./worlds/{world}/chunks |
| Drive loading screens | LoadingPlugin / WorldReady / LoadingProgress |
Bundled by the convenience plugins |
| Mine or place blocks manually | MiningPlugin / PlacementPlugin |
Call tick_mining, stop_mining, try_place_voxel, and tick_placement from your systems |
| Use included item/hotbar UX | default features or --features items |
Enables inventory, hotbar, drops, and related UI |
Minimal main.rs that spawns an asteroid world with config and persistence:
use Arc;
use *;
use *;
Update ViewerPosition every frame so the streaming system knows where to load chunks:
Run the bundled example:
Module Overview
| Module | Description |
|---|---|
voxel |
VoxelType trait, DefaultVoxel enum, and VoxelPalette resource |
content |
Author-defined BlockDefinition, BlockRegistry, and VoxelContentPlugin |
chunk |
Chunk<V> flat-array storage, ChunkCoord, constants, coordinate utilities, and binary persistence |
noise |
Seed-based value noise, FBM, and hash3 — no external noise crates |
generator |
ChunkGenerator<V> trait, GeneratorPlugin, and GeneratorResource |
generator::asteroid |
AsteroidGenerator with FBM surface deformation and mineral veins |
mesh |
Greedy meshing (generate_chunk_mesh, generate_chunk_mesh_with_neighbors), MeshPlugin, LOD computation |
world |
ChunkManager, ViewerPosition, lifecycle events, streaming system, WorldPlugin, WorldConfig, PersistencePlugin |
world/occlusion |
OcclusionPlugin, is_chunk_occluded — hides chunks fully enclosed by solid neighbors |
world/collision |
Sphere and capsule collision detection and resolution against solid voxels |
world/mining |
MiningPlugin, MiningConfig, MiningState, tick_mining, stop_mining, VoxelBroken, MiningProgress |
world/placement |
PlacementPlugin, PlacementConfig, PlacementState, try_place_voxel, tick_placement, VoxelPlaced |
world/loading |
LoadingPlugin, LoadingProgress, WorldReady, WorldLoadingState |
render |
Shared StandardMaterial for vertex-colored chunks, RenderPlugin |
player |
6DOF jetpack player (PlayerPlugin, PlayerConfig, capsule collision) |
ui/pause_menu |
Optional PauseMenuPlugin with PauseMenuState and PauseMenuConfig |
prelude |
Convenience re-export of all public types |
Author-defined Content
VoxelContentPlugin<V> initializes a BlockRegistry<V> resource.
With the items feature enabled, ItemContentPlugin<I> and
BlockDropContentPlugin<I> also provide ItemRegistry<I> and
BlockDropRegistry<I>. These registries do not create a game, ship
space/survival presets, or impose a closed list of gameplay categories. They are
horizontal tools: the game author registers content definitions and decides what
their gameplay attributes mean.
For setup code that should fail loudly, registries also expose require(...)
helpers and block-drop validation:
BlockRegistry::require("id")/ItemRegistry::require("id")return explicit missing-id errors instead ofOption.BlockDropRegistry::validate_blocks(&blocks)catches drops attached to block ids that were never registered.BlockDropRegistry::validate_items(&items)catches drops that produce item values that were never registered.BlockDropRegistry::apply_to_drop_table(&blocks, &mut drop_table)bridges author-defined block ids into the runtime voxel-byteDropTableconsumed byDropsPlugin.snapshot()on block, item, and drop registries returns deterministic serializable data for docs, tooling, manifests, or AI inspection.
The framework only separates two concerns:
- Engine contracts — technical facts the voxel runtime may need, such as whether a block emits mesh geometry, collides, has opacity, color, or texture layers.
- Author-defined gameplay data — arbitrary attributes and tags such as hardness, rarity, mana conductivity, drops, faction, temperature, item mass, or tool rules.
use *;
use *;
new
.add_plugins
.add_plugins
.add_systems;
With the items feature, item and drop content uses the same author-defined
style:
use *;
use *;
new
.add_plugins
.add_plugins
.add_plugins
.add_plugins
.add_systems;
Run the headless content example:
The example also prints a JSON block-content snapshot so you can see the exact author-defined content surface exposed to external tools.
World Configuration
The framework reads world.toml from the working directory at startup via WorldConfigPlugin (included in VoxelPlugin). If the file is absent or malformed, all values fall back to their defaults.
The bundled examples also support loading persisted world metadata from worlds/<name>/world.json when re-opening an existing saved world.
world.toml format
= 42
= [0.0, 0.0, 0.0]
= 150.0
= 200.0
[]
= 42
= 20
= 15.0
= 40.0
[]
= 15000.0
= 0.1
WorldConfig is inserted as a Bevy resource after loading and can be read in any system:
Building a generator from config
WorldConfig::build_asteroid_generator() constructs an AsteroidGenerator directly from the TOML asteroid settings:
The WorldConfigPlugin is registered automatically by VoxelPlugin. To add it standalone:
use WorldConfigPlugin;
new
.add_plugins
.run;
Persistence
PersistencePlugin wires chunk auto-save into the Bevy game loop. Every time a ChunkModified event fires, the affected chunk is written to disk in binary format. Chunks are also saved when they stream out of range (save-on-unload).
use *;
new
.add_plugins;
Use a custom voxel type the same way:
new
.add_plugins;
Overriding PersistenceConfig
PersistenceConfig controls the save directory and whether auto-save is active. PersistencePlugin installs its defaults when it is added, so insert your override after the plugin:
use PersistenceConfig;
new
.add_plugins
.insert_resource;
| Field | Default | Description |
|---|---|---|
save_dir |
"./worlds/world/chunks" |
Directory for chunk binary files (created automatically) |
auto_save |
true |
Write to disk on every ChunkModified event |
On load, the generator pipeline calls try_load_chunk before spawning an async generation task. If a saved file exists for a given coordinate, it is loaded directly — generation is skipped.
LOD System
Chunks have two discrete detail levels driven by distance from the viewer. The ChunkLod component on each chunk entity tracks the current level and is updated every frame by lod_update_system.
| LOD level | Distance from viewer | Greedy-mesh step | Detail |
|---|---|---|---|
0 |
< 200 units | 1 | Full |
1 |
>= 200 units | 2 | Half |
When the level changes, a ChunkModified event is emitted so the mesh system regenerates the geometry at the new step size.
Hysteresis prevents oscillation at boundaries: a chunk must move clearly past a threshold before the LOD level changes, avoiding rapid mesh rebuilds when the viewer hovers near a distance boundary.
compute_lod and lod_to_step are available from the prelude if you need to query LOD directly:
use *;
// chunk_pos is the world-space position of the chunk (e.g. from chunk_center())
let lod: u8 = compute_lod;
let step: usize = lod_to_step;
Occlusion Culling
OcclusionPlugin hides any chunk whose six face-adjacent neighbors are all fully solid. Because none of that chunk's border faces are visible, its mesh is set to Visibility::Hidden automatically and restored when a neighbor changes.
use *;
new
.add_plugins
.add_plugins
.add_plugins
.run;
You can also query occlusion directly without the plugin:
use *;
let occluded = ;
Mining & Placement
Both systems are pure-function APIs — no hidden Bevy systems are injected. Register the plugins to initialize resources and messages, then call the free functions from your own systems.
new
.add_plugins
.add_plugins;
Mining
tick_mining is called every frame while the mine button is held. It accumulates elapsed time against MiningConfig::break_time, emits MiningProgress each frame, and emits VoxelBroken (plus ChunkModified to trigger remeshing) when the voxel breaks.
Call stop_mining when the button is released to reset progress:
stop_mining;
Override break time via MiningConfig:
app.insert_resource;
Placement
try_place_voxel is called once when the place button is pressed. It returns false if the cooldown has not expired or the target voxel is already solid. tick_placement advances the cooldown timer and must be called every frame.
Override cooldown via PlacementConfig:
app.insert_resource;
Loading Screen
LoadingPlugin tracks the initial chunk load and emits two message types:
LoadingProgress— fired every frame while loading, carriesloaded,total, andprogress(0.0–1.0).WorldReady— fired exactly once when all chunks withinload_distanceare loaded for the first time.
new
.add_plugins
.add_plugins;
Detect WorldReady to transition out of a loading screen:
Drive a progress bar with LoadingProgress:
WorldLoadingState is also available as a resource if you prefer polling over event handling:
Player
PlayerPlugin<V> adds a first-person player with capsule collision, mouse look, WASD movement, and selectable movement/look modes. The default is zero-g 6DOF flight; anchored free flight and grounded gravity movement are also available through PlayerConfig::mode.
use PlayerPlugin;
new
.add_plugins
.add_plugins
.insert_resource;
| Input | Action |
|---|---|
| Mouse | Depends on PlayerConfig::mode: FreeFlightSixDof gives yaw + pitch with no clamp; FreeFlightAnchored gives FPS-style yaw around a world-axis anchor with pitch clamped to ±89° and a level horizon |
| Q / E | In FreeFlightSixDof, roll left/right (continuous or snap, configured in the mode); in FreeFlightAnchored, switch the anchor to the next signed world axis (±X/±Y/±Z) with a snap animation; disabled in Grounded |
| W / S | Forward / backward |
| A / D | Strafe left / right |
| Space | Move along local up |
| Shift | Move along local down |
| Left click | Lock cursor |
| Escape | Release cursor (second: close window) |
If your game uses an AppState, skip PlayerPlugin and add the systems manually gated to your playing state:
use ;
new
.add_systems
.add_systems;
Pause Menu
PauseMenuPlugin is an optional plugin that provides a full pause menu with a settings submenu. It manages its own PauseMenuState — use it to gate your gameplay systems:
use ;
new
.add_plugins
.add_plugins
.add_systems
.add_systems;
| State | Description |
|---|---|
PauseMenuState::Playing |
Normal gameplay — menus hidden |
PauseMenuState::Paused |
Pause overlay visible (Resume / Settings / Quit) |
PauseMenuState::Settings |
Settings submenu (FOV, SFX volume) |
The Settings submenu writes directly to the camera's Projection (FOV) and to SfxConfig::volume (SFX volume).
Customizing the font
Override PauseMenuConfig before adding the plugin:
use PauseMenuConfig;
Coordinate Utilities
Four free functions convert between world space, chunk grid, and local voxel space. All are available via use voxel_framework::prelude::*.
use Vec3;
use *;
let world_pos = new;
// Which chunk contains this world position?
let coord = world_to_chunk_coord;
// → IVec3(1, 0, 0) (chunk boundary at x=16.0)
// Which voxel within that chunk?
let = world_to_local_coord;
// → (2, 0, 0)
// World-space minimum corner of a chunk.
let origin = chunk_origin;
// → Vec3(16.0, 0.0, 0.0)
// World-space center of a chunk.
let center = chunk_center;
// → Vec3(24.0, 8.0, 8.0)
All functions use Euclidean division so negative coordinates map to the correct chunk (e.g. world_pos.x = -1.0 maps to chunk -1, not 0).
Implementing a Custom Voxel Type
use VoxelType;
Implementing a Custom Generator
use IVec3;
use Chunk;
use ChunkGenerator;
;
Register it the same way as AsteroidGenerator:
use Arc;
use ;
app.add_plugins
.insert_resource;
Voxel Palette (DefaultVoxel)
| Variant | Byte | RGBA color |
|---|---|---|
Air |
0 | (0.00, 0.00, 0.00, 0.0) — transparent |
Rock |
1 | (0.35, 0.30, 0.28, 1.0) — warm grey-brown |
IronOre |
2 | (0.55, 0.35, 0.20, 1.0) — rusty orange |
SiliconCrystal |
3 | (0.40, 0.50, 0.80, 1.0) — blue-violet |
RareMineral |
4 | (0.20, 0.85, 0.60, 1.0) — vivid teal-green |
Profiling
Compile with --features tracing to enable internal spans for hot paths
(mesh generation, chunk load/unload, async generation dispatch, occlusion,
collision, raycast). With the feature off the spans expand to nothing —
zero runtime overhead in default builds.
Add --features tracy to route spans to a Tracy
profiler client. Call voxel_framework::profile::init_tracy() from your main()
before constructing the Bevy App so the subscriber is installed first
(only one global tracing subscriber may be active at a time):
For AI Assistants and Code Agents
This repository includes compact orientation files for tools like ChatGPT, Codex, Claude, and other code agents:
llms.txtis the shortest high-signal summary: what the crate is, which files to read first, and the runtime contracts that matter.AGENTS.mdexplains how to build a game withvoxel-framework: core abstractions, plugin choices, feature flags, commands, and common gotchas.docs/architecture.mdis the deeper architecture reference for plugin categories, runtime flow, persistence, interaction flow, and extension seams.- Rustdoc remains the source of truth for public API signatures and examples.
If you pass this project to an AI assistant, start with llms.txt, then
README.md, then AGENTS.md, and only then dive into src/lib.rs / rustdoc.
That order gives the model the product intent before the implementation detail.
License
LGPL-3.0-or-later. See LICENSE.