bevy-voxel-runtime

Bevy 0.19 — production voxel runtime

When to use this skill

• Edits can cross section boundaries or affect AO/lighting halo samples.
• Background remesh results can arrive after newer edits or unload/reload.
• Mesh/collider uploads, queue growth, or visible-section latency cause frame spikes.
• A prototype currently spawns one AsyncComputeTaskPool task per edit.

Use this skill after the block catalog and mesher are correct. It owns the runtime contract between edits, background meshing, and main-thread presentation. A worker result is only a proposal: the world revision must still accept it.

Canonical pattern

use bevy::prelude::*;
use std::collections::{BinaryHeap, HashMap, VecDeque};

#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
struct SectionCoord { x: i32, y: i32, z: i32 }

#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
struct WorkToken {
    coord: SectionCoord,
    revision: u64,
    epoch: u64,
}

#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
enum WorkState {
    #[default]
    Idle,
    Queued,
    Running,
    RunningAndDirty,
    Ready,
}

#[derive(Resource, Default)]
struct RemeshRuntime {
    state: HashMap<SectionCoord, WorkState>,
    latest: HashMap<SectionCoord, WorkToken>,
    queued: BinaryHeap<PriorityEntry>,
    completed: VecDeque<MeshResult>,
}

#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
struct PriorityEntry {
    // Include the token or queue generation so obsolete heap entries can be skipped.
    priority: i64,
    queue_generation: u64,
    token: WorkToken,
}

struct MeshResult {
    token: WorkToken,
    mesh: MeshPayload,
    collider: ColliderPayload,
}

struct MeshPayload;
struct ColliderPayload;

The worker input must own an immutable snapshot of the section plus required halo. Do not hold ECS borrows, asset borrows, or world locks across background work.

Gotchas and invariants

1. Derive dirty fan-out from the mesher's actual read stencil. An interior edit dirties one section; a face-boundary edit also dirties the orthogonal neighbour. Ambient occlusion, smooth lighting, or other halo reads can require edge/corner neighbours too.
2. Give every section a monotonic content revision and a lifecycle epoch. Capture both in each job and result. Never identify validity by coordinates alone.
3. Keep at most one queued/running/pending-result intent per section. An edit during a running job marks that section dirty again; it does not spawn an equivalent job.
4. Bound worker starts, completed-result storage, mesh/collider applications, upload bytes, and apply time. A thread pool is not backpressure.
5. Re-check revision and epoch immediately before replacing presentation state. Reject stale results and count them; never let an old task overwrite a new edit.
6. Swap the visible mesh and matching collider as one accepted revision. Do not show geometry from revision N while collision still represents N-1.