Expand description
§voxel-framework
A reusable voxel engine library built on Bevy, providing all the infrastructure needed to build voxel-based games and simulations: chunk storage, procedural generation, greedy meshing, world streaming, PBR rendering, and player interaction.
§Overview
The framework is built around three core abstractions:
-
voxel::VoxelType— a trait that every voxel palette must implement. It describes whether a voxel is solid, what color it renders as, and how it serializes to and from a single byte for persistence. The built-invoxel::DefaultVoxelpalette covers five material types (Air, Rock, IronOre, SiliconCrystal, RareMineral) and is ready to use out of the box. -
chunk::Chunk<V>— the fundamental storage unit. A 16×16×16 flat array of voxels stored on the heap. All generation, meshing, and I/O operate on chunks identified by achunk::ChunkCoord(anIVec3where one unit equalsCHUNK_SIZEworld-space units). -
generator::ChunkGenerator— an async-safe trait implemented by procedural generators. Generators run on a BevyAsyncComputeTaskPoolthread and produce fully populatedchunk::Chunk<V>values, which are then handed back to the main world for meshing and insertion.
§Plugin Catalog Architecture
voxel-framework exposes a flat catalog of Bevy plugins grouped by
responsibility. Game crates compose the plugins they need instead of
depending on a hidden monolithic game plugin:
| Category | Purpose | Examples |
|---|---|---|
| Engine | Foundation for streamable/renderable voxel worlds | world::WorldPlugin, mesh::MeshPlugin, render::RenderPlugin |
| World Data | Chunk sources, generation, persistence, lifecycle data | generator::GeneratorPlugin, world::PersistencePlugin |
| Gameplay | Reusable rules and interactions | content::VoxelContentPlugin, stats::VoxelStatsPlugin, effects::VoxelEffectsPlugin, world::mining::MiningPlugin, world::placement::PlacementPlugin, player::PlayerPlugin |
| Default Implementation | Replaceable UI/audio/visual defaults | ui::UiPlugin, ui::VoxelHudPlugin, skybox::SkyboxPlugin, audio::DefaultAudioPlugin |
| Convenience | Compatibility bundles, input adapters, recipes, prototyping helpers | VoxelCorePlugin, VoxelPlugin |
These categories are also represented by marker traits in
plugin_category. They are documentation and API classification tools;
Bevy composition still uses the normal Plugin trait.
VoxelCorePlugin and VoxelPlugin remain available as convenience
bundles for compatibility and quick starts, but they are not the primary
architecture. New domain behavior should normally be modeled as an explicit
Engine, World Data, Gameplay, or Default Implementation plugin.
generator::GeneratorPlugin is always opt-in because it is generic
over V: VoxelType and requires the caller to supply a
generator::GeneratorResource holding a concrete generator. Add it
separately after either a bundle or explicit engine plugins.
ui::VoxelHudPlugin is also explicit and remains outside ui::UiPlugin
and the convenience bundles. Authors register domain-neutral presentation
definitions, publish screen-ready values, and may schedule same-frame
publishers in ui::HudSystemSet::Publish. The retained renderer preserves
element identity and safely hides unresolved or unavailable asset inputs.
§The Chunk Pipeline
The full data flow from viewer movement to rendered geometry:
ViewerPosition update
│
▼
WorldPlugin — streaming system
Computes which chunks are within the configured render distance.
Emits ChunkRequested events for chunks not yet loaded.
│
▼
GeneratorPlugin — async generation (AsyncComputeTaskPool)
Spawns a task per requested chunk. Each task calls
ChunkGenerator::generate(coord) → Chunk<V>.
When the task completes, inserts the Chunk<V> component and emits
ChunkModified so downstream systems are notified.
│
▼
MeshPlugin — greedy mesh generation
Reacts to ChunkModified. Iterates the chunk with a configurable LOD
step, runs the greedy meshing algorithm, and uploads a Bevy Mesh asset.
│
▼
RenderPlugin — PBR material + entity spawn
Attaches a shared chunk PBR material and a MeshBundle to the chunk
entity so Bevy's renderer picks it up on the next frame.
│
▼
OcclusionPlugin — neighbor-solid occlusion
Reacts to ChunkModified and hides chunks whose six face-adjacent
neighbours are all loaded and fully solid.§Quick Start
A minimal working world using the built-in asteroid generator:
use bevy::prelude::*;
use voxel_framework::{
VoxelPlugin,
generator::{GeneratorPlugin, GeneratorResource},
generator::asteroid::{AsteroidConfig, AsteroidGenerator},
voxel::DefaultVoxel,
};
use std::sync::Arc;
App::new()
.add_plugins(DefaultPlugins)
.add_plugins(VoxelPlugin::<DefaultVoxel>::new())
.add_plugins(GeneratorPlugin::<DefaultVoxel>::new())
.insert_resource(GeneratorResource::<DefaultVoxel> {
generator: Arc::new(AsteroidGenerator::new(AsteroidConfig::default())),
})
.run();Use explicit catalog plugins instead of VoxelPlugin when you want full
control over engine, world data, gameplay, and presentation defaults.
§Extending the Framework
To use a custom voxel palette, implement voxel::VoxelType on your own type and
substitute it wherever the framework is generic over V: VoxelType:
generator::GeneratorPlugin::<YourVoxel>::new()mesh::MeshPlugin::<YourVoxel>::new()render::RenderPlugin::<YourVoxel>::new()
To drive generation, implement generator::ChunkGenerator and wrap it in
a generator::GeneratorResource.
See prelude for the most commonly used re-exports.
Modules§
- audio
- Decoupled sound-effect system for the voxel framework.
- chunk
- Chunk data model, coordinate utilities, and persistence for the voxel world.
- content
- Author-defined content registries for voxel games.
- crafting
- Crafting system — shapeless recipes, registry, and in-game crafting menu.
- effects
- Author-defined effect registries and active effect state.
- fragments
- Voxel break-apart fragment effect.
- generator
- Procedural chunk generation trait, async pipeline, and Bevy plugin.
- items
- Item system — inventory, drop tables, hotbar, and persistence.
- mesh
- Greedy mesh generation for voxel chunks with LOD and neighbor-aware seam culling.
- mobs
- Simple mob (enemy entity) system for voxel worlds.
- noise
- Pure-Rust, dependency-free noise primitives for procedural world generation.
- player
- Six-degrees-of-freedom (6DOF) player controller for zero-gravity environments.
- plugin_
category - Official plugin category marker traits.
- prelude
- Convenient re-exports of the most commonly used types.
- profile
- Internal profiling helpers.
- render
- Rendering support for voxel chunks.
- settings
- Persistent user settings saved to
worlds/{world_name}/settings.json. - skybox
- Configurable skybox system for the voxel framework.
- stats
- Author-defined stat registries and runtime stat values.
- ui
- HUD overlay plugins for voxel game user interfaces.
- voxel
- Voxel type trait, the built-in
DefaultVoxelpalette, and runtime color lookup. - world
- World streaming, chunk lifecycle, and runtime configuration.
Macros§
- profile_
span - Opens a profiling span scoped to the enclosing block.
Structs§
- Voxel
Core Plugin - Convenience bundle for the historical core voxel runtime.
- Voxel
Plugin - Quick-start convenience bundle for demos and prototypes.