SuperAPI AI 工具集

bevy-tilemap

编程与开发

查看项目

更新于 10-16 10:40

技能介绍

用途

bevy-tilemap 用于在存储一组网格瓦片(grid of tiles)之前参考,帮助在 Bevy 项目中以符合 ECS 习惯的方式实现瓦片地图。Bevy 通过 Sprite 与 TextureAtlas 来绘制单元格,而网格本身是一个资源(Resource)以及一组由你拥有的实体(entities)。

主要能力

  • ECS 数据形态:TileGrid 资源持有宽度、高度和每个槽位对应的 cell id;TileCell 组件在精灵实体上保存网格坐标。
  • 绘制方式:使用 TextureAtlasLayout::from_grid 切分图集(sheet),Sprite::from_atlas_image 选取单元格索引。
  • 生成时序:在 Startup 阶段生成网格;自动拼接(autotile)规则是对邻居 id 的普通函数。
  • 自动化拼接:通过四邻居位掩码(上、右、下、左)选择图集索引,空邻居保持为零。

使用方式

技能给出依赖声明示例:

[dependencies]
bevy = "0.20"

核心模型是“网格为唯一真源,精灵只是它的视图”。示例定义:

#[derive(Resource)]
struct TileGrid {
    width: i32,
    height: i32,
    cells: Vec<u16>,
}

impl TileGrid {
    fn index(&self, x: i32, y: i32) -> Option<usize> {
        if x < 0 || y < 0 || x >= self.width || y >= self.height {
            return None;
        }
        Some((y * self.width + x) as usize)
    }

    fn get(&self, x: i32, y: i32) -> u16 {
        self.index(x, y).map(|i| self.cells[i]).unwrap_or(0)
    }
}

#[derive(Component)]
struct TileCell {
    x: i32,
    y: i32,
}

一个 4x4、每格 16 像素的图集会成为一个 layout 资产,每个实心单元格生成一个精灵。生成函数示例:

fn spawn_tiles(
    mut commands: Commands,
    asset_server: Res<AssetServer>,
    mut layouts: ResMut<Assets<TextureAtlasLayout>>,
    grid: Res<TileGrid>,
) {
    let layout = layouts.add(TextureAtlasLayout::from_grid(
        UVec2::splat(16),
        4,
        4,
        None,
        None,
    ));
    let image = asset_server.load("tiles.png");
    let tile = 16.0;
    for y in 0..grid.height {
        for x in 0..grid.width {
            let id = grid.get(x, y);
            if id == 0 {
                continue;
            }
            commands.spawn((
                Sprite::from_atlas_image(
                    image.clone(),
                    TextureAtlas {
                        layout: layout.clone(),
                        index: id as usize,
                    },
                ),
                Transform::from_xyz(x as f32 * tile, y as f32 * tile, 0.0),
                TileCell { x, y },
            ));
        }
    }
    commands.spawn(Camera2d);
}

自动拼接索引示例(四邻居位掩码):

fn autotile_index(grid: &TileGrid, x: i32, y: i32) -> usize {
    let solid = |nx: i32, ny: i32| u16::from(grid.get(nx, ny) != 0);
    let mask = solid(x, y + 1)
        | (solid(x + 1, y) << 1)
        | (solid(x, y - 1) << 2)
        | (solid(x - 1, y) << 3);
    mask as usize
}

fn repaint(grid: Res<TileGrid>, mut tiles: Query<(&TileCell, &mut Sprite)>) {
    for (cell, mut sprite) in &mut tiles {
        if let Some(atlas) = sprite.texture_atlas.as_mut() {
            atlas.index = autotile_index(&grid, cell.x, cell.y);
        }
    }
}

技能还给出设计概念与 Bevy 惯用法的对应表:TileSet atlas 对应 TextureAtlasLayout::from_grid 加 Sprite::from_atlas_image;TileMap layer 对应 TileGrid 资源加每个可见单元格一个实体;Autotile 对应从邻居 id 到图集索引的函数。

专家知识要点

目标版本为 Bevy 0.20+。核心 ECS 类型包括 Component、Resource、Query、Commands、Startup、Update、Fixed / FixedMain(bevy::time)、.chain()、Plugin、DefaultPlugins、MinimalPlugins。消息与观察者属于所有权槽位,其 API 见 bevy-events-messaging。除非用 .chain() 为冲突系统排序,系统并行运行。

状态所有权表:单个实体数据由 Component 持有,通过 Query 由单个系统修改;全应用单一值由 Resource 持有;生成由 Commands 负责;不可竞争的次序用 .chain() 约束;插件边界由 Plugin 在 build 中注册系统与资源。借用规则:两个系统若同时可变查询同一组件,必须排序(.chain())或拆分使只有一个写入。

决策表要点:每实体数据用 Component + Query;应用级配置或时钟用 Resource;稳定仿真步长用 FixedMain 和 Fixed 时钟;启动生成用 Startup 中的 Commands;非共享状态的跨系统通知使用消息或观察者槽位;文档集之外的 API 先查官方文档。

适用场景

  • 在 Bevy 中加载和渲染由网格瓦片构成的 2D 地图。
  • 需要根据邻居关系自动刷新瓦片贴图(autotile)。
  • 需要以 ECS 方式管理地图数据与可见单元格实体。
  • 运行时按需生成或销毁 TileCell 实体以实现更大世界的流式加载。

限制

技能明确说明:没有引擎自带的 tilemap 类型。基于网格的碰撞属于物理范畴,交由 bevy-physics-2d 处理。对更大世界进行流式处理,意味着从同一资源生成或销毁 TileCell 实体。此外,不在本技能中发明物理、寻路、网络或 XR 相关的 crate。

参考

官方页面保持在无版本号的 bevy.org URL 上,库版本固定为 0.20.0。单元格通过 Sprite 与 TextureAtlas 绘制,没有引擎的 tile-map 类型。官方文档包括 Assets(https://bevy.org/assets/)、Examples(https://github.com/bevyengine/bevy/tree/latest/examples#examples)、ECS(https://bevy.org/learn/quick-start/getting-started/ecs/)、Plugins(https://bevy.org/learn/quick-start/getting-started/plugins/)。相关技能包括前置的 bevy-master、bevy-ecs-composition、bevy-procedural-generation、bevy-data-resources,以及互补的 godot-tilemap-mastery。