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.10 is the current package line for this 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. Package metadata and
guidance may be prepared before the corresponding crate and tag are published.
Version 0.9.0 introduces focused player input and explicit click-to-capture. Players start with a free cursor; losing focus releases control. See the player section and CHANGELOG migration notes for changes to public system signatures.
Compatibility target:
| Area | Current status |
|---|---|
| Crate version | 0.10.x |
| Bevy version | 0.18 |
| Rust version | MSRV 1.89 |
| Stability | Public API can still change across 0.x minor releases |
| Distribution | crates.io for released versions; git tags for pinned source installs |
Bevy 0.18.1 and bevy_ecs require Rust 1.89.0. The MSRV CI lane uses
Rust 1.89.0 for cargo check --locked --lib with default, no-default, and
all features, plus focused inventory, crafting, and persistence tests on Linux.
Since this library does not track Cargo.lock,
CI resolves a fresh lockfile on that toolchain before the locked checks;
consumer dependency resolutions and other targets may require newer Rust.
The candidate gate covers formatting, feature combinations, doctests, integration
tests, exact Rust 1.89.0 checks, documentation, package contents, and targeted
Windows inventory-persistence tests. The CI workflow in .github/workflows/rust.yml
supports these gates without using cargo build. Candidate preparation does not
publish, push, tag, or integrate the candidate; publication is a separate human
decision after validation.
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.
basic_worldandminetestare graphical Bevy apps and require a working display.content_definitions,stats_definitions, andeffect_definitionsuseMinimalPluginsand run headlessly in a terminal. Headless examples and tests do not replace manual playtesting of the graphical runtime.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 | VoxelContentPlugin<V>, VoxelStatsPlugin, VoxelEffectsPlugin, MiningPlugin, PlacementPlugin, PlayerPlugin<V>, HotbarPlugin, DropsPlugin<I> |
| Default Implementation | Replaceable UI/audio/visual defaults | UiPlugin, VoxelHudPlugin, 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.
VoxelContentPlugin<V>, VoxelStatsPlugin, and VoxelEffectsPlugin are
independent, horizontal Gameplay choices. They initialize empty registries and
runtime state for definitions owned by the game author; they do not install a
vertical genre preset or a JSON-driven configuration layer. Register only the
content, stats, and effects your game needs through the Rust API. Deterministic
snapshots are available for tooling and may be serialized by the caller, but
they are not a second configuration model.
// 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;
for unreleased candidate development, use a local checkout or an explicitly
chosen repository revision. Do not assume candidate metadata implies a tag.
[]
# Option A — released 0.10 line (recommended for consumers):
= "0.10"
# Option B — local clone side-by-side (development):
= { = "../voxel-framework" }
# Option C — from the matching release tag:
= { = "https://github.com/cristhofert/voxel-framework", = "v0.10.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, UI/visual helpers, and SFX request generation; audio playback remains opt-in |
| 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 |
| Publish an author-defined retained HUD | VoxelHudPlugin |
Explicit, non-generic, domain-neutral, and not included in UiPlugin or convenience bundles |
| 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:
Bundled examples
| Example | Runtime | Purpose |
|---|---|---|
content_definitions |
Headless (MinimalPlugins); requires items (enabled by default) |
Author-defined blocks, items, drops, validation, and snapshots |
stats_definitions |
Headless (MinimalPlugins) |
Author-defined global/entity stats, mutation helpers, and messages |
effect_definitions |
Headless (MinimalPlugins) |
Author-defined global/entity effects, ticking, and lifecycle messages |
hud |
Headless (MinimalPlugins); feature-independent |
Neutral text, bar, icon, and segment definitions with same-frame publication and retained updates |
basic_world |
Graphical; display required; requires items (enabled by default) |
Small playable asteroid world; see examples/basic_world.md |
minetest |
Graphical; display required; requires items, crafting, and mobs (enabled by default) |
Larger integration example |
The headless examples are the fastest way to inspect author-defined APIs without opening a window. The HUD, stats, and effects examples do not require optional framework features.
Module Overview
| Module | Description |
|---|---|
voxel |
VoxelType trait, DefaultVoxel enum, and VoxelPalette resource |
content |
Author-defined BlockDefinition, BlockRegistry, and VoxelContentPlugin |
stats |
Author-defined StatDefinition, StatRegistry, StatSet, and VoxelStatsPlugin |
effects |
Author-defined EffectDefinition, EffectRegistry, ActiveEffectSet, and VoxelEffectsPlugin |
ui::hud |
Author-defined HudRegistry, HudValueSet, retained presentations, and explicit VoxelHudPlugin |
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.
Author-defined Stats
VoxelStatsPlugin initializes two empty resources:
StatRegistry— the catalog of stats the game author chooses to define.StatSet— runtime values keyed by those author-defined stat ids.
The plugin intentionally registers no default health, stamina, oxygen, mana,
hunger, thirst, or body schema. Those are game decisions. A survival game can
define oxygen; an RPG can define mana; an arcade sandbox can define no stats
at all. The framework only provides ids, bounds, clamping, mutation helpers,
metadata, tags, and deterministic snapshots.
For inspection, StatSet::normalized(id, ®istry) returns a 0.0..=1.0
ratio across the stat bounds, while is_at_or_below,
is_at_or_above, is_at_or_below_percent, and
is_at_or_above_percent give authors small threshold helpers. These helpers are
for the author's own UI, rules, effects, alarms, or progression systems; the
framework still does not implement any of those layers or assign gameplay
meaning to a stat id.
StatSet works in two scopes:
- Global stats: use the
StatSetresource initialized byVoxelStatsPluginfor world/session values. - Entity stats: attach
StatSet::from_registry(®istry)as a component to any entity that needs its own values: player, mob, vehicle, machine, settlement, or any other author-defined subject.
use *;
use ;
use *;
new
.add_plugins
.add_plugins
.add_systems
.add_systems;
Run the headless stats example:
Like content snapshots, StatRegistry::snapshot() and StatSet::snapshot()
return deterministic serializable data for docs, tooling, manifests, or AI
inspection.
Use read helpers when you want to inspect state without changing it:
let oxygen_ratio = values.normalized?;
if values.is_at_or_below_percent?
Use set_stat, add_stat, drain_stat, and fill_stat when a Bevy system
wants to emit a StatChanged message. They emit only when the clamped value
actually changes. If you only need a plain data mutation, StatSet::set,
StatSet::add, StatSet::drain, and StatSet::fill remain available and do
not depend on Bevy message writers. If a reader must react in the same update as
the writer, order it after the writer with .chain() or explicit Bevy system
ordering.
Author-defined Effects
VoxelEffectsPlugin initializes two empty resources:
EffectRegistry— the catalog of effects the game author chooses to define.ActiveEffectSet— runtime active effects, usable globally or as an entity component.
This is not the older player::effects::StatusEffectsPlugin, and it is not a
potion system. The plugin intentionally registers no poison, speed,
regeneration, low-oxygen, buff/debuff taxonomy, or player-specific behavior.
Those are game decisions. The framework only provides ids, durations, stacks,
metadata, tags, deterministic snapshots, and optional Bevy lifecycle messages.
use *;
use ;
use *;
new
.add_plugins
.add_plugins
.add_systems
.add_systems;
Attach ActiveEffectSet::new() to entities when the effect scope belongs to a
specific subject:
commands.spawn;
Read-side helpers keep gameplay and UI code registry-free once an effect is active:
if active.is_active
Run the headless effects example:
Like content and stats snapshots, EffectRegistry::snapshot() and
ActiveEffectSet::snapshot() return deterministic serializable data for docs,
tooling, manifests, or AI inspection. Active effect snapshots include both the
initial duration and current remaining duration for timed instances.
Author-defined Retained HUD
VoxelHudPlugin is an explicit, non-generic presentation plugin. It is not
included in UiPlugin, VoxelCorePlugin<V>, or VoxelPlugin<V>, and it does
not require gameplay plugins or optional Cargo features:
new
.add_plugins
.add_plugins
.add_systems
.add_systems;
Authors register neutral text, bar, icon, and bounded-segment definitions in
HudRegistry, then publish screen-ready HudValues through HudValueSet.
HudSystemSet::Publish is the same-frame boundary before retained
reconciliation and rendering. Missing or mismatched values hide safely or use a
compatible author fallback, with transition-deduplicated HudDiagnostic
messages instead of panics.
HudRegistry::snapshot() and HudValueSet::snapshot() provide deterministic,
id-ordered inspection. They are not a persistence format or JSON/config DSL.
The plugin coexists with UiPlugin and custom Bevy UI, so custom overlays can
migrate element by element: keep game-owned queries, explicitly publish neutral
view values, verify each retained replacement, then remove the old entity.
There are no reserved ids, vertical presets, automatic stats/effects/content bridges, player discovery, thresholds, rules, or interactions. See the complete HUD guide and run the feature-independent headless example:
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;
Inventory and Crafting
With items, Inventory<I> and ContainerComponent<I> implement
Container<I> using the ordinary Rust API. With crafting, recipe input and
output quantities are aggregated by ItemType equality in first-occurrence
order, not by serialized bytes. Zero quantities are ignored, empty recipes are
allowed, and positive default/is_empty() items or totals above u32::MAX make
a recipe invalid. can_craft checks ingredients only, not output capacity.
Built-in containers stage consumption and production privately, then commit
only a complete exchange. Capacity is evaluated after consumption, so an
ingredient can free a slot for a different output. Failed exchanges leave the
inventory unchanged. Live stacks must be positive and non-empty, capacity
must equal slots.len(), and each item's aggregate quantity must fit u32.
add returns all unaccepted quantities, including representational overflow;
count_of defensively saturates for malformed public fields. There is no new
author-configured stack limit.
Custom containers can opt into the defaulted method
Container::try_exchange_atomic(&mut self, remove: &[(I, u32)], add: &[(I, u32)])
returning Option<Result<(), ContainerExchangeError>>. None and Some(Err(_))
must not mutate; Some(Ok(())) means the entire exchange completed. The neutral,
public #[non_exhaustive] error is available through items and the prelude:
InvalidRequest, InvalidContainer, InsufficientItems, and CapacityExceeded.
No new trait bounds or mandatory methods are required.
try_craft keeps its three errors: invalid requests/recipes become
InvalidRecipe, missing ingredients become InsufficientIngredients, and
invalid containers or output-capacity failures become InventoryFull.
Legacy containers returning None use a conservative non-atomic fallback:
it checks current space without crediting slots that consumption might free,
deduplicates requests, and checks actual removal/addition returns. It stops on
the first failure, never reports false success, and does not invent rollback.
Such a failure may leave partial consumption or production; implement the
atomic hook when all-or-nothing crafting is required.
Inventory JSON persistence
save_inventory and load_inventory keep their existing signatures and JSON
schema. Saving a malformed source returns an InvalidInput I/O error. Loading
rejects a capacity/slot-length mismatch or per-item aggregate overflow with
InvalidData; malformed JSON is also an error. Zero-count entries and item
bytes decoded as unknown/default/is_empty() become None at the same indexes.
Valid holes, duplicate stacks, and slot order are preserved, including
zero-capacity inventories. No save migration or arbitrary capacity ceiling is
introduced.
Saving serializes first, writes a private sibling temporary file with
write_all, applies existing Permissions, syncs the file, and replaces the
destination atomically. Any failure before replacement preserves the previous
bytes and cleans up the temporary file; there is no delete-old-first or direct
write fallback. New files retain private temporary-file permissions. Existing
symlinks are followed while preserving the link; dangling symlinks, non-regular
or read-only targets, and multiply hard-linked files on Unix are rejected.
These guarantees concern whole-file visibility and pre-replacement failure,
not universal power-cut durability. Existing Permissions are preserved,
but ownership, ACLs, extended attributes, and protection against hostile parent
namespace races are not guaranteed. Concurrent successful writers leave one
whole last-writer snapshot, not transaction isolation. These inventory-JSON
guarantees do not change chunk/world persistence or add automatic game-state
saving.
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 in focused window | Lock cursor and enable player input |
| Escape | Release cursor (if already free: close focused window) |
The player starts with a free, visible cursor. Click the focused game window to
control it. Losing focus releases control; returning requires another click.
Look and movement ignore input while unfocused or released. Pointer capture does
not grant OS keyboard focus or disable desktop shortcuts. Headless simulations
without a primary window retain synthetic-input support. Other input systems can
use player_input_active as a run condition; keep player_look scheduled so it
can discard inactive mouse motion.
For a native diagnostic, run cargo run --example player_focus. Click the window,
move with WASD, press Escape, and Alt-Tab away and back. The example logs native
focus events and received keys. Verify that startup and focus return leave the
cursor free, inactive input does not move/rotate the camera, and a fresh focused
click restores control. Check ordinary keys separately from desktop shortcuts.
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 |
Chunk opacity
All four solid default voxels are opaque. Air emits no geometry at either LOD.
Without a texture array, chunks use an opaque shared StandardMaterial so
foreground terrain writes depth and occludes surfaces behind it.
Custom palettes that need the previous blended fallback must opt in before startup:
use *;
use ChunkMaterialConfig;
let mut app = new;
app.insert_resource;
This policy applies to every fallback chunk, not individual voxel types.
Blending retains the existing sorting limitations; it does not provide separate
opaque/translucent meshes or per-triangle sorting. The texture-array path is
unchanged and ignores this configuration. Existing fully specified
ChunkMaterialConfig literals must add alpha_mode or use
..Default::default().
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.