Flecs Query Language 完全指南:从语法到源码的查询语言深度解析

原创2026-09-24 21:04:461,906 阅读
文章标签:游戏开发高性能计算

Flecs Query Language 完全指南:从语法到源码的查询语言深度解析

Flecs Query Language(FQL)是 Flecs 中以字符串形式描述查询的声明式语言,它让开发者可以在运行时动态创建查询,常用于游戏服务器请求数据、Mod 扩展、工具链集成等场景。本文以官方文档 FlecsQueryLanguage.md 为主体,完整讲解查询语言的每一项语法(运算符、访问修饰符、通配符、变量、来源、遍历与高级特性),并结合仓库源码(DSL 解析器、C/C++ 查询 API、示例程序)给出实现级佐证。读完本文,你将能独立编写任意复杂的 Flecs 查询表达式,并理解其在底层如何被解析与求值。

查询语言是什么

Flecs Query Language 是 Flecs 查询的字符串化表示。与直接使用 C/C++ API(如 ecs_query_init 或 C++ 的 query_builder)构造查询不同,字符串形式的查询表达式可以在运行时动态生成,因此特别适合:

  • 工具链集成:如 Flecs Explorer 这类调试工具直接接受查询表达式;
  • Mod / 脚本化:由数据驱动或用户输入生成查询条件;
  • 远程服务:Flecs REST API 的查询端点可以基于查询表达式向游戏服务器请求数据。

从源码角度看,FQL 表达式通过 ecs_query_desc_t::expr 字段传给查询创建 API。该字段在 flecs.h 中注释为 "Query DSL expression (optional)",即 ecs_query_desc_t 既允许通过 terms<a href="https://link.gitcode.com/i/2284e505e05b7ef5f10ffc76e60b95b1" target="_blank">] 数组逐项描述条件,也允许直接传入一段 DSL 字符串,由解析器转换为等价的 term 列表。表达式解析器位于 [src/addons/query_dsl/parser.c,受 FLECS_QUERY_DSL 宏控制,该宏默认启用(见 addon_defines.h),同时在 json.h 中也会被自动启用以保证解析组件 ID 表达式。

快速示例

先看一个贯穿全文的典型例子:

// Match spaceship entities that are docked to a planet
SpaceShip, (DockedTo, $planet), Planet($planet)

这条查询做了三件事:

  1. SpaceShip:匹配拥有 SpaceShip 组件的实体(即所有飞船);
  2. (DockedTo, $planet):匹配拥有 DockedTo 关系(关系目标记作变量 $planet)的实体;
  3. Planet($planet):约束变量 $planet 必须是一个拥有 Planet 组件的实体。

它最终筛选出「停靠在某颗行星上的飞船」,且每次迭代都能通过变量 $planet 直接拿到那颗行星。

基础语法

一条 Flecs 查询表达式由逗号分隔的多个 term 组成,每个 term 是一个查询条件,匹配实体必须满足所有条件(默认情况下 term 之间是 AND 关系)。

组件(Components)

最基本的条件是「实体必须拥有某个组件」:

// Match entities that have Position and Velocity
Position, Velocity

这条查询匹配所有同时拥有 Position 与 Velocity 的实体。注意它匹配的是至少拥有这两个组件的实体——即使实体还拥有 Mass、Name 等其他组件,依然会被匹配。这是因为 Flecs 是 archetype ECS,查询按「实体必须拥有的组件集合」过滤,而不是要求「恰好拥有这些组件」。

对(Pairs)

Flecs 的关系(Relationship)在查询中表示为对(Pair),用括号包裹两个元素:

// Match entities that have (Likes, Bob) and (Eats, Apples)
(Likes, Bob), (Eats, Apples)

这条查询匹配同时拥有 (Likes, Bob) 和 (Eats, Apples) 两个关系的实体。对的第一元素是关系本身,第二元素是关系目标(target)。

运算符(Operators)

运算符改变 term 的匹配方式。同一时刻一个 term 只能应用一个运算符。解析器在 parser.c 中对 ||(or 运算符)的处理可以印证这一点:当 term 已被标记为 EcsAnd 时才能改写为 EcsOr,否则会报错 cannot mix operators in || expression。

Not(!)

! 运算符取反一个 term,匹配不满足该条件的实体:

// Match entities that have Position but not Velocity
Position, !Velocity

Or(||)

|| 运算符将一组 term 串联起来,要求至少一个为真:

// Match entities that have Position and Velocity or Mass
Position, Velocity || Mass

该查询匹配拥有 Position,且(拥有 Velocity 或 拥有 Mass)的实体。

Optional(?)

? 运算符标记一个 term 为可选项。可选 term 不改变查询匹配哪些实体,它的意义在于:

  • 通过查询直接获取组件数据,比在迭代后再调用 get 更高效;
  • 让一条查询完成原本需要拆分多条查询才能完成的工作。
// Match entities that have Position and optionally Velocity
Position, ?Velocity

AndFrom(and|)

andfrom 运算符让查询匹配另一个实体所拥有的全部组件。用于提供组件列表的实体通常是 prefab——因为 prefab 本身不会被查询匹配到:

// Match entities with Position and all components that MyType has
Position, and|MyType

其中 MyType 可以这样创建:

flecs::entity my_type = world.prefab("MyType")
    .add<Velocity>()
    .add<Mass>();

于是上面的查询等价于:

Position, Velocity, Mass

NotFrom(not|)

notfrom 运算符匹配不拥有另一个实体所列任何组件的实体:

// Match entities with Position and not any of the components that MyType has
Position, not|MyType

同样以 MyType = {Velocity, Mass} 为例,等价于:

Position, !Velocity, !Mass

OrFrom(or|)

orfrom 运算符匹配至少拥有另一个实体所列组件之一的实体:

// Match entities with Position and at least one of the components that MyType has
Position, or|MyType

等价于:

Position, Velocity || Mass

这三个 *From 运算符非常契合「组件模板」模式:把一组组件定义在某个 prefab 实体上,然后在查询中引用它,避免把同样的组件列表重复写在多条查询里。

访问修饰符(Access Modifiers)

访问修饰符放在 term 之前,用方括号包裹,用于指定该 term 数据的访问方式:

修饰符 说明
[in] 匹配的组件为只读
[out] 匹配的组件为读写
[inout] 匹配的组件为读写
[none] 匹配的组件不被访问
[filter] term 不产生事件(仅用于 observer)

示例:

[inout] Position, [in] Velocity

当不指定访问修饰符时,term 默认为 InOutDefault。其默认规则是:匹配自有(owned)组件的 term 默认 [inout],匹配共享(shared)组件的 term 默认 [in]——后者包括单例(singleton)term、以及通过 up 遍历匹配到的 term。[filter] 修饰符主要用于 observer 场景:标记为 filter 的 term 只参与匹配判断,不触发事件,常用于「一个 observer 只关注 A 组件,但只有同时拥有 B 组件时才触发」的需求。

通配符(Wildcards)

查询表达式支持通配符,用于匹配某个组件或对的任意/全部实例。通配符可以出现在 term 的任何位置,下面都是合法的通配符查询:

Position, (Likes, *)
Position, (*, Dogs)
Position, (*, *)
Position, *

查询结果会包含通配符实际匹配到的具体组件或对的信息,应用可以通过 C API 的 ecs_field_id() 或 C++ 的 flecs::iter::id() 检查到底匹配到了什么。在 iter.hpp 中可以看到,C++ 的 iter::id(index) 底层正是调用 ecs_field_id(iter_, index) 后包装成 flecs::id。官方示例 wildcards/src/main.cpp 也演示了如何在迭代时用 it.pair(0).second() 取出通配符实际匹配到的关系目标。

匹配全部(* 通配符)

* 通配符返回通配符位置的所有匹配实例:

// Match entities with a (Likes, *) pair
// Return all matching pairs
(Likes, *)

如果一个实体同时拥有 (Likes, Dogs) 和 (Likes, Cats),它会被该查询返回两次——每个对各一次。

当查询中出现多个 * 通配符时,所有匹配结果的排列组合都会被返回。例如:

// Match entities with (Likes, *) and (Eats, *) pairs
// Return all pair permutations
(Likes, *), (Eats, *)

一个同时拥有 (Likes, Dogs)、(Likes, Cats)、(Eats, Pizza)、(Eats, Salad) 的实体,将产生四个结果:

  • (Likes, Dogs), (Eats, Pizza)
  • (Likes, Dogs), (Eats, Salad)
  • (Likes, Cats), (Eats, Pizza)
  • (Likes, Cats), (Eats, Salad)

任意一个(_ 通配符)

any 通配符 _ 每个通配符位置最多返回一个结果:

// Match entities with a (Likes, *) pair
// Return at most one result per entity
(Likes, _)

如果实体同时拥有 (Likes, Dogs) 和 (Likes, Cats),查询只返回一个结果。返回的 id 中,any 通配符的位置会被替换为 *,表示并未匹配到具体某个对:

  • (Likes, *)

当查询中有多个 _ 通配符时,每个实体只返回一个结果:

// Match entities with (Likes, *) and (Eats, *) pairs
// Return at most one result per entity
(Likes, _), (Eats, _)

前述实体将只返回:

  • (Likes, *), (Eats, *)

* 与 _ 的核心区别在于:前者穷举所有组合(适合需要遍历全部实例的场景),后者收敛到单结果(适合只关心「是否存在」的判断)。

变量(Variables)

变量通过 $ 前缀声明。它的作用是约束通配符的取值:确保一个 term 中通配符匹配到的值,在其他 term 中也使用同一个值:

// Match all entities that eat what they like
(Likes, $food), (Eats, $food)

如果一个实体拥有 (Likes, Dogs)、(Likes, Pizza)、(Eats, Pizza)、(Eats, Salad),该查询只产生一个结果:

  • (Likes, Pizza), (Eats, Pizza)

对比一下未使用变量的全通配符查询:

(Likes, *), (Eats, *)

它会返回四种组合:

  • (Likes, Dogs), (Eats, Pizza)
  • (Likes, Dogs), (Eats, Salad)
  • (Likes, Pizza), (Eats, Pizza)
  • (Likes, Pizza), (Eats, Salad)

可见 (Likes, $food), (Eats, $food) 的结果是上述结果的严格子集——变量把两个 term 的匹配值「绑定」到了一起。

以 _ 开头的变量名被视为匿名变量,它们参与匹配约束,但在迭代查询结果时无法被访问(不会出现在查询变量表中)。

在 C++ API 中,变量既可以用查询 DSL 字符串表达,也可以由 builder 显式声明。官方示例 variables/src/main.cpp 中,DSL 写法 Eats($this, $Food), Healthy($Food) 被翻译为 .with<Eats>("$food") 与 .with<Healthy>().src("$food"),并且在迭代前通过 q.find_var("food") 拿到变量的索引,然后在回调中用 it.get_var(food_var) 读取变量对应的实体。C 侧对应的底层 API 是 ecs_query_find_var / ecs_query_var_name / ecs_query_var_is_entity(定义于 flecs.h,位于 FLECS_QUERY_PLANS 宏保护下)。

来源(Source)

每个 term 都有一个 source(来源),即该 term 在哪个实体上匹配。如果不显式指定,来源默认为内置的 $this 变量。下面两条查询等价:

// Implicit source
Position, Velocity
// Explicit source
Position($this), Velocity($this)

注意两个 term 使用同一个 $this 来源,这保证了两个组件匹配在同一个实体上。

对的显式/隐式写法如下:

// Implicit source
(Likes, Dogs), (Eats, Salad)
// Explicit source
Likes($this, Dogs), Eats($this, Salad)

一条查询可以同时包含多个不同来源的 term,下面分节介绍支持的各种来源类型。

静态来源(Static source)

静态来源是在查询创建时就已经确定的实体,直接用实体名作为来源即可:

// Match TimeOfDay component on 'Game' entity
TimeOfDay(Game)

该 term 不会在迭代时变化——它永远在名为 Game 的实体上匹配 TimeOfDay。静态来源非常适合读取全局单例数据。

变量来源(Variable source)

变量可以作为 term 的来源。前面已经提到,未指定来源时隐式使用内置变量 $this:

// Match entities with both Position and Velocity
Position($this), Velocity($this)

变量作为来源时可以同时出现在其他 term 的不同位置,实现跨 term 绑定。例如,下面这条查询匹配所有「拥有带 Serializable 组件标记的组件」的实体——注意 $component 在第一个 term 中作为关系目标(Serializable($component) 实际等价于 (Serializable, $component) 的语法糖),在第二个 term 中又作为来源:

Serializable($component), $component($this)

再回到开篇的飞船示例,把「停靠」和「行星」两个条件绑定到同一个变量上:

SpaceShip($this), DockedTo($this, $planet), Planet($planet)

还可以用变量表达更复杂的语义,例如「吃健康食物但不喜欢所吃食物的实体」:

Eats($this, $food), !Likes($this, $food), Healthy($food)

这里 $food 同时出现在三个 term 中:第一个 term 绑定「正在吃什么」,第二个 term 否定「喜欢它」,第三个 term 约束它「健康」。

遍历(Traversal)

查询遍历(traversal)让 term 可以沿关系向上查找,直到找到拥有该组件的实体。最典型的场景是变换(transform)系统:既要匹配实体自身的 Transform 组件,也要匹配其父级的 Transform 组件。

Transform($this), Transform($this|up ChildOf)

省略显式来源后可写为:

Transform, Transform(up ChildOf)

由于 ChildOf 是默认的遍历关系,还可以进一步简写为:

Transform, Transform(up)

cascade 与 desc

cascade 修饰符与 up 类似,但结果按广度优先(breadth-first)顺序返回。这常用于变换系统,确保父级先于子级完成变换计算:

Transform, Transform(cascade)

desc 修饰符可与 cascade 组合,返回相反顺序(先子级后父级)的结果:

Transform, Transform(cascade|desc)

self

self 遍历修饰符与 up 组合时,会先测试实体自身是否拥有组件,找不到再沿层级向上查找:

// First try matching Style on self, find on parent if not found
Position, Style(self|up)

当组件带有 (OnInstantiate, Inherit) trait 时,查询会自动为 IsA 关系插入 self|up 遍历。下面两条查询等价(前提是 Style 具有 (OnInstantiate, Inherit) trait):

Position, Style
Position, Style(self|up IsA)

其中 OnInstantiate 是 Flecs 内置的 trait 常量,C++ 侧定义于 c_types.hpp。

遍历修饰符可以用于任何带有 Traversable trait 的关系。C++ 中给自定义关系打上该标记的方式如下:

world.component<MyRelationship>().add(flecs::Traversable);

Traversable 常量同样定义在 c_types.hpp,底层对应 EcsTraversable。

组件继承的向下遍历

当查询匹配的组件可以被继承(即存在通过 IsA 关系链接的子类)时,查询会自动沿 IsA 关系向下遍历以找出所有子类。例如,若 MeleeUnit 通过 IsA 关系继承自 Unit,下面这条查询会同时匹配拥有 Unit 和拥有 MeleeUnit 的实体:

Unit

要阻止查询评估组件继承,可以给组件添加 self 修饰符:

Unit|self

当 term 带有显式来源时,self 修饰符放在括号之前:

Unit|self($this)

传递关系的自动遍历

当查询匹配的关系带有 Transitive trait(如 LocatedIn)时,查询会根据变量位置自动向上或向下遍历该关系。Transitive 常量定义于 c_types.hpp。要阻止传递匹配,给对的第二个元素加上 self 修饰符:

LocatedIn($this, SanFrancisco|self)

这样只会匹配直接拥有 (LocatedIn, SanFrancisco) 的实体,而不会匹配如 (LocatedIn, GoldenGateBridge)(即位于金门大桥、因而也位于旧金山的实体)之类的间接结果。

高级特性(Advanced)

等式运算符(Equality operators)

等式运算符让查询可以对变量做值或名称匹配。下面的查询把变量 $this 与特定实体比较:

SpaceShip($this), $this == UssEnterprise || $this == Voyager

!= 用于取反:

SpaceShip($this), $this != UssEnterprise

查询也可以比较两个变量:

PoweredBy($this, $source), $this != $source

当操作数是字符串时,等式运算符测试的是实体的名称:

SpaceShip($this), $this == "UssEnterprise"

~= 运算符做模糊比较,等价于 substr 函数的行为(子串匹配):

SpaceShip($this), $this ~= "Uss"

~= 的结果可以用 ! 前缀取反:

SpaceShip($this), $this ~= "!Uss"

当等式运算符是第一个填充某变量的 term 时,它会为变量赋值:

$this == "UssEnterprise", SpaceShip($this)

这里 $this 被赋值名为 UssEnterprise 的实体,之后 SpaceShip($this) 只在该实体上匹配。解析器在 parser.c 中对 $this == 形式的 term 做了专门处理:将等式左侧作为 source、右侧作为要匹配的值,并支持实体名(identifier)与字符串两种操作数形式。

查找变量(Lookup variables)

变量可以作为按名称查找的起点,用于匹配结构明确的层级。下面的查询匹配「驾驶舱没有电力的飞船」:

// Match all spaceship entities where the cockpit has no power
SpaceShip($this), !Powered($this.cockpit)

查询会在 $this 匹配到的实体的作用域内查找名为 cockpit 的子实体,并以该子实体作为 Powered 的匹配来源。如果找不到名为 cockpit 的实体,该 term 求值为 false(结合 ! 即:找不到则整条查询匹配失败)。

成员匹配(Member matching)

如果组件成员的字段类型是 ecs_entity_t,查询可以直接匹配组件成员的值。下面的查询匹配 Movement 组件中 direction 成员的值等于 Left 的实体:

Movement.direction($this, Left)

等价于带隐式来源的写法:

(Movement.direction, Left)

成员表达式也可以与变量组合:

(Thrusters.left, $thruster), Active($thruster)

该查询匹配「左推进器处于激活状态」的实体:(Thrusters.left, $thruster) 将 $thruster 绑定为 Thrusters 组件 left 成员中存储的实体,Active($thruster) 再约束该实体拥有 Active。

依赖变量(Dependent variables)

当一个变量首次出现在条件求值的 term 中时,后续使用该变量的 term 只会在变量确实被设置后才求值。这为查询内创造了简单的分支逻辑:

// $animal and $food are set conditionally
(Likes, $animal) || (Eats, $food),
Friendly($animal), // Evaluated if (Likes, $animal) matched
Healthy($food)     // Evaluated if (Eats, $food) matched

这里 || 让 $animal 或 $food 二者至多其一被设置:若 (Likes, $animal) 匹配,则 Friendly($animal) 参与求值;若 (Eats, $food) 匹配,则 Healthy($food) 参与求值;未被设置的那一侧的后续 term 不会导致查询失败。

依赖变量也可以由可选 term 创建:

// Planet($object) is only evaluated if (DockedTo, $object)
// returned a result.
SpaceShip, ?(DockedTo, $object), Planet($object)

?(DockedTo, $object) 为可选 term,$object 只有在它匹配到结果时才会被设置,因此 Planet($object) 只在停靠成功时求值。

查询作用域(Query scopes)

查询作用域可以把一个运算符应用于多个 term 的结果。目前查询作用域仅支持与 not 运算符组合使用。作用域用 !{ } 包裹:

// Match spaceships where none of the engines are healthy
SpaceShip, !{ (Engine, $engine), Healthy($engine) }

这条查询匹配「没有任何引擎健康」的飞船:作用域内的 (Engine, $engine) 与 Healthy($engine) 必须同时为真(AND 组合),再被外层 ! 取反。

// Match spaceships where all of the engines are healthy
SpaceShip, !{ (Engine, $engine), !Healthy($engine) }

这条查询匹配「所有引擎都健康」的飞船:作用域内先对「引擎不健康」取反,整体再取反,等价于「不存在不健康的引擎」。

在代码中使用查询语言

C API

C API 中,只需在 ecs_query_desc_t 的 expr 字段填入查询表达式,然后调用 ecs_query_init 创建查询(声明见 flecs.h):

ecs_query_desc_t desc = {0};
desc.expr = "SpaceShip, (DockedTo, $planet), Planet($planet)";
ecs_query_t *q = ecs_query_init(world, &desc);

ecs_iter_t it = ecs_query_iter(world, q);
while (ecs_query_next(&it)) {
    // ...
}

ecs_query_iter 创建迭代器(flecs.h),ecs_query_next 反复推进迭代;对于通配符 term,用 ecs_field_id(&it, index) 取得实际匹配到的 id。相关查询 API 完整声明集中在 flecs.h 的 Queries 分组中。

C++ API

C++ 中既可以直接用 DSL 字符串构造查询,也可以用 builder 逐步声明:

flecs::query<> q = ecs.query_builder()
    .with<Eats>("$food")
    .with<Healthy>().src("$food")
    .build();

builder 方式与 DSL 表达式 Eats($this, $Food), Healthy($Food) 等价(完整代码见 variables/src/main.cpp)。通配符与 flecs::iter::id() 的使用可参考 wildcards/src/main.cpp——它在迭代中通过 it.pair(0).second() 取出 (Eats, *) 实际匹配到的食物。

功能开关与依赖

查询语言是 Flecs 查询体系的一部分,其运行依赖两个默认启用的 addon:

  • FLECS_CACHED_QUERIES:缓存查询支持;
  • FLECS_QUERY_PLANS:高级查询特性(运算符、关系、变量)——ecs_query_find_var 等变量 API 即处于该宏保护下(flecs.h)。

二者在 addon_defines.h 中默认定义。字符串表达式的解析则依赖 FLECS_QUERY_DSL(默认启用)。关于缓存、查询计划、分组、排序等查询特性的完整说明,见仓库内的 Queries.md 查询手册。

小结

Flecs Query Language 用一套紧凑而完整的语法覆盖了从「简单的组件匹配」到「跨图模式匹配」的全部需求:运算符(!、||、? 以及 and|/not|/or|)控制 term 的组合逻辑;访问修饰符控制数据访问权限;通配符(*、_)与变量($name)负责灵活地穷举或绑定匹配值;来源机制(静态、$this、变量)决定 term 在哪个实体上匹配;遍历修饰符(up、cascade、self 等)把层级与继承语义融入查询;等式、查找、成员匹配与查询作用域则进一步把查询推向图模式的深度匹配。这套语法既可以通过字符串在运行时动态生成(适合工具、Mod 与远程查询),也有 C/C++ builder API 提供编译期类型安全,是 Flecs 中 system、observer、序列化等上层功能共同的基石。

登录后查看全文
flecs