游戏客户端架构 / 系统课时

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,可以直接使用对应数据。

Include、Exclude 和 Optional 查询条件组合筛选实体的流程图

图中的阶段顺序用于帮助理解条件组合。实际 ECS 查询引擎可以调整过滤执行顺序以提高效率,只要最终匹配语义不变,结果集合就应该相同。

用代码验证组合条件

下面使用原生 Python 实现一个独立的查询函数。Include 与 Exclude 都表示组件名称集合,Optional 则在查询完成后读取。

示例不调用任何特定引擎 API,可以直接运行,适合先验证筛选语义。

python
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}")

预期输出:

text
命中: [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 更新集合。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

Include 与 Exclude 怎么组合

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通