48. DECS, Daslang entity component system

The DECS module implements low level functionality of Daslang entity component system.

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

require daslib/decs

Under normal circumstances, the module is not used without the boost package:

require daslib/desc_boost

48.1. Type aliases

ComponentHash = uint64

Hash value of the ECS component type

TypeHash = uint64

Hash value of the individual type

DeferEval = lambda<(var act:DeferAction):void>

Lambda which holds deferred action. Typically creation of destruction of an entity.

ComponentMap = array<ComponentValue>

Table of component values for individual entity.

PassFunction = function<void>

One of the callbacks which form individual pass.

48.2. Constants

INVALID_ENTITY_ID = [[decs::EntityId ]]

Entity ID which represents invalid entity.

48.3. Structures

CTypeInfo

Type information for the individual component subtype. Consists of type name and collection of type-specific routines to control type values during its lifetime, serialization, etc.

Fields

  • basicType : Type - basic type of the component

  • mangledName : string - mangled name of the type

  • fullName : string - full name of the type

  • hash : TypeHash - hash of the type

  • size : uint - size of the type

  • eraser : function<(arr:array<uint8>):void> - function to erase component value

  • clonner : function<(dst:array<uint8>;src:array<uint8>):void> - function to clone component value

  • serializer : function<(arch: Archive ;arr:array<uint8>;name:string):void> - function to serialize component value

  • dumper : function<(elem:void?):string> - function to dump component value as text

  • mkTypeInfo : function<void> - function to make TypeInfo for the component type

  • gc : function<(src:array<uint8>):lambda<void>> - function to perform GC marking on the component value

Component

Single ECS component. Contains component name, data, and data layout.

Fields

  • name : string - name of the component

  • hash : ComponentHash - hash of the component

  • stride : int - stride of the component data

  • data : array<uint8> - raw data of the component

  • info : CTypeInfo - type information of the component

  • gc_dummy : lambda<void> - this is here so that GC can find real representation of data

EntityId
Fields

  • id : uint - Unique identifier of the entity. Consists of id (index in the data array) and generation.

  • generation : int - index of the entity

Archetype

ECS archetype. Archetype is unique combination of components.

Fields

  • hash : ComponentHash - hash of the archetype (combination of component hashes)

  • components : array< Component > - list of components in the archetype

  • size : int - number of entities in the archetype

  • eidIndex : int - index of the ‘eid’ component in the components array

ComponentValue

Value of the component during creation or transformation.

Fields

  • name : string - name of the component

  • info : CTypeInfo - type information of the component

  • data : float4[4] - raw data of the component

EcsRequestPos

Location of the ECS request in the code (source file and line number).

Fields

  • file : string - source file

  • line : uint - line number

EcsRequest

Individual ESC requests. Contains list of required components, list of components which are required to be absent. Caches list of archetypes, which match the request.

Fields

  • hash : ComponentHash - hash of the request

  • req : array<string> - required components

  • reqn : array<string> - required components which are not present

  • archetypes : array<int> - sorted list of matching archetypes

  • at : EcsRequestPos - location of the request in the code

DecsState

Entire state of the ECS system. Conntains archtypes, entities and entity free-list, entity lokup table, all archetypes and archetype lookups, etc.

Fields

  • archetypeLookup : table< ComponentHash ;int> - lookup of archetype by its hash

  • allArchetypes : array< Archetype > - all archetypes in the system

  • entityFreeList : array< EntityId > - list of free entity IDs

  • entityLookup : array<tuple<generation:int;archetype: ComponentHash ;index:int>> - lookup of entity by its ID

  • componentTypeCheck : table<string; CTypeInfo > - lookup of component type info by its name

  • ecsQueries : array< EcsRequest > - all ECS requests

  • queryLookup : table< ComponentHash ;int> - lookup of ECS request by its hash

DecsPass

Individual pass of the update of the ECS system. Contains pass name and list of all pass calblacks.

Fields

  • name : string - name of the pass

  • calls : array< PassFunction > - list of all pass callbacks

48.4. Comparison and access

EntityId implicit==(a: EntityId implicit; b: EntityId implicit) : bool()

Equality operator for entity IDs.

Arguments
EntityId implicit!=(a: EntityId implicit; b: EntityId implicit) : bool()

Inequality operator for entity IDs.

Arguments
ComponentMap.(cmp: ComponentMap; name: string) : ComponentValue&()

Access to component value by name. For example:

create_entity <| @ ( eid, cmp )
    cmp.pos := float3(i)    // same as cmp |> set("pos",float3(i))
Arguments

48.5. Access (get/set/clone)

clone(cv: ComponentValue; val: EntityId)

Sets individual component value. Verifies that the value is of the correct type.

Arguments
clone(cv: ComponentValue; val: bool)

Sets individual component value. Verifies that the value is of the correct type.

Arguments
clone(cv: ComponentValue; val: range)

Sets individual component value. Verifies that the value is of the correct type.

Arguments
clone(cv: ComponentValue; val: urange)

Sets individual component value. Verifies that the value is of the correct type.

Arguments
clone(cv: ComponentValue; val: range64)

Sets individual component value. Verifies that the value is of the correct type.

Arguments
clone(cv: ComponentValue; val: urange64)

Sets individual component value. Verifies that the value is of the correct type.

Arguments
clone(cv: ComponentValue; val: string)

Sets individual component value. Verifies that the value is of the correct type.

Arguments
clone(cv: ComponentValue; val: int)

Sets individual component value. Verifies that the value is of the correct type.

Arguments
clone(cv: ComponentValue; val: int8)

Sets individual component value. Verifies that the value is of the correct type.

Arguments
clone(cv: ComponentValue; val: int16)

Sets individual component value. Verifies that the value is of the correct type.

Arguments
clone(cv: ComponentValue; val: int64)

Sets individual component value. Verifies that the value is of the correct type.

Arguments
clone(cv: ComponentValue; val: int2)

Sets individual component value. Verifies that the value is of the correct type.

Arguments
clone(cv: ComponentValue; val: int3)

Sets individual component value. Verifies that the value is of the correct type.

Arguments
clone(cv: ComponentValue; val: int4)

Sets individual component value. Verifies that the value is of the correct type.

Arguments
clone(cv: ComponentValue; val: uint)

Sets individual component value. Verifies that the value is of the correct type.

Arguments
clone(cv: ComponentValue; val: uint8)

Sets individual component value. Verifies that the value is of the correct type.

Arguments
clone(cv: ComponentValue; val: uint16)

Sets individual component value. Verifies that the value is of the correct type.

Arguments
clone(cv: ComponentValue; val: uint64)

Sets individual component value. Verifies that the value is of the correct type.

Arguments
clone(cv: ComponentValue; val: uint2)

Sets individual component value. Verifies that the value is of the correct type.

Arguments
clone(cv: ComponentValue; val: uint3)

Sets individual component value. Verifies that the value is of the correct type.

Arguments
clone(cv: ComponentValue; val: uint4)

Sets individual component value. Verifies that the value is of the correct type.

Arguments
clone(cv: ComponentValue; val: float)

Sets individual component value. Verifies that the value is of the correct type.

Arguments
clone(cv: ComponentValue; val: float2)

Sets individual component value. Verifies that the value is of the correct type.

Arguments
clone(cv: ComponentValue; val: float3)

Sets individual component value. Verifies that the value is of the correct type.

Arguments
clone(cv: ComponentValue; val: float4)

Sets individual component value. Verifies that the value is of the correct type.

Arguments
clone(cv: ComponentValue; val: float3x3)

Sets individual component value. Verifies that the value is of the correct type.

Arguments
clone(cv: ComponentValue; val: float3x4)

Sets individual component value. Verifies that the value is of the correct type.

Arguments
clone(cv: ComponentValue; val: float4x4)

Sets individual component value. Verifies that the value is of the correct type.

Arguments
clone(cv: ComponentValue; val: double)

Sets individual component value. Verifies that the value is of the correct type.

Arguments
clone(dst: Component; src: Component)

Clones component value.

Arguments
has(arch: Archetype; name: string) : bool()

Returns true if object has specified subobjec.

Arguments
has(cmp: ComponentMap; name: string) : bool()

Returns true if component map has specified component.

Arguments
remove(cmp: ComponentMap; name: string)

Removes speicified value from the component map.

Arguments
set(cv: ComponentValue; val: auto) : auto()

Sets individual component value. Verifies that the value is of the correct type.

Arguments
get(arch: Archetype; name: string; value: auto(TT)) : auto()

Creates temporary array of component given specific name and type of component. If component is not found - panic.

Arguments

  • arch : Archetype

  • name : string

  • value : auto(TT)

get(cmp: ComponentMap; name: string; value: auto(TT)) : auto()

Gets component value specified by name and type. Will panic if name matches but type does not.

Arguments
set(cmp: ComponentMap; name: string; value: auto(TT)) : auto()

Set component value specified by name and type. If value already exists, it is overwritten. If already existing value type is not the same - panic.

Arguments

48.6. Deubg and serialization

describe(info: CTypeInfo) : string()

Returns textual description of the type.

Arguments
serialize(arch: Archive; src: Component)

Serializes component value.

Arguments
finalize(cmp: Component)

Deletes component.

Arguments
debug_dump()

Prints out state of the ECS system.

48.7. Stages

register_decs_stage_call(name: string; pcall: PassFunction)

Registration of a single pass callback. This is a low-level function, used by decs_boost macros.

Arguments
decs_stage(name: string)

Invokes specific ECS pass. commit is called before and after the invocation.

Arguments

  • name : string

commit()

Finishes all deferred actions.

48.8. Deferred actions

update_entity(entityid: EntityId implicit; blk: lambda<(eid:EntityId;var cmp:ComponentMap):void>)

Creates deferred action to update entity specified by id.

Arguments
create_entity(blk: lambda<(eid:EntityId;var cmp:ComponentMap):void>) : EntityId()

Creates deferred action to create entity.

Arguments
delete_entity(entityid: EntityId implicit)

Creates deferred action to delete entity specified by id.

Arguments

48.9. GC and reset

restart()

Restarts ECS by erasing all deferred actions and entire state.

before_gc()

Low level callback to be called before the garbage collection. This is a low-level function typically used by live.

after_gc()

Low level callback to be called after the garbage collection. This is a low-level function typically used by live.

48.10. Iteration

for_each_archetype(erq: EcsRequest; blk: block<(arch:Archetype):void>)

Invokes block for each entity of each archetype that can be processed by the request.

Arguments
for_eid_archetype(eid: EntityId implicit; hash: ComponentHash; erq: function<():void>; blk: block<(arch:Archetype;index:int):void>) : bool()

Invokes block for the specific entity id, given request. Request is returned by a specified function.

Arguments
for_each_archetype(hash: ComponentHash; erq: function<():void>; blk: block<(arch:Archetype):void>)

Invokes block for each entity of each archetype that can be processed by the request. Request is returned by a specified function.

Arguments
for_each_archetype_find(hash: ComponentHash; erq: function<():void>; blk: block<(arch:Archetype):bool>) : bool()

Invokes block for each entity of each archetype that can be processed by the request. Request is returned by a specified function. If block returns true, iteration is stopped.

Arguments
decs_array(atype: auto(TT); src: array<uint8>; capacity: int) : auto()

Low level function returns temporary array of component given specific type of component.

Arguments

  • atype : auto(TT)

  • src : array<uint8>

  • capacity : int

get_ro(arch: Archetype; name: string; value: auto(TT)[]) : array<TT[-2]>()

Returns const temporary array of component given specific name and type of component for array components.

Arguments

  • arch : Archetype

  • name : string

  • value : auto(TT)[-1]

get_ro(arch: Archetype; name: string; value: auto(TT)) : array<TT>()

Returns const temporary array of component given specific name and type of component for regular components.

Arguments

  • arch : Archetype

  • name : string

  • value : auto(TT)

get_default_ro(arch: Archetype; name: string; value: auto(TT)) : iterator<TT const&>()

Returns const iterator of component given specific name and type of component. If component is not found - iterator will kepp returning the specified value.

Arguments

  • arch : Archetype

  • name : string

  • value : auto(TT)

get_optional(arch: Archetype; name: string; value: auto(TT)?) : iterator<TT?>()

Returns const iterator of component given specific name and type of component. If component is not found - iterator will kepp returning default value for the component type.

Arguments

  • arch : Archetype

  • name : string

  • value : auto(TT)?

48.11. Request

EcsRequestPos(at: LineInfo) : EcsRequestPos()

Constructs EcsRequestPos from rtti::LineInfo.

Arguments
verify_request(erq: EcsRequest) : tuple<ok:bool;error:string>()

Verifies ESC request. Returns pair of boolean (true for OK) and error message.

Arguments
compile_request(erq: EcsRequest)

Compiles ESC request, by creating request hash.

Arguments
lookup_request(erq: EcsRequest) : int()

Looks up ESC request in the request cache.

Arguments