游戏客户端架构 / 系统课时
Include 与 Exclude 怎么组合
Include 与 Exclude 怎么组合
本课解决组件查询中更常见的筛选问题:一个运动系统既要处理拥有 Position 和 Velocity 的实体,又要跳过 Disabled 实体,同时允许部分实体额外携带 Health。你将学会组合 Include、Exclude 与可选组件,并准确判断最终结果集合。
学习目标
- 理解 Include、Exclude 和可选组件分别对查询结果产生什么影响。
- 能够组合多个条件,正确判断实体是否应该被 System 处理。
- 能够通过可运行示例验证筛选结果,并避免把可选组件误写成必需条件。
先分清三种组件条件
假设 MovementSystem 只应该更新正常启用的可移动实体。某些实体拥有 Health,可以在更新时读取生命值;没有 Health 的实体仍然允许移动。
这时查询涉及三种不同职责。
| 条件 | 查询含义 | 当前示例 |
|---|---|---|
| Include | 指定组件必须全部存在 | Position、Velocity |
| Exclude | 指定组件必须全部不存在 | Disabled |
| Optional | 组件可有可无,不影响是否命中 | Health |
多个 Include 条件之间是逻辑与:实体必须同时拥有 Position 和 Velocity。多个 Exclude 条件之间同样要求全部不存在:只要出现任意一个被排除组件,实体就不能命中。
因此,本例的匹配规则可以写成:
Has(Position) AND Has(Velocity) AND NOT Has(Disabled)
Health 不参与这个布尔表达式。它只决定命中实体是否有额外的生命值数据可供读取。
从实体集合看筛选过程
构造六个实体,观察不同组件组合对结果的影响。
| Entity | Position | Velocity | Disabled | Health | 最终命中 |
|---|---|---|---|---|---|
| 201 | 有 | 有 | 无 | 无 | 是 |
| 202 | 有 | 有 | 有 | 无 | 否 |
| 203 | 有 | 有 | 无 | 有 | 是 |
| 204 | 有 | 有 | 无 | 有 | 是 |
| 205 | 有 | 无 | 无 | 有 | 否 |
| 206 | 有 | 有 | 有 | 有 | 否 |
首先执行 Include,要求同时具备 Position 和 Velocity,候选集合为 201、202、203、204、206。Entity 205 因缺少 Velocity 被淘汰。
然后执行 Exclude,移除带有 Disabled 的 202 和 206。最终命中集合为 201、203、204。
最后读取可选 Health:201 没有 Health,但依然命中;203 和 204 拥有 Health,可以直接使用对应数据。

图中的阶段顺序用于帮助理解条件组合。实际 ECS 查询引擎可以调整过滤执行顺序以提高效率,只要最终匹配语义不变,结果集合就应该相同。
用代码验证组合条件
下面使用原生 Python 实现一个独立的查询函数。Include 与 Exclude 都表示组件名称集合,Optional 则在查询完成后读取。
示例不调用任何特定引擎 API,可以直接运行,适合先验证筛选语义。
entities = {
201: {
"Position": {"x": 0},
"Velocity": {"x": 2},
},
202: {
"Position": {"x": 1},
"Velocity": {"x": 3},
"Disabled": {},
},
203: {
"Position": {"x": 2},
"Velocity": {"x": 1},
"Health": {"hp": 80},
},
204: {
"Position": {"x": 3},
"Velocity": {"x": -1},
"Health": {"hp": 50},
},
205: {
"Position": {"x": 4},
"Health": {"hp": 60},
},
206: {
"Position": {"x": 5},
"Velocity": {"x": 1},
"Disabled": {},
"Health": {"hp": 20},
},
}
def query_entities(world, include, exclude):
matched = []
for eid, components in world.items():
# Include 全部存在,且 Exclude 全部不存在。
if include.issubset(components) and exclude.isdisjoint(components):
matched.append(eid)
return matched
include = {"Position", "Velocity"}
exclude = {"Disabled"}
optional = "Health"
matched = query_entities(entities, include, exclude)
print("命中:", matched)
for eid in matched:
# 可选组件缺失不影响命中,只改变读取结果。
health = entities[eid].get(optional)
hp = health["hp"] if health is not None else "无"
print(f"{eid}: Health={hp}")预期输出:
命中: [201, 203, 204]
201: Health=无
203: Health=80
204: Health=50这段代码用 issubset() 实现全部包含条件,用 isdisjoint() 实现全部排除条件。两者都只检查组件名称是否存在,不会读取组件内部的业务字段。
查询后的 get() 用于尝试获取 Health。即使组件不存在,也不会把实体从已经得到的命中集合里删除。
示例输出顺序来自 Python 字典的插入顺序,真实 ECS 查询可能采用不同的遍历顺序,不应依赖这个顺序编写业务规则。
可选组件与排除条件的边界
最容易出现的错误,是把 Optional 理解为“存在时才匹配”。如果把 Health 也放进 Include,那么 Entity 201 将不再命中,查询就变成了必须同时拥有 Position、Velocity 和 Health。
另一种错误,是根据组件数据是否为空判断组件是否存在。示例中的 Disabled 使用空字典作为标记,表示实体确实拥有 Disabled 组件。虽然空字典在 Python 条件判断中为假,但它仍然应该触发排除规则。
因此,组件存在性判断必须基于组件存储或注册信息,而不是依赖组件数据的真假值。对于仅表示开关状态的标记组件,这一点尤其重要。
还需要区分“没有某个组件”和“组件内部的某个字段处于禁用状态”。例如 Exclude(Disabled) 只能排除拥有 Disabled 组件的实体,不能自动理解其他组件内部的 enabled=False。如果禁用状态存储在字段中,就需要额外的值过滤逻辑。
当 Include 和 Exclude 同时包含同一个组件时,查询条件互相矛盾,结果必然为空。构建查询时应尽早检查这种冲突,避免系统长期无命中却没有明显错误提示。
什么时候应该拆分查询
Optional 适合用于额外数据读取,但并不意味着所有可选组件都应该塞进同一个 System。
如果 MovementSystem 对所有命中实体执行相同的位置更新,仅在显示调试信息时额外读取 Health,保留一个查询比较合理。
如果有 Health 和没有 Health 的实体需要执行两套完全不同的逻辑,或者 System 内出现大量针对 Health 的条件分支,就可以考虑拆成两个更明确的处理集合:
- Include(Position, Velocity, Health),Exclude(Disabled):处理同时拥有生命值数据的可移动实体。
- Include(Position, Velocity),Exclude(Disabled, Health):处理不带生命值数据的可移动实体。
这两个集合互不重叠,能避免同一实体被两个分支重复处理。不过,只有在分支确实复杂、需要不同的执行策略时才值得拆分;为一两个简单字段增加多个查询,也会提高维护成本。
可以再做一次边界验证:从 Entity 202 移除 Disabled 后,它应该进入结果;给 Entity 201 增加 Health 后,结果集合不应变化,只是它的可选数据从无变为可读取。
设计组合查询时,先确定哪些组件决定实体能否参与,再确定哪些组件仅提供额外信息。Include 控制必须具备的能力,Exclude 控制禁止参与的状态,Optional 控制处理时可读取的附加数据。把三者职责区分清楚,才能得到可预测、易验证的 System 更新集合。