用途
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。