用途
本技能用于 Bevy 引擎中的 3D 关卡组装,即在关卡里放置网格、灯光与碰撞体。它聚焦于 ECS 形态下的世界搭建:实体携带变换与渲染组件,图元转换为网格并挂载到 Mesh3d 与 MeshMaterial3d 上。
适用时机:当需要把网格、灯光和碰撞体放入关卡时加载本技能。场景生成机制属于 bevy-asset-scenes;物理刚体属于 bevy-physics-3d。
主要能力
- 生成:实体携带变换与渲染组件。图元(Cuboid、Sphere、Cylinder)转换为 Mesh,并挂载在 Mesh3d 加 MeshMaterial3d 上。
- 场景:bevy_scene 与 bevy_gltf 是特性。生成细节在 bevy-asset-scenes(AssetServer、场景生成)。
- 灯光:DirectionalLight 是带 Transform 的实体。雾是相机实体上的 DistanceFog。完整灯光设置属于 bevy-3d-lighting。
- 系统:哪些单元格已存在是一个 Resource。生成单元格是 Update 中的 Commands。
使用方式
技能给出了 spawn_level 示例:通过 Commands、Assets<Mesh>、Assets<StandardMaterial> 生成地板、柱子、球体、方向光与带距离雾的相机。
道具拼装(Kitbash props)是普通实体。辅助函数返回实体 id,便于后续系统把标记父级到它上面,示例为 spawn_prop。
单元格流式加载:已存在于世界中的单元格记录在一个资源上。流式系统只为尚未记录的单元格插入标记组件与网格,示例为 LoadedCells 资源、CellMarker 组件与 stream_cells 系统。
依赖声明为 bevy = "0.20"。
关卡选择对照:
- 打包关卡:通过 bevy-asset-scenes 生成的场景资产。
- 道具拼装:带 Mesh3d 与 MeshMaterial3d 的实体。
- 氛围:DirectionalLight、DistanceFog 与相机实体。
范围:上述图元覆盖灰盒方块、柱子和球体。高度图是自行填充的 Mesh,然后用同样的 Mesh3d 生成。碰撞体编写在选定物理求解器后属于 bevy-physics-3d。
状态归属与排序规则
目标: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())或拆分使只有一个写入。无关系统保持并行。
决策对照:
- 每实体数据:Component + Query;不要用复制到实体上的脚本字段。
- 应用级配置或时钟:Resource;不要把值复制到每个实体。
- 稳定模拟步长:FixedMain 与 Fixed 时钟;不要把模拟绑定到原始帧 Update。
- 启动生成:Startup 中的 Commands;不要从渲染系统生成。
- 非共享状态的跨系统通知:bevy-events-messaging 中的消息或观察者槽位;不要在本文件中发明新事件类型。
- 文档集之外的 API:先查官方文档;不要使用编造的 crate 或 API。
可加载 references/ecs-ownership.md 查看归属表。
限制与禁止事项
- 不要在文档 URL 中固定 /0.20.0/。原因:链接保持最新;0.20 目标在正文中说明一次。
- 不要从两个无序系统可变查询同一组件。原因:除非 .chain() 排序,调度会并行运行系统。
- 不要在此发明物理、导航、网络或 XR crate。原因:本技能只命名有文档的 Bevy crate 与模块。
- Bevy 代码中不使用 CSG、网格地图或世界环境节点类型。原因:灰盒网格、灯光与 DistanceFog 是有文档的 Bevy 部件。
- 不发明 API,也不把未命名的第三方 crate 作为选定求解器。原因:Bevy 代码保持惯用 ECS,只使用有文档的 Bevy API。
参考与相关技能
官方链接保持在 bevy.org。bevy-master 上的库固定为 0.20.0。
官方文档:Assets(官方资产目录,未选择第三方 crate)、Examples(最新分支上的示例树)、ECS(Component、系统、Query、Startup、Update 与 .chain())、Plugins(Plugin、DefaultPlugins、MinimalPlugins 与 add_plugins)。
前置技能:bevy-master(枢纽与调度)、bevy-ecs-composition(组件与系统)、bevy-asset-scenes(场景生成)、bevy-3d-lighting(灯光)、bevy-3d-materials(表面)、bevy-camera-systems(视图)。
互补技能:bevy-procedural-generation(生成布局)、bevy-physics-3d(模拟道具,求解器尚未选定)、godot-3d-world-building(Godot 路线上的同一主题)。
下游/消费者:暂无。
主技能:bevy-master(Bevy 路由器)。