49. 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
49.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.
49.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.