.. _stdlib_decs_boost:

======================
用于 DECS 的 Boost 包
======================

.. include:: detail/decs_boost.rst

DECS_BOOST 模块实现 DECS 的查询、阶段和模板。
在正常情况下，这是 DECS 的主要 require 模块。

所有函数和符号都在 “decs_boost” 模块中，使用 require 来访问它。 ::

    require daslib/desc_boost


++++++++++++
类型别名
++++++++++++

.. _alias-ItCheck:

.. das:attribute:: ItCheck is a variant type

+---+------+
+yes+string+
+---+------+
+no +bool  +
+---+------+


DECS 前缀检查。

++++++++++++++++++++
函数注释
++++++++++++++++++++

.. _handle-decs_boost-REQUIRE:

.. das:attribute:: REQUIRE

此注释提供了实体所需的组件列表。

.. _handle-decs_boost-REQUIRE_NOT:

.. das:attribute:: REQUIRE_NOT

此注释提供了组件列表，这些组件不需要属于实体。

.. _handle-decs_boost-decs:

.. das:attribute:: decs

此宏将函数转换为 DECS pass 阶段查询。可能的参数是 `stage`, 'REQUIRE', 和 `REQUIRE_NOT`。
它具有 `query` 的所有其他属性（例如对模板进行作的能力）。例如::

    [decs(stage=update_ai, REQUIRE=ai_turret)]
        def update_ai ( eid:EntityId; var turret:Turret; pos:float3 )
            ...

在上面的示例中，查询被添加到 `update_ai` 阶段。该查询还要求传递给它的每个实体都有一个 `ai_turret` 属性。

+++++++++++
调用宏
+++++++++++

.. _call-macro-decs_boost-query:

.. das:attribute:: query

此宏实现 `query` 功能。有 2 种类型的查询：
    * query(...) - 返回与查询匹配的实体列表
    * query(eid) - 返回与 eid 匹配的单个实体
例如::

    query() <| $ ( eid:EntityId; pos, vel : float3 )
        print("[{eid}] pos={pos} vel={vel}\n")

上面的查询将打印所有具有 position 和 velocity 的实体。
这是另一个例子::

    query(kaboom) <| $ ( var pos:float3&; vel:float3; col:uint=13u )
        pos += vel
上面的查询会将速度添加到具有 eid kaboom 的实体的位置。

查询可以有 `REQUIRE` 和 `REQUIRE_NOT` 子句::

    var average : float3
    query <| $ [REQUIRE(tank)] ( pos:float3 )
        average += pos

上面的查询将添加所有实体的 `pos` 组件，这些实体也有一个 `tank` 组件。

此外，查询可以扩展实体的组件。例如::

    [decs_template(prefix="particle")]
    struct Particle
        pos, vel : float3
    ...
    query <| $ ( var q : Particle )
        q.pos += q.vel                  // 这实际上是 particlepos += particlevel


在上面的示例中，结构 q ： Particle 不作为变量存在。相反，它被扩展为访问实体的各个组件。
REQURE 部分会自动填充模板的所有组件。
如果未指定 template prefix，则 prefix 取自模板的名称（将为 “Particle_”）。
指定空前缀 `[decs_template(prefix)]` 将导致不添加前缀。

注意：除了将 structure 标记为模板外，该宏还会生成 `apply_decs_template` 和 `remove_decs_template` 函数。
`apply_decs_template` 用于将模板添加到实体，`remove_decs_template` 用于从实体中删除模板的所有组件：

    for i in range(3)
        create_entity <| @ ( eid, cmp )
            apply_decs_template(cmp, [[Particle pos=float3(i), vel=float3(i+1)]])

.. _call-macro-decs_boost-find_query:

.. das:attribute:: find_query

此宏实现 `find_query` 功能。
它在大多数方面类似于 `query`，主要区别在于：
    * 没有基于 EID 的 FIND 查询
    * 找到第一个匹配项后，find_query停止
例如::

    let found = find_query <| $ ( pos,dim:float3; obstacle:Obstacle )
    if !obstacle.wall
        return false
    let aabb = [[AABB min=pos-dim*0.5, max=pos+dim*0.5 ]]
    if is_intersecting(ray, aabb, 0.1, dist)
        return true

在上面的示例中，一旦找到第一个外find_query，它将返回 `true`。
注意：如果缺少 return 或到达 find_query 块的末尾 - 则假定 find_query 没有找到任何内容，并将返回 false。

++++++++++++++++
结构宏
++++++++++++++++

.. _handle-decs_boost-decs_template:

.. das:attribute:: decs_template

此宏为给定结构创建模板。
为结构类型生成 `apply_decs_template` 和 `remove_decs_template` 函数。