用途
当一份 3D 设计需要以精灵(sprite)或公告板(billboard)方式渲染时,可以加载本技能。其原则是玩法组件保持不动,渲染组件发生变化。
主要能力
- 绘制替换:在公告板足够的情况下,把网格与 PBR 材质实体的渲染部分替换为 Sprite。
- 相机:使用来自 bevy-camera-systems 的 Camera2d。
- 光照:对于无光照精灵,不需要 3D 光源实体;同时不应在玩法代码中保留 clustered-light 假设。
- 顺序控制:通过自有的 DrawOrder 组件记录绘制顺序,再写入 Transform。
组件保留与变更对照
| 部分 | Bevy 惯例 |
|---|---|
| actor 上的玩法 | 保留相同组件;把渲染组件换成 Sprite。 |
| 视角 | Camera2d。 |
| 绘制顺序 | 自己存储的 DrawOrder 组件,然后写入 Transform。 |
使用方式(代码示例)
依赖配置:
[dependencies]
bevy = "0.20"
玩法组件保留在实体上,移除 3D 渲染组件并换上 Sprite,Camera2d 作为视角。
#[derive(Component)]
struct Actor;
#[derive(Component)]
struct DrawOrder(f32);
fn spawn_flat_view(mut commands: Commands) {
commands.spawn(Camera2d);
}
fn present_as_sprites(
mut commands: Commands,
asset_server: Res<AssetServer>,
actors: Query<(Entity, &DrawOrder), With<Actor>>,
) {
let image = asset_server.load("actors/hero.png");
for (entity, order) in &actors {
commands
.entity(entity)
.remove::<Mesh3d>()
.remove::<MeshMaterial3d<StandardMaterial>>()
.insert((
Sprite {
image: image.clone(),
custom_size: Some(Vec2::new(64.0, 64.0)),
..default()
},
Transform::from_xyz(0.0, order.0, 0.0),
));
}
}
新 actor 可以直接以平面形态生成,玩法系统查询的仍是同一个 Actor 组件。
#[derive(Component)]
struct Actor;
fn spawn_sprite_actor(mut commands: Commands, asset_server: Res<AssetServer>) {
commands.spawn((
Actor,
Sprite {
image: asset_server.load("actors/hero.png"),
color: Color::WHITE,
..default()
},
Transform::from_xyz(0.0, 0.0, 0.0),
));
}
fn face_motion(mut actors: Query<(&Transform, &mut Sprite), With<Actor>>) {
for (transform, mut sprite) in &mut actors {
sprite.flip_x = transform.translation.x < 0.0;
}
}
无需 3D 相机即可按存储的顺序对精灵排序。较高的 DrawOrder 映射到较高的 Y,使 2D 相机在俯视布局中更晚绘制它。
#[derive(Component)]
struct DrawOrder(f32);
fn apply_draw_order(mut sprites: Query<(&DrawOrder, &mut Transform), With<Sprite>>) {
for (order, mut transform) in &mut sprites {
transform.translation.y = order.0;
}
}
专家知识要点
目标版本: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 | Update 或 FixedMain |
| 全应用共享的一个值 | Resource | 一个系统 | Startup 插入,然后由读取它的调度使用 |
| 生成 | Commands | 执行生成的系统 | 初始世界用 Startup;运行时生成用后续调度 |
| 不可竞态的顺序 | .chain() | 仅被链式的系统 | 同一调度 |
| 插件边界 | Plugin | build 注册系统与资源 | 应用运行之前 |
借用规则:两个系统若都可变地查询同一组件,必须排序(.chain())或拆分,使只有一个写入。无关系统保持并行。这是 ECS 页面规则,不是对某个 system-set API 的猜测。
决策
| 如果你需要 | 这样做 | 不要 |
|---|---|---|
| 每实体数据 | Component + Query | 存放在世界之外的普通 struct |
| 全应用配置或时钟 | Resource | 把值复制到每个实体上 |
| 稳定模拟步长 | FixedMain 与 Fixed 时钟 | 把模拟绑在原始帧 Update 上 |
| 启动时生成 | 在 Startup 中使用 Commands | 从渲染系统生成 |
| 非共享状态的跨系统通知 | bevy-events-messaging 中的消息或观察者槽位 | 在本文件中新造事件类型 |
| 文档集之外的 API | 先查官方文档 | 编造的 crate 或 API |
所有权表见 references/ecs-ownership.md。
禁止事项
- 不要在文档 URL 中固定 /0.20.0/。原因:链接保持在 latest;0.20 目标在正文中说明一次即可。
- 不要用两个未排序的系统可变查询同一组件。原因:除非 .chain() 排序,否则调度会并行运行系统。
- 不要在此发明物理、导航、网络或 XR crate。原因:本技能只命名有文档的 Bevy crate 与模块。
- 不要在已变为精灵的实体上遗留 Mesh3d 或 MeshMaterial3d。原因:同一实体上的两条渲染路径会争抢同一个 transform。
- 不要发明 API 或把未具名第三方 crate 当作选定求解器。原因:Bevy 代码应保持地道 ECS 并只用有文档的 Bevy API。
参考
bevy-master 上的库固定为 0.20.0,永久链接保持不带版本。
官方文档
- Assets:官方资源目录。未选定第三方 crate。
- Examples:latest 分支上的示例树。
- 2D examples:精灵与相机示例。
- ECS:Component、系统、Query、Startup、Update 与 .chain()。
- Plugins:Plugin、DefaultPlugins、MinimalPlugins 与 add_plugins。
相关技能
前置
- bevy-master:枢纽与调度。
- bevy-ecs-composition:组件与系统。
- bevy-camera-systems:Camera2d。
- bevy-2d-animation:精灵剪辑。
补充
- bevy-adapt-2d-to-3d:反向适配。
下游 / 消费者
- 暂未提供。
主技能
- bevy-master:Bevy 路由器。
适用场景
- 将已有 3D 设计的玩法逻辑迁移到 2D 精灵或公告板呈现。
- 需要在 2D 视角下保持原有玩法组件不变、仅替换渲染层。
- 需要在 2D 场景中控制精灵绘制顺序。
限制
- 目标版本为 Bevy 0.20+,资料未提供其他版本兼容性。
- 涉及物理、导航、网络或 XR 等功能时,本技能不提供相应 crate 支持。
- 资料未提供收费、价格或平台相关信息。