Skip to main content

Crate voxel_framework

Crate voxel_framework 

Source
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-in voxel::DefaultVoxel palette 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 a chunk::ChunkCoord (an IVec3 where one unit equals CHUNK_SIZE world-space units).

  • generator::ChunkGenerator — an async-safe trait implemented by procedural generators. Generators run on a Bevy AsyncComputeTaskPool thread and produce fully populated chunk::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:

CategoryPurposeExamples
EngineFoundation for streamable/renderable voxel worldsworld::WorldPlugin, mesh::MeshPlugin, render::RenderPlugin
World DataChunk sources, generation, persistence, lifecycle datagenerator::GeneratorPlugin, world::PersistencePlugin
GameplayReusable rules and interactionscontent::VoxelContentPlugin, stats::VoxelStatsPlugin, effects::VoxelEffectsPlugin, world::mining::MiningPlugin, world::placement::PlacementPlugin, player::PlayerPlugin
Default ImplementationReplaceable UI/audio/visual defaultsui::UiPlugin, ui::VoxelHudPlugin, skybox::SkyboxPlugin, audio::DefaultAudioPlugin
ConvenienceCompatibility bundles, input adapters, recipes, prototyping helpersVoxelCorePlugin, 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:

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 DefaultVoxel palette, 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§

VoxelCorePlugin
Convenience bundle for the historical core voxel runtime.
VoxelPlugin
Quick-start convenience bundle for demos and prototypes.