SuperAPI AI 工具集

bevy-state-machines

编程与开发

查看项目

更新于 10-16 10:40

技能介绍

用途

在 Bevy 应用中管理与组织状态逻辑。当应用需要一个大的运行模式(例如暂停、位于菜单中、加载中),或者某个实体需要一个小型模式标志时,可使用本技能。Bevy 提供两种不同的状态归属方式,应保持二者分离:应用级模式使用 bevy::state 中的 States 类型,实体级模式使用 Component。

主要能力

应用状态(App states)

bevy::state 提供应用范围的有限状态机。共有三种类型实现 States:

  • 标准 States:仅通过设置 NextState<S> 资源来改变状态。
  • SubStates:同样使用 NextState<S>,但当源状态不处于所要求的状态时,会从 World 中移除。
  • ComputedStates:通过 compute 方法从其他状态派生而来。

过渡调度与事件

  • OnEnter<S>、OnExit<S>、OnTransition<S> 会在匹配的状态过渡上运行系统。
  • StateTransitionEvent<S> 在状态 S 变化时触发。
  • 运行条件包括 in_state<S> 和 state_changed<S>。

实体生命周期

DespawnOnEnter<S> 和 DespawnOnExit<S> 会在相应的状态过渡上反生成(despawn)实体,属于 state_scoped 范畴。

特性与安装

bevy_state 包含在默认的 bevy 应用插件中。使用 init_state 安装状态,使用 add_sub_state 安装子状态。

实体级模式

将枚举存入 Component,并在系统中进行分支判断。该枚举不是 States 类型。

使用方式

依赖配置:

[dependencies]
bevy = "0.20"

应用模式使用 States,游戏逻辑系统使用 in_state,暂停操作写入 NextState。示例代码展示了通过 init_state::<AppMode>()、OnEnter 调度与 run_if(in_state(...)) 组合来实现模式切换;同时给出 SubStates 的暂停标志示例(仅在 AppMode::Play 激活时存在,否则被移除),以及单实体 Stance 组件的示例。

适用场景

  • 应用模式(菜单、暂停、游戏):使用 States 类型与 NextState<S>。
  • 只在某个模式下运行逻辑:使用 in_state 或 OnEnter / OnExit / OnTransition 调度。
  • 仅存在于父模式内的子模式:使用 SubStates。
  • 从其他模式派生的模式:使用 ComputedStates。
  • 单个角色的姿态:使用枚举 Component 加系统。除非确实是应用范围的,否则不使用 States。

限制与注意事项

  • 目标版本为 Bevy 0.20+。
  • 不要在文档 URL 中固定 /0.20.0/ 版本号,链接保持 latest。
  • 不要从两个未排序的系统可变查询同一组件,因为它们会并行运行,除非用 .chain() 排序。
  • 不要在本技能中虚构物理、导航、网络或 XR crate。
  • 不要使用 Godot 的动画树或节点状态机类型,Bevy 代码保持地道的 ECS 风格。
  • 不要编造 App 状态设置方法,不要使用第三方 crate。
  • 实体级姿态是 Stance 组件;动画图属于 bevy-animation-graph。消息与观察者属于独立归属槽位,参见 bevy-events-messaging。
  • 其他事实(如具体收费、价格、平台支持等)暂未提供。

参考

官方文档:Bevy ECS 快速入门(Component 与 Query 用于实体级模式标志)、Bevy 示例树(latest 分支,状态示例位于其中)。相关技能包括前置的 bevy-master、bevy-data-resources,互补的 bevy-events-messaging、godot-state-machine-advanced,下游的 bevy-character-movement,以及作为路由的 bevy-master。