48. DECS、Daslang 实体组件系统

DECS 模块实现了 Daslang 实体组件系统的低级功能。

所有函数和符号都在 “decs” 模块中，使用 require 来访问它。

require daslib/decs

一般情况下，没有 boost 包的模块是不使用的:

require daslib/desc_boost

48.1. 类型别名

ComponentHash = uint64

ECS 组件类型的哈希值

TypeHash = uint64

单个类型的哈希值

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

Lambda 保存延迟作。通常是创建或销毁实体。

ComponentMap = array<ComponentValue>

单个实体的组件值表。

PassFunction = function<void>

构成 individual pass 的回调之一。

CTypeInfo

CTypeInfo 字段是

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

键入单个组件子类型的信息。 由类型名称和特定于类型的例程集合组成，用于在其生命周期、序列化等期间控制类型值。

Component

Component 字段是

name	string
hash	ComponentHash
stride	int
data	array<uint8>
info	decs::CTypeInfo
gc_dummy	lambda<>

单个 ECS 组件。包含组件名称、数据和数据布局。

EntityId

EntityId 字段是

id	uint
generation	int

实体的唯一标识符。由 id （数据数组中的索引） 和 generation 组成。

Archetype

Archetype 字段是

hash	ComponentHash
components	array< decs::Component >
size	int
eidIndex	int

ECS 原型。Archetype 是组件的独特组合。

ComponentValue

ComponentValue 字段是

name	string
info	decs::CTypeInfo
data	float4[4]

创建或转换期间组件的值。

EcsRequestPos

EcsRequestPos 字段是

file	string
line	uint

ECS 请求在代码中的位置（源文件和行号）。

EcsRequest

EcsRequest 字段是

hash	ComponentHash
req	array<string>
reqn	array<string>
archetypes	array<int>
at	decs::EcsRequestPos

单个 ESC 请求。包含必需组件列表、需要缺少的组件列表。 缓存与请求匹配的原型列表。

DecsState

DecsState 字段是

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>

ECS 系统的整个状态。 包括原型、实体和实体自由列表、实体 lokup 表、所有原型和原型查找等。

DecsPass

DecsPass 字段是

name	string
calls	array< PassFunction >

ECS 系统更新的单独通道。 包含通道名称和所有通道 calblack 的列表。

48.2. 比较和访问

• == (a:decs::EntityId const implicit;b:decs::EntityId const implicit) : bool

• != (a:decs::EntityId const implicit;b:decs::EntityId const implicit) : bool

• . (cmp:array<decs::ComponentValue> -const;name:string const) : decs::ComponentValue&

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

== returns bool

argument	argument type
a	decs::EntityId const implicit
b	decs::EntityId const implicit

实体 ID 的相等运算符。

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

!= returns bool

argument	argument type
a	decs::EntityId const implicit
b	decs::EntityId const implicit

实体 ID 的不等运算符。

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

. returns decs::ComponentValue &

argument	argument type
cmp	ComponentMap
name	string const

按名称访问组件值。例如:

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

48.3. 访问 (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:int 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 (arch:decs::Archetype const;name:string const) : bool

• has (cmp:array<decs::ComponentValue> -const;name:string const) : bool

• remove (cmp:array<decs::ComponentValue> -const;name:string const) : void

• set (cv:decs::ComponentValue -const;val:auto const) : auto

• 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	decs::ComponentValue
val	decs::EntityId const

克隆组件值。

clone(cv: ComponentValue; val: bool const)

argument	argument type
cv	decs::ComponentValue
val	bool const

克隆组件值。

clone(cv: ComponentValue; val: range const)

argument	argument type
cv	decs::ComponentValue
val	range const

克隆组件值。

clone(cv: ComponentValue; val: urange const)

argument	argument type
cv	decs::ComponentValue
val	urange const

克隆组件值。

clone(cv: ComponentValue; val: range64 const)

argument	argument type
cv	decs::ComponentValue
val	range64 const

克隆组件值。

clone(cv: ComponentValue; val: urange64 const)

argument	argument type
cv	decs::ComponentValue
val	urange64 const

克隆组件值。

clone(cv: ComponentValue; val: string const)

argument	argument type
cv	decs::ComponentValue
val	string const

克隆组件值。

clone(cv: ComponentValue; val: int const)

argument	argument type
cv	decs::ComponentValue
val	int const

克隆组件值。

clone(cv: ComponentValue; val: int8 const)

argument	argument type
cv	decs::ComponentValue
val	int8 const

克隆组件值。

clone(cv: ComponentValue; val: int16 const)

argument	argument type
cv	decs::ComponentValue
val	int16 const

克隆组件值。

clone(cv: ComponentValue; val: int64 const)

argument	argument type
cv	decs::ComponentValue
val	int64 const

克隆组件值。

clone(cv: ComponentValue; val: int2 const)

argument	argument type
cv	decs::ComponentValue
val	int2 const

克隆组件值。

clone(cv: ComponentValue; val: int3 const)

argument	argument type
cv	decs::ComponentValue
val	int3 const

克隆组件值。

clone(cv: ComponentValue; val: int4 const)

argument	argument type
cv	decs::ComponentValue
val	int4 const

克隆组件值。

clone(cv: ComponentValue; val: uint const)

argument	argument type
cv	decs::ComponentValue
val	uint const

克隆组件值。

clone(cv: ComponentValue; val: uint8 const)

argument	argument type
cv	decs::ComponentValue
val	uint8 const

克隆组件值。

clone(cv: ComponentValue; val: uint16 const)

argument	argument type
cv	decs::ComponentValue
val	uint16 const

克隆组件值。

clone(cv: ComponentValue; val: uint64 const)

argument	argument type
cv	decs::ComponentValue
val	uint64 const

克隆组件值。

clone(cv: ComponentValue; val: uint2 const)

argument	argument type
cv	decs::ComponentValue
val	uint2 const

克隆组件值。

clone(cv: ComponentValue; val: uint3 const)

argument	argument type
cv	decs::ComponentValue
val	uint3 const

克隆组件值。

clone(cv: ComponentValue; val: uint4 const)

argument	argument type
cv	decs::ComponentValue
val	uint4 const

克隆组件值。

clone(cv: ComponentValue; val: float const)

argument	argument type
cv	decs::ComponentValue
val	float const

克隆组件值。

clone(cv: ComponentValue; val: float2 const)

argument	argument type
cv	decs::ComponentValue
val	float2 const

克隆组件值。

clone(cv: ComponentValue; val: float3 const)

argument	argument type
cv	decs::ComponentValue
val	float3 const

克隆组件值。

clone(cv: ComponentValue; val: float4 const)

argument	argument type
cv	decs::ComponentValue
val	float4 const

克隆组件值。

clone(cv: ComponentValue; val: float3x3 const)

argument	argument type
cv	decs::ComponentValue
val	math::float3x3 const

克隆组件值。

clone(cv: ComponentValue; val: float3x4 const)

argument	argument type
cv	decs::ComponentValue
val	math::float3x4 const

克隆组件值。

clone(cv: ComponentValue; val: float4x4 const)

argument	argument type
cv	decs::ComponentValue
val	math::float4x4 const

克隆组件值。

clone(cv: ComponentValue; val: double const)

argument	argument type
cv	decs::ComponentValue
val	double const

克隆组件值。

clone(dst: Component; src: Component const)

argument	argument type
dst	decs::Component
src	decs::Component const

克隆组件值。

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

has returns bool

argument	argument type
arch	decs::Archetype const
name	string const

如果 object 指定了 subobjec，则返回 true。

has(cmp: ComponentMap; name: string const)

has returns bool

argument	argument type
cmp	ComponentMap
name	string const

如果 object 指定了 subobjec，则返回 true。

remove(cmp: ComponentMap; name: string const)

argument	argument type
cmp	ComponentMap
name	string const

从组件映射中删除特定值。

set(cv: ComponentValue; val: auto const)

set returns auto

argument	argument type
cv	decs::ComponentValue
val	auto const

设置由 name 和 type 指定的组件值。 如果 value 已存在，则将其覆盖。如果已经存在的值类型不相同 - 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

获取由 name 和 type 指定的组件值。 如果 name 匹配，但 type 不匹配，则会 panic。

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

get returns auto

argument	argument type
cmp	ComponentMap
name	string const
value	auto(TT)

获取由 name 和 type 指定的组件值。 如果 name 匹配，但 type 不匹配，则会 panic。

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

设置由 name 和 type 指定的组件值。 如果 value 已存在，则将其覆盖。如果已经存在的值类型不相同 - panic。 overwrite insert new one

48.4. Deubg 和序列化

• describe (info:decs::CTypeInfo const) : string

• serialize (arch:archive::Archive -const;src:decs::Component -const) : void

• finalize (cmp:decs::Component -const) : void

• debug_dump () : void

describe(info: CTypeInfo const)

describe returns string

argument	argument type
info	decs::CTypeInfo const

返回类型的文本说明。

serialize(arch: Archive; src: Component)

argument	argument type
arch	archive::Archive
src	decs::Component

序列化组件值。

finalize(cmp: Component)

argument	argument type
cmp	decs::Component

删除组件。

debug_dump()

打印出 ECS 系统的状态。 debug(arch)

48.5. Stages

• register_decs_stage_call (name:string const;pcall:function<void> const) : void

• decs_stage (name:string const) : void

• commit () : void

register_decs_stage_call(name: string const; pcall: PassFunction)

argument	argument type
name	string const
pcall	PassFunction

注册单个传递回调。这是一个低级函数，由 decs_boost 宏使用。 insert new one

decs_stage(name: string const)

argument	argument type
name	string const

调用特定的 ECS pass。 commit 在调用之前和之后调用。

commit()

完成所有延迟的作。

48.6. 延迟操作

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

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

• delete_entity (entityid:decs::EntityId const implicit) : void

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>

创建延迟作以更新由 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>

创建延迟作以创建实体。

delete_entity(entityid: EntityId const implicit)

argument	argument type
entityid	decs::EntityId const implicit

创建延迟作以删除由 id 指定的实体。

48.7. GC 和 reset

• restart () : void

• before_gc () : void

• after_gc () : void

restart()

通过擦除所有延迟的作和整个状态来重新启动 ECS。

before_gc()

在垃圾回收之前调用的低级回调。 这是 live 通常使用的低级函数。

after_gc()

在垃圾回收后调用的低级回调。 这是 live 通常使用的低级函数。

48.8. 迭代

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

• for_eid_archetype (eid:decs::EntityId const implicit;hash:uint64 const;erq:function<decs::EcsRequest> -const;blk:block<(arch:decs::Archetype const;index:int const):void> const) : bool const

• for_each_archetype (hash:uint64 const;erq:function<decs::EcsRequest> -const;blk:block<(arch:decs::Archetype const):void> const) : void

• for_each_archetype_find (hash:uint64 const;erq:function<decs::EcsRequest> -const;blk:block<(arch:decs::Archetype const):bool> const) : bool const

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

• get_ro (arch:decs::Archetype const;name:string const;value:auto(TT) const[]) : array<TT[-2] -const -& -#> const

• get_ro (arch:decs::Archetype const;name:string const;value:auto(TT) const) : array<TT -const -& -#> const

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

• get_optional (arch:decs::Archetype const;name:string const;value:auto(TT)? const) : iterator<TT -const -& -#?>

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

为请求可处理的每个原型的每个实体调用 block。 请求由指定的函数返回。

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

为给定请求的特定实体 ID 调用 block。 请求由指定的函数返回。

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

为请求可处理的每个原型的每个实体调用 block。 请求由指定的函数返回。

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

为请求可处理的每个原型的每个实体调用 block。 请求由指定的函数返回。 如果 block 返回 true，则停止迭代。 [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

低级函数返回给定特定类型组件的组件的临时数组。

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]

返回给定常规组件的特定名称和组件类型的组件的 const 临时数组。

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

返回给定常规组件的特定名称和组件类型的组件的 const 临时数组。

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

返回给定特定名称和组件类型的组件的 const 迭代器。 如果未找到 component - iterator 将 keepp 返回指定的值。

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

返回给定特定名称和组件类型的组件的 const 迭代器。 如果未找到 component - iterator 将 keepp 返回 component 类型的默认值。

48.9. Request

• EcsRequestPos (at:rtti::LineInfo const) : decs::EcsRequestPos

• verify_request (erq:decs::EcsRequest -const) : tuple<ok:bool;error:string>

• compile_request (erq:decs::EcsRequest -const) : void

• lookup_request (erq:decs::EcsRequest -const) : int

EcsRequestPos(at: LineInfo const)

EcsRequestPos returns decs::EcsRequestPos

argument	argument type
at	rtti::LineInfo const

从 rtti::LineInfo 构造 EcsRequestPos。

verify_request(erq: EcsRequest)

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

argument	argument type
erq	decs::EcsRequest

验证 ESC 请求。返回一对布尔值（true 表示正常）和错误消息。 这几乎查询了所有内容 假设 require_not 通常更短

compile_request(erq: EcsRequest)

argument	argument type
erq	decs::EcsRequest

通过创建请求哈希来编译 ESC 请求。

lookup_request(erq: EcsRequest)

lookup_request returns int

argument	argument type
erq	decs::EcsRequest

在请求缓存中查找 ESC 请求。