bevy-voxel-data

Bevy 0.19 — 体素数据（RON、调色板、KTX2 图集）

何时使用此技能

• 以作者可编辑的文本格式定义可修改的方块目录。
• 构建以 BlockId（u16/u32）为键的运行时调色板，以便在网格生成时快速查找。
• 将每个方块的纹理打包到单个图集中，让所有区块共用一种材质。
• 将图集切换为 KTX2，以便以适合 GPU 的压缩格式交付。
• 选择运行时区块存储格式（平坦数组、RLE、调色板压缩、混合格式）。
• 优化程序化世界生成：极值边界检查、噪声上采样、噪声缓存、跨生物群系共享噪声。
• 在选择依赖项之前，了解 Rust/Bevy 体素 crate 生态及其当前不足。

规范的端到端流程

1. 在 RON 中定义方块（assets/blocks.ron）。id 是不可变的序列化标识；name 是展示文本，可以更改：

(
    blocks: [
        ( id: "core:air", name: "Air", visibility: Empty ),
        ( id: "core:grass", name: "Grass", visibility: Opaque,
          faces: ( top: "textures/grass_top.png",
                   bottom: "textures/dirt.png",
                   side: "textures/grass_side.png" ) ),
        ( id: "core:stone", name: "Stone", visibility: Opaque,
          faces: ( all: "textures/stone.png" ) ),
    ],
)

2. Rust 核心类型 — BlockCatalog 是 Bevy Asset；Palette 是 Resource：

pub type BlockId = u16;

#[derive(Debug, Deserialize, Clone, Eq, Hash, PartialEq)]
#[serde(transparent)]
pub struct StableBlockId(pub String);

#[derive(Debug, Deserialize, Asset, TypePath)]
pub struct BlockCatalog { pub blocks: Vec<BlockDef> }

#[derive(Resource, Default)]
pub struct Palette {
    pub by_id: Vec<PaletteEntry>, // dense, process-local BlockId
    pub by_stable_id: HashMap<StableBlockId, BlockId>,
}

#[derive(Clone)]
pub struct PaletteEntry {
    pub stable_id:  StableBlockId,
    pub name:       String,
    pub visibility: Visibility,
    /// Atlas tile per face: [−X, −Y, −Z, +X, +Y, +Z] (block-mesh order).
    pub face_tiles: [u16; 6],
}

3. 构建调色板 — 验证稳定 ID 的唯一性，遍历目录，查找每个面在 AtlasIndex 中对应的路径，并分配稠密的运行时 BlockId 值。目录顺序可能影响此运行时布局，但它绝不是持久化约定。存档和网络格式应直接存储稳定 ID，或携带自己的稳定 ID 调色板，并在加载时进行映射。

4. 绑定图集 到 StandardMaterial.base_color_texture；在网格生成过程中计算每个顶点的 UV，计算方式为 tile_x = tile_index % atlas_cols。

主题

主题	参考资料
完整 RON 架构、所有字段、serde 默认值、解析器说明	references/ron-schema.md
BlockDef / BlockFaces / Visibility 类型、完整的 build_palette、face_tiles 槽位约定	references/palette.md
KTX2 打包、图块尺寸预算、确保 mip 安全的边距、各平台的 BC7/ETC2/ASTC	references/ktx2-atlas.md
StandardMaterial 绑定、UV 公式、逐顶点发光、采样器配置、Alpha 模式	references/atlas-binding.md
运行时区块存储格式 — 平坦数组、RLE、调色板压缩、混合格式 — 含 RAM 估算	references/storage-formats.md
程序化生成模式 — 噪声上采样、生物群系共享、极值边界、缓存	references/generation.md
Rust/Bevy 体素 crate 生态概览（block-mesh、building-blocks、feldspar 等）	references/ecosystem.md

注意事项

• KTX2 需显式启用。 Bevy 通过 Cargo 功能 ktx2 支持 KTX2（在 3d bundle 中默认启用）。对于精简的 WASM 构建，请显式添加 ktx2 和 zstd。桌面端使用 BC7，移动端使用 ETC2/ASTC — 详见 references/ktx2-atlas.md。
• 运行时 BlockId 不是持久化标识。 它是根据当前目录重新构建的稠密索引。应持久化 core:stone 这类不可变的命名空间 ID，验证其唯一性，并在加载时将其映射到当前运行时调色板。
• mip 级别 ≥ 1 时会出现纹理渗色。 在每个图块周围添加 2 像素边距，或改用纹理数组，并为每个切片设置 clamp_to_edge。详情请参阅 references/ktx2-atlas.md 和 references/atlas-binding.md。
• Translucent 方块需要单独的绘制调用。 在第二种材质上使用 AlphaMode::Blend，并为每个区块单独创建网格批次 — 半透明四边形不能与不透明四边形合并。
• 不要在发布的构建中于运行时烘焙图集。 在内容构建阶段运行烘焙脚本；提交 .ktx2 和 JSON 索引；启动时加载两者。

另请参阅

• bevy-voxel-pipeline — 消耗 face_tiles 的网格生成步骤。
• bevy-voxel-runtime — 编辑脏标记、修订版本、有限网格重生成，以及网格／碰撞体应用。
• bevy-save-load — 版本化持久化和稳定 ID 迁移。
• bevy-custom-assets — 实现 RON 目录加载器。
• bevy-pbr-materials — 将图集接入 StandardMaterial。