bevy_voxel_world

什么是 `bevy_voxel_world`

这个插件使得在Bevy中生成和修改体素地形变得简单。bevy_voxel_world 处理多线程网格生成、区块生成/销毁、纹理映射，并提供了一个可以从任何系统访问的易用API。

bvw_480

$ cargo run -r --example noise_terrain

世界可以通过两种主要方式控制：通过地形查找函数，以及直接使用 set_voxel 和 get_voxel 函数。世界有两个"层"的体素信息，一个是由地形查找函数确定的程序化层，另一个是由 set_voxel 控制并存储在 HashMap 中的持久层。持久层始终覆盖程序化层。这样，世界可以无限大，但我们只需要存储有意更改的体素信息。在当前实现中，已生成区块的程序化层会被缓存，所以如果生成距离很大，仍可能使用大量内存。

关于如何使用地形查找函数的示例，请参见此示例。

基本设置

为你的世界创建一个配置结构：

#[derive(Resource, Clone, Default)]
struct MyWorld;

impl VoxelWorldConfig for MyWorld {
    // 所有选项都有默认值，所以你只需添加你想修改的选项。
    // 完整列表请参见 src/configuration.rs
    fn spawning_distance(&self) -> u32 {
        25
    }
}

然后使用你的配置添加插件：

.add_plugins(VoxelWorldPlugin::with_config(MyWorld))

配置结构有两个作用：

提供配置值
其类型也作为世界实例标识符。这意味着你可以通过添加多个插件实例来创建多个世界，只要每个实例都有一个唯一的配置结构。这里是使用不同材质的两个世界的示例

访问世界

要在系统中访问体素世界实例，你可以使用 VoxelWorld 系统参数。VoxelWorld 接受一个类型参数，即你想访问的世界的配置结构。

set_voxel 和 get_voxel 访问函数可用于操作世界中的体素数据。

fn my_system(mut voxel_world: VoxelWorld<MyWorld>) {
    voxel_world.set_voxel(IVec3 { ... }, WorldVoxel::Solid(0));
}

这将更新持久 HashMap 中给定位置的体素值，并导致 bevy_voxel_world 将受影响的区块排队重新生成网格。

体素由其在世界中的XYZ坐标（由 IVec3 指定）作为键。体素类型由 WorldVoxel 类型指定。体素可以是 Unset、Air 或 Solid。

体素材质

Solid 体素持有一个 u8 材质类型值。因此，最多支持256种材质类型。材质类型可以通过映射回调轻松映射到2D纹理数组中的索引。

可以在配置中提供自定义数组纹理。它应该是一个大小为 W x (W * n) 的图像，其中 n 是索引数。因此，4个16x16像素纹理的数组大小应为16x64像素。索引数量在第二个参数中指定。

然后，要映射哪些索引属于哪些材质类型，你可以提供一个 texture_index_mapper 回调：

impl VoxelWorldConfig for MyWorld {
    fn texture_index_mapper(&self) -> Arc<dyn Fn(u8) -> [u32; 3] + Send + Sync> {
        Arc::new(|vox_mat: u8| match vox_mat {
            SNOWY_BRICK => [0, 1, 2],
            FULL_BRICK => [2, 2, 2],
            GRASS | _ => [3, 3, 3],
        })
    }

    fn voxel_texture(&self) -> Option<(String, u32)> {
        Some(("example_voxel_texture.png".into(), 4)) // 具有4个索引的数组纹理
    }
}

texture_index_mapper 回调接收一个材质类型，应返回一个包含三个值的数组。这些值表示哪个纹理索引映射到体素的 [顶部, 侧面, 底部]。

有关可运行的示例，请参见纹理示例。

自定义着色器支持

如果你需要进一步自定义材质，可以在添加插件时使用 .with_material(MyCustomVoxelMaterial) 来注册你自己的Bevy材质。这允许你在 bevy_voxel_world 中使用自定义着色器。更多详情请参见此示例。

射线投射

要从屏幕上的像素位置（例如鼠标位置）找到体素世界中的体素位置，你可以向体素世界投射射线。

fn do_something_with_mouse_voxel_pos(
    voxel_world: VoxelWorld<MyWorld>,
    camera_info: Query<(&Camera, &GlobalTransform), With<VoxelWorldCamera<MyWorld>>>,
    mut cursor_evr: EventReader<CursorMoved>,
) {
    for ev in cursor_evr.read() {
        // 从光标位置获取射向世界的射线
        let (camera, cam_gtf) = camera_info.single();
        let Some(ray) = camera.viewport_to_world(cam_gtf, ev.position) else {
            return;
        };

        if let Some(result) = voxel_world.raycast(ray, &|(_pos, _vox)| true) {
            // result.position 将是体素在世界中的位置，类型为 Vec3
            // 要获取射线相交表面方向上体素旁边的空位置，可以使用 result.normal：
            // let empty_pos = result.position + result.normal;
        }
    }
}

更多详情请参见射线投射的完整示例。