SuperAPI AI 工具集

bevy-adapt-2d-to-3d

编程与开发

查看项目

更新于 10-16 11:38

技能介绍

用途

该技能用于将 Bevy 2D 设计升级为带 3D 摄像机与网格的形态,同时保留原有玩法组件。核心做法是:替换摄像机和可绘制对象,而不改动角色身上的玩法组件。

主要能力

  • 摄像机替换:将 Camera2d 替换为 Camera3d 与透视 Projection。
  • 绘制替换:将 2D 的 Sprite 替换为 Mesh3d 与 MeshMaterial3d,材质使用 StandardMaterial。
  • 运动数据提升:把平面 Vec2 速度提升为 XZ 平面上的 Vec3 wish 速度(WishVelocity)。
  • 以启动系统(startup system)重写已生成(spawn)的实体。

技能中的对照关系为:保留——角色上的玩法组件、摄像机实体、作为数据的平面运动;替换——Sprite 换成 Mesh3d 与 MeshMaterial3d、Camera2d 换成 Camera3d 与透视 Projection、Vec2 速度换成 XZ 上的 Vec3 wish。

文档明确说明:不存在转换辅助函数(no conversion helper),而是由启动系统重写已生成实体;物理求解器仍归物理相关技能。

使用方式

依赖声明:

[dependencies]
bevy = "0.20"

示例代码包含三个系统与一个插件:

  • promote_actors:移除 Sprite,插入 Mesh3d、MeshMaterial3d 与新的 Transform。示例中使用 Cuboid::new(0.8, 1.6, 0.8).mesh() 作为网格,并设置 StandardMaterial 的 base_color。
  • promote_camera:移除 Camera2d,插入 Camera3d::default()、Projection::Perspective(PerspectiveProjection::default()) 以及摄像机 Transform。
  • lift_velocity:把 PlanarVelocity(Vec2) 的 x、y 映射为 Vec3::new(planar.0.x, 0.0, planar.0.y) 写入 WishVelocity。
  • AdaptTo3dPlugin:在 Startup 中按 .chain() 顺序注册 promote_actors 与 promote_camera,并在 FixedUpdate 中注册 lift_velocity。

另有一段 spawn_follow_camera 示例,生成带透视投影(fov: 50.0_f32.to_radians())的 Camera3d。

适用场景

当一款 2D 设计需要获得 3D 摄像机与网格时加载本技能:保留玩法组件,只替换摄像机和可绘制对象。文档还给出了 ECS 状态归属与决策参考,例如:单个实体数据用 Component + Query;应用级配置或时钟用 Resource;稳定模拟步长用 FixedMain 与 Fixed 时钟;启动生成用 Startup 中的 Commands。跨系统且非共享状态的通知属于 bevy-events-messaging 的消息或观察者槽位;文档之外的 API 应先查官方文档。

限制与约束

  • 目标版本为 Bevy 0.20+,依赖为 bevy = "0.20"。
  • 文档明确禁止:不要在文档 URL 中固定 /0.20.0/;不要从两个无序系统中可变查询同一组件(除非用 .chain() 排序);不要在本技能中发明物理、导航、网络或 XR crate;不要使用来自其他引擎的 node convert-to-3D 操作;不要在 Bevy 代码中使用外部引擎类型;不要把虚构 API 或未具名第三方 crate 作为选定求解器。
  • 文档说明:Bevy 没有场景树转换(no scene-tree convert)。
  • 关于收费、价格、平台等事实,资料中暂未提供。

参考

官方文档链接: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-camera-systems、bevy-3d-world-building(前置),bevy-adapt-3d-to-2d(互补),下游消费者暂未提供。