SuperAPI AI 工具集

bevy-app-resources

编程与开发

查看项目

更新于 10-16 11:39

技能介绍

用途

本技能用于在 Bevy 中处理必须对整个应用存在的数据与逻辑,包括唯一的时钟、唯一的规则集、启动时的生成,以及必须按顺序执行的一对系统。当数据需要在全应用范围内唯一存在,或需要在启动阶段完成初始化时使用。与 bevy-data-resources 配合,用于区分数据应作为组件还是资源。

主要能力

文档围绕以下 ECS 形态展开:

  • App:Apps 页面所述,App 包含一个 World 和外层循环,负责初始化资源(唯一副本)、把系统加入 Schedule,并通过插件导入其他 App 变更。
  • Resources:涉及 Resource、Res、ResMut 与 insert_resource。Time 由 add_plugins(DefaultPlugins) 提供。
  • Plugins:在 Resources 页面中实现 Plugin,并在 build 内插入资源。DefaultPlugins 是提供 Time 的插件集合。
  • Schedules:add_systems(Startup, ...) 在其他系统前运行一次;add_systems(Update, ...) 是重复运行的调度;.chain() 用于给必须看到彼此写入的系统排序。bevy::ecs::message 仅把 FixedUpdate 作为 signal_message_update_system 之后运行的调度提及。固定时间步时钟类型留在 bevy-character-movement 中。
  • States:应用级模式属于 bevy::state,不是全局节点,详见 bevy-state-machines。

使用方式与选择依据

App 层面的选择表:

需求 Bevy 惯用法
全应用唯一副本 在 App 上插入的 Resource
每帧运行的逻辑 Update 上的系统(或成链的一对系统)
启动初始化 Startup 系统,或在 Plugin 中 insert_resource
一次性通知 消息或事件,参见 bevy-events-messaging

范围约定:

  • 在 Plugin::build 内用 insert_resource 插入应用级数据,或从 Startup 系统插入。
  • 对两个都要可变使用同一资源的系统,用 .chain() 排序。
  • 存档文件是你自己序列化的 Resource,运行中的副本留在 World 中。

示例说明

Cargo 依赖示例将 bevy 版本设为 0.20。Rust 示例演示一个规则资源、一次启动生成,以及一对不得在 Score 上竞争的系统:Ruleset 与 Score 均为 Resource,RulesPlugin 在 build 中写入 Ruleset、初始化 Score,并在 Startup 中加入 spawn_session,在 Update 中用 .chain() 串联 apply_gravity、award、publish。由于 award 与 publish 都触及 Score 或 Transform,而 apply_gravity 也写 Transform,三者保持在同一链中。

第二个插件示例仅读取规则资源,HudPlugin 在 Update 中加入 log_rules。

第三个示例展示固定步长模拟:fixed_step 读取 Time<Fixed> 并运行于 FixedUpdate,FixedRulesPlugin 在 FixedUpdate 中加入该系统。文中说明 fixed_step 在本模块中拥有 Falling 标记,而启动示例使用自己的 Falling 标记。

专家知识要点

目标版本: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/,链接保持 latest,0.20 目标只在正文中说明一次。
  • 不要从两个无序系统可变查询同一组件,因为除非 .chain() 排序,调度会并行运行系统。
  • 不要在此处臆造物理、导航、网络或 XR crate,本技能只命名有文档记录的 Bevy crate 与模块。
  • 不要为应用数据使用进程级全局静态量,App 上的 Resource 是唯一所有者,系统通过 Res 或 ResMut 借用。
  • 不要臆造 DefaultPlugins 与 Resources 页面所用 Plugin trait 之外的插件列表。
  • 不要使用第三方 crate,Bevy 代码保持惯用 ECS 且只使用有文档记录的 Bevy API。

参考

bevy-master 的库版本固定为 0.20.0,永久链接保持不带版本号。

官方文档:Apps(App、World、资源、Schedule、插件)、Resources(Resource、insert_resource、Plugin::build、DefaultPlugins、Time)、Quick Start: ECS(Startup、Update、add_systems、.chain())、Examples(latest 分支上的示例树)。

相关技能:前置为 bevy-master(中心与调度)和 bevy-project-foundations(crate 与 App::new());互补为 bevy-data-resources(数据何时是组件而非资源)与 bevy-state-machines(应用级 States 用于模式切换);下游/消费者为存档、音频与场景技能,覆盖持久化、播放与场景生成;主技能为 bevy-master(Bevy 路由)。