附录 C：ECS 速查表

SystemParam 一览

参数类型	用途	可变性
Query<D, F>	查询带过滤器的组件组合	D 决定
Res<T>	读取全局资源	只读
ResMut<T>	修改全局资源	可变
Commands	排队实体/组件的增删改	延迟
EventReader<T>	读取事件	只读
EventWriter<T>	写入事件	可变
MessageReader<T>	读取消息（0.18 新增）	只读
MessageWriter<T>	写入消息	可变
Local<T>	系统私有状态（跨调用保持）	可变
RemovedComponents<T>	监听组件移除	只读
QueryState<D, F>	缓存的查询状态（用于自定义参数）	—
SystemState<...>	缓存的系统参数集合	—
ParamSet<...>	互斥的参数集合	一次只访问一个
FilteredResources	资源的只读视图	只读
FilteredResourcesMut	资源的可变视图	可变
Trigger<T>	Observer 中的事件触发器	—

Query 数据类型

类型	含义
&T	只读访问组件 T
&mut T	可变访问组件 T
Option<&T>	组件 T 可能不存在
Has<T>	返回 bool，组件 T 是否存在
Entity	实体句柄
Ref<T>	只读访问 + 变更检测
Mut<T>	可变访问 + 变更检测

Query 过滤器

过滤器	含义
With<T>	必须有组件 T（不出现在数据中）
Without<T>	必须没有组件 T
Changed<T>	组件 T 本帧被修改过
Added<T>	组件 T 本帧被添加
Or<(F1, F2, ...)>	任一过滤器匹配
Allows<T>	与 Disabled 配合，允许查询被禁用的实体

Schedule API

注册系统

app.add_systems(Update, my_system);
app.add_systems(Update, (sys_a, sys_b).chain());
app.add_systems(Update, sys_a.run_if(condition));
app.add_systems(OnEnter(MenuState::Main), setup_menu);
app.add_systems(OnExit(MenuState::Main), cleanup_menu);

SystemSet

#[derive(SystemSet, Debug, Clone, PartialEq, Eq, Hash)]
struct GameplaySet;

app.configure_sets(Update, GameplaySet.run_if(in_state(GameState::Playing)));
app.add_systems(Update, physics.in_set(GameplaySet));

排序

app.add_systems(Update, sys_b.after(sys_a));
app.add_systems(Update, sys_a.before(sys_b));
app.add_systems(Update, (sys_a, sys_b, sys_c).chain()); // a → b → c

Run Conditions

app.add_systems(Update, my_system.run_if(in_state(GameState::Playing)));
app.add_systems(Update, my_system.run_if(resource_changed::<Clock>));
app.add_systems(Update, my_system.run_if(on_timer(Duration::from_secs(1))));
app.add_systems(Update, my_system.run_if(not(in_state(GameState::Paused))));

Commands 常用操作

// 生成实体
let id = commands.spawn((ComponentA, ComponentB)).id();

// 生成带 Children 的实体
commands.spawn(Node).with_children(|parent| {
    parent.spawn(Text::new("Hello"));
});

// 添加组件
commands.entity(id).insert(ComponentC);

// 移除组件
commands.entity(id).remove::<ComponentC>();

// 销毁实体
commands.entity(id).despawn();

// 插入资源
commands.insert_resource(MyResource::default());

// 移除资源
commands.remove_resource::<MyResource>();

生命周期事件

事件	触发时机
OnAdd	组件被添加到实体时
OnInsert	组件被添加或覆盖时
OnReplace	组件即将被覆盖时（旧值还在）
OnRemove	组件被移除时
DespawnOnExit	状态退出时自动销毁实体