tecs.ecs#

The ECS shared by game code and engine systems.

Build queries during setup, reuse them from systems, and put all game state on entities:

local moving: tecs.Query

local function game(world: tecs.World)
    moving = world:newQuery({include = {tecs.Transform2D}})

    world:addSystem({
        name = "game.Drift",
        phase = tecs.ecs.phases.Update,
        run = function(delta: number)
            for archetype, length in moving:iter() do
                local transform <const> = archetype:getMut(
                    tecs.Transform2D
                )
                for row = 1, length do
                    transform[row].x = transform[row].x + 60 * delta
                end
            end
        end,
    })

    world:spawn(tecs.Transform2D(0, 0))
end

Read columns through archetype:get. Write through getMut so dirty-gated systems can find the change. See Worlds, Components, Queries, and Systems for the complete ECS model.

Module contents#

Submodules#

Constructors#

Types#

Functions#

Values#

Constructors#

tecs.ecs.newComponent Static#

Creates and registers a new table component. See ecs.ComponentOptions and the component docs for the shared fields / defaults / init / .new model.

function tecs.ecs.newComponent<C is Component>(
    options: ComponentOptions<C>
): C

Type Parameters#

Arguments#

Returns#

tecs.ecs.newFFIComponent Static#

Creates and registers an FFI-based component. Same constructor model as newComponent, but the base instance is an FFI struct.

function tecs.ecs.newFFIComponent<C is Component>(
    options: FFIComponentOptions<C>
): C

Type Parameters#

Arguments#

Returns#

tecs.ecs.newFFIRelationship Static#

Creates an FFI-backed relationship with data fields.

function tecs.ecs.newFFIRelationship<R is Relationship>(
    config: FFIRelationshipOptions<R>
): R

Type Parameters#

Arguments#

Returns#

tecs.ecs.newRelationship Static#

Creates and registers a relationship component.

A target-only relationship needs a name and flags. Add container and fields when each edge carries data.

function tecs.ecs.newRelationship<R is Relationship>(
    config: RelationshipOptions<R>
): R

Type Parameters#

Arguments#

Returns#

tecs.ecs.newScalarComponent Static#

Creates and registers a new scalar component.

function tecs.ecs.newScalarComponent<T>(
    options: ScalarComponentOptions<T>
): ScalarComponent<T>

Type Parameters#

Arguments#

Returns#

tecs.ecs.newTagComponent Static#

Creates and registers a tag component. A tag holds no per-row state, so a snapshot saves its presence and writes no payload for it.

function tecs.ecs.newTagComponent(
    options: TagComponentOptions
): Component

Arguments#

Returns#

tecs.ecs.newWorld Static#

Creates a new World.

function tecs.ecs.newWorld(config: types.World.Config): World

Arguments#

Returns#

Types#

tecs.ecs.Archetype interface#

Archetype stores contiguous component columns.

interface tecs.ecs.Archetype
    id: integer
    entities: DoubleArray
    componentList: {components.Component}

    addEntityObserver: function(self, ArchetypeEntityObserver)
    anyComponentDirty: function(self): boolean
    dirtyComponents: function(self): function(): components.Component
    forEachRelationship: function<T is components.Relationship>(
        self, row: T, callback: integer, function(T)
    )
    get: function<T is components.Component>(self, T): {T}
    getFirstRelationship: function<T is components.Relationship>(
        self, row: T, integer
    ): T
    getMut: function<T is components.Component>(self, T): {T}
    isComponentDirty: function(
        self, component: components.Component
    ): boolean
    markAllComponentsDirty: function(self)
    markComponentDirty: function(self, components.Component)
    set: function<C is components.Component>(
        self, row: integer, value: C
    )
end

tecs.ecs.Archetype.id field#

Read-only. The unique identifier of the archetype in the ECS container.

tecs.ecs.Archetype.id: integer

tecs.ecs.Archetype.entities field#

Read-only. Entity IDs that belong to this archetype. Length is entities[0]; rows are 1-based (entities[1] is the first entity).

tecs.ecs.Archetype.entities: DoubleArray

tecs.ecs.Archetype.componentList field#

Read-only. Components in this archetype, in the order they were passed at construction. Finalized at creation -- archetypes never add or remove components. Iterate with #componentList / ipairs to walk the archetype's signature.

tecs.ecs.Archetype.componentList: {components.Component}

tecs.ecs.Archetype:addEntityObserver Instance#

Register an observer for lifecycle changes on this archetype. The observer remains attached for the archetype's lifetime. Registration applies only to this archetype; it does not discover other archetypes with the same components. See ArchetypeEntityObserver.

function tecs.ecs.Archetype.addEntityObserver(
    self, ArchetypeEntityObserver
)

Arguments

Returns

None.

tecs.ecs.Archetype:anyComponentDirty Instance#

True if any component on this archetype is currently dirty. Useful for bulk re-sync paths that don't track dirty granularity below the archetype level.

function tecs.ecs.Archetype.anyComponentDirty(self): boolean

Arguments

Returns

tecs.ecs.Archetype:dirtyComponents Instance#

Iterate components currently marked dirty on this archetype.

function tecs.ecs.Archetype.dirtyComponents(
    self
): function(): components.Component

Arguments

Returns

tecs.ecs.Archetype:forEachRelationship Instance#

Iterate all relationship instances of the given container for the entity at row.

function tecs.ecs.Archetype.forEachRelationship<T is components.Relationship>(
    self, row: T, callback: integer, function(T)
)

Type Parameters

Arguments

Returns

None.

tecs.ecs.Archetype:get Instance#

Read-only column access. Returns the row-indexed column for the given component type, or nil if the archetype doesn't carry it. Does NOT mark the component dirty.

function tecs.ecs.Archetype.get<T is components.Component>(
    self, T
): {T}

Type Parameters

Arguments

Returns

tecs.ecs.Archetype:getFirstRelationship Instance#

Get the first relationship instance of the given container for the entity at row, or nil if none exists.

function tecs.ecs.Archetype.getFirstRelationship<T is components.Relationship>(
    self, row: T, integer
): T

Type Parameters

Arguments

Returns

tecs.ecs.Archetype:getMut Instance#

Mutable column access. Returns the row-indexed column AND marks the component dirty on this archetype. Use this at every site where you intend to write into the column.

function tecs.ecs.Archetype.getMut<T is components.Component>(
    self, T
): {T}

Type Parameters

Arguments

Returns

tecs.ecs.Archetype:isComponentDirty Instance#

True if the given component's column on this archetype is currently marked dirty.

function tecs.ecs.Archetype.isComponentDirty(
    self, component: components.Component
): boolean

Arguments

Returns

tecs.ecs.Archetype:markAllComponentsDirty Instance#

Mark every component on this archetype dirty.

Says that every column changed and says nothing about where, so a consumer that can resync single rows resyncs the whole archetype after it. Prefer markComponentDirty for a column you can name.

function tecs.ecs.Archetype.markAllComponentsDirty(self)

Arguments

Returns

None.

tecs.ecs.Archetype:markComponentDirty Instance#

Mark a single component dirty on this archetype. Idempotent.

function tecs.ecs.Archetype.markComponentDirty(
    self, components.Component
)

Arguments

Returns

None.

tecs.ecs.Archetype:set Instance#

Set a component value at a row and mark it dirty. Use for in-place updates that don't change the entity's archetype.

function tecs.ecs.Archetype.set<C is components.Component>(
    self, row: integer, value: C
)

Type Parameters

Arguments

Returns

None.

tecs.ecs.ArchetypeCreated record#

An event emitted at entity 0 (world) when a new archetype is created.

record tecs.ecs.ArchetypeCreated is types.events.Event
    archetype: types.Archetype

    metamethod __call: function(self, types.Archetype): ArchetypeCreated
end

Interfaces#

tecs.ecs.ArchetypeCreated.archetype field#

Engine-owned. Reports this public value.

tecs.ecs.ArchetypeCreated.archetype: types.Archetype

tecs.ecs.ArchetypeCreated:__call metamethod#

Create a new ArchetypeCreated event.

metamethod tecs.ecs.ArchetypeCreated.$meta.__call(
    self, types.Archetype
): ArchetypeCreated

Arguments

Returns

tecs.ecs.ArchetypeEntityObserver interface#

ArchetypeEntityObserver receives entity changes within an archetype.

interface tecs.ecs.ArchetypeEntityObserver
    onActivated: function(self, archetype: Archetype)
    onArchetypeDestroyed: function(self, Archetype)
    onDeactivated: function(self, archetype: Archetype)
    onEntitiesAdded: function(
        self,
        archetype: Archetype,
        firstRow: integer,
        lastRow: integer,
        count: integer,
        sourceArchetype: Archetype
    )
    onEntitiesRemoved: function(
        self,
        archetype: Archetype,
        firstRow: integer,
        lastRow: integer,
        count: integer,
        destArchetype: Archetype
    )
    onEntityMove: function(
        self,
        archetype: Archetype,
        entity: integer,
        fromRow: integer,
        toRow: integer
    )
end

tecs.ecs.ArchetypeEntityObserver:onActivated Instance#

Called when archetype transitions from empty to non-empty (0 -> 1 entities).

function tecs.ecs.ArchetypeEntityObserver.onActivated(
    self, archetype: Archetype
)

Arguments

Returns

None.

tecs.ecs.ArchetypeEntityObserver:onArchetypeDestroyed Instance#

Called when an archetype is being permanently destroyed (during world:compact()). Observers must remove all references to the archetype.

function tecs.ecs.ArchetypeEntityObserver.onArchetypeDestroyed(
    self, Archetype
)

Arguments

Returns

None.

tecs.ecs.ArchetypeEntityObserver:onDeactivated Instance#

Called when archetype transitions from non-empty to empty (1 -> 0 entities).

function tecs.ecs.ArchetypeEntityObserver.onDeactivated(
    self, archetype: Archetype
)

Arguments

Returns

None.

tecs.ecs.ArchetypeEntityObserver:onEntitiesAdded Instance#

Called once per contiguous range of entities added to the archetype.

function tecs.ecs.ArchetypeEntityObserver.onEntitiesAdded(
    self,
    archetype: Archetype,
    firstRow: integer,
    lastRow: integer,
    count: integer,
    sourceArchetype: Archetype
)

Arguments

Returns

None.

tecs.ecs.ArchetypeEntityObserver:onEntitiesRemoved Instance#

Called once per contiguous range of entities removed from the archetype.

function tecs.ecs.ArchetypeEntityObserver.onEntitiesRemoved(
    self,
    archetype: Archetype,
    firstRow: integer,
    lastRow: integer,
    count: integer,
    destArchetype: Archetype
)

Arguments

Returns

None.

tecs.ecs.ArchetypeEntityObserver:onEntityMove Instance#

Called when an entity is swap-popped into a different row. Implementing onEntitiesAdded is not required.

function tecs.ecs.ArchetypeEntityObserver.onEntityMove(
    self,
    archetype: Archetype,
    entity: integer,
    fromRow: integer,
    toRow: integer
)

Arguments

Returns

None.

tecs.ecs.Bundle interface#

Bundle names a reusable component collection.

interface tecs.ecs.Bundle
    interface Definition
        required: {components.Component}
        with: {components.Component: boolean | function(): components.Component}
    end

    name: string
    required: {string}
    defaulted: {string}

    spawn: function(self, ...: components.Component): integer
end

tecs.ecs.Bundle.Definition interface#

Declarative bundle definition.

interface tecs.ecs.Bundle.Definition
    required: {components.Component}
    with: {components.Component: boolean | function(): components.Component}
end

tecs.ecs.Bundle.Definition.required field

Caller-writable. Components that must be provided as positional args to spawn().

tecs.ecs.Bundle.Definition.required: {components.Component}

tecs.ecs.Bundle.Definition.with field

Caller-writable. Components with defaults, keyed by component type. Value is either a factory function returning a component instance, or true to call the component's default constructor.

tecs.ecs.Bundle.Definition.with: {components.Component: boolean | function(): components.Component}

tecs.ecs.Bundle.name field#

Read-only. The name of the bundle.

tecs.ecs.Bundle.name: string

tecs.ecs.Bundle.required field#

Read-only. Component names that must be provided when spawning.

tecs.ecs.Bundle.required: {string}

tecs.ecs.Bundle.defaulted field#

Read-only. Component names with default factories.

tecs.ecs.Bundle.defaulted: {string}

tecs.ecs.Bundle:spawn Instance#

Reserve an entity using this bundle and stage its placement for the next pipeline barrier.

function tecs.ecs.Bundle.spawn(
    self, ...: components.Component
): integer

Arguments

Returns

tecs.ecs.BundleDef interface#

BundleDef configures a bundle.

interface tecs.ecs.BundleDef
    required: {components.Component}
    with: {components.Component: boolean | function(): components.Component}
end

tecs.ecs.BundleDef.required field#

Caller-writable. Components that must be provided as positional args to spawn().

tecs.ecs.BundleDef.required: {components.Component}

tecs.ecs.BundleDef.with field#

Caller-writable. Components with defaults, keyed by component type. Value is either a factory function returning a component instance, or true to call the component's default constructor.

tecs.ecs.BundleDef.with: {components.Component: boolean | function(): components.Component}

tecs.ecs.Component interface#

Component names any component definition.

interface tecs.ecs.Component
    componentType: self
    componentName: string
    componentId: integer
    relationshipType: Component
    wildcardContainer: Component
    target: integer
    transient: boolean

    deserialize: function(world: World, data: {string: any}): self
    init: function(self, any)
    new: function({string: any}): self
    serialize: function(instance: self): {string: any}
    metamethod __call: function(self, ...: any): self
end

tecs.ecs.Component.componentType field#

Read-only. The container type of the component, available on instances and containers.

tecs.ecs.Component.componentType: self

tecs.ecs.Component.componentName field#

Read-only. The name of the component.

tecs.ecs.Component.componentName: string

tecs.ecs.Component.componentId field#

Read-only. The auto-incrementing ID of the component container.

tecs.ecs.Component.componentId: integer

tecs.ecs.Component.relationshipType field#

Read-only. Relationship components only: the relationship container type (nil for non-relationships). For containers, this equals self. For instances, it points to the container.

tecs.ecs.Component.relationshipType: Component

tecs.ecs.Component.wildcardContainer field#

Read-only. Relationship instance wildcard container (nil for non-relationships and containers). For Rel(target) dense instances, this points back to Rel.

tecs.ecs.Component.wildcardContainer: Component

tecs.ecs.Component.target field#

Read-only. Relationship components only: The target entity ID (for relationship instances only).

tecs.ecs.Component.target: integer

tecs.ecs.Component.transient field#

Read-only. True if this component is runtime-only and omitted from snapshots.

tecs.ecs.Component.transient: boolean

tecs.ecs.Component.deserialize Static#

Deserialize a component instance from a plain table.

function tecs.ecs.Component.deserialize(
    world: World, data: {string: any}
): self

Arguments

Returns

tecs.ecs.Component.init Static#

Optional post-allocation positional initializer used by the built-in factories. Runs after the base instance has been allocated and any declarative field population has occurred.

function tecs.ecs.Component.init(self, any)

Arguments

Returns

None.

tecs.ecs.Component.new Static#

Build a component instance from a table of named fields. The positional __call form is the hot path; new is the ergonomic/snapshot form.

function tecs.ecs.Component.new({string: any}): self

Arguments

Returns

tecs.ecs.Component.serialize Static#

Serialize a component instance to a plain table.

function tecs.ecs.Component.serialize(instance: self): {string: any}

Arguments

Returns

tecs.ecs.Component:__call metamethod#

Creates an instance of the component from the container using positional arguments.

metamethod tecs.ecs.Component.$meta.__call(self, ...: any): self

Arguments

Returns

tecs.ecs.ComponentOptions interface#

ComponentOptions configures a table component.

interface tecs.ecs.ComponentOptions<C is Component> is ContainerComponentOptions<C>
    fields: {string}
    defaults: {any}

    __call: function(C, any)
    deserialize: function(World, {string: any}): C
    init: function(C, any)
    new: function({string: any}): C
    serialize: function(C): {string: any}
end

Interfaces#

Type Parameters#

tecs.ecs.ComponentOptions.fields field#

Caller-writable. Ordered field names for positional construction and .new(data). Example: fields = {"x", "y"} means Component(1, 2) maps to {x = 1, y = 2} and Component.new({x = 1, y = 2}) unpacks by the same order. The generated constructor is loaded so LuaJIT sees literal field assignments.

tecs.ecs.ComponentOptions.fields: {string}

tecs.ecs.ComponentOptions.defaults field#

Caller-writable. Positional defaults, in the same order as fields. Use nil for fields that have no default. Requires fields.

tecs.ecs.ComponentOptions.defaults: {any}

tecs.ecs.ComponentOptions.__call Static#

Optional custom constructor hook for the container's __call. When present, Tecs allocates a base instance, applies declarative defaults, then invokes this hook as __call(instance, ...). On this path, init is NOT auto-run; call Component.init(...) explicitly from __call if desired.

function tecs.ecs.ComponentOptions.__call(C, any)

Arguments

Returns

None.

tecs.ecs.ComponentOptions.deserialize Static#

Custom deserialization function (optional). Reconstructs a component instance from a plain table.

function tecs.ecs.ComponentOptions.deserialize(World, {string: any}): C

Arguments

Returns

tecs.ecs.ComponentOptions.init Static#

Optional post-allocation positional initializer. Runs after the base instance has been allocated and any declarative fields / defaults have been applied. Use for validation, normalization, or derived state. If provided without fields or new, registration errors because Tecs would have no clear way to implement .new(data).

function tecs.ecs.ComponentOptions.init(C, any)

Arguments

Returns

None.

tecs.ecs.ComponentOptions.new Static#

Optional table-form constructor, called as Component.new(data). When fields are present, Tecs generates this automatically by unpacking named fields and routing through __call.

function tecs.ecs.ComponentOptions.new({string: any}): C

Arguments

Returns

tecs.ecs.ComponentOptions.serialize Static#

Custom serialization function (optional). Converts a component instance to a plain table for JSON serialization.

function tecs.ecs.ComponentOptions.serialize(C): {string: any}

Arguments

Returns

tecs.ecs.ContainerComponentOptions interface#

Shared options for creating different components.

interface tecs.ecs.ContainerComponentOptions<C is Component> is BasicComponentOptions<C>
    container: C
end

Interfaces#

Type Parameters#

tecs.ecs.ContainerComponentOptions.container field#

Caller-writable. The component container/type to use (required).

tecs.ecs.ContainerComponentOptions.container: C

tecs.ecs.DoubleArray interface#

DoubleArray names an FFI array of doubles.

interface tecs.ecs.DoubleArray is {integer}
    metamethod __len: function(self)
end

Interfaces#

tecs.ecs.DoubleArray:__len metamethod#

Reads the count out of slot 0 rather than probing for a border, so #array is exact even though slot 0 is occupied and would otherwise make the array look empty to Lua's own length operator. A macro, so it costs one load at the call site.

metamethod tecs.ecs.DoubleArray.$meta.__len(self)

Arguments

Returns

None.

tecs.ecs.FFIComponentOptions interface#

FFIComponentOptions configures an FFI component.

interface tecs.ecs.FFIComponentOptions<C is Component> is ContainerComponentOptions<C>
    fields: {{string, string}}
    defaults: {any}
    metatable: {any: any}

    __call: function(C, any)
    deserialize: function(World, {string: any}): C
    init: function(C, any)
    new: function({string: any}): C
    serialize: function(C): {string: any}
end

Interfaces#

Type Parameters#

tecs.ecs.FFIComponentOptions.fields field#

Caller-writable. FFI field definitions for the backing struct.

tecs.ecs.FFIComponentOptions.fields: {{string, string}}

tecs.ecs.FFIComponentOptions.defaults field#

Caller-writable. Positional defaults, in the same order as fields.

tecs.ecs.FFIComponentOptions.defaults: {any}

tecs.ecs.FFIComponentOptions.metatable field#

Caller-writable. Optional metatable to apply to FFI instances (for instance methods).

tecs.ecs.FFIComponentOptions.metatable: {any: any}

tecs.ecs.FFIComponentOptions.__call Static#

Optional custom constructor hook. Same semantics as ComponentOptions.__call, but the base instance is an FFI struct.

function tecs.ecs.FFIComponentOptions.__call(C, any)

Arguments

Returns

None.

tecs.ecs.FFIComponentOptions.deserialize Static#

Custom deserialization function (optional). Reconstructs a component instance from a plain table. Typically reruns the same construction path a fresh spawn would take so the restored instance gets valid runtime state.

function tecs.ecs.FFIComponentOptions.deserialize(
    World, {string: any}
): C

Arguments

Returns

tecs.ecs.FFIComponentOptions.init Static#

Optional post-allocation positional initializer. Same semantics as ComponentOptions.init, but the base instance is an FFI struct.

function tecs.ecs.FFIComponentOptions.init(C, any)

Arguments

Returns

None.

tecs.ecs.FFIComponentOptions.new Static#

Optional table-form constructor. Defaults to unpacking fields by name into positional args and routing through __call.

function tecs.ecs.FFIComponentOptions.new({string: any}): C

Arguments

Returns

tecs.ecs.FFIComponentOptions.serialize Static#

Custom serialization function (optional). Converts a component instance to a plain table for JSON serialization. Return nil to omit the component from snapshots.

function tecs.ecs.FFIComponentOptions.serialize(C): {string: any}

Arguments

Returns

tecs.ecs.FFIRelationshipOptions interface#

FFIRelationshipOptions configures an FFI relationship.

interface tecs.ecs.FFIRelationshipOptions<R is Relationship> is BaseRelationshipOptions<R>, FFIComponentOptions<R>
end

Interfaces#

Type Parameters#

tecs.ecs.FinishSnapshotLoad record#

An event emitted on entity 0 once tecs.loadSnapshot finishes -- after all entities are restored AND every data callback has run. Useful for cleanup or "load is complete" callbacks.

record tecs.ecs.FinishSnapshotLoad is types.events.Event
    prelude: any

    metamethod __call: function(self): FinishSnapshotLoad
end

Interfaces#

tecs.ecs.FinishSnapshotLoad.prelude field#

Engine-owned. The snapshot prelude (version, counts).

tecs.ecs.FinishSnapshotLoad.prelude: any

tecs.ecs.FinishSnapshotLoad:__call metamethod#

metamethod tecs.ecs.FinishSnapshotLoad.$meta.__call(
    self
): FinishSnapshotLoad

Arguments

Returns

tecs.ecs.FixedOverload enum#

FixedOverload selects fixed-step overload behavior.

enum tecs.ecs.FixedOverload
    "accumulate"
    "drop"
end

tecs.ecs.OnDespawn record#

An event emitted when a specific entity is despawned.

record tecs.ecs.OnDespawn is types.events.Event
    entity: integer

    metamethod __call: function(self, integer): OnDespawn
end

Interfaces#

tecs.ecs.OnDespawn.entity field#

Engine-owned. Reports this public value.

tecs.ecs.OnDespawn.entity: integer

tecs.ecs.OnDespawn:__call metamethod#

Create a new OnDespawn event.

metamethod tecs.ecs.OnDespawn.$meta.__call(self, integer): OnDespawn

Arguments

Returns

tecs.ecs.OnSnapshotSave record#

An event emitted on entity 0 at the start of tecs.saveSnapshot, BEFORE archetype data is written. Listeners can: - Attach arbitrary keyed metadata via ev:addData(key, value) (queued; flushed into the data section after archetypes). - Mark plugin-derived entities for omission via ev:exclude(component). Entities carrying any excluded component are skipped entirely; on load the plugin re-derives them from durable source-of-truth entities that ARE saved.

record tecs.ecs.OnSnapshotSave is types.events.Event
    addData: function(self, string, any)
    exclude: function(self, types.components.Component)
    metamethod __call: function(self): OnSnapshotSave
end

Interfaces#

tecs.ecs.OnSnapshotSave:addData Instance#

Encode a (key, value) pair into the snapshot's data section. Keys MUST be strings; values must be string.buffer-encodable. Plugins typically use namespaced keys (e.g. "tecs.physics", "mygame.scoreboard") to avoid collisions.

function tecs.ecs.OnSnapshotSave.addData(self, string, any)

Arguments

Returns

None.

tecs.ecs.OnSnapshotSave:exclude Instance#

Exclude every entity that carries component from the snapshot. Use this when a plugin owns derived state (e.g. TileChunk projection of a Tilemap, physics body backing a RigidBody marker) and can re-spawn those entities on load from a durable source component that IS saved.

function tecs.ecs.OnSnapshotSave.exclude(
    self, types.components.Component
)

Arguments

Returns

None.

tecs.ecs.OnSnapshotSave:__call metamethod#

metamethod tecs.ecs.OnSnapshotSave.$meta.__call(self): OnSnapshotSave

Arguments

Returns

tecs.ecs.OnSpawn record#

An event emitted when a specific entity is spawned.

record tecs.ecs.OnSpawn is types.events.Event
    entity: integer

    metamethod __call: function(self, integer): OnSpawn
end

Interfaces#

tecs.ecs.OnSpawn.entity field#

Engine-owned. Reports this public value.

tecs.ecs.OnSpawn.entity: integer

tecs.ecs.OnSpawn:__call metamethod#

Create a new OnSpawn event.

metamethod tecs.ecs.OnSpawn.$meta.__call(self, integer): OnSpawn

Arguments

Returns

tecs.ecs.Phase interface#

Phase identifies one system phase.

interface tecs.ecs.Phase
    name: string
    position: integer
    children: {Phase}
end

tecs.ecs.Phase.name field#

Read-only. The name of the phase.

tecs.ecs.Phase.name: string

tecs.ecs.Phase.position field#

Read-only. The public pipeline position for this phase.

tecs.ecs.Phase.position: integer

tecs.ecs.Phase.children field#

Read-only. Child phases of this phase.

tecs.ecs.Phase.children: {Phase}

tecs.ecs.phases record#

Defines the predefined ECS phases, or lifecycle states, of the game and event loop.

Tecs provides these standard phases but also supports custom pipelines via World.Config.pipelineFactory. Read-only. phases contains the phases a system may join.

record tecs.ecs.phases
    record AllGroups is Phase
    end

    record MainGroup is Phase
    end

    record PreStartup is Phase
    end

    record Startup is Phase
    end

    record PostStartup is Phase
    end

    record StartupGroup is Phase
    end

    record Ingress is Phase
    end

    record First is Phase
    end

    record PreUpdate is Phase
    end

    record FixedFirst is Phase
    end

    record FixedPreUpdate is Phase
    end

    record FixedUpdate is Phase
    end

    record FixedPostUpdate is Phase
    end

    record FixedLast is Phase
    end

    record FixedUpdateGroup is Phase
    end

    record Update is Phase
    end

    record PostUpdate is Phase
    end

    record RenderFirst is Phase
    end

    record PreRender is Phase
    end

    record Render is Phase
    end

    record PostRender is Phase
    end

    record RenderLast is Phase
    end

    record RenderGroup is Phase
    end

    record Last is Phase
    end

    record PreShutdown is Phase
    end

    record Shutdown is Phase
    end

    record PostShutdown is Phase
    end

    record ShutdownGroup is Phase
    end

    index: {Phase}
end

tecs.ecs.phases.AllGroups record#

Contains all phases that make up the ECS lifecycle.

record tecs.ecs.phases.AllGroups is Phase
end

Interfaces

tecs.ecs.phases.MainGroup record#

A meta-phase for the main game loop.

record tecs.ecs.phases.MainGroup is Phase
end

Interfaces

tecs.ecs.phases.PreStartup record#

Runs once at application start for critical initialization (e.g., logging, core systems).

record tecs.ecs.phases.PreStartup is Phase
end

Interfaces

tecs.ecs.phases.Startup record#

Runs once at application start for general initialization (e.g., loading assets, creating entities).

record tecs.ecs.phases.Startup is Phase
end

Interfaces

tecs.ecs.phases.PostStartup record#

Runs once after startup for final setup (e.g., starting gameplay, enabling systems).

record tecs.ecs.phases.PostStartup is Phase
end

Interfaces

tecs.ecs.phases.StartupGroup record#

record tecs.ecs.phases.StartupGroup is Phase
end

Interfaces

tecs.ecs.phases.Ingress record#

Runs once at the start of a logical update for sealed platform and external-service input. Observers run here in event sequence order.

record tecs.ecs.phases.Ingress is Phase
end

Interfaces

tecs.ecs.phases.First record#

Runs at the very start of each frame (e.g., time updates, input polling).

record tecs.ecs.phases.First is Phase
end

Interfaces

tecs.ecs.phases.PreUpdate record#

Runs before the main update (e.g., physics preparation, event processing).

record tecs.ecs.phases.PreUpdate is Phase
end

Interfaces

tecs.ecs.phases.FixedFirst record#

Runs at the start of each fixed timestep iteration (e.g., fixed timer updates).

record tecs.ecs.phases.FixedFirst is Phase
end

Interfaces

tecs.ecs.phases.FixedPreUpdate record#

Runs before fixed update (e.g., collision detection preparation).

record tecs.ecs.phases.FixedPreUpdate is Phase
end

Interfaces

tecs.ecs.phases.FixedUpdate record#

Runs at fixed timestep intervals for deterministic updates (e.g., physics simulation, gameplay logic).

record tecs.ecs.phases.FixedUpdate is Phase
end

Interfaces

tecs.ecs.phases.FixedPostUpdate record#

Runs after fixed update (e.g., collision response, constraint solving).

record tecs.ecs.phases.FixedPostUpdate is Phase
end

Interfaces

tecs.ecs.phases.FixedLast record#

Runs at the end of each fixed timestep iteration (e.g., state synchronization).

record tecs.ecs.phases.FixedLast is Phase
end

Interfaces

tecs.ecs.phases.FixedUpdateGroup record#

record tecs.ecs.phases.FixedUpdateGroup is Phase
end

Interfaces

tecs.ecs.phases.Update record#

Main update phase, runs once per frame for gameplay logic and non-physics updates.

record tecs.ecs.phases.Update is Phase
end

Interfaces

tecs.ecs.phases.PostUpdate record#

Runs after update and before rendering (e.g., animation, transform updates, camera updates).

record tecs.ecs.phases.PostUpdate is Phase
end

Interfaces

tecs.ecs.phases.RenderFirst record#

Runs at the start of rendering (e.g., clearing buffers, setting up render state).

record tecs.ecs.phases.RenderFirst is Phase
end

Interfaces

tecs.ecs.phases.PreRender record#

Runs just before rendering (e.g., culling, sorting, batching).

record tecs.ecs.phases.PreRender is Phase
end

Interfaces

tecs.ecs.phases.Render record#

Main rendering phase (e.g., drawing sprites, meshes, UI).

record tecs.ecs.phases.Render is Phase
end

Interfaces

tecs.ecs.phases.PostRender record#

Runs just after rendering (e.g., post-processing effects, screen transitions).

record tecs.ecs.phases.PostRender is Phase
end

Interfaces

tecs.ecs.phases.RenderLast record#

Runs at the end of rendering (e.g., presenting frame, GPU synchronization).

record tecs.ecs.phases.RenderLast is Phase
end

Interfaces

tecs.ecs.phases.RenderGroup record#

record tecs.ecs.phases.RenderGroup is Phase
end

Interfaces

tecs.ecs.phases.Last record#

Runs at the very end of each frame (e.g., cleanup, metrics collection, frame timing).

record tecs.ecs.phases.Last is Phase
end

Interfaces

tecs.ecs.phases.PreShutdown record#

Runs just before shutdown (e.g., saving game state, closing connections).

record tecs.ecs.phases.PreShutdown is Phase
end

Interfaces

tecs.ecs.phases.Shutdown record#

Main shutdown phase (e.g., releasing resources, destroying entities).

record tecs.ecs.phases.Shutdown is Phase
end

Interfaces

tecs.ecs.phases.PostShutdown record#

Runs after shutdown for final cleanup (e.g., logging shutdown metrics, final cleanup).

record tecs.ecs.phases.PostShutdown is Phase
end

Interfaces

tecs.ecs.phases.ShutdownGroup record#

record tecs.ecs.phases.ShutdownGroup is Phase
end

Interfaces

tecs.ecs.phases.index field#

Read-only. Maps each lifecycle position to its phase definition.

tecs.ecs.phases.index: {Phase}

tecs.ecs.Pipeline interface#

Pipeline identifies a world update pipeline.

interface tecs.ecs.Pipeline
    count: integer
    fixedTimestep: number
    fixedAccumulator: number
    fixedStepCount: integer
    fixedMaxSteps: integer
    fixedOverload: FixedOverload
    fixedTimeDropped: number
    fixedStepsDropped: integer

    addSystem: function(self, config: SystemConfig)
    disablePhase: function(self, phase: Phase)
    enablePhase: function(self, phase: Phase)
    listSystems: function(self): {SystemInfo}
    registerPhase: function(self, phase: Phase)
    removeSystem: function(self, systemName: string)
    run: function(self, phase: Phase, dt: number, world: World)
    setSystemEnabled: function(
        self, systemName: string, enabled: boolean
    ): boolean, string
    update: function(self, dt: number, world: World)
end

tecs.ecs.Pipeline.count field#

Read-only. The number of systems in the pipeline.

tecs.ecs.Pipeline.count: integer

tecs.ecs.Pipeline.fixedTimestep field#

Read-only. The fixed timestep interval in seconds (e.g., 1/60 for 60Hz physics).

tecs.ecs.Pipeline.fixedTimestep: number

tecs.ecs.Pipeline.fixedAccumulator field#

Read-only. Accumulated time not yet consumed by fixed updates. Use with fixedTimestep to compute interpolation alpha: accumulator / timestep.

tecs.ecs.Pipeline.fixedAccumulator: number

tecs.ecs.Pipeline.fixedStepCount field#

Read-only. Fixed steps run since the pipeline was made.

tecs.ecs.Pipeline.fixedStepCount: integer

tecs.ecs.Pipeline.fixedMaxSteps field#

Read-only. The most fixed steps one update will run before the overload policy decides what happens to the rest. Defaults to 10.

tecs.ecs.Pipeline.fixedMaxSteps: integer

tecs.ecs.Pipeline.fixedOverload field#

Read-only. What happens to the time those steps would have consumed. Defaults to "drop".

tecs.ecs.Pipeline.fixedOverload: FixedOverload

tecs.ecs.Pipeline.fixedTimeDropped field#

Read-only. Simulated seconds abandoned by the "drop" policy since the pipeline was made. Stays at zero under "accumulate", which abandons nothing, and stays at zero on a machine that keeps up.

Read it. A simulation, a replay or anything networked is wrong by exactly this much, and nothing else in the world says so.

tecs.ecs.Pipeline.fixedTimeDropped: number

tecs.ecs.Pipeline.fixedStepsDropped field#

Read-only. Fixed steps that were owed and never ran, on the same terms. Whole steps only: fixedTimeDropped is this many timesteps, because a drop leaves the sub-step remainder alone rather than resetting the interpolation alpha along with it.

tecs.ecs.Pipeline.fixedStepsDropped: integer

tecs.ecs.Pipeline:addSystem Instance#

Add a system to the pipeline.

function tecs.ecs.Pipeline.addSystem(self, config: SystemConfig)

Arguments

Returns

None.

tecs.ecs.Pipeline:disablePhase Instance#

Disable a phase.

function tecs.ecs.Pipeline.disablePhase(self, phase: Phase)

Arguments

Returns

None.

tecs.ecs.Pipeline:enablePhase Instance#

Enable a phase.

function tecs.ecs.Pipeline.enablePhase(self, phase: Phase)

Arguments

Returns

None.

tecs.ecs.Pipeline:listSystems Instance#

Reports every system the pipeline holds.

function tecs.ecs.Pipeline.listSystems(self): {SystemInfo}

Arguments

Returns

tecs.ecs.Pipeline:registerPhase Instance#

Register a custom phase with the pipeline.

function tecs.ecs.Pipeline.registerPhase(self, phase: Phase)

Arguments

Returns

None.

tecs.ecs.Pipeline:removeSystem Instance#

Remove a system from the pipeline.

function tecs.ecs.Pipeline.removeSystem(self, systemName: string)

Arguments

Returns

None.

tecs.ecs.Pipeline:run Instance#

Run a specific phase.

function tecs.ecs.Pipeline.run(
    self, phase: Phase, dt: number, world: World
)

Arguments

Returns

None.

tecs.ecs.Pipeline:setSystemEnabled Instance#

Enables or disables one system, leaving it registered either way.

function tecs.ecs.Pipeline.setSystemEnabled(
    self, systemName: string, enabled: boolean
): boolean, string

Arguments

Returns