48. Boost package for DECS

The DECS_BOOST module implements queries, stages, and templates for the DECS. Under normal circumstances this is the main require module for DECS.

All functions and symbols are in “decs_boost” module, use require to get access to it.

require daslib/desc_boost

48.1. Type aliases

ItCheck is a variant type

yes

string

no

bool

DECS prefix check.

48.2. Function annotations

REQUIRE

This annotation provides list of required components for entity.

REQUIRE_NOT

This annotation provides list of components, which are required to not be part of the entity.

decs

This macro converts a function into a DECS pass stage query. Possible arguments are stage, ‘REQUIRE’, and REQUIRE_NOT. It has all other properties of a query (like ability to operate on templates). For example:

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

In the example above a query is added to the update_ai stage. The query also requires that each entity passed to it has an ai_turret property.

48.3. Call macros

query
This macro implmenets ‘query` functionality. There are 2 types of queries:
  • query(…) - returns a list of entities matching the query

  • query(eid) - returns a single entity matching the eid

For example:

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

The query above will print all entities with position and velocity. Here is another example:

query(kaboom) <| $ ( var pos:float3&; vel:float3; col:uint=13u )
    pos += vel

The query above will add the velocity to the position of an entity with eid kaboom.

Query can have REQUIRE and REQUIRE_NOT clauses:

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

The query above will add pos components of all entities, which also have a tank component.

Additionally queries can atuomaticall expand components of entities. For example:

[decs_template(prefix="particle")]
struct Particle
    pos, vel : float3
...
query <| $ ( var q : Particle )
    q.pos += q.vel                  // this is actually particlepos += particlevel

In the example above structure q : Particle does not exist as a variable. Instead it is expanded into accessing individual componentes of the entity. REQURE section of the query is automatically filled with all components of the template. If template prefix is not specified, prefix is taken from the name of the template (would be “Particle_”). Specifying empty prefix [decs_template(prefix)] will result in no prefix beeing added.

Note: apart from tagging structure as a template, the macro also generates apply_decs_template and remove_decs_template functions. apply_decs_template is used to add template to an entity, and remove_decs_template is used to remove all components of the template from the entity:

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

This macro implmenets ‘find_query` functionality. It is similar to query in most ways, with the main differences being:

  • there is no eid-based find query

  • the find_query stops once the first match is found

For example:

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

In the example above the find_query will return true once the first intesection is found. Note: if return is missing, or end of find_query block is reached - its assumed that find_query did not find anything, and will return false.