bevy-tilemap

用途

bevy-tilemap 是一个面向 Bevy 引擎的 ECS 瓦片地图技能，用于在存储瓦片网格之前加载参考。Bevy 使用 Sprite 和 TextureAtlas 绘制格子，网格本身是一个资源（Resource）以及一组由你拥有的实体（Entity）。

主要能力

以资源形式保存瓦片网格：TileGrid 拥有宽度、高度以及每个槽位的一个单元 id。
以组件形式记录格子坐标：TileCell 在精灵实体上存储网格坐标。
绘制：TextureAtlasLayout::from_grid 切分图集，Sprite::from_atlas_image 选取单元索引。
调度：在 Startup 中生成网格。自动瓦片（autotile）规则是作用于邻居 id 的普通函数。
自动瓦片：用四邻居位掩码选取图集索引，空邻居保持为零。

使用方式

依赖声明为 bevy = "0.20"。核心思路是：网格是唯一数据源，精灵只是它的视图。

TileGrid 资源示例：

#[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,
}

一个 4×4、每格 16 像素的图集成为一个布局资产。每个实心格子生成一个精灵：

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);
        }
    }
}

概念映射

TileSet 图集 → TextureAtlasLayout::from_grid 加 Sprite::from_atlas_image
TileMap 图层 → TileGrid 资源，每个可见格子一个实体
自动瓦片 → 从邻居 id 到图集索引的函数

适用场景

适用于 Bevy 0.20+ 的 2D 瓦片地图场景，例如需要以网格形式存储和绘制瓦片、按邻居关系自动选择瓦片外观的项目。

限制

没有引擎级瓦片地图类型。
基于网格的碰撞属于 bevy-physics-2d 的物理范畴。
流式加载更大世界意味着从同一资源生成和销毁 TileCell 实体。
本技能只命名有文档记录的 Bevy crate 和模块，不发明物理、导航、网络或 XR crate。
不使用 Godot 的 TileMap 或 TileSet 类型，不指定某个具名瓦片地图 crate 作为解决方案。
不要在文档 URL 中固定 /0.20.0/；0.20 目标只在正文中说明一次。
不要从两个无序系统可变查询同一组件；调度会并行运行系统，除非用 .chain() 排序。

技能介绍

用途

主要能力

使用方式

概念映射

适用场景

限制

相关技能