bevy-voxel-runtime

Bevy 0.19 — 生产级体素运行时

何时使用此技能

• 修改可能跨越区块边界，或影响 AO／光照的边缘采样。
• 后台重建网格的结果可能在较新的修改或卸载／重新加载之后才到达。
• 网格／碰撞体上传、队列增长或可见区块延迟会导致帧时间尖峰。
• 原型目前会为每次修改启动一个 AsyncComputeTaskPool 任务。

请在区块目录和网格生成器正确后使用此技能。它负责定义修改、后台网格生成和主线程呈现之间的运行时约定。工作线程的结果只是一项提议：世界版本仍必须接受它。

规范模式

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;

工作线程的输入必须包含区块及其所需边缘区域的不可变快照。 不要在后台工作期间持有 ECS 借用、资源借用或世界锁。

注意事项和不变量

1. 根据网格生成器实际读取的采样范围确定脏标记的传播范围。内部修改会使一个区块变脏；边界修改还会使相邻的正交区块变脏。环境光遮蔽、平滑光照或其他边缘采样也可能需要将边缘和角落的邻区标记为脏。
2. 为每个区块分配单调递增的内容版本和生命周期纪元。每个任务和结果都要捕获这两个值。判断有效性时，绝不能只依靠坐标。
3. 每个区块最多保留一个已排队／运行中／待处理结果的意图。运行中的任务执行期间若发生修改，只需再次将该区块标记为脏；不要启动等效任务。
4. 限制工作线程启动数、已完成结果的存储量、网格／碰撞体的应用量、上传字节数和应用耗时。线程池不等于背压。
5. 在替换呈现状态之前，重新检查版本和纪元。拒绝过期结果并统计数量；绝不能让旧任务覆盖新修改。
6. 将可见网格和匹配的碰撞体作为同一个已接受版本进行切换。不要显示版本 N 的几何体，同时让碰撞仍对应版本 N-1。

运行时流程

edit -> compute dirty footprint -> bump revisions -> coalesce queue intent
     -> priority scheduler -> bounded task starts -> completed-result queue
     -> validate token -> bounded main-thread upload -> mesh+collider swap
                                      \-> stale reject + metric

• 在明确排序的模拟集合中执行修改收集和脏标记。
• 只有在有可用工作线程时才创建快照；否则，排队的修改会继续合并，且不会分配任务输入。
• 优先处理可见且对碰撞至关重要的区块，然后处理由近及远的可见区块，最后处理屏幕外工作。加入等待时长，避免远处工作永远得不到处理。
• 在 Update／PostUpdate 中，或通过具有可测量的每帧预算的独占系统应用上传。GPU 资源创建属于主世界工作，不属于工作线程工作。
• 如果任务在卸载／重新加载后才完成，即使新区块恰好具有相同的版本号，纪元不匹配也会使结果被拒绝。

选择相关的深入说明

问题	阅读内容
脏标记范围、边缘语义、版本和生命周期令牌	脏标记与版本
合并、优先级堆、任务所有权和队列限制	队列与优先级
过期结果拒绝、呈现原子切换和诊断信息	应用与遥测

生产环境审查清单

• 边界修改会重建所有网格会读取该变更采样点的区块。
• 卸载／重新加载同一坐标的区块会使先前的结果失效。
• 对一个区块进行 1,000 次突发修改只会产生有界工作，而不是 1,000 个任务。
• 过期结果无法修改网格、碰撞体、版本或就绪状态。
• 补做工作同时遵守数量和字节数／耗时预算。
• 可见碰撞缺口的优先级高于远处的外观工作，同时不会导致后者永远得不到处理。
• 在有代表性的构建中，可以观测队列深度、等待时长、任务延迟、过期数量、合并数量、上传字节数和已接受版本。

另请参阅

• bevy-voxel-data — 稳定的序列化方块 ID 和稠密运行时调色板。
• bevy-voxel-pipeline — 网格生成和 block-mesh-rs。
• bevy-diagnostics-profiling — 诊断、跨度和平台预算。
• bevy-physics — 碰撞体所有权和物理调度。