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.

CTypeInfo

CTypeInfo fields are

basicType

rtti::Type

mangledName

string

fullName

string

hash

TypeHash

size

uint

eraser

function<(arr:array<uint8>):void>

clonner

function<(dst:array<uint8>;src:array<uint8> const):void>

serializer

function<(arch: archive::Archive ;arr:array<uint8>;name:string const):void>

dumper

function<(elem:void? const):string>

mkTypeInfo

function<>

gc

function<(src:array<uint8>):lambda<>>

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.

Component

Component fields are

name

string

hash

ComponentHash

stride

int

data

array<uint8>

info

decs::CTypeInfo

gc_dummy

lambda<>

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

EntityId

EntityId fields are

id

uint

generation

int

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

Archetype

Archetype fields are

hash

ComponentHash

components

array< decs::Component >

size

int

eidIndex

int

ECS archetype. Archetype is unique combination of components.

ComponentValue

ComponentValue fields are

name

string

info

decs::CTypeInfo

data

float4[4]

Value of the component during creation or transformation.

EcsRequestPos

EcsRequestPos fields are

file

string

line

uint

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

EcsRequest

EcsRequest fields are

hash

ComponentHash

req

array<string>

reqn

array<string>

archetypes

array<int>

at

decs::EcsRequestPos

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.

DecsState

DecsState fields are

archetypeLookup

table< ComponentHash ;int>

allArchetypes

array< decs::Archetype >

entityFreeList

array< decs::EntityId >

entityLookup

array<tuple<generation:int;archetype: ComponentHash ;index:int>>

componentTypeCheck

table<string; decs::CTypeInfo >

ecsQueries

array< decs::EcsRequest >

queryLookup

table< ComponentHash ;int>

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

DecsPass

DecsPass fields are

name

string

calls

array< PassFunction >

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

48.2. Comparison and access

operator ==(a: EntityId const implicit; b: EntityId const implicit)

== returns bool

argument

argument type

a

decs::EntityId const implicit

b

decs::EntityId const implicit

Equality operator for entity IDs.

operator !=(a: EntityId const implicit; b: EntityId const implicit)

!= returns bool

argument

argument type

a

decs::EntityId const implicit

b

decs::EntityId const implicit

Inequality operator for entity IDs.

operator .(cmp: ComponentMap; name: string const)

. returns decs::ComponentValue &

argument

argument type

cmp

ComponentMap

name

string const

Access to component value by name. For example:

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

48.3. Access (get/set/clone)

clone(cv: ComponentValue; val: EntityId const)

argument

argument type

cv

decs::ComponentValue

val

decs::EntityId const

Clones component value.

clone(cv: ComponentValue; val: bool const)

argument

argument type

cv

decs::ComponentValue

val

bool const

Clones component value.

clone(cv: ComponentValue; val: range const)

argument

argument type

cv

decs::ComponentValue

val

range const

Clones component value.

clone(cv: ComponentValue; val: urange const)

argument

argument type

cv

decs::ComponentValue

val

urange const

Clones component value.

clone(cv: ComponentValue; val: range64 const)

argument

argument type

cv

decs::ComponentValue

val

range64 const

Clones component value.

clone(cv: ComponentValue; val: urange64 const)

argument

argument type

cv

decs::ComponentValue

val

urange64 const

Clones component value.

clone(cv: ComponentValue; val: string const)

argument

argument type

cv

decs::ComponentValue

val

string const

Clones component value.

clone(cv: ComponentValue; val: int const)

argument

argument type

cv

decs::ComponentValue

val

int const

Clones component value.

clone(cv: ComponentValue; val: int8 const)

argument

argument type

cv

decs::ComponentValue

val

int8 const

Clones component value.

clone(cv: ComponentValue; val: int16 const)

argument

argument type

cv

decs::ComponentValue

val

int16 const

Clones component value.

clone(cv: ComponentValue; val: int64 const)

argument

argument type

cv

decs::ComponentValue

val

int64 const

Clones component value.

clone(cv: ComponentValue; val: int2 const)

argument

argument type

cv

decs::ComponentValue

val

int2 const

Clones component value.

clone(cv: ComponentValue; val: int3 const)

argument

argument type

cv

decs::ComponentValue

val

int3 const

Clones component value.

clone(cv: ComponentValue; val: int4 const)

argument

argument type

cv

decs::ComponentValue

val

int4 const

Clones component value.

clone(cv: ComponentValue; val: uint const)

argument

argument type

cv

decs::ComponentValue

val

uint const

Clones component value.

clone(cv: ComponentValue; val: uint8 const)

argument

argument type

cv

decs::ComponentValue

val

uint8 const

Clones component value.

clone(cv: ComponentValue; val: uint16 const)

argument

argument type

cv

decs::ComponentValue

val

uint16 const

Clones component value.

clone(cv: ComponentValue; val: uint64 const)

argument

argument type

cv

decs::ComponentValue

val

uint64 const

Clones component value.

clone(cv: ComponentValue; val: uint2 const)

argument

argument type

cv

decs::ComponentValue

val

uint2 const

Clones component value.

clone(cv: ComponentValue; val: uint3 const)

argument

argument type

cv

decs::ComponentValue

val

uint3 const

Clones component value.

clone(cv: ComponentValue; val: uint4 const)

argument

argument type

cv

decs::ComponentValue

val

uint4 const

Clones component value.

clone(cv: ComponentValue; val: float const)

argument

argument type

cv

decs::ComponentValue

val

float const

Clones component value.

clone(cv: ComponentValue; val: float2 const)

argument

argument type

cv

decs::ComponentValue

val

float2 const

Clones component value.

clone(cv: ComponentValue; val: float3 const)

argument

argument type

cv

decs::ComponentValue

val

float3 const

Clones component value.

clone(cv: ComponentValue; val: float4 const)

argument

argument type

cv

decs::ComponentValue

val

float4 const

Clones component value.

clone(cv: ComponentValue; val: float3x3 const)

argument

argument type

cv

decs::ComponentValue

val

math::float3x3 const

Clones component value.

clone(cv: ComponentValue; val: float3x4 const)

argument

argument type

cv

decs::ComponentValue

val

math::float3x4 const

Clones component value.

clone(cv: ComponentValue; val: float4x4 const)

argument

argument type

cv

decs::ComponentValue

val

math::float4x4 const

Clones component value.

clone(cv: ComponentValue; val: double const)

argument

argument type

cv

decs::ComponentValue

val

double const

Clones component value.

clone(dst: Component; src: Component const)

argument

argument type

dst

decs::Component

src

decs::Component const

Clones component value.

has(arch: Archetype const; name: string const)

has returns bool

argument

argument type

arch

decs::Archetype const

name

string const

Returns true if object has specified subobjec.

has(cmp: ComponentMap; name: string const)

has returns bool

argument

argument type

cmp

ComponentMap

name

string const

Returns true if object has specified subobjec.

remove(cmp: ComponentMap; name: string const)

argument

argument type

cmp

ComponentMap

name

string const

Removes speicified value from the component map.

set(cv: ComponentValue; val: auto const)

set returns auto

argument

argument type

cv

decs::ComponentValue

val

auto const

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. overwrite insert new one

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

get returns auto

argument

argument type

arch

decs::Archetype const

name

string const

value

auto(TT) const

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

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

get returns auto

argument

argument type

cmp

ComponentMap

name

string const

value

auto(TT)

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

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

set returns auto

argument

argument type

cmp

ComponentMap

name

string const

value

auto(TT) const

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. overwrite insert new one

48.4. Deubg and serialization

describe(info: CTypeInfo const)

describe returns string

argument

argument type

info

decs::CTypeInfo const

Returns textual description of the type.

serialize(arch: Archive; src: Component)

argument

argument type

arch

archive::Archive

src

decs::Component

Serializes component value.

finalize(cmp: Component)

argument

argument type

cmp

decs::Component

Deletes component.

debug_dump()

Prints out state of the ECS system. debug(arch)

48.5. Stages

register_decs_stage_call(name: string const; pcall: PassFunction)

argument

argument type

name

string const

pcall

PassFunction

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

decs_stage(name: string const)

argument

argument type

name

string const

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

commit()

Finishes all deferred actions.

48.6. Deferred actions

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

argument

argument type

entityid

decs::EntityId const implicit

blk

lambda<(eid: decs::EntityId const;cmp: ComponentMap ):void>

Creates deferred action to update entity specified by id.

create_entity(blk: lambda<(eid:EntityId const;var cmp:array<ComponentValue>):void>)

create_entity returns decs::EntityId

argument

argument type

blk

lambda<(eid: decs::EntityId const;cmp: ComponentMap ):void>

Creates deferred action to create entity.

delete_entity(entityid: EntityId const implicit)

argument

argument type

entityid

decs::EntityId const implicit

Creates deferred action to delete entity specified by id.

48.7. 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.8. Iteration

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

argument

argument type

erq

decs::EcsRequest

blk

block<(arch: decs::Archetype const):void> const

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

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

for_eid_archetype returns bool const

argument

argument type

eid

decs::EntityId const implicit

hash

ComponentHash

erq

function<>

blk

block<(arch: decs::Archetype const;index:int const):void> const

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

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

argument

argument type

hash

ComponentHash

erq

function<>

blk

block<(arch: decs::Archetype const):void> const

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

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

for_each_archetype_find returns bool const

argument

argument type

hash

ComponentHash

erq

function<>

blk

block<(arch: decs::Archetype const):bool> const

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. [template(atype)]

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

decs_array returns auto

argument

argument type

atype

auto(TT) const

src

array<uint8> const

capacity

int const

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

get_ro(arch: Archetype const; name: string const; value: auto(TT) const[])

get_ro returns array<TT[-2]> const

argument

argument type

arch

decs::Archetype const

name

string const

value

auto(TT) const[-1]

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

get_ro(arch: Archetype const; name: string const; value: auto(TT) const)

get_ro returns array<TT> const

argument

argument type

arch

decs::Archetype const

name

string const

value

auto(TT) const

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

get_default_ro(arch: Archetype const; name: string const; value: auto(TT) const)

get_default_ro returns iterator<TT const&>

argument

argument type

arch

decs::Archetype const

name

string const

value

auto(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.

get_optional(arch: Archetype const; name: string const; value: auto(TT)? const)

get_optional returns iterator<TT?>

argument

argument type

arch

decs::Archetype const

name

string const

value

auto(TT)? const

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.

48.9. Request

EcsRequestPos(at: LineInfo const)

EcsRequestPos returns decs::EcsRequestPos

argument

argument type

at

rtti::LineInfo const

Constructs EcsRequestPos from rtti::LineInfo.

verify_request(erq: EcsRequest)

verify_request returns tuple<ok:bool;error:string>

argument

argument type

erq

decs::EcsRequest

Verifies ESC request. Returns pair of boolean (true for OK) and error message. this queries just about everything assuming require_not is typically shorter

compile_request(erq: EcsRequest)

argument

argument type

erq

decs::EcsRequest

Compiles ESC request, by creating request hash.

lookup_request(erq: EcsRequest)

lookup_request returns int

argument

argument type

erq

decs::EcsRequest

Looks up ESC request in the request cache.