SuperAPI AI 工具集

bevy-adapt-3d-to-2d

编程与开发

查看项目

更新于 10-16 10:39

技能介绍

用途

当一份 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 支持。
  • 资料未提供收费、价格或平台相关信息。