.. _stdlib_decs:

=====================================
DECS, Daslang entity component system
=====================================

.. das:module:: decs

The DECS module implements a Data-oriented Entity Component System.
Entities are identified by integer IDs and store components as typed data.
Systems query and process entities by their component signatures,
enabling cache-friendly batch processing of game objects.

See :ref:`tutorial_decs` for a hands-on tutorial.

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

.. code-block:: das

    require daslib/decs



++++++++++++
Type aliases
++++++++++++

.. _alias-ComponentHash:

.. das:attribute:: ComponentHash = uint64

daslang Entity Component System (DECS).

A pure-daslang ECS runtime: entities with dynamic component
composition, archetypal storage, queries, commit/deferred
create/delete, and serialization. Use with ``decs_boost`` for
the query macro syntax.
Hash value of the ECS component type


.. _alias-TypeHash:

.. das:attribute:: TypeHash = uint64

Hash value of the individual type


.. _alias-DeferEval:

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

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


.. _alias-ComponentMap:

.. das:attribute:: ComponentMap = array<ComponentValue>

Table of component values for individual entity.


.. _alias-PassFunction:

.. das:attribute:: PassFunction = function<void>

One of the callbacks which form individual pass.



+++++++++
Constants
+++++++++

.. _global-decs-INVALID_ENTITY_ID:

.. das:attribute:: INVALID_ENTITY_ID = struct<decs::EntityId>(uninitialized )

INVALID_ENTITY_ID:decs::EntityId const


++++++++++
Structures
++++++++++

.. _struct-decs-CTypeInfo:

.. das:attribute:: 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** :  :ref:`Type <enum-rtti-Type>` - basic type of the component

         * **mangledName** : string - mangled name of the type

         * **fullName** : string - full name of the type

         * **hash** :  :ref:`TypeHash <alias-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: :ref:`Archive <struct-archive-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



.. _struct-decs-Component:

.. das:attribute:: Component

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

:Fields: * **name** : string - name of the component

         * **hash** :  :ref:`ComponentHash <alias-ComponentHash>` - hash of the component

         * **stride** : int - stride of the component data

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

         * **info** :  :ref:`CTypeInfo <struct-decs-CTypeInfo>` - type information of the component

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



.. _struct-decs-EntityId:

.. das:attribute:: 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



.. _struct-decs-Archetype:

.. das:attribute:: Archetype

ECS archetype. Archetype is unique combination of components.

:Fields: * **hash** :  :ref:`ComponentHash <alias-ComponentHash>` - hash of the archetype (combination of component hashes)

         * **components** : array< :ref:`Component <struct-decs-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



.. _struct-decs-ComponentValue:

.. das:attribute:: ComponentValue

Value of the component during creation or transformation.

:Fields: * **name** : string - name of the component

         * **info** :  :ref:`CTypeInfo <struct-decs-CTypeInfo>` - type information of the component

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



.. _struct-decs-EcsRequestPos:

.. das:attribute:: EcsRequestPos

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

:Fields: * **file** : string - source file

         * **line** : uint - line number



.. _struct-decs-EcsRequest:

.. das:attribute:: EcsRequest

Individual ECS 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** :  :ref:`ComponentHash <alias-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** :  :ref:`EcsRequestPos <struct-decs-EcsRequestPos>` - location of the request in the code



.. _struct-decs-DecsState:

.. das:attribute:: DecsState

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

:Fields: * **archetypeLookup** : table< :ref:`ComponentHash <alias-ComponentHash>`;int> - lookup of archetype by its hash

         * **allArchetypes** : array< :ref:`Archetype <struct-decs-Archetype>`> - all archetypes in the system

         * **entityFreeList** : array< :ref:`EntityId <struct-decs-EntityId>`> - list of free entity IDs

         * **entityLookup** : array<tuple<generation:int;archetype: :ref:`ComponentHash <alias-ComponentHash>`;index:int>> - lookup of entity by its ID

         * **componentTypeCheck** : table<string; :ref:`CTypeInfo <struct-decs-CTypeInfo>`> - lookup of component type info by its name

         * **ecsQueries** : array< :ref:`EcsRequest <struct-decs-EcsRequest>`> - all ECS requests

         * **queryLookup** : table< :ref:`ComponentHash <alias-ComponentHash>`;int> - lookup of ECS request by its hash



.. _struct-decs-DecsPass:

.. das:attribute:: DecsPass

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

:Fields: * **name** : string - name of the pass

         * **calls** : array< :ref:`PassFunction <alias-PassFunction>`> - list of all pass callbacks




+++++++++++++++++++++
Comparison and access
+++++++++++++++++++++

  *  :ref:`ComponentMap. (var cmp: ComponentMap; name: string) : ComponentValue& <function-decs__dot__ComponentMap_string>`
  *  :ref:`EntityId\!= (a: EntityId; b: EntityId) : bool <function-decs__ex__eq__EntityId_EntityId>`
  *  :ref:`EntityId== (a: EntityId; b: EntityId) : bool <function-decs__eq__eq__EntityId_EntityId>`

.. _function-decs__dot__ComponentMap_string:

.. das:function:: 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: * **cmp** :  :ref:`ComponentMap <alias-ComponentMap>`

            * **name** : string

.. _function-decs__ex__eq__EntityId_EntityId:

.. das:function:: EntityId!=(a: EntityId; b: EntityId) : bool

Inequality operator for entity IDs.


:Arguments: * **a** :  :ref:`EntityId <struct-decs-EntityId>` implicit

            * **b** :  :ref:`EntityId <struct-decs-EntityId>` implicit

.. _function-decs__eq__eq__EntityId_EntityId:

.. das:function:: EntityId==(a: EntityId; b: EntityId) : bool

Equality operator for entity IDs.


:Arguments: * **a** :  :ref:`EntityId <struct-decs-EntityId>` implicit

            * **b** :  :ref:`EntityId <struct-decs-EntityId>` implicit


++++++++++++++++++++++
Access (get/set/clone)
++++++++++++++++++++++

  *  :ref:`clone (var cv: ComponentValue; val: bool) <function-decs_clone_ComponentValue_bool>`
  *  :ref:`clone (var cv: ComponentValue; val: EntityId) <function-decs_clone_ComponentValue_EntityId>`
  *  :ref:`clone (var cv: ComponentValue; val: urange) <function-decs_clone_ComponentValue_urange>`
  *  :ref:`clone (var cv: ComponentValue; val: range) <function-decs_clone_ComponentValue_range>`
  *  :ref:`clone (var cv: ComponentValue; val: string) <function-decs_clone_ComponentValue_string>`
  *  :ref:`clone (var cv: ComponentValue; val: urange64) <function-decs_clone_ComponentValue_urange64>`
  *  :ref:`clone (var cv: ComponentValue; val: int) <function-decs_clone_ComponentValue_int>`
  *  :ref:`clone (var cv: ComponentValue; val: range64) <function-decs_clone_ComponentValue_range64>`
  *  :ref:`clone (var cv: ComponentValue; val: int64) <function-decs_clone_ComponentValue_int64>`
  *  :ref:`clone (var cv: ComponentValue; val: int16) <function-decs_clone_ComponentValue_int16>`
  *  :ref:`clone (var cv: ComponentValue; val: int2) <function-decs_clone_ComponentValue_int2>`
  *  :ref:`clone (var cv: ComponentValue; val: int3) <function-decs_clone_ComponentValue_int3>`
  *  :ref:`clone (var cv: ComponentValue; val: int4) <function-decs_clone_ComponentValue_int4>`
  *  :ref:`clone (var cv: ComponentValue; val: int8) <function-decs_clone_ComponentValue_int8>`
  *  :ref:`clone (var cv: ComponentValue; val: uint16) <function-decs_clone_ComponentValue_uint16>`
  *  :ref:`clone (var cv: ComponentValue; val: uint8) <function-decs_clone_ComponentValue_uint8>`
  *  :ref:`clone (var cv: ComponentValue; val: uint64) <function-decs_clone_ComponentValue_uint64>`
  *  :ref:`clone (var cv: ComponentValue; val: uint2) <function-decs_clone_ComponentValue_uint2>`
  *  :ref:`clone (var cv: ComponentValue; val: uint3) <function-decs_clone_ComponentValue_uint3>`
  *  :ref:`clone (var cv: ComponentValue; val: float) <function-decs_clone_ComponentValue_float>`
  *  :ref:`clone (var cv: ComponentValue; val: uint4) <function-decs_clone_ComponentValue_uint4>`
  *  :ref:`clone (var cv: ComponentValue; val: float2) <function-decs_clone_ComponentValue_float2>`
  *  :ref:`clone (var cv: ComponentValue; val: float3) <function-decs_clone_ComponentValue_float3>`
  *  :ref:`clone (var cv: ComponentValue; val: uint) <function-decs_clone_ComponentValue_uint>`
  *  :ref:`clone (var cv: ComponentValue; val: float3x4) <function-decs_clone_ComponentValue_float3x4>`
  *  :ref:`clone (var cv: ComponentValue; val: float3x3) <function-decs_clone_ComponentValue_float3x3>`
  *  :ref:`clone (var cv: ComponentValue; val: float4x4) <function-decs_clone_ComponentValue_float4x4>`
  *  :ref:`clone (var cv: ComponentValue; val: double) <function-decs_clone_ComponentValue_double>`
  *  :ref:`clone (var dst: Component; src: Component) <function-decs_clone_Component_Component>`
  *  :ref:`clone (var cv: ComponentValue; val: float4) <function-decs_clone_ComponentValue_float4>`
  *  :ref:`find_component_index (arch: Archetype; name: string) : int <function-decs_find_component_index_Archetype_string>`
  *  :ref:`get (var cmp: ComponentMap; name: string; var value: auto(TT)) : auto <function-decs_get_ComponentMap_string_autoTT_0x46a>`
  *  :ref:`get (arch: Archetype; name: string; value: auto(TT)) : auto <function-decs_get_Archetype_string_autoTT_0x2f8>`
  *  :ref:`get_component (eid: EntityId; name: string; defval: auto(TT)) : TT <function-decs_get_component_EntityId_string_autoTT_0x448>`
  *  :ref:`has (arch: Archetype; name: string) : bool <function-decs_has_Archetype_string>`
  *  :ref:`has (var cmp: ComponentMap; name: string) : bool <function-decs_has_ComponentMap_string>`
  *  :ref:`remove (var cmp: ComponentMap; name: string) <function-decs_remove_ComponentMap_string>`
  *  :ref:`set (var cv: ComponentValue; val: auto) : auto <function-decs_set_ComponentValue_auto_0xbc>`
  *  :ref:`set (var cmp: ComponentMap; name: string; value: auto(TT)) : auto <function-decs_set_ComponentMap_string_autoTT_0x53f>`
  *  :ref:`set_direct (var arch: Archetype; name: string; eidx: int; value: auto(TT)) : auto <function-decs_set_direct_Archetype_string_int_autoTT_0x563>`
  *  :ref:`set_direct_at (var arch: Archetype; comp_idx: int; eidx: int; value: auto(TT)) : auto <function-decs_set_direct_at_Archetype_int_int_autoTT_0x55b>`


clone
^^^^^

.. _function-decs_clone_ComponentValue_bool:

.. das:function:: clone(cv: ComponentValue; val: bool)

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


:Arguments: * **cv** :  :ref:`ComponentValue <struct-decs-ComponentValue>`

            * **val** : bool

.. _function-decs_clone_ComponentValue_EntityId:

.. das:function:: clone(cv: ComponentValue; val: EntityId)

.. _function-decs_clone_ComponentValue_urange:

.. das:function:: clone(cv: ComponentValue; val: urange)

.. _function-decs_clone_ComponentValue_range:

.. das:function:: clone(cv: ComponentValue; val: range)

.. _function-decs_clone_ComponentValue_string:

.. das:function:: clone(cv: ComponentValue; val: string)

.. _function-decs_clone_ComponentValue_urange64:

.. das:function:: clone(cv: ComponentValue; val: urange64)

.. _function-decs_clone_ComponentValue_int:

.. das:function:: clone(cv: ComponentValue; val: int)

.. _function-decs_clone_ComponentValue_range64:

.. das:function:: clone(cv: ComponentValue; val: range64)

.. _function-decs_clone_ComponentValue_int64:

.. das:function:: clone(cv: ComponentValue; val: int64)

.. _function-decs_clone_ComponentValue_int16:

.. das:function:: clone(cv: ComponentValue; val: int16)

.. _function-decs_clone_ComponentValue_int2:

.. das:function:: clone(cv: ComponentValue; val: int2)

.. _function-decs_clone_ComponentValue_int3:

.. das:function:: clone(cv: ComponentValue; val: int3)

.. _function-decs_clone_ComponentValue_int4:

.. das:function:: clone(cv: ComponentValue; val: int4)

.. _function-decs_clone_ComponentValue_int8:

.. das:function:: clone(cv: ComponentValue; val: int8)

.. _function-decs_clone_ComponentValue_uint16:

.. das:function:: clone(cv: ComponentValue; val: uint16)

.. _function-decs_clone_ComponentValue_uint8:

.. das:function:: clone(cv: ComponentValue; val: uint8)

.. _function-decs_clone_ComponentValue_uint64:

.. das:function:: clone(cv: ComponentValue; val: uint64)

.. _function-decs_clone_ComponentValue_uint2:

.. das:function:: clone(cv: ComponentValue; val: uint2)

.. _function-decs_clone_ComponentValue_uint3:

.. das:function:: clone(cv: ComponentValue; val: uint3)

.. _function-decs_clone_ComponentValue_float:

.. das:function:: clone(cv: ComponentValue; val: float)

.. _function-decs_clone_ComponentValue_uint4:

.. das:function:: clone(cv: ComponentValue; val: uint4)

.. _function-decs_clone_ComponentValue_float2:

.. das:function:: clone(cv: ComponentValue; val: float2)

.. _function-decs_clone_ComponentValue_float3:

.. das:function:: clone(cv: ComponentValue; val: float3)

.. _function-decs_clone_ComponentValue_uint:

.. das:function:: clone(cv: ComponentValue; val: uint)

.. _function-decs_clone_ComponentValue_float3x4:

.. das:function:: clone(cv: ComponentValue; val: float3x4)

.. _function-decs_clone_ComponentValue_float3x3:

.. das:function:: clone(cv: ComponentValue; val: float3x3)

.. _function-decs_clone_ComponentValue_float4x4:

.. das:function:: clone(cv: ComponentValue; val: float4x4)

.. _function-decs_clone_ComponentValue_double:

.. das:function:: clone(cv: ComponentValue; val: double)

.. _function-decs_clone_Component_Component:

.. das:function:: clone(dst: Component; src: Component)

.. _function-decs_clone_ComponentValue_float4:

.. das:function:: clone(cv: ComponentValue; val: float4)

----

.. _function-decs_find_component_index_Archetype_string:

.. das:function:: find_component_index(arch: Archetype; name: string) : int

Returns the index of a named component within the archetype's component array.
Used to resolve component locations once, then write many entities via `set_direct_at`.


:Arguments: * **arch** :  :ref:`Archetype <struct-decs-Archetype>`

            * **name** : string


get
^^^

.. _function-decs_get_ComponentMap_string_autoTT_0x46a:

.. das:function:: 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: * **cmp** :  :ref:`ComponentMap <alias-ComponentMap>`

            * **name** : string

            * **value** : auto(TT)

.. _function-decs_get_Archetype_string_autoTT_0x2f8:

.. das:function:: get(arch: Archetype; name: string; value: auto(TT)) : auto

----

.. _function-decs_get_component_EntityId_string_autoTT_0x448:

.. das:function:: get_component(eid: EntityId; name: string; defval: auto(TT)) : TT

Returns a copy of the named component for the given entity.
If the entity is dead or the component is not found, returns ``defval``.
The type of the component is inferred from the type of ``defval``.
Panics if the component exists but its type does not match.


:Arguments: * **eid** :  :ref:`EntityId <struct-decs-EntityId>`

            * **name** : string

            * **defval** : auto(TT)


has
^^^

.. _function-decs_has_Archetype_string:

.. das:function:: has(arch: Archetype; name: string) : bool

Returns true if object has specified subobjec.


:Arguments: * **arch** :  :ref:`Archetype <struct-decs-Archetype>`

            * **name** : string

.. _function-decs_has_ComponentMap_string:

.. das:function:: has(cmp: ComponentMap; name: string) : bool

----

.. _function-decs_remove_ComponentMap_string:

.. das:function:: remove(cmp: ComponentMap; name: string)

Removes specified value from the component map.


:Arguments: * **cmp** :  :ref:`ComponentMap <alias-ComponentMap>`

            * **name** : string


set
^^^

.. _function-decs_set_ComponentValue_auto_0xbc:

.. das:function:: set(cv: ComponentValue; val: auto) : auto

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


:Arguments: * **cv** :  :ref:`ComponentValue <struct-decs-ComponentValue>`

            * **val** : auto

.. _function-decs_set_ComponentMap_string_autoTT_0x53f:

.. das:function:: set(cmp: ComponentMap; name: string; value: auto(TT)) : auto

----

.. _function-decs_set_direct_Archetype_string_int_autoTT_0x563:

.. das:function:: set_direct(arch: Archetype; name: string; eidx: int; value: auto(TT)) : auto

Writes a component value directly into archetype storage at the given entity index.
Convenience wrapper — does a name lookup per call. For bulk writes, prefer
`find_component_index` + `set_direct_at` to resolve the name once.


:Arguments: * **arch** :  :ref:`Archetype <struct-decs-Archetype>`

            * **name** : string

            * **eidx** : int

            * **value** : auto(TT)

.. _function-decs_set_direct_at_Archetype_int_int_autoTT_0x55b:

.. das:function:: set_direct_at(arch: Archetype; comp_idx: int; eidx: int; value: auto(TT)) : auto

Writes a component value directly into archetype storage by pre-resolved component index.
O(1) per write — use `find_component_index` once, then this for each entity.


:Arguments: * **arch** :  :ref:`Archetype <struct-decs-Archetype>`

            * **comp_idx** : int

            * **eidx** : int

            * **value** : auto(TT)


+++++++++++++
Entity status
+++++++++++++

  *  :ref:`entity_count () : int <function-decs_entity_count>`
  *  :ref:`is_alive (eid: EntityId) : bool <function-decs_is_alive_EntityId>`

.. _function-decs_entity_count:

.. das:function:: entity_count() : int

Returns the total number of alive entities across all archetypes.


.. _function-decs_is_alive_EntityId:

.. das:function:: is_alive(eid: EntityId) : bool

Returns true if the entity is alive (exists and has not been deleted).
An entity is alive when its id is within bounds and its generation matches the lookup table.


:Arguments: * **eid** :  :ref:`EntityId <struct-decs-EntityId>`


+++++++++++++++++++++++
Debug and serialization
+++++++++++++++++++++++

  *  :ref:`debug_dump () <function-decs_debug_dump>`
  *  :ref:`debug_dump_string () : string <function-decs_debug_dump_string>`
  *  :ref:`debug_dump_writer (var writer: StringBuilderWriter) <function-decs_debug_dump_writer_StringBuilderWriter>`
  *  :ref:`describe (info: CTypeInfo) : string <function-decs_describe_CTypeInfo>`
  *  :ref:`finalize (var cmp: Component) <function-decs_finalize_Component>`
  *  :ref:`serialize (var arch: Archive; var src: Component) <function-decs_serialize_Archive_Component>`

.. _function-decs_debug_dump:

.. das:function:: debug_dump()

Prints out state of the ECS system to LOG_DEBUG.


.. _function-decs_debug_dump_string:

.. das:function:: debug_dump_string() : string

Returns state of the ECS system as a string.


.. _function-decs_debug_dump_writer_StringBuilderWriter:

.. das:function:: debug_dump_writer(writer: StringBuilderWriter)

Writes state of the ECS system to a StringBuilderWriter.


:Arguments: * **writer** :  :ref:`StringBuilderWriter <handle-strings-StringBuilderWriter>`

.. _function-decs_describe_CTypeInfo:

.. das:function:: describe(info: CTypeInfo) : string

Returns textual description of the type.


:Arguments: * **info** :  :ref:`CTypeInfo <struct-decs-CTypeInfo>`

.. _function-decs_finalize_Component:

.. das:function:: finalize(cmp: Component)

Deletes component.


:Arguments: * **cmp** :  :ref:`Component <struct-decs-Component>`

.. _function-decs_serialize_Archive_Component:

.. das:function:: serialize(arch: Archive; src: Component)

Serializes component value.


:Arguments: * **arch** :  :ref:`Archive <struct-archive-Archive>`

            * **src** :  :ref:`Component <struct-decs-Component>`


++++++
Stages
++++++

  *  :ref:`commit () <function-decs_commit>`
  *  :ref:`decs_stage (name: string) <function-decs_decs_stage_string>`
  *  :ref:`register_decs_stage_call (name: string; pcall: PassFunction) <function-decs_register_decs_stage_call_string_PassFunction>`

.. _function-decs_commit:

.. das:function:: commit()

Finishes all deferred actions.


.. _function-decs_decs_stage_string:

.. das:function:: decs_stage(name: string)

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


:Arguments: * **name** : string

.. _function-decs_register_decs_stage_call_string_PassFunction:

.. das:function:: 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: * **name** : string

            * **pcall** :  :ref:`PassFunction <alias-PassFunction>`


++++++++++++++++
Deferred actions
++++++++++++++++

  *  :ref:`create_entities (count: int; blk: block\<(eid:EntityId;i:int;var cmp:ComponentMap):void\>) <function-decs_create_entities_int_block_ls_eid_c_EntityId;i_c_int;var_cmp_c_ComponentMap_c_void_gr_>`
  *  :ref:`create_entities_from_cmp (count: int; var cmp: ComponentMap; fill_blk: block\<(var arch:Archetype;eidx:int;eid:EntityId;i:int):void\>) <function-decs_create_entities_from_cmp_int_ComponentMap_block_ls_var_arch_c_Archetype;eidx_c_int;eid_c_EntityId;i_c_int_c_void_gr_>`
  *  :ref:`create_entity (var blk: lambda\<(eid:EntityId;var cmp:ComponentMap):void\>) : EntityId <function-decs_create_entity_lambda_ls_eid_c_EntityId;var_cmp_c_ComponentMap_c_void_gr_>`
  *  :ref:`delete_entity (entityid: EntityId) <function-decs_delete_entity_EntityId>`
  *  :ref:`update_entity (entityid: EntityId; var blk: lambda\<(eid:EntityId;var cmp:ComponentMap):void\>) <function-decs_update_entity_EntityId_lambda_ls_eid_c_EntityId;var_cmp_c_ComponentMap_c_void_gr_>`

.. _function-decs_create_entities_int_block_ls_eid_c_EntityId;i_c_int;var_cmp_c_ComponentMap_c_void_gr_:

.. das:function:: create_entities(count: int; blk: block<(eid:EntityId;i:int;var cmp:ComponentMap):void>)

Creates `count` entities in bulk. All entities must have the same archetype
(same set of components). This is much faster than calling `create_entity` in
a loop because it does a single archetype lookup and a single resize per
component array for the entire batch.

Unlike `create_entity`, this is immediate — entities are visible to queries
right after the call returns (no `commit` needed).

Example::

    create_entities(100) $(eid : EntityId; i : int; var cmp : ComponentMap)
        apply_decs_template(cmp, Particle(pos = origin, vel = compute_vel(i)))



:Arguments: * **count** : int

            * **blk** : block<(eid: :ref:`EntityId <struct-decs-EntityId>`;i:int;cmp: :ref:`ComponentMap <alias-ComponentMap>`):void>

.. _function-decs_create_entities_from_cmp_int_ComponentMap_block_ls_var_arch_c_Archetype;eidx_c_int;eid_c_EntityId;i_c_int_c_void_gr_:

.. das:function:: create_entities_from_cmp(count: int; cmp: ComponentMap; fill_blk: block<(var arch:Archetype;eidx:int;eid:EntityId;i:int):void>)

Creates `count` entities in bulk with maximum performance. Takes a pre-built
ComponentMap (used once to establish the archetype shape), then calls `fill_blk`
for each entity to write directly into archetype storage, bypassing ComponentMap.

Typically called by macro-generated ``create_entities`T`` functions rather than
directly. See `create_entities` for the simpler ComponentMap-based API.


:Arguments: * **count** : int

            * **cmp** :  :ref:`ComponentMap <alias-ComponentMap>`

            * **fill_blk** : block<(arch: :ref:`Archetype <struct-decs-Archetype>`;eidx:int;eid: :ref:`EntityId <struct-decs-EntityId>`;i:int):void>

.. _function-decs_create_entity_lambda_ls_eid_c_EntityId;var_cmp_c_ComponentMap_c_void_gr_:

.. das:function:: create_entity(blk: lambda<(eid:EntityId;var cmp:ComponentMap):void>) : EntityId

Creates deferred action to create entity.


:Arguments: * **blk** : lambda<(eid: :ref:`EntityId <struct-decs-EntityId>`;cmp: :ref:`ComponentMap <alias-ComponentMap>`):void>

.. _function-decs_delete_entity_EntityId:

.. das:function:: delete_entity(entityid: EntityId)

Creates deferred action to delete entity specified by id.


:Arguments: * **entityid** :  :ref:`EntityId <struct-decs-EntityId>` implicit

.. _function-decs_update_entity_EntityId_lambda_ls_eid_c_EntityId;var_cmp_c_ComponentMap_c_void_gr_:

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

Creates deferred action to update entity specified by id.


:Arguments: * **entityid** :  :ref:`EntityId <struct-decs-EntityId>` implicit

            * **blk** : lambda<(eid: :ref:`EntityId <struct-decs-EntityId>`;cmp: :ref:`ComponentMap <alias-ComponentMap>`):void>


++++++++++++
GC and reset
++++++++++++

  *  :ref:`after_gc () <function-decs_after_gc>`
  *  :ref:`before_gc () <function-decs_before_gc>`
  *  :ref:`restart () <function-decs_restart>`

.. _function-decs_after_gc:

.. das:function:: after_gc()

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


.. _function-decs_before_gc:

.. das:function:: before_gc()

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


.. _function-decs_restart:

.. das:function:: restart()

Restarts ECS by erasing all deferred actions and entire state.



+++++++++
Iteration
+++++++++

  *  :ref:`decs_array (atype: auto(TT); src: array\<uint8\>; capacity: int) : auto <function-decs_decs_array_autoTT_array_ls_uint8_gr__int_0x2e5>`
  *  :ref:`for_each_archetype (hash: ComponentHash; var erq: function\<():void\>; blk: block\<(arch:Archetype):void\>) <function-decs_for_each_archetype_ComponentHash_function_ls__c_void_gr__block_ls_arch_c_Archetype_c_void_gr_>`
  *  :ref:`for_each_archetype (var erq: EcsRequest; blk: block\<(arch:Archetype):void\>) <function-decs_for_each_archetype_EcsRequest_block_ls_arch_c_Archetype_c_void_gr_>`
  *  :ref:`for_each_archetype_find (hash: ComponentHash; var erq: function\<():void\>; blk: block\<(arch:Archetype):bool\>) : bool <function-decs_for_each_archetype_find_ComponentHash_function_ls__c_void_gr__block_ls_arch_c_Archetype_c_bool_gr_>`
  *  :ref:`for_eid_archetype (eid: EntityId; hash: ComponentHash; var erq: function\<():void\>; blk: block\<(arch:Archetype;index:int):void\>) : bool <function-decs_for_eid_archetype_EntityId_ComponentHash_function_ls__c_void_gr__block_ls_arch_c_Archetype;index_c_int_c_void_gr_>`
  *  :ref:`get_default_ro (arch: Archetype; name: string; value: auto(TT)) : iterator\<TT const&\> <function-decs_get_default_ro_Archetype_string_autoTT_0x32b>`
  *  :ref:`get_optional (arch: Archetype; name: string; value: auto(TT)?) : iterator\<TT?\> <function-decs_get_optional_Archetype_string_autoTT_q_>`
  *  :ref:`get_ro (arch: Archetype; name: string; value: auto(TT)) : array\<TT\> <function-decs_get_ro_Archetype_string_autoTT_0x324>`
  *  :ref:`get_ro (arch: Archetype; name: string; value: auto(TT)[]) : array\<TT[-2]\> <function-decs_get_ro_Archetype_string_autoTT_lb__rb__0x31c>`

.. _function-decs_decs_array_autoTT_array_ls_uint8_gr__int_0x2e5:

.. das:function:: decs_array(atype: auto(TT); src: array<uint8>; capacity: int) : auto

.. warning::
  This is unsafe operation.

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


:Arguments: * **atype** : auto(TT)

            * **src** : array<uint8>

            * **capacity** : int


for_each_archetype
^^^^^^^^^^^^^^^^^^

.. _function-decs_for_each_archetype_ComponentHash_function_ls__c_void_gr__block_ls_arch_c_Archetype_c_void_gr_:

.. das:function:: 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: * **hash** :  :ref:`ComponentHash <alias-ComponentHash>`

            * **erq** : function<void>

            * **blk** : block<(arch: :ref:`Archetype <struct-decs-Archetype>`):void>

.. _function-decs_for_each_archetype_EcsRequest_block_ls_arch_c_Archetype_c_void_gr_:

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

----

.. _function-decs_for_each_archetype_find_ComponentHash_function_ls__c_void_gr__block_ls_arch_c_Archetype_c_bool_gr_:

.. das:function:: 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: * **hash** :  :ref:`ComponentHash <alias-ComponentHash>`

            * **erq** : function<void>

            * **blk** : block<(arch: :ref:`Archetype <struct-decs-Archetype>`):bool>

.. _function-decs_for_eid_archetype_EntityId_ComponentHash_function_ls__c_void_gr__block_ls_arch_c_Archetype;index_c_int_c_void_gr_:

.. das:function:: for_eid_archetype(eid: EntityId; 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: * **eid** :  :ref:`EntityId <struct-decs-EntityId>` implicit

            * **hash** :  :ref:`ComponentHash <alias-ComponentHash>`

            * **erq** : function<void>

            * **blk** : block<(arch: :ref:`Archetype <struct-decs-Archetype>`;index:int):void>

.. _function-decs_get_default_ro_Archetype_string_autoTT_0x32b:

.. das:function:: 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 keep returning the specified value.


:Arguments: * **arch** :  :ref:`Archetype <struct-decs-Archetype>`

            * **name** : string

            * **value** : auto(TT)

.. _function-decs_get_optional_Archetype_string_autoTT_q_:

.. das:function:: 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 keep returning default value for the component type.


:Arguments: * **arch** :  :ref:`Archetype <struct-decs-Archetype>`

            * **name** : string

            * **value** : auto(TT)?


get_ro
^^^^^^

.. _function-decs_get_ro_Archetype_string_autoTT_0x324:

.. das:function:: 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** :  :ref:`Archetype <struct-decs-Archetype>`

            * **name** : string

            * **value** : auto(TT)

.. _function-decs_get_ro_Archetype_string_autoTT_lb__rb__0x31c:

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


+++++++
Request
+++++++

  *  :ref:`EcsRequestPos (at: LineInfo) : EcsRequestPos <function-decs_EcsRequestPos_LineInfo>`
  *  :ref:`compile_request (var erq: EcsRequest) <function-decs_compile_request_EcsRequest>`
  *  :ref:`lookup_request (var erq: EcsRequest) : int <function-decs_lookup_request_EcsRequest>`
  *  :ref:`verify_request (var erq: EcsRequest) : tuple\<ok:bool;error:string\> <function-decs_verify_request_EcsRequest>`

.. _function-decs_EcsRequestPos_LineInfo:

.. das:function:: EcsRequestPos(at: LineInfo) : EcsRequestPos

Constructs EcsRequestPos from rtti::LineInfo.


:Arguments: * **at** :  :ref:`LineInfo <handle-rtti-LineInfo>`

.. _function-decs_compile_request_EcsRequest:

.. das:function:: compile_request(erq: EcsRequest)

Compiles ECS request, by creating request hash.


:Arguments: * **erq** :  :ref:`EcsRequest <struct-decs-EcsRequest>`

.. _function-decs_lookup_request_EcsRequest:

.. das:function:: lookup_request(erq: EcsRequest) : int

Looks up ECS request in the request cache.


:Arguments: * **erq** :  :ref:`EcsRequest <struct-decs-EcsRequest>`

.. _function-decs_verify_request_EcsRequest:

.. das:function:: verify_request(erq: EcsRequest) : tuple<ok:bool;error:string>

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


:Arguments: * **erq** :  :ref:`EcsRequest <struct-decs-EcsRequest>`