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 |
|
mangledName |
string |
fullName |
string |
hash |
|
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>):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 |
|
stride |
int |
data |
array<uint8> |
info |
|
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 |
|
components |
array< decs::Component > |
size |
int |
eidIndex |
int |
ECS archetype. Archetype is unique combination of components.
-
ComponentValue
¶
ComponentValue fields are
name |
string |
info |
|
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 |
|
req |
array<string> |
reqn |
array<string> |
archetypes |
array<int> |
at |
|
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 |
|
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:decs::ComponentValue -const;val:decs::EntityId const) : void
clone (cv:decs::ComponentValue -const;val:bool const) : void
clone (cv:decs::ComponentValue -const;val:range const) : void
clone (cv:decs::ComponentValue -const;val:urange const) : void
clone (cv:decs::ComponentValue -const;val:range64 const) : void
clone (cv:decs::ComponentValue -const;val:urange64 const) : void
clone (cv:decs::ComponentValue -const;val:string const) : void
clone (cv:decs::ComponentValue -const;val:int8 const) : void
clone (cv:decs::ComponentValue -const;val:int16 const) : void
clone (cv:decs::ComponentValue -const;val:int64 const) : void
clone (cv:decs::ComponentValue -const;val:int2 const) : void
clone (cv:decs::ComponentValue -const;val:int3 const) : void
clone (cv:decs::ComponentValue -const;val:int4 const) : void
clone (cv:decs::ComponentValue -const;val:uint const) : void
clone (cv:decs::ComponentValue -const;val:uint8 const) : void
clone (cv:decs::ComponentValue -const;val:uint16 const) : void
clone (cv:decs::ComponentValue -const;val:uint64 const) : void
clone (cv:decs::ComponentValue -const;val:uint2 const) : void
clone (cv:decs::ComponentValue -const;val:uint3 const) : void
clone (cv:decs::ComponentValue -const;val:uint4 const) : void
clone (cv:decs::ComponentValue -const;val:float const) : void
clone (cv:decs::ComponentValue -const;val:float2 const) : void
clone (cv:decs::ComponentValue -const;val:float3 const) : void
clone (cv:decs::ComponentValue -const;val:float4 const) : void
clone (cv:decs::ComponentValue -const;val:math::float3x3 const) : void
clone (cv:decs::ComponentValue -const;val:math::float3x4 const) : void
clone (cv:decs::ComponentValue -const;val:math::float4x4 const) : void
clone (cv:decs::ComponentValue -const;val:double const) : void
clone (dst:decs::Component -const;src:decs::Component const) : void
has (cmp:array<decs::ComponentValue> -const;name:string const) : bool
remove (cmp:array<decs::ComponentValue> -const;name:string const) : void
get (arch:decs::Archetype const;name:string const;value:auto(TT) const) : auto
get (cmp:array<decs::ComponentValue> -const;name:string const;value:auto(TT) -const) : auto
set (cmp:array<decs::ComponentValue> -const;name:string const;value:auto(TT) const) : auto
-
clone
(cv: ComponentValue; val: EntityId const)¶
argument |
argument type |
---|---|
cv |
|
val |
decs::EntityId const |
Clones component value.
-
clone
(cv: ComponentValue; val: bool const)
argument |
argument type |
---|---|
cv |
|
val |
bool const |
Clones component value.
-
clone
(cv: ComponentValue; val: range const)
argument |
argument type |
---|---|
cv |
|
val |
range const |
Clones component value.
-
clone
(cv: ComponentValue; val: urange const)
argument |
argument type |
---|---|
cv |
|
val |
urange const |
Clones component value.
-
clone
(cv: ComponentValue; val: range64 const)
argument |
argument type |
---|---|
cv |
|
val |
range64 const |
Clones component value.
-
clone
(cv: ComponentValue; val: urange64 const)
argument |
argument type |
---|---|
cv |
|
val |
urange64 const |
Clones component value.
-
clone
(cv: ComponentValue; val: string const)
argument |
argument type |
---|---|
cv |
|
val |
string const |
Clones component value.
-
clone
(cv: ComponentValue; val: int const)
argument |
argument type |
---|---|
cv |
|
val |
int const |
Clones component value.
-
clone
(cv: ComponentValue; val: int8 const)
argument |
argument type |
---|---|
cv |
|
val |
int8 const |
Clones component value.
-
clone
(cv: ComponentValue; val: int16 const)
argument |
argument type |
---|---|
cv |
|
val |
int16 const |
Clones component value.
-
clone
(cv: ComponentValue; val: int64 const)
argument |
argument type |
---|---|
cv |
|
val |
int64 const |
Clones component value.
-
clone
(cv: ComponentValue; val: int2 const)
argument |
argument type |
---|---|
cv |
|
val |
int2 const |
Clones component value.
-
clone
(cv: ComponentValue; val: int3 const)
argument |
argument type |
---|---|
cv |
|
val |
int3 const |
Clones component value.
-
clone
(cv: ComponentValue; val: int4 const)
argument |
argument type |
---|---|
cv |
|
val |
int4 const |
Clones component value.
-
clone
(cv: ComponentValue; val: uint const)
argument |
argument type |
---|---|
cv |
|
val |
uint const |
Clones component value.
-
clone
(cv: ComponentValue; val: uint8 const)
argument |
argument type |
---|---|
cv |
|
val |
uint8 const |
Clones component value.
-
clone
(cv: ComponentValue; val: uint16 const)
argument |
argument type |
---|---|
cv |
|
val |
uint16 const |
Clones component value.
-
clone
(cv: ComponentValue; val: uint64 const)
argument |
argument type |
---|---|
cv |
|
val |
uint64 const |
Clones component value.
-
clone
(cv: ComponentValue; val: uint2 const)
argument |
argument type |
---|---|
cv |
|
val |
uint2 const |
Clones component value.
-
clone
(cv: ComponentValue; val: uint3 const)
argument |
argument type |
---|---|
cv |
|
val |
uint3 const |
Clones component value.
-
clone
(cv: ComponentValue; val: uint4 const)
argument |
argument type |
---|---|
cv |
|
val |
uint4 const |
Clones component value.
-
clone
(cv: ComponentValue; val: float const)
argument |
argument type |
---|---|
cv |
|
val |
float const |
Clones component value.
-
clone
(cv: ComponentValue; val: float2 const)
argument |
argument type |
---|---|
cv |
|
val |
float2 const |
Clones component value.
-
clone
(cv: ComponentValue; val: float3 const)
argument |
argument type |
---|---|
cv |
|
val |
float3 const |
Clones component value.
-
clone
(cv: ComponentValue; val: float4 const)
argument |
argument type |
---|---|
cv |
|
val |
float4 const |
Clones component value.
-
clone
(cv: ComponentValue; val: float3x3 const)
argument |
argument type |
---|---|
cv |
|
val |
math::float3x3 const |
Clones component value.
-
clone
(cv: ComponentValue; val: float3x4 const)
argument |
argument type |
---|---|
cv |
|
val |
math::float3x4 const |
Clones component value.
-
clone
(cv: ComponentValue; val: float4x4 const)
argument |
argument type |
---|---|
cv |
|
val |
math::float4x4 const |
Clones component value.
-
clone
(cv: ComponentValue; val: double const)
argument |
argument type |
---|---|
cv |
|
val |
double const |
Clones component value.
-
clone
(dst: Component; src: Component const)
argument |
argument type |
---|---|
dst |
|
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 |
|
name |
string const |
Returns true if object has specified subobjec.
-
remove
(cmp: ComponentMap; name: string const)¶
argument |
argument type |
---|---|
cmp |
|
name |
string const |
Removes speicified value from the component map.
-
set
(cv: ComponentValue; val: auto const)¶
set returns auto
argument |
argument type |
---|---|
cv |
|
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.
-
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 |
|
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 |
|
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.
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 |
|
src |
|
Serializes component value.
-
finalize
(cmp: Component)¶
argument |
argument type |
---|---|
cmp |
|
Deletes component.
-
debug_dump
()¶
Prints out state of the ECS system.
48.5. Stages¶
-
register_decs_stage_call
(name: string const; pcall: PassFunction)¶
argument |
argument type |
---|---|
name |
string const |
pcall |
|
Registration of a single pass callback. This is a low-level function, used by decs_boost macros.
-
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 |
|
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 |
|
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 |
|
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 |
|
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.
-
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 |
|
Verifies ESC request. Returns pair of boolean (true for OK) and error message.
-
compile_request
(erq: EcsRequest)¶
argument |
argument type |
---|---|
erq |
|
Compiles ESC request, by creating request hash.
-
lookup_request
(erq: EcsRequest)¶
lookup_request returns int
argument |
argument type |
---|---|
erq |
|
Looks up ESC request in the request cache.