tecs.ecs

The entity component system shared by game code and engine systems.

The ECS exposes staged entity lifetime, tag and scalar components, dense archetype storage, and reusable queries. A spawn reserves its id immediately, and commit publishes structural changes.

Declaring components#

Derive tecs.ecs.Component on a record or struct, use its declaration in queries, and supply ordinary new values to mutations. Structs select native columns; records select managed columns. Names default to the module-qualified declaration name. @component(name = "game.Velocity") pins a persisted name across declaration or namespace changes; @component(transient = true) omits snapshot values.

Native components store Nupp structs inline in contiguous native columns. Nupp owns the struct layout and methods. Tecs owns column capacity, publication and dirty tracking. There is no generated parallel C schema and no row wrapper in the query loop. A native column grows geometrically with a single memory copy; bulk spawns reserve the whole destination range before calling their writer.

@derive(tecs.ecs.Component, nupp.derive.Debug, nupp.derive.Serde)
local struct Velocity
    x: number = 0
    y: number = 0
end
local world = tecs.ecs.newWorld()
world:batchSpawn(1000, {Velocity})
world:commit()
for candidate, count in world:newQuery({include = {Velocity}}):iter() do
    local column = assert(candidate:getMut(Velocity))
    unsafe do
        for row = 1, assert(count) do column[row].x += 1 end
    end
end

Built-in transforms, tint, shape material, camera, lights, animation, sound, physics values and numeric UI components use this storage and derive nupp.derive.Debug and nupp.derive.Serde. Derived methods work on constructed values and borrowed rows without changing column layout. Use nupp.serde.json():prepare(nupp.serde.of(Velocity)) for a typed JSON codec; Nupp's separate nupp.derive.JSON provider currently admits records only. Generic Serde encoding describes physical component fields, whereas world snapshots use the component's registered codecs. Asset-bearing built-ins keep their custom name-based codecs and never persist process-local IDs as assets.

get and getMut return T[?] for a native component, and the existing managed array for a table or scalar component. Native rows use the same one-based indices as the query's entity list; row zero is padding. Use the query count, not #column, pairs, ipairs, or table library operations on a native column. Direct C-array indexing requires Nupp's unsafe scope. world:get still returns one typed struct value, and world:getMut marks the owning column dirty first.

Native column assignments copy bytes, including inline fixed arrays. Entities never share these inline rows, even when they receive the same constructed input or requirement. Struct values returned by reads are live row references, not owned copies. Column views and row references expire at the next structural publication, compaction, clear, or snapshot restore. Reacquire them afterwards. Never retain a native row reference across such a boundary or use commit inside its loop.

Automatic codecs support numeric and boolean fields and fixed arrays of those types. Nested structs and pointers are also supported with custom codecs or transient = true; their owners must keep pointed-to storage alive. Unions, bitfields and variable arrays are rejected. Never persist process-local pointer addresses. Table snapshots have automatic field codecs; arrays are saved one-based and signed/unsigned 64-bit integers are saved as exact decimal strings. Optional save and either load or world-aware deserialize hooks must be supplied together. They replace automatic codecs and disable native raw encoding in both directions so custom behavior is never silently bypassed. Transient and required components follow the ordinary ECS rules. Binary snapshots copy eligible native columns directly and migrate older scalar layouts using their saved field fingerprints.

Derive tecs.ecs.Relationship on a target-bearing record or struct. Optional @relationship settings configure its name, exclusivity, sparse placement, reverse indexing, cascades and transient snapshot policy. Use tecs.ecs.targeting(EdgeType, target) for a dense target-specific selector. Native relationships use the same field policy and support exclusive or multiple targets, reverse lookup, cascades and sparse or dense edge placement. Its struct must contain a target: number field. Dense targeting() selectors return native columns. A wildcard relationship column is a managed array of references to its first native edge, not another copy of that edge. Sparse edge lists likewise retain native values. Changes through wildcard, target-specific and relationship-iteration access therefore reach the same payload. Sparse relationships retain constructed edge objects. Reusing one edge instance for several sources shares that payload; construct separate instances for independent values and mark every affected source dirty after mutating a deliberately shared payload.

Component requirements#

Every component factory accepts requires, including scalar components and both relationship factories. A requirement is a component definition or a constructed tecs.ecs.ComponentInput. Definitions use their default value when a missing column is initialized; record default factories run separately for each entity. Constructed instances supply shared values instead, including across bulk operations. Their outer records are not copied. Treat these shared records as immutable or explicitly mark every affected entity dirty after an external write.

local health = tecs.ecs.newScalarComponent({
    name = "game.Health", kind = "number", default = 100,
})
local enemy = tecs.ecs.newTagComponent({
    name = "game.Enemy", requires = {health(50), tecs.ecs.Transform2D},
})
local world = tecs.ecs.newWorld()
local id = world:spawn(enemy)
world:commit()
assert(world:get(id, health) == 50)

Requirements expand transitively into the same staged archetype transition. spawn, spawnAt, bundles, bulk spawns, set and batchSet all apply them. They are initialized before membership callbacks and bulk writers observe the new columns. Explicit spawn inputs and already-present components keep their values, including values staged earlier in the same transaction. A definition explicitly passed to spawn uses its own default instead of a required instance.

Tecs copies requirement lists at registration and caches their transitive closures. Traversal is breadth-first in declaration order and deduplicates by component identity; the first encountered requirement for a component wins. Cycles terminate without repeating the root component. Multiple explicit spawn components expand in argument order after all explicit inputs are collected.

Requirements are addition rules, not permanent invariants. Replacing a value, adding an unrelated component, or adding another target to an existing relationship does not restore deliberately removed requirements. Removing a component leaves its requirements in place. Removing and re-adding it expands its closure again. Snapshot restore follows spawnAt: it reapplies requirements missing from saved data, including defaults for omitted transient components.

A required relationship must be a constructed, target-bearing instance, not a bare relationship definition. It participates in dense target matching, reverse lookup and cascade deletion just like an explicitly added edge. Target ids in a process-wide requirement must be meaningful in every world using that component. All requirements of an edge apply to its source, not its target. An existing relationship takes precedence over a required edge to that relationship.

Query membership#

Queries exclude Disabled unless their include list explicitly requests it. Setting type = "logic" also excludes Paused, with the same explicit-include override. include requires every component, includeAny requires at least one, and exclude rejects any listed component. The world copies these lists.

local moving = world:newQuery({
    type = "logic",
    include = {tecs.ecs.Transform2D},
    exclude = {tecs.ecs.ChildOf},
})
for candidate, count, entities in moving:iter() do
    local transforms = assert(candidate:getMut(tecs.ecs.Transform2D))
    unsafe do
        for row = 1, count do
            transforms[row].x = transforms[row].x + 1
        end
    end
end

groupBy assigns an integer group once per matching archetype. iter() visits groups in ascending order, groups() yields nonempty groups, and group(id) visits one group's archetypes. count() and getGroupCount(id) read current entity counts. Iterators are independent and can be nested.

onEntitiesAdded receives the initial matching rows and subsequent entries. onEntitiesRemoved receives departing rows before removal. Both callbacks take (archetype, firstRow, lastRow, count) with one-based inclusive bounds. Moves between two matching archetypes do not fire either callback. A callback may stage mutations; the active commit drains them after the current publication. Changing fields on an existing component is not a membership change.

temp = true freezes the matched archetype set at construction, while reading its live rows. Temporary queries do not subscribe to new archetypes and cannot declare membership callbacks. Structural changes remain staged until a barrier, so leaving an iterator early requires no cleanup. Do not call commit inside an active query iteration.

Relationship storage#

newRelationship constructs target-only edges. Relationships are non-exclusive and dense by default. exclusive = true replaces a source's previous edge. Otherwise setting an existing target replaces that edge and preserves the others. sparse = true stores edges by entity without creating a distinct archetype for each target set. Dense relationships expose relationship:targeting(entity) for include/exclude constraints and direct access to one target's column.

local follows = tecs.ecs.newRelationship({
    name = "game.Follows", reverseIndex = true,
})
local leader = world:spawn()
local other = world:spawn()
local follower = world:spawn(follows(leader), follows(other))
world:commit()
local followers = world:newQuery({include = {follows:targeting(leader)}})
world:remove(follower, follows(other))
world:commit()

Remove a relationship definition to remove every edge; pass an instance to remove just its target, for either storage mode. get and getFirstRelationship return the first edge in ascending target order. forEachRelationship visits every edge in that order. Its archetype counterpart takes a one-based row. Edge values are live; use getMut before changing payload fields. Never write an edge's target field directly: set maintains the signature and reverse index.

newRelationship(EdgeType, options) creates an explicit payload relationship. Its constructor receives the target first and returns a value with that same target field. Automatic codecs preserve the top-level declared type; custom codecs handle resource identities or nested managed types. RelationshipDefinition<T> retains T through world reads, iteration and targeted column access. Snapshots store relationship names and edges, independent of generated dense target-component identifiers.

newComponent(ValueType, options) and newRelationship(EdgeType, options) create distinct named definitions from one value declaration. When the type derives the ECS contract, its initializer supplies construction and defaults. A type without that derive supplies explicit construction factories and a name. Registration uses the type witness without running a constructor or default factory. Custom codecs, world-aware decoding and requirements belong in these options. Calling a factory with a derived type's default name registers that type's definition; a different name creates an independent identity whose values must be supplied through the returned factory.

reverseIndex = true enables relationshipSources, callback-based targets, and depth-first traverse. Traversal excludes its root, reports direct children at depth zero and visits each identifier at most once. walkUp follows the first edge at each level, reports the direct parent at depth one, and raises on cycles or its default depth limit of 100. Return false from its callback to stop early. cascadeDelete = true requires an exclusive, reverse-indexed relationship. Destruction then removes the descendants in the same publication barrier. For a reverse-indexed dense relationship without cascading, deleting a target removes just that target's incoming edges. Non-cascading sparse edges retain the target identifier until explicitly removed; always check isAlive before using such a target as a live entity.

Bulk mutations and maintenance#

batchSpawn(count, inputs, callback?) reserves a shared signature once and publishes its rows at the next barrier. It returns (firstId, nil) only when every packed identity is contiguous; otherwise it returns (nil, ids). Use the explicit list in that case, including after recycling slots or clearing a world whose used prefix and fresh suffix carry different generations. batchSpawnAt validates all supplied identities before reserving them, for restoration work. Like spawnAt, it does not add the active state's automatic tag. batchSpawnAtRaw(ids, count, inputs, callback?) reads a zero-based native double array without materializing an ID list. The world retains the array until publication; its selected prefix must not change before that barrier. This restoration path also permits initializing EntityKey before index registration.

local firstId, ids = world:batchSpawn(100, {tecs.ecs.Transform2D},
    function(candidate: tecs.ecs.Archetype, first: integer, last: integer)
        local transforms = assert(candidate:getMut(tecs.ecs.Transform2D))
        unsafe do
            for row = first, last do
                transforms[row].x = row * 10
            end
        end
    end
)
world:commit()

Initializers receive (archetype, firstRow, lastRow, count) with one-based inclusive bounds, after placement but before query-entry and spawn events. Cancelled spawns receive no rows or events. Later set and remove calls on reserved IDs apply after initialization. A batch takes explicit relationship values such as ChildOf(parent), not a bare relationship without a target. Never overwrite relationship targets through a column; stage per-entity set calls when targets vary. Ordinary batch spawn signatures cannot contain EntityKey, including through requirements; assign keys individually with set.

batchSet(query, value) and batchRemove(query, componentOrRelationshipValue) stage changes for the query's committed members at the call. batchDespawn(query) uses normal lifecycle events, observer cleanup and relationship cascading. Queries must belong to the same world; temporary queries are supported. New members that arrive later in the transaction are not retroactively selected. Query state filters apply, so include Disabled explicitly when selecting it.

batchSet(query, Component, callback) ensures a plain component exists and invokes the writer at the barrier, once per contiguous affected row range. Writers use getMut, see earlier staged writes, and precede later scalar writes. Entries into queries that require the added component see initialized values. Callback mode rejects instances and relationships; constant mode supports edges. Bulk setting EntityKey is rejected because a shared value cannot claim distinct keys. Explicit record constants get independent shallow outer copies, retaining their record type; nested references remain shared. Instance-valued requirements remain shared. Default factories run per entity.

Bulk storage paths operate on compact batch descriptors and native slot stamps. A contiguous spawn allocates no identity list or per-entity transaction records. Plain whole-archetype moves exchange common column buffers when the destination is empty and copy native ranges when it is populated; plain deletion truncates storage once. Relationships, durable keys and selections changed by earlier publication use the per-entity behavior where needed. Query batches retain native identity snapshots to preserve membership at the call. Reacquire column views after publication, including a buffer exchange.

All operations remain deferred. Callback boundaries preserve call order inside the transaction; they do not publish early from the API call. A callback can stage further work for the same commit to drain, but cannot clear or compact the world during publication. As with scalar mutations, a callback failure is not an atomic rollback of already published rows.

forEachArchetype includes empty and disabled archetypes. dirtyArchetypes() captures an independent iterator over the queue in first-dirtied order, including empty ones changed by removal. Dirty marks clear at the end of update. findArchetypes(Component) uses the component index, including empty matches. getStats(fill) updates a caller-owned statistics record without allocating one.

Entity IDs occupy contiguous native double columns. Their exact length remains available through #entities; row zero holds that length. Use indexed numeric loops, not table-library functions or ipairs, and treat the column as read-only. Persistent queries maintain active-only lists through lifecycle notifications. iter, group and groups return reusable generic-for functions, their state and an initial cursor. They allocate no per-iteration closure and support nested and interleaved traversal. Manual stepping must pass that state and prior result.

Observe ArchetypeCreated at address zero to attach addEntityObserver callbacks before an archetype's first publication. Added and removed ranges are one-based; swap-pop onEntityMove positions are zero-based. Added callbacks see initialized values, removed callbacks can still read departing rows, and moves identify the opposite archetype. Activation, deactivation and destruction are also observable.

structuralDescribed(previousCount) reports whether bounded row residue covers a consumer's structural count. structuralAdded() identifies an appended suffix; structuralTouched() returns a borrowed list and count of swap-pop overwrites. A false description requires a full refresh. trackValueCount(Component) opts a column into the aggregate valueCount() counter; structural writes do not increment that counter. archetype:set(row, instance) replaces an existing value and marks it dirty, but cannot change relationship membership.

Call compact() outside dispatch on a committed world. It prunes empty dense relationship archetypes with dead target identities, releases their persistent query/group entries, and reuses freed archetype IDs without renumbering survivors. Ordinary empty archetypes and the empty-signature sentinel remain registered. It also rebuilds row tables whose occupancy has fallen since their high-water mark. The returned counts are (pruned, rebuilt); the second counts rebuilt stores, not bytes reclaimed or an exposed native capacity. Component values, dirty flags, systems and persistent queries survive. Reacquire column/entity views after compaction, and do not compact or commit inside an active iterator. An explicitly retained temporary query can keep an old empty archetype object alive, but it will not adopt a new archetype that later reuses the same ID.

World-managed random streams#

world:randomStream(name) returns a nupp.random.Random owned by the world. The world seed and the non-empty stream name determine its sequence, independently of which other streams exist or how many values they draw. Repeated calls return the same generator. Use namespaced names and capture streams during setup.

local world = tecs.ecs.newWorld()
world:seedRandom(42)
local loot = world:randomStream("game.loot")
local roll = loot:integer(1, 20)
local saved = world:saveSnapshot()
local expected = loot:next()
world:loadSnapshot(saved)
assert(loot:next() == expected)

The initial world seed is the fixed value 0x5EED1234, not a clock reading. seedRandom(seed) reads a 32-bit word and restarts all existing streams in place; future streams derive their seeds from the new world seed too. Drawing, shuffling, ranges and individual state access use Nupp's generator methods directly. Independent generators outside a world use nupp.random.newRandom. Generators are mutable and must not be shared across concurrent workers.

The first stream or seed call enables snapshot persistence under tecs.random. This reserved key, its {seed, streams} payload and the byte-based name-to-seed mapping are persistence contracts. Each saved stream contains four signed 32-bit state words. Saving neither advances the generators nor leaves a live view into them.

Loading a snapshot restores already-captured generators in place, creates saved streams not yet requested, and restarts existing streams absent from the save using the restored world seed. A fresh world needs no initialization call before loading saved random data. Random state restores after entity publication and before custom snapshot handlers run. Malformed random payloads raise before the world clears entities or changes generators. Unsigned 32-bit saved words are accepted and normalized too.

A snapshot without tecs.random leaves current streams and the seed unchanged. Clearing entities also leaves them alone. Runtime closures such as timer predicates are not snapshot state: giving runif.every a world stream restores its future random draws, but does not rewind the timer's elapsed time. The tecs.random key cannot be supplied through custom data or a snapshot handler. Installing audio uses the tecs.audio stream for pitch variance automatically; standalone mixers retain their own independent Nupp generators.

System scheduling#

registerPhase({name = "game.Custom"}) registers a custom leaf; children makes an ordered tree of registered names. position selects its inspection-registry position, not automatic execution in the default frame. Run the tree explicitly with runPhase, or provide WorldConfig.pipelineFactory to replace scheduling. The custom Pipeline receives the world's task scope, owns system ordering and phase barriers, and receives all registration, phase-control and inspection calls. Its fixed remainder and phase-enabled flags participate in snapshots.

addSystem accepts before and after lists of system names. Constraints apply only within one leaf phase; missing names and names in other phases contribute no edge. Self references are ignored and duplicate edges count once. Among systems whose dependencies are satisfied, the earliest registered runs first. Disabled systems retain their position and ordering edges.

The world copies constraint lists. It rebuilds the schedule after registration changes, validating every phase before the next dispatch publishes staged work or runs any system. A cycle raises with its phase and blocked system names. listSystems() reports dependency order and also raises for a cycle. Remove a conflicting system to repair the schedule; enabling or disabling cannot repair it.

An update, startup, shutdown or explicit runPhase captures one schedule at its entry. A system added during that dispatch starts on the next external dispatch, even if its phase has not run yet. Removal and enable/disable changes affect remaining dispatches immediately. Listing during a dispatch describes the next schedule without changing the active one. Ordering does not introduce structural barriers: request commitBefore or commitAfter when a same-phase dependency also requires publication of staged entities.

Call world:enqueueCommit() when that extra barrier is conditional on work performed by a system. Requests from its body or runIf predicate coalesce into one publication after the body returns, or after a false predicate skips it, before the next system runs. Suspension does not end the system: its query view stays unchanged until it returns. Requests alone never publish midway through iteration. A publication callback may request another commit without recursion; the active drain includes its staged work.

Outside a running system, enqueueCommit() publishes synchronously, including child work settling after dispatch. Leave any query iterator before calling it there. Explicit commit() remains synchronous even inside a system. If a body or predicate raises, the dispatcher clears its request without introducing a barrier during unwinding; pending mutations remain staged for a later commit. Publication failures retain already published rows and discard unpublished work, as with any other commit failure.

world:addSystem({
    name = "game.SpawnWave",
    phase = tecs.ecs.phases.Update,
    before = {"game.MoveEnemies"},
    commitAfter = true,
    runIf = tecs.ecs.runif.both(
        tecs.ecs.runif.inState("game"),
        tecs.ecs.runif.every(2)
    ),
    run = spawnWave,
})

tecs.ecs.runif provides after, every, cooldown, inState, both, either and negate. Timers consume the phase delta only when evaluated. after removes its system before its one allowed run; every retains excess elapsed time but fires at most once per dispatch; cooldown starts ready and discards excess time when firing. Each timer factory creates state for one system. Reusing a predicate shares that state. Timer closures are not snapshots.

Combinators short-circuit, including their operands' side effects. The example pauses its timer outside game; swapping the operands keeps the timer advancing and spends ticks outside that state. A disabled system or phase never evaluates its predicates. Use every(interval, jitter, generator) for jitter, supplying a nupp.random.Random directly. The first interval is unjittered and later intervals clamp to one percent of the base interval. Pass a named world stream to snapshot its random state; there is no implicit stream or automatic timer rewind when an entity snapshot is restored.

function newComponent<T>(witness: Type<T>, options: ComponentOptions<T>?): ComponentDefinition<T>

function newTagComponent(options: TagComponentOptions): Component

function newWorld(config: WorldConfig?): World

record Archetype
    id: integer
    signature: string
    componentIds: {[integer]: boolean}
    components: {components.Component}
    entities: entitycolumn.DoubleArray
    columns: {[integer]: any}
    addEntityObserver: function(self: Archetype, observer: EntityObserver): nil
    structuralDescribed: function(self: Archetype, count: integer): boolean
    structuralAdded: function(self: Archetype): integer
    structuralTouched: function(self: Archetype): ({integer}, integer)
    valueCount: function(self: Archetype): integer
    trackValueCount: function(self: Archetype, component: components.Selector): nil
    set: function(self: Archetype, row: integer, input: components.Input): nil

    get: (function<C is components.Component>(self: Archetype, component: C): C.Column?)
        & (function<T is derived.Value>(self: Archetype, component: Type<T>): derived.Column(T, derived.Edge)?)
    getMut: (function<C is components.Component>(self: Archetype, component: C): C.Column?)
        & (function<T is derived.Value>(self: Archetype, component: Type<T>): derived.Column(T, derived.Edge)?)
    isComponentDirty: function(self: Archetype, component: components.Selector): boolean
    anyComponentDirty: function(self: Archetype): boolean
    markComponentDirty: function(self: Archetype, component: components.Selector): nil
    markAllComponentsDirty: function(self: Archetype): nil
    clearDirtyComponents: function(self: Archetype): nil
    dirtyComponents: function(self: Archetype): function(): components.Component?
    structuralCount: function(self: Archetype): integer
    writeCount: function(self: Archetype, component: components.Selector): integer
    forEachRelationship: (
        function<C is components.Component>(
            self: Archetype,
            relationship: C,
            row: integer,
            callback: function(value: C.Value)
        ): nil
    )
        & (
        function<T is derived.Edge>(
            self: Archetype,
            relationship: Type<T>,
            row: integer,
            callback: function(value: T)
        ): nil
    )
    getFirstRelationship: (
        function<C is components.Component>(self: Archetype, relationship: C, row: integer): C.Value?
    )
        & (function<T is derived.Edge>(self: Archetype, relationship: Type<T>, row: integer): T?)
end

addEntityObserver: function(self: Archetype, observer: EntityObserver): nil

structuralDescribed: function(self: Archetype, count: integer): boolean

structuralAdded: function(self: Archetype): integer

structuralTouched: function(self: Archetype): ({integer}, integer)

valueCount: function(self: Archetype): integer

trackValueCount: function(self: Archetype, component: components.Selector): nil

set: function(self: Archetype, row: integer, input: components.Input): nil

isComponentDirty: function(self: Archetype, component: components.Selector): boolean

anyComponentDirty: function(self: Archetype): boolean

markComponentDirty: function(self: Archetype, component: components.Selector): nil

markAllComponentsDirty: function(self: Archetype): nil

clearDirtyComponents: function(self: Archetype): nil

dirtyComponents: function(self: Archetype): function(): components.Component?

structuralCount: function(self: Archetype): integer

writeCount: function(self: Archetype, component: components.Selector): integer

id: integer

signature: string

componentIds: {[integer]: boolean}

components: {components.Component}

entities: entitycolumn.DoubleArray

columns: {[integer]: any}

get: (function<C is components.Component>(self: Archetype, component: C): C.Column?)
& (function<T is derived.Value>(self: Archetype, component: Type<T>): derived.Column(T, derived.Edge)?)

getMut: (function<C is components.Component>(self: Archetype, component: C): C.Column?)
& (function<T is derived.Value>(self: Archetype, component: Type<T>): derived.Column(T, derived.Edge)?)

forEachRelationship: (
    function<C is components.Component>(
        self: Archetype,
        relationship: C,
        row: integer,
        callback: function(value: C.Value)
    ): nil
)
    & (
    function<T is derived.Edge>(
        self: Archetype,
        relationship: Type<T>,
        row: integer,
        callback: function(value: T)
    ): nil
)

getFirstRelationship: (
    function<C is components.Component>(self: Archetype, relationship: C, row: integer): C.Value?
)
    & (function<T is derived.Edge>(self: Archetype, relationship: Type<T>, row: integer): T?)

record ArchetypeCreated
    archetype: archetype.Archetype
end

archetype: archetype.Archetype

interface ArchetypeEntityObserver
    onEntitiesAdded: (
        function(
            self: EntityObserver,
            value: Archetype,
            first: integer,
            last: integer,
            count: integer,
            source: Archetype?
        )
    )?
    onEntitiesRemoved: (
        function(
            self: EntityObserver,
            value: Archetype,
            first: integer,
            last: integer,
            count: integer,
            target: Archetype?
        )
    )?
    onEntityMove: (function(self: EntityObserver, value: Archetype, entity: integer, fromRow: integer, toRow: integer))?
    onActivated: (function(self: EntityObserver, value: Archetype))?
    onDeactivated: (function(self: EntityObserver, value: Archetype))?
    onArchetypeDestroyed: (function(self: EntityObserver, value: Archetype))?
end

onEntitiesAdded: (
    function(
        self: EntityObserver,
        value: Archetype,
        first: integer,
        last: integer,
        count: integer,
        source: Archetype?
    )
)?

onEntitiesRemoved: (
    function(
        self: EntityObserver,
        value: Archetype,
        first: integer,
        last: integer,
        count: integer,
        target: Archetype?
    )
)?

onEntityMove: (function(self: EntityObserver, value: Archetype, entity: integer, fromRow: integer, toRow: integer))?

onActivated: (function(self: EntityObserver, value: Archetype))?

onDeactivated: (function(self: EntityObserver, value: Archetype))?

onArchetypeDestroyed: (function(self: EntityObserver, value: Archetype))?

type BatchCallback = function(
    candidate: archetype.Archetype,
    firstRow: integer,
    lastRow: integer,
    count: integer
)

record Bundle
    name: string
    required: {string}
    defaulted: {string}

    spawn: function(self: Bundle, ...: components.Input): integer
end

spawn: function(self: Bundle, ...: components.Input): integer

name: string

required: {string}

defaulted: {string}

type BundleDefinition = {
    required: {components.Selector}?,
    with: {[components.Selector]: true | BundleFactory}?
}

interface Component
    associated type Value = self
    associated type Column = {self.Value}

    componentId: integer
    componentName: string
    storageType: string
    transient: boolean
end

Value: associatedDecl

Column: associatedDecl

componentId: integer

componentName: string

storageType: string

transient: boolean

record component
    name: string?
    transient: boolean?
end

name: string?

transient: boolean?

interface ComponentDefinition<T> is Component
    associated type Value == T
    associated type Column == derived.StorageColumn(T)
    construct: function(...: any): T
    defaultFactory: function(): T
    snapshotSave: function(value: T): any
    snapshotLoad: function(value: any, exclusive world: any): T
    metamethod __call: function(self, ...: any): FFIInstance<T, TypedComponent<T>>
end

construct: function(...: any): T

defaultFactory: function(): T

snapshotSave: function(value: T): any

snapshotLoad: function(value: any, exclusive world: any): T

__call: function(self, ...: any): FFIInstance<T, TypedComponent<T>>

Value: associatedDecl

Column: associatedDecl

type ComponentInput = Component
| Type<derived.Value>
| derived.Value
| ScalarInstance<any>
| TableInstance<any>
| FFIInstance<any, any>
| RelationshipInstance
| RelationshipBatch

type ComponentOptions<T> = {
    --- Caller-writable. Sets the persisted identity; defaults to the derived name.
    name: string?,

    --- Caller-writable. Overrides the declaration's initializer for factory calls.
    construct: (function(...: any): T)?,

    --- Caller-writable. Overrides per-entity default initialization.
    default: (function(): T)?,

    --- Caller-writable. Omits this definition's values from snapshots.
    transient: boolean?,

    --- Caller-writable. Adds missing components or shared instances transitively.
    requires: {ComponentInput}?,

    --- Caller-writable. Replaces automatic encoding; pair with load or deserialize.
    save: (function(value: T): any)?,

    --- Caller-writable. Reconstructs a saved value; excludes deserialize.
    load: (function(value: any): T)?,

    --- Caller-writable. Reconstructs a value with the destination world; excludes load.
    deserialize: (function(exclusive world: World, value: any): T)?
}

sealed interface ComponentValue
end

type DoubleArray = DoubleArray2

type EdgeOptions<T> = {
    --- Caller-writable. Sets the persisted identity; defaults to the derived name.
    name: string?,

    --- Caller-writable. Constructs an edge from its target and optional payload
    --- arguments.
    construct: (function(target: integer, ...: any): T)?,

    --- Caller-writable. Omits this definition's edges from snapshots.
    transient: boolean?,

    --- Caller-writable. Adds missing components or shared instances transitively.
    requires: {ComponentInput}?,

    --- Caller-writable. Replaces automatic encoding; pair with load or deserialize.
    save: (function(value: T): any)?,

    --- Caller-writable. Reconstructs a saved edge; excludes deserialize.
    load: (function(value: any): T)?,

    --- Caller-writable. Reconstructs an edge with the destination world; excludes load.
    deserialize: (function(exclusive world: World, value: any): T)?,

    --- Caller-writable. Limits each source to one target when true.
    exclusive: boolean?,

    --- Caller-writable. Selects entity-indexed edges instead of dense target columns.
    sparse: boolean?,

    --- Caller-writable. Maintains target-to-source lookup when true.
    reverseIndex: boolean?,

    --- Caller-writable. Deletes sources with their target; requires reverseIndex and
    --- exclusive.
    cascadeDelete: boolean?
}

type EntityLifecycle = OnSpawn | OnDespawn

record FinishSnapshotLoad
    prelude: SnapshotPrelude
end

prelude: SnapshotPrelude

type FixedOverload = "drop" | "accumulate"

type NewRelationship = (function(options: RelationshipOptions): Relationship)
& (function<T>(witness: Type<T>, options: EdgeOptions<T>?): RelationshipDefinition<T>)

record OnDespawn
    entity: integer
    source: archetype.Archetype
    row: integer
    requestedDespawns: {integer}
    function get<C is components.Component>(borrows self: OnDespawn, component: C): C.Value? end

    function despawn(self: OnDespawn, entity: integer): nil end
end

get: function get<C is components.Component>(borrows self: OnDespawn, component: C): C.Value?

despawn: function despawn(self: OnDespawn, entity: integer): nil

entity: integer

source: archetype.Archetype

row: integer

requestedDespawns: {integer}

record OnSnapshotSave
    data: {[string]: any}
    excluded: {components.Component}
    function addData(self: OnSnapshotSave, key: string, value: any): nil end

    function exclude(self: OnSnapshotSave, component: components.Selector): nil end
end

addData: function addData(self: OnSnapshotSave, key: string, value: any): nil

exclude: function exclude(self: OnSnapshotSave, component: components.Selector): nil

data: {[string]: any}

excluded: {components.Component}

record OnSpawn
    entity: integer
end

entity: integer

type Phase = string

type PhaseDefinition = {
    --- Caller-writable. Supplies a nonempty stable system-inspection name.
    name: string,

    --- Caller-writable. Selects the registry position; nil appends after existing
    --- positions.
    position: integer?,

    --- Caller-writable. Lists already registered child names; nil declares a leaf.
    children: {string}?
}

type PhaseGroup = "StartupGroup"
| "FixedUpdateGroup"
| "RenderGroup"
| "MainGroup"
| "ShutdownGroup"
| "AllGroups"

type PhaseSelection = Phase | PhaseGroup

interface Pipeline
    count: integer
    fixedTimestep: number
    fixedMaxSteps: integer
    fixedOverload: FixedOverload
    fixedAccumulator: number
    fixedStepCount: integer
    fixedTimeDropped: number
    fixedStepsDropped: integer
    phaseStates: {boolean}
    update: function(self: Pipeline, dt: number, exclusive world: World, borrows scope: tasks.Scope): nil
    run: function(
        self: Pipeline,
        phase: phases.Selection,
        dt: number,
        exclusive world: World,
        borrows scope: tasks.Scope
    ): nil
    addSystem: function(self: Pipeline, config: SystemConfig): string
    removeSystem: function(self: Pipeline, name: string): boolean
    listSystems: function(self: Pipeline): {SystemInfo}
    setSystemEnabled: function(self: Pipeline, name: string, enabled: boolean): (boolean, string?)
    enablePhase: function(self: Pipeline, phase: phases.Selection): nil
    disablePhase: function(self: Pipeline, phase: phases.Selection): nil
    isPhaseEnabled: function(self: Pipeline, phase: phases.Phase): boolean
    registerPhase: function(self: Pipeline, phase: phases.Definition): nil
end

update: function(self: Pipeline, dt: number, exclusive world: World, borrows scope: tasks.Scope): nil

run: function(
    self: Pipeline,
    phase: phases.Selection,
    dt: number,
    exclusive world: World,
    borrows scope: tasks.Scope
): nil

addSystem: function(self: Pipeline, config: SystemConfig): string

removeSystem: function(self: Pipeline, name: string): boolean

listSystems: function(self: Pipeline): {SystemInfo}

setSystemEnabled: function(self: Pipeline, name: string, enabled: boolean): (boolean, string?)

enablePhase: function(self: Pipeline, phase: phases.Selection): nil

disablePhase: function(self: Pipeline, phase: phases.Selection): nil

isPhaseEnabled: function(self: Pipeline, phase: phases.Phase): boolean

registerPhase: function(self: Pipeline, phase: phases.Definition): nil

count: integer

fixedTimestep: number

fixedMaxSteps: integer

fixedOverload: FixedOverload

fixedAccumulator: number

fixedStepCount: integer

fixedTimeDropped: number

fixedStepsDropped: integer

phaseStates: {boolean}

struct PreviousTransform2D
    x: number
    y: number
    rotation: number
end

x: number

y: number

rotation: number

record Query
    descriptor: Descriptor
    iter: function(self: Query): (IterFn, Query, archetype.Archetype?)
    groups: function(self: Query): (GroupsIterFn, Query, integer?)
    group: function(self: Query, groupId: integer): (GroupIterFn, GroupState, archetype.Archetype?)
    getGroup: function(self: Query, candidate: archetype.Archetype): integer?
    getGroupCount: function(self: Query, groupId: integer): integer
    count: function(self: Query): integer
end

iter: function(self: Query): (IterFn, Query, archetype.Archetype?)

groups: function(self: Query): (GroupsIterFn, Query, integer?)

group: function(self: Query, groupId: integer): (GroupIterFn, GroupState, archetype.Archetype?)

getGroup: function(self: Query, candidate: archetype.Archetype): integer?

getGroupCount: function(self: Query, groupId: integer): integer

count: function(self: Query): integer

descriptor: Descriptor

type QueryDescriptor = {
    --- Caller-writable. Names this query for inspection.
    name: string?,

    --- Caller-writable. Excludes Paused for logic queries; nil behaves like render.
    type: ("logic" | "render")?,

    --- Caller-writable. Requires all listed components and overrides their automatic
    --- exclusions.
    include: {components.Selector}?,

    --- Caller-writable. Requires at least one listed component; an empty list adds no
    --- constraint.
    includeAny: {components.Selector}?,

    --- Caller-writable. Rejects every listed component.
    exclude: {components.Selector}?,

    --- Caller-writable. Receives entering rows after publication, including initial
    --- members.
    onEntitiesAdded: MembershipCallback?,

    --- Caller-writable. Receives departing rows while their old values remain readable.
    onEntitiesRemoved: MembershipCallback?,

    --- Caller-writable. Retains only initially matching archetypes, with live rows, and
    --- forbids callbacks.
    temp: boolean?,

    --- Caller-writable. Assigns each matching archetype an integer group once.
    groupBy: (function(candidate: archetype.Archetype): integer)?
}

record Relationship is Component
    associated type Value = RelationshipValue

    componentId: integer
    componentName: string
    storageType: string
    transient: boolean
    exclusive: boolean
    reverseIndex: boolean
    cascadeDelete: boolean
    sparse: boolean

    metamethod __call: function(self, target: integer): RelationshipInstance
    targeting: function(self: RelationshipComponent, target: integer): RelationshipComponent
end

__call: function(self, target: integer): RelationshipInstance

targeting: function(self: RelationshipComponent, target: integer): RelationshipComponent

Value: associatedDecl

componentId: integer

componentName: string

storageType: string

transient: boolean

exclusive: boolean

reverseIndex: boolean