# `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. ```nupp @derive(tecs.ecs.Component, nupp.derive.Debug) 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`, whose methods work on constructed values and borrowed rows without changing column layout. Serialization needs no derive: `nupp.serde.binding(Velocity)` selects the declaration's fields for `nupp.serde.json.encode` and `decode`. That generic 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 a Nupp `@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`](#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. ```nupp 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. ```nupp 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. ```nupp 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` 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. ```nupp 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.Xoshiro128` 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. ```nupp 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 `new nupp.random.Xoshiro128(seed)`. 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. ```nupp 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.Xoshiro128` 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. ## Submodules | Module | Description | | --- | --- | | `tecs.ecs.phases` | The ordered frame phase constants. | | `tecs.ecs.runif` | Provides timer, state and logical predicates for system dispatch. | ## Types ### `Archetype` _record_ ```nupp record Archetype ... ``` A dense archetype returned by query iteration. #### Members | Name | Kind | Description | | --- | --- | --- | | [`id`](#tecs.ecs.Archetype.id) | field | | | [`signature`](#tecs.ecs.Archetype.signature) | field | | | [`componentIds`](#tecs.ecs.Archetype.componentIds) | field | | | [`components`](#tecs.ecs.Archetype.components) | field | | | [`entities`](#tecs.ecs.Archetype.entities) | field | | | [`columns`](#tecs.ecs.Archetype.columns) | field | Engine-owned. | | [`dirty`](#tecs.ecs.Archetype.dirty) | field | | | [`structureVersion`](#tecs.ecs.Archetype.structureVersion) | field | | | [`valueVersions`](#tecs.ecs.Archetype.valueVersions) | field | | | [`sparseEdges`](#tecs.ecs.Archetype.sparseEdges) | field | | | [`storageHighWater`](#tecs.ecs.Archetype.storageHighWater) | field | | | [`nativeCapacity`](#tecs.ecs.Archetype.nativeCapacity) | field | | | [`nativeColumns`](#tecs.ecs.Archetype.nativeColumns) | field | | | [`nativeAliases`](#tecs.ecs.Archetype.nativeAliases) | field | | | [`observers`](#tecs.ecs.Archetype.observers) | field | | | [`activated`](#tecs.ecs.Archetype.activated) | field | | | [`dirtyQueue`](#tecs.ecs.Archetype.dirtyQueue) | field | | | [`dirtyEpoch`](#tecs.ecs.Archetype.dirtyEpoch) | field | | | [`residueFrom`](#tecs.ecs.Archetype.residueFrom) | field | | | [`addedFrom`](#tecs.ecs.Archetype.addedFrom) | field | | | [`touched`](#tecs.ecs.Archetype.touched) | field | | | [`touchedAll`](#tecs.ecs.Archetype.touchedAll) | field | | | [`countedValues`](#tecs.ecs.Archetype.countedValues) | field | | | [`valueVersion`](#tecs.ecs.Archetype.valueVersion) | field | | | [`plain`](#tecs.ecs.Archetype.plain) | field | | | [`addEdges`](#tecs.ecs.Archetype.addEdges) | field | | | [`removeEdges`](#tecs.ecs.Archetype.removeEdges) | field | | | [`movePlans`](#tecs.ecs.Archetype.movePlans) | field | | | [`addEntityObserver`](#tecs.ecs.Archetype.addEntityObserver) | method | Registers publication callbacks without replaying existing rows. | | [`structuralDescribed`](#tecs.ecs.Archetype.structuralDescribed) | method | Reports whether row residue completely describes changes since a structural count. | | [`structuralAdded`](#tecs.ecs.Archetype.structuralAdded) | method | Returns the first appended one-based row in this dirty window, or zero. | | [`structuralTouched`](#tecs.ecs.Archetype.structuralTouched) | method | Returns the reused swap-pop row residue for this dirty window. | | [`valueCount`](#tecs.ecs.Archetype.valueCount) | method | Counts explicitly tracked value writes, excluding structural changes. | | [`trackValueCount`](#tecs.ecs.Archetype.trackValueCount) | method | Enables aggregate value counting for one present component. | | [`set`](#tecs.ecs.Archetype.set) | method | Writes one existing component without changing row membership. | | [`get`](#tecs.ecs.Archetype.get) | field | | | [`getMut`](#tecs.ecs.Archetype.getMut) | field | | | [`isComponentDirty`](#tecs.ecs.Archetype.isComponentDirty) | method | | | [`anyComponentDirty`](#tecs.ecs.Archetype.anyComponentDirty) | method | | | [`markComponentDirty`](#tecs.ecs.Archetype.markComponentDirty) | method | | | [`markAllComponentsDirty`](#tecs.ecs.Archetype.markAllComponentsDirty) | method | | | [`clearDirtyComponents`](#tecs.ecs.Archetype.clearDirtyComponents) | method | | | [`dirtyComponents`](#tecs.ecs.Archetype.dirtyComponents) | method | | | [`structuralCount`](#tecs.ecs.Archetype.structuralCount) | method | Returns the structural write count, which survives dirty-bit clearing. | | [`writeCount`](#tecs.ecs.Archetype.writeCount) | method | Returns one column's write count, which survives dirty-bit clearing. | | [`forEachRelationship`](#tecs.ecs.Archetype.forEachRelationship) | field | Iterates an entity row's edges in target order. | | [`getFirstRelationship`](#tecs.ecs.Archetype.getFirstRelationship) | field | Returns the first edge in target order. | #### `id` _field_ ```nupp id: integer ``` #### `signature` _field_ ```nupp signature: string ``` #### `componentIds` _field_ ```nupp componentIds: {[integer]: boolean} ``` #### `components` _field_ ```nupp components: {components.Component} ``` #### `entities` _field_ ```nupp entities: entitycolumn.DoubleArray ``` #### `columns` _field_ ```nupp columns: {[integer]: any} ``` Engine-owned. Holds heterogeneous managed arrays or native C arrays. This storage seam is public for world internals; game code uses get or getMut. #### `dirty` _field_ ```nupp dirty: {[integer]: boolean} ``` `@private` #### `structureVersion` _field_ ```nupp structureVersion: integer ``` `@private` #### `valueVersions` _field_ ```nupp valueVersions: {[integer]: integer} ``` `@private` #### `sparseEdges` _field_ ```nupp sparseEdges: {[integer]: {[integer]: {any}}} ``` `@private` #### `storageHighWater` _field_ ```nupp storageHighWater: integer ``` `@private` #### `nativeCapacity` _field_ ```nupp nativeCapacity: integer ``` `@private` #### `nativeColumns` _field_ ```nupp nativeColumns: {[integer]: ffistorage.Storage}? ``` `@private` #### `nativeAliases` _field_ ```nupp nativeAliases: {[integer]: integer}? ``` `@private` #### `observers` _field_ ```nupp observers: {EntityObserver} ``` `@private` #### `activated` _field_ ```nupp activated: boolean ``` `@private` #### `dirtyQueue` _field_ ```nupp dirtyQueue: DirtyQueue? ``` `@private` #### `dirtyEpoch` _field_ ```nupp dirtyEpoch: integer ``` `@private` #### `residueFrom` _field_ ```nupp residueFrom: integer ``` `@private` #### `addedFrom` _field_ ```nupp addedFrom: integer ``` `@private` #### `touched` _field_ ```nupp touched: {integer} ``` `@private` #### `touchedAll` _field_ ```nupp touchedAll: boolean ``` `@private` #### `countedValues` _field_ ```nupp countedValues: {[integer]: boolean} ``` `@private` #### `valueVersion` _field_ ```nupp valueVersion: integer ``` `@private` #### `plain` _field_ ```nupp plain: boolean ``` `@private` #### `addEdges` _field_ ```nupp addEdges: {[integer]: Archetype} ``` `@private` #### `removeEdges` _field_ ```nupp removeEdges: {[integer]: Archetype} ``` `@private` #### `movePlans` _field_ ```nupp movePlans: {[Archetype]: MovePlan} ``` `@private` #### `addEntityObserver` _method_ ```nupp addEntityObserver: function(self: Archetype, observer: EntityObserver): nil ``` Registers publication callbacks without replaying existing rows. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Archetype` | The archetype to observe. | | `observer` | `EntityObserver` | The callbacks retained until destruction. | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `structuralDescribed` _method_ ```nupp structuralDescribed: function(self: Archetype, count: integer): boolean ``` Reports whether row residue completely describes changes since a structural count. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Archetype` | The archetype to inspect. | | `count` | `integer` | The consumer's previous structural count. | ##### Returns | Type | Description | | --- | --- | | `boolean` | Returns false when a full refresh is necessary. | #### `structuralAdded` _method_ ```nupp structuralAdded: function(self: Archetype): integer ``` Returns the first appended one-based row in this dirty window, or zero. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Archetype` | The archetype to inspect. | ##### Returns | Type | Description | | --- | --- | | `integer` | Returns the suffix start, which may exceed the current row count. | #### `structuralTouched` _method_ ```nupp structuralTouched: function(self: Archetype): ({integer}, integer) ``` Returns the reused swap-pop row residue for this dirty window. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Archetype` | The archetype to inspect. | ##### Returns | Type | Description | | --- | --- | | `{integer}` | Returns the borrowed row list and its live prefix length. | | `integer` | | #### `valueCount` _method_ ```nupp valueCount: function(self: Archetype): integer ``` Counts explicitly tracked value writes, excluding structural changes. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Archetype` | The archetype to inspect. | ##### Returns | Type | Description | | --- | --- | | `integer` | Returns the monotonically increasing counter. | #### `trackValueCount` _method_ ```nupp trackValueCount: function(self: Archetype, component: components.Selector): nil ``` Enables aggregate value counting for one present component. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Archetype` | The archetype to track. | | `component` | `components.Selector` | The column whose future writes contribute to valueCount. | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `set` _method_ ```nupp set: function(self: Archetype, row: integer, input: components.Input): nil ``` Writes one existing component without changing row membership. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Archetype` | The archetype to update. | | `row` | `integer` | The one-based live row. | | `input` | `components.Input` | The constructed component value. | ##### Returns | Type | Description | | --- | --- | | `nil` | | ##### Raises | Type | Condition | | --- | --- | | `string` | when the row or component is absent, or the input changes relationship membership or a durable key. | #### `get` _field_ ```nupp get: (function(self: Archetype, component: C): C.Column?) & (function(self: Archetype, component: Type): derived.Column(T, derived.Edge)?) ``` #### `getMut` _field_ ```nupp getMut: (function(self: Archetype, component: C): C.Column?) & (function(self: Archetype, component: Type): derived.Column(T, derived.Edge)?) ``` #### `isComponentDirty` _method_ ```nupp isComponentDirty: function(self: Archetype, component: components.Selector): boolean ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Archetype` | | | `component` | `components.Selector` | | ##### Returns | Type | Description | | --- | --- | | `boolean` | | #### `anyComponentDirty` _method_ ```nupp anyComponentDirty: function(self: Archetype): boolean ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Archetype` | | ##### Returns | Type | Description | | --- | --- | | `boolean` | | #### `markComponentDirty` _method_ ```nupp markComponentDirty: function(self: Archetype, component: components.Selector): nil ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Archetype` | | | `component` | `components.Selector` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `markAllComponentsDirty` _method_ ```nupp markAllComponentsDirty: function(self: Archetype): nil ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Archetype` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `clearDirtyComponents` _method_ ```nupp clearDirtyComponents: function(self: Archetype): nil ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Archetype` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `dirtyComponents` _method_ ```nupp dirtyComponents: function(self: Archetype): function(): components.Component? ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Archetype` | | ##### Returns | Type | Description | | --- | --- | | `function(): components.Component?` | | #### `structuralCount` _method_ ```nupp structuralCount: function(self: Archetype): integer ``` Returns the structural write count, which survives dirty-bit clearing. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Archetype` | | ##### Returns | Type | Description | | --- | --- | | `integer` | | #### `writeCount` _method_ ```nupp writeCount: function(self: Archetype, component: components.Selector): integer ``` Returns one column's write count, which survives dirty-bit clearing. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Archetype` | | | `component` | `components.Selector` | | ##### Returns | Type | Description | | --- | --- | | `integer` | | #### `forEachRelationship` _field_ ```nupp forEachRelationship: ( function( self: Archetype, relationship: C, row: integer, callback: function(value: C.Value) ): nil ) & ( function( self: Archetype, relationship: Type, row: integer, callback: function(value: T) ): nil ) ``` Iterates an entity row's edges in target order. #### `getFirstRelationship` _field_ ```nupp getFirstRelationship: ( function(self: Archetype, relationship: C, row: integer): C.Value? ) & ( function(self: Archetype, relationship: Type, row: integer): T? ) ``` Returns the first edge in target order. ### `ArchetypeCreated` _record_ ```nupp record ArchetypeCreated ... ``` `@derive(events.Event)` `@event(name="ArchetypeCreated")` Reports newly registered archetypes at the world's zero address. #### Members | Name | Kind | Description | | --- | --- | --- | | [`archetype`](#tecs.ecs.ArchetypeCreated.archetype) | field | Read-only. | #### `archetype` _field_ ```nupp archetype: archetype.Archetype ``` Read-only. Identifies the new archetype, available for lifecycle observation. ### `ArchetypeEntityObserver` _interface_ ```nupp interface ArchetypeEntityObserver ... ``` Receives row and lifetime notifications from one archetype. #### Members | Name | Kind | Description | | --- | --- | --- | | [`onEntitiesAdded`](#tecs.ecs.ArchetypeEntityObserver.onEntitiesAdded) | field | Caller-writable. | | [`onEntitiesRemoved`](#tecs.ecs.ArchetypeEntityObserver.onEntitiesRemoved) | field | Caller-writable. | | [`onEntityMove`](#tecs.ecs.ArchetypeEntityObserver.onEntityMove) | field | Caller-writable. | | [`onActivated`](#tecs.ecs.ArchetypeEntityObserver.onActivated) | field | Caller-writable. | | [`onDeactivated`](#tecs.ecs.ArchetypeEntityObserver.onDeactivated) | field | Caller-writable. | | [`onArchetypeDestroyed`](#tecs.ecs.ArchetypeEntityObserver.onArchetypeDestroyed) | field | Caller-writable. | #### `onEntitiesAdded` _field_ ```nupp onEntitiesAdded: ( function( self: EntityObserver, value: Archetype, first: integer, last: integer, count: integer, source: Archetype? ) )? ``` Caller-writable. Receives initialized one-based rows and their previous archetype. #### `onEntitiesRemoved` _field_ ```nupp onEntitiesRemoved: ( function( self: EntityObserver, value: Archetype, first: integer, last: integer, count: integer, target: Archetype? ) )? ``` Caller-writable. Receives still-readable one-based rows and their destination. #### `onEntityMove` _field_ ```nupp onEntityMove: (function(self: EntityObserver, value: Archetype, entity: integer, fromRow: integer, toRow: integer))? ``` Caller-writable. Receives a swap-pop relocation with zero-based row indices. #### `onActivated` _field_ ```nupp onActivated: (function(self: EntityObserver, value: Archetype))? ``` Caller-writable. Runs when the archetype becomes nonempty. #### `onDeactivated` _field_ ```nupp onDeactivated: (function(self: EntityObserver, value: Archetype))? ``` Caller-writable. Runs when the archetype becomes empty. #### `onArchetypeDestroyed` _field_ ```nupp onArchetypeDestroyed: (function(self: EntityObserver, value: Archetype))? ``` Caller-writable. Runs before maintenance permanently unregisters the archetype. ### `BatchCallback` _type_ ```nupp type BatchCallback = function( candidate: archetype.Archetype, firstRow: integer, lastRow: integer, count: integer ) ``` Initializes or updates a contiguous one-based archetype row range at a barrier. ### `Bundle` _record_ ```nupp record Bundle ... ``` A reusable world-bound spawn shape. #### Members | Name | Kind | Description | | --- | --- | --- | | [`name`](#tecs.ecs.Bundle.name) | field | | | [`required`](#tecs.ecs.Bundle.required) | field | | | [`defaulted`](#tecs.ecs.Bundle.defaulted) | field | | | [`world`](#tecs.ecs.Bundle.world) | field | | | [`requiredComponents`](#tecs.ecs.Bundle.requiredComponents) | field | | | [`defaultComponents`](#tecs.ecs.Bundle.defaultComponents) | field | | | [`defaultFactories`](#tecs.ecs.Bundle.defaultFactories) | field | | | [`cachedTarget`](#tecs.ecs.Bundle.cachedTarget) | field | | | [`cachedState`](#tecs.ecs.Bundle.cachedState) | field | | | [`requiredDefaults`](#tecs.ecs.Bundle.requiredDefaults) | field | | | [`plain`](#tecs.ecs.Bundle.plain) | field | | | [`scratchInputs`](#tecs.ecs.Bundle.scratchInputs) | field | | | [`busy`](#tecs.ecs.Bundle.busy) | field | | | [`spawn`](#tecs.ecs.Bundle.spawn) | method | | #### `name` _field_ ```nupp name: string ``` #### `required` _field_ ```nupp required: {string} ``` #### `defaulted` _field_ ```nupp defaulted: {string} ``` #### `world` _field_ ```nupp world: any ``` `@private` #### `requiredComponents` _field_ ```nupp requiredComponents: {components.Component} ``` `@private` #### `defaultComponents` _field_ ```nupp defaultComponents: {components.Component} ``` `@private` #### `defaultFactories` _field_ ```nupp defaultFactories: {BundleFactory?} ``` `@private` #### `cachedTarget` _field_ ```nupp cachedTarget: archetype.Archetype? ``` `@private` #### `cachedState` _field_ ```nupp cachedState: components.Component? ``` `@private` #### `requiredDefaults` _field_ ```nupp requiredDefaults: {[integer]: any} ``` `@private` #### `plain` _field_ ```nupp plain: boolean ``` `@private` #### `scratchInputs` _field_ ```nupp scratchInputs: {components.Input} ``` `@private` #### `busy` _field_ ```nupp busy: boolean ``` `@private` #### `spawn` _method_ ```nupp spawn: function(self: Bundle, ...: components.Input): integer ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Bundle` | | | `...` | `components.Input` | | ##### Returns | Type | Description | | --- | --- | | `integer` | | ### `BundleDefinition` _type_ ```nupp type BundleDefinition = { required: {components.Selector}?, with: {[components.Selector]: true | BundleFactory}? } ``` Required and defaulted components for a bundle. ### `Component` _interface_ ```nupp interface Component ... ``` A process-wide component definition. #### Members | Name | Kind | Description | | --- | --- | --- | | [`Value`](#tecs.ecs.Component.Value) | field | | | [`Column`](#tecs.ecs.Component.Column) | field | | | [`componentId`](#tecs.ecs.Component.componentId) | field | | | [`componentName`](#tecs.ecs.Component.componentName) | field | | | [`storageType`](#tecs.ecs.Component.storageType) | field | | | [`transient`](#tecs.ecs.Component.transient) | field | | #### `Value` _field_ ```nupp Value: associatedDecl ``` #### `Column` _field_ ```nupp Column: associatedDecl ``` #### `componentId` _field_ ```nupp componentId: integer ``` #### `componentName` _field_ ```nupp componentName: string ``` #### `storageType` _field_ ```nupp storageType: string ``` #### `transient` _field_ ```nupp transient: boolean ``` ### `component` _record_ ```nupp record component ... ``` `@annotation(targets={"record","struct"})` Configures a derived component's persisted identity and snapshot policy. #### Members | Name | Kind | Description | | --- | --- | --- | | [`name`](#tecs.ecs.component.name) | field | Caller-writable. | | [`transient`](#tecs.ecs.component.transient) | field | Caller-writable. | #### `name` _field_ ```nupp name: string? ``` Caller-writable. Pins the persisted name; nil uses the qualified declaration. #### `transient` _field_ ```nupp transient: boolean? ``` Caller-writable. Omits this component's values from snapshots. ### `ComponentDefinition` _interface_ ```nupp interface ComponentDefinition is Component ... ``` A named definition with its column type selected from the value declaration. #### Type parameters | Name | Description | | --- | --- | | `T` | | #### Members | Name | Kind | Description | | --- | --- | --- | | [`Value`](#tecs.ecs.ComponentDefinition.Value) | field | | | [`Column`](#tecs.ecs.ComponentDefinition.Column) | field | | | [`construct`](#tecs.ecs.ComponentDefinition.construct) | method | | | [`defaultFactory`](#tecs.ecs.ComponentDefinition.defaultFactory) | method | | | [`snapshotSave`](#tecs.ecs.ComponentDefinition.snapshotSave) | method | | | [`snapshotLoad`](#tecs.ecs.ComponentDefinition.snapshotLoad) | method | | | [`\_\_call`](#tecs.ecs.ComponentDefinition.__call) | metamethod | | #### `Value` _field_ ```nupp Value: associatedDecl ``` #### `Column` _field_ ```nupp Column: associatedDecl ``` #### `construct` _method_ ```nupp construct: function(...: any): T ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `...` | `any` | | ##### Returns | Type | Description | | --- | --- | | `T` | | #### `defaultFactory` _method_ ```nupp defaultFactory: function(): T ``` ##### Returns | Type | Description | | --- | --- | | `T` | | #### `snapshotSave` _method_ ```nupp snapshotSave: function(value: T): any ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `T` | | ##### Returns | Type | Description | | --- | --- | | `any` | | #### `snapshotLoad` _method_ ```nupp snapshotLoad: function(value: any, exclusive world: any): T ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `any` | | | `exclusive world` | `any` | | ##### Returns | Type | Description | | --- | --- | | `T` | | #### `__call` _metamethod_ ```nupp __call: function(self, ...: any): FFIInstance> ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `?` | `self` | | | `...` | `any` | | ##### Returns | Type | Description | | --- | --- | | `FFIInstance\\>` | | ### `ComponentInput` _type_ ```nupp type ComponentInput = Component | Type | derived.Value | ScalarInstance | TableInstance | FFIInstance | RelationshipInstance | RelationshipBatch ``` A component definition or constructed value accepted by a mutation. ### `ComponentOptions` _type_ ```nupp type ComponentOptions = { --- 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)? } ``` Configures an explicit component identity from a declaration. #### Type parameters | Name | Description | | --- | --- | | `T` | | ### `ComponentValue` _interface_ ```nupp sealed interface ComponentValue ``` Bounds generic helpers to records or structs deriving the component contract. ### `DoubleArray` _interface_ ```nupp interface DoubleArray ... ``` Exposes the native, one-based packed entity ID column and its exact length. #### Members | Name | Kind | Description | | --- | --- | --- | | [`\_\_len`](#tecs.ecs.DoubleArray.__len) | metamethod | | | [`\_\_index`](#tecs.ecs.DoubleArray.__index) | metamethod | | | [`\_\_newindex`](#tecs.ecs.DoubleArray.__newindex) | metamethod | | #### `__len` _metamethod_ ```nupp __len: function(self: DoubleArray): integer ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `DoubleArray` | | ##### Returns | Type | Description | | --- | --- | | `integer` | | #### `__index` _metamethod_ ```nupp __index: function(self: DoubleArray, index: integer): integer ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `DoubleArray` | | | `index` | `integer` | | ##### Returns | Type | Description | | --- | --- | | `integer` | | #### `__newindex` _metamethod_ ```nupp __newindex: function(self: DoubleArray, index: integer, id: integer?): nil ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `DoubleArray` | | | `index` | `integer` | | | `id` | `integer?` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | ### `EdgeOptions` _type_ ```nupp type EdgeOptions = { --- 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? } ``` Configures a named payload relationship from a declaration. #### Type parameters | Name | Description | | --- | --- | | `T` | | ### `EntityLifecycle` _type_ ```nupp type EntityLifecycle = OnSpawn | OnDespawn ``` The payload shared by entity spawn and despawn lifecycle events. ### `FinishSnapshotLoad` _record_ ```nupp record FinishSnapshotLoad ... ``` `@derive(events.Event)` `@event(name="FinishSnapshotLoad")` Reports completion of snapshot metadata restoration. #### Members | Name | Kind | Description | | --- | --- | --- | | [`prelude`](#tecs.ecs.FinishSnapshotLoad.prelude) | field | Read-only. | #### `prelude` _field_ ```nupp prelude: SnapshotPrelude ``` Read-only. Describes the restored snapshot. ### `FixedOverload` _type_ ```nupp type FixedOverload = "drop" | "accumulate" ``` The policy applied when a frame exceeds its fixed-step limit. ### `NewRelationship` _type_ ```nupp type NewRelationship = (function(options: RelationshipOptions): Relationship) & (function(witness: Type, options: EdgeOptions?): RelationshipDefinition) ``` Accepts target-only options or a declaration with payload relationship options. ### `OnDespawn` _record_ ```nupp record OnDespawn ... ``` `@derive(events.Event)` `@event(name="OnDespawn")` Fires at the entity address and address zero immediately before removal. #### Members | Name | Kind | Description | | --- | --- | --- | | [`entity`](#tecs.ecs.OnDespawn.entity) | field | | | [`source`](#tecs.ecs.OnDespawn.source) | field | Engine-owned. | | [`row`](#tecs.ecs.OnDespawn.row) | field | Engine-owned. | | [`requestedDespawns`](#tecs.ecs.OnDespawn.requestedDespawns) | field | Engine-owned. | | [`get`](#tecs.ecs.OnDespawn.get) | method | Reads one of the entity's committed components before removal. | | [`despawn`](#tecs.ecs.OnDespawn.despawn) | method | Stages another entity for despawn at the same commit barrier. | #### `entity` _field_ ```nupp entity: integer ``` #### `source` _field_ ```nupp source: archetype.Archetype ``` Engine-owned. Identifies the entity's last committed archetype. #### `row` _field_ ```nupp row: integer ``` Engine-owned. Identifies the entity's zero-based row before removal. #### `requestedDespawns` _field_ ```nupp requestedDespawns: {integer} ``` Engine-owned. Collects dependent entities observers ask to despawn. #### `get` _method_ ```nupp get: function get(borrows self: OnDespawn, component: C): C.Value? ``` Reads one of the entity's committed components before removal. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `OnDespawn` | | | `component` | `C` | | ##### Returns | Type | Description | | --- | --- | | `C.Value?` | | #### `despawn` _method_ ```nupp despawn: function despawn(self: OnDespawn, entity: integer): nil ``` Stages another entity for despawn at the same commit barrier. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `OnDespawn` | | | `entity` | `integer` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | ### `OnSnapshotSave` _record_ ```nupp record OnSnapshotSave ... ``` `@derive(events.Event)` `@event(name="OnSnapshotSave")` Allows snapshot participants to attach metadata and exclude regenerated entities. #### Members | Name | Kind | Description | | --- | --- | --- | | [`data`](#tecs.ecs.OnSnapshotSave.data) | field | Engine-owned. | | [`excluded`](#tecs.ecs.OnSnapshotSave.excluded) | field | Engine-owned. | | [`addData`](#tecs.ecs.OnSnapshotSave.addData) | method | Attaches one named detached value to the snapshot. | | [`exclude`](#tecs.ecs.OnSnapshotSave.exclude) | method | Excludes every entity carrying a derived-data component. | #### `data` _field_ ```nupp data: {[string]: any} ``` Engine-owned. Supplies save staging to event construction; use addData instead. #### `excluded` _field_ ```nupp excluded: {components.Component} ``` Engine-owned. Supplies exclusion staging to event construction; use exclude instead. #### `addData` _method_ ```nupp addData: function addData(self: OnSnapshotSave, key: string, value: any): nil ``` Attaches one named detached value to the snapshot. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `OnSnapshotSave` | The call-scoped save event. | | `key` | `string` | The unique nonempty metadata key. | | `value` | `any` | The serializable metadata value. | ##### Returns | Type | Description | | --- | --- | | `nil` | | ##### Raises | Type | Condition | | --- | --- | | `string` | when a key is empty or repeated. | #### `exclude` _method_ ```nupp exclude: function exclude(self: OnSnapshotSave, component: components.Selector): nil ``` Excludes every entity carrying a derived-data component. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `OnSnapshotSave` | The call-scoped save event. | | `component` | `components.Selector` | The component whose entities must be regenerated after load. | ##### Returns | Type | Description | | --- | --- | | `nil` | | ### `OnSpawn` _record_ ```nupp record OnSpawn ... ``` `@derive(events.Event)` `@event(name="OnSpawn")` Fires at address zero after an entity becomes committed and alive. #### Members | Name | Kind | Description | | --- | --- | --- | | [`entity`](#tecs.ecs.OnSpawn.entity) | field | | #### `entity` _field_ ```nupp entity: integer ``` ### `Phase` _type_ ```nupp type Phase = string ``` A frame phase. ### `PhaseDefinition` _type_ ```nupp 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}? } ``` Declares a custom phase or ordered phase tree. ### `PhaseGroup` _type_ ```nupp type PhaseGroup = "StartupGroup" | "FixedUpdateGroup" | "RenderGroup" | "MainGroup" | "ShutdownGroup" | "AllGroups" ``` An ordered predefined group of frame or lifecycle phases. ### `PhaseSelection` _type_ ```nupp type PhaseSelection = Phase | PhaseGroup ``` A leaf phase or predefined group accepted by schedule controls. ### `Pipeline` _interface_ ```nupp interface Pipeline ... ``` Implements custom scheduling while the world owns entities and task scopes. #### Members | Name | Kind | Description | | --- | --- | --- | | [`count`](#tecs.ecs.Pipeline.count) | field | Read-only. | | [`fixedTimestep`](#tecs.ecs.Pipeline.fixedTimestep) | field | Read-only. | | [`fixedMaxSteps`](#tecs.ecs.Pipeline.fixedMaxSteps) | field | Read-only. | | [`fixedOverload`](#tecs.ecs.Pipeline.fixedOverload) | field | Read-only. | | [`fixedAccumulator`](#tecs.ecs.Pipeline.fixedAccumulator) | field | Engine-owned. | | [`fixedStepCount`](#tecs.ecs.Pipeline.fixedStepCount) | field | Read-only. | | [`fixedTimeDropped`](#tecs.ecs.Pipeline.fixedTimeDropped) | field | Read-only. | | [`fixedStepsDropped`](#tecs.ecs.Pipeline.fixedStepsDropped) | field | Read-only. | | [`phaseStates`](#tecs.ecs.Pipeline.phaseStates) | field | Engine-owned. | | [`update`](#tecs.ecs.Pipeline.update) | method | Dispatches a frame inside the world's existing task scope. | | [`run`](#tecs.ecs.Pipeline.run) | method | Dispatches one phase or phase tree inside the world's task scope. | | [`addSystem`](#tecs.ecs.Pipeline.addSystem) | method | Registers a system and returns its unique name. | | [`removeSystem`](#tecs.ecs.Pipeline.removeSystem) | method | Removes a named system. | | [`listSystems`](#tecs.ecs.Pipeline.listSystems) | method | Returns detached system inspection data. | | [`setSystemEnabled`](#tecs.ecs.Pipeline.setSystemEnabled) | method | Changes a registered system's enabled state. | | [`enablePhase`](#tecs.ecs.Pipeline.enablePhase) | method | Enables a phase tree. | | [`disablePhase`](#tecs.ecs.Pipeline.disablePhase) | method | Disables a phase tree. | | [`isPhaseEnabled`](#tecs.ecs.Pipeline.isPhaseEnabled) | method | Reports whether a leaf is enabled. | | [`registerPhase`](#tecs.ecs.Pipeline.registerPhase) | method | Registers a custom phase tree and assigns any omitted position. | #### `count` _field_ ```nupp count: integer ``` Read-only. Reports the registered system count. #### `fixedTimestep` _field_ ```nupp fixedTimestep: number ``` Read-only. Reports the fixed-step duration in seconds. #### `fixedMaxSteps` _field_ ```nupp fixedMaxSteps: integer ``` Read-only. Limits catch-up iterations in one frame. #### `fixedOverload` _field_ ```nupp fixedOverload: FixedOverload ``` Read-only. Selects drop or accumulate for excess fixed time. #### `fixedAccumulator` _field_ ```nupp fixedAccumulator: number ``` Engine-owned. Stores the fixed remainder; snapshot restore writes it. #### `fixedStepCount` _field_ ```nupp fixedStepCount: integer ``` Read-only. Reports completed fixed iterations. #### `fixedTimeDropped` _field_ ```nupp fixedTimeDropped: number ``` Read-only. Reports abandoned fixed time in seconds. #### `fixedStepsDropped` _field_ ```nupp fixedStepsDropped: integer ``` Read-only. Reports abandoned whole fixed steps. #### `phaseStates` _field_ ```nupp phaseStates: {boolean} ``` Engine-owned. Stores enabled flags by registered phase position; snapshots restore it. #### `update` _method_ ```nupp update: function(self: Pipeline, dt: number, exclusive world: World, borrows scope: tasks.Scope): nil ``` Dispatches a frame inside the world's existing task scope. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Pipeline` | The custom scheduler. | | `dt` | `number` | The frame duration in seconds. | | `exclusive world` | `World` | The world whose systems run. | | `borrows scope` | `tasks.Scope` | The call-scoped owner of child tasks. | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `run` _method_ ```nupp run: function( self: Pipeline, phase: phases.Selection, dt: number, exclusive world: World, borrows scope: tasks.Scope ): nil ``` Dispatches one phase or phase tree inside the world's task scope. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Pipeline` | The custom scheduler. | | `phase` | `phases.Selection` | The selected phase name. | | `dt` | `number` | The elapsed seconds supplied to systems. | | `exclusive world` | `World` | The world whose systems run. | | `borrows scope` | `tasks.Scope` | The call-scoped owner of child tasks. | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `addSystem` _method_ ```nupp addSystem: function(self: Pipeline, config: SystemConfig): string ``` Registers a system and returns its unique name. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Pipeline` | The custom scheduler. | | `config` | `SystemConfig` | The system and its ordering constraints. | ##### Returns | Type | Description | | --- | --- | | `string` | Returns the registered name. | #### `removeSystem` _method_ ```nupp removeSystem: function(self: Pipeline, name: string): boolean ``` Removes a named system. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Pipeline` | The custom scheduler. | | `name` | `string` | The registered name. | ##### Returns | Type | Description | | --- | --- | | `boolean` | Returns whether the system existed. | #### `listSystems` _method_ ```nupp listSystems: function(self: Pipeline): {SystemInfo} ``` Returns detached system inspection data. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Pipeline` | The custom scheduler. | ##### Returns | Type | Description | | --- | --- | | `{SystemInfo}` | Returns systems in dispatch order. | #### `setSystemEnabled` _method_ ```nupp setSystemEnabled: function(self: Pipeline, name: string, enabled: boolean): (boolean, string?) ``` Changes a registered system's enabled state. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Pipeline` | The custom scheduler. | | `name` | `string` | The registered name. | | `enabled` | `boolean` | The desired state. | ##### Returns | Type | Description | | --- | --- | | `boolean` | Returns success and an optional failure reason. | | `string?` | | #### `enablePhase` _method_ ```nupp enablePhase: function(self: Pipeline, phase: phases.Selection): nil ``` Enables a phase tree. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Pipeline` | The custom scheduler. | | `phase` | `phases.Selection` | The selected name. | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `disablePhase` _method_ ```nupp disablePhase: function(self: Pipeline, phase: phases.Selection): nil ``` Disables a phase tree. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Pipeline` | The custom scheduler. | | `phase` | `phases.Selection` | The selected name. | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `isPhaseEnabled` _method_ ```nupp isPhaseEnabled: function(self: Pipeline, phase: phases.Phase): boolean ``` Reports whether a leaf is enabled. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Pipeline` | The custom scheduler. | | `phase` | `phases.Phase` | The selected name. | ##### Returns | Type | Description | | --- | --- | | `boolean` | Returns whether dispatch is enabled. | #### `registerPhase` _method_ ```nupp registerPhase: function(self: Pipeline, phase: phases.Definition): nil ``` Registers a custom phase tree and assigns any omitted position. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Pipeline` | The custom scheduler. | | `phase` | `phases.Definition` | The phase declaration. | ##### Returns | Type | Description | | --- | --- | | `nil` | | ### `PreviousTransform2D` _struct_ ```nupp struct PreviousTransform2D ... ``` `@derive(nupp.derive.Debug)` Stores the position and rotation before the current fixed step. #### Members | Name | Kind | Description | | --- | --- | --- | | [`x`](#tecs.ecs.PreviousTransform2D.x) | field | Engine-owned. | | [`y`](#tecs.ecs.PreviousTransform2D.y) | field | Engine-owned. | | [`rotation`](#tecs.ecs.PreviousTransform2D.rotation) | field | Engine-owned. | #### `x` _field_ ```nupp x: number ``` Engine-owned. Stores the previous horizontal position in world units. #### `y` _field_ ```nupp y: number ``` Engine-owned. Stores the previous vertical position in world units. #### `rotation` _field_ ```nupp rotation: number ``` Engine-owned. Stores the previous clockwise rotation in radians. ### `Query` _record_ ```nupp record Query ... ``` A reusable archetype query. #### Members | Name | Kind | Description | | --- | --- | --- | | [`owner`](#tecs.ecs.Query.owner) | field | | | [`descriptor`](#tecs.ecs.Query.descriptor) | field | Read-only. | | [`include`](#tecs.ecs.Query.include) | field | | | [`exclude`](#tecs.ecs.Query.exclude) | field | | | [`includeAny`](#tecs.ecs.Query.includeAny) | field | | | [`active`](#tecs.ecs.Query.active) | field | | | [`positions`](#tecs.ecs.Query.positions) | field | | | [`lifecycle`](#tecs.ecs.Query.lifecycle) | field | | | [`matched`](#tecs.ecs.Query.matched) | field | | | [`groupIds`](#tecs.ecs.Query.groupIds) | field | | | [`groupPositions`](#tecs.ecs.Query.groupPositions) | field | | | [`grouped`](#tecs.ecs.Query.grouped) | field | | | [`archetypeGroups`](#tecs.ecs.Query.archetypeGroups) | field | | | [`iter`](#tecs.ecs.Query.iter) | method | Iterates nonempty archetypes, in ascending group order when grouped. | | [`groups`](#tecs.ecs.Query.groups) | method | Iterates nonempty group identifiers in ascending order. | | [`group`](#tecs.ecs.Query.group) | method | Iterates nonempty archetypes in one group. | | [`getGroup`](#tecs.ecs.Query.getGroup) | method | Returns an archetype's assigned group. | | [`getGroupCount`](#tecs.ecs.Query.getGroupCount) | method | Counts entities in one group. | | [`count`](#tecs.ecs.Query.count) | method | Counts all currently matching entities. | #### `owner` _field_ ```nupp owner: Owner? ``` `@private` #### `descriptor` _field_ ```nupp descriptor: Descriptor ``` Read-only. Describes the normalized query; mutation after construction is unsupported. #### `include` _field_ ```nupp include: {components.Component} ``` `@private` #### `exclude` _field_ ```nupp exclude: {components.Component} ``` `@private` #### `includeAny` _field_ ```nupp includeAny: {components.Component} ``` `@private` #### `active` _field_ ```nupp active: {archetype.Archetype} ``` `@private` #### `positions` _field_ ```nupp positions: {[archetype.Archetype]: integer} ``` `@private` #### `lifecycle` _field_ ```nupp lifecycle: archetype.EntityObserver? ``` `@private` #### `matched` _field_ ```nupp matched: {[archetype.Archetype]: boolean} ``` `@private` #### `groupIds` _field_ ```nupp groupIds: {integer} ``` `@private` #### `groupPositions` _field_ ```nupp groupPositions: {[integer]: integer} ``` `@private` #### `grouped` _field_ ```nupp grouped: {[integer]: GroupState} ``` `@private` #### `archetypeGroups` _field_ ```nupp archetypeGroups: {[archetype.Archetype]: integer} ``` `@private` #### `iter` _method_ ```nupp iter: function(self: Query): (IterFn, Query, archetype.Archetype?) ``` Iterates nonempty archetypes, in ascending group order when grouped. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Query` | The query to read. | ##### Returns | Type | Description | | --- | --- | | `IterFn` | Returns an independent iterator yielding an archetype, count and live entity column. | | `Query` | | | `archetype.Archetype?` | | #### `groups` _method_ ```nupp groups: function(self: Query): (GroupsIterFn, Query, integer?) ``` Iterates nonempty group identifiers in ascending order. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Query` | The query to read. | ##### Returns | Type | Description | | --- | --- | | `GroupsIterFn` | Returns an independent iterator, empty for ungrouped queries. | | `Query` | | | `integer?` | | #### `group` _method_ ```nupp group: function(self: Query, groupId: integer): (GroupIterFn, GroupState, archetype.Archetype?) ``` Iterates nonempty archetypes in one group. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Query` | The query to read. | | `groupId` | `integer` | The integer group identifier. | ##### Returns | Type | Description | | --- | --- | | `GroupIterFn` | Returns an independent iterator yielding an archetype, count and live entity column. | | `GroupState` | | | `archetype.Archetype?` | | #### `getGroup` _method_ ```nupp getGroup: function(self: Query, candidate: archetype.Archetype): integer? ``` Returns an archetype's assigned group. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Query` | The query to read. | | `candidate` | `archetype.Archetype` | The archetype to inspect. | ##### Returns | Type | Description | | --- | --- | | `integer?` | Returns nil when unmatched or ungrouped. | #### `getGroupCount` _method_ ```nupp getGroupCount: function(self: Query, groupId: integer): integer ``` Counts entities in one group. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Query` | The query to read. | | `groupId` | `integer` | The integer group identifier. | ##### Returns | Type | Description | | --- | --- | | `integer` | Returns zero when the group is absent. | #### `count` _method_ ```nupp count: function(self: Query): integer ``` Counts all currently matching entities. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Query` | The query to read. | ##### Returns | Type | Description | | --- | --- | | `integer` | Returns the committed entity count. | ### `QueryDescriptor` _type_ ```nupp 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: const{components.Selector}?, --- Caller-writable. Requires at least one listed component; an empty list adds no --- constraint. includeAny: const{components.Selector}?, --- Caller-writable. Rejects every listed component. exclude: const{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)? } ``` Membership constraints, grouping and notifications for a reusable query. ### `Relationship` _record_ ```nupp record Relationship is Component ... ``` A target-only entity relationship with selectable cardinality and storage. #### Members | Name | Kind | Description | | --- | --- | --- | | [`Value`](#tecs.ecs.Relationship.Value) | field | | | [`componentId`](#tecs.ecs.Relationship.componentId) | field | | | [`componentName`](#tecs.ecs.Relationship.componentName) | field | | | [`storageType`](#tecs.ecs.Relationship.storageType) | field | | | [`transient`](#tecs.ecs.Relationship.transient) | field | | | [`exclusive`](#tecs.ecs.Relationship.exclusive) | field | | | [`reverseIndex`](#tecs.ecs.Relationship.reverseIndex) | field | | | [`cascadeDelete`](#tecs.ecs.Relationship.cascadeDelete) | field | | | [`sparse`](#tecs.ecs.Relationship.sparse) | field | Read-only. | | [`\_\_call`](#tecs.ecs.Relationship.__call) | metamethod | | | [`targeting`](#tecs.ecs.Relationship.targeting) | method | Returns a component matching one target of this dense relationship. | #### `Value` _field_ ```nupp Value: associatedDecl ``` #### `componentId` _field_ ```nupp componentId: integer ``` #### `componentName` _field_ ```nupp componentName: string ``` #### `storageType` _field_ ```nupp storageType: string ``` #### `transient` _field_ ```nupp transient: boolean ``` #### `exclusive` _field_ ```nupp exclusive: boolean ``` #### `reverseIndex` _field_ ```nupp reverseIndex: boolean ``` #### `cascadeDelete` _field_ ```nupp cascadeDelete: boolean ``` #### `sparse` _field_ ```nupp sparse: boolean ``` Read-only. Selects entity-indexed edge storage; false selects target-specific dense columns. #### `__call` _metamethod_ ```nupp __call: function(self, target: integer): RelationshipInstance ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `?` | `self` | | | `target` | `integer` | | ##### Returns | Type | Description | | --- | --- | | `RelationshipInstance` | | #### `targeting` _method_ ```nupp targeting: function(self: RelationshipComponent, target: integer): RelationshipComponent ``` Returns a component matching one target of this dense relationship. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Relationship` | The relationship definition. | | `target` | `integer` | The packed target entity identifier. | ##### Returns | Type | Description | | --- | --- | | `Relationship` | Returns a stable target-specific component definition. | ##### Raises | Type | Condition | | --- | --- | | `string` | when the relationship uses sparse storage or the target is invalid. | ### `relationship` _record_ ```nupp record relationship ... ``` `@annotation(targets={"record","struct"})` Configures a derived relationship's identity, cardinality and storage policy. #### Members | Name | Kind | Description | | --- | --- | --- | | [`name`](#tecs.ecs.relationship.name) | field | Caller-writable. | | [`transient`](#tecs.ecs.relationship.transient) | field | Caller-writable. | | [`exclusive`](#tecs.ecs.relationship.exclusive) | field | Caller-writable. | | [`sparse`](#tecs.ecs.relationship.sparse) | field | Caller-writable. | | [`reverseIndex`](#tecs.ecs.relationship.reverseIndex) | field | Caller-writable. | | [`cascadeDelete`](#tecs.ecs.relationship.cascadeDelete) | field | Caller-writable. | #### `name` _field_ ```nupp name: string? ``` Caller-writable. Pins the persisted name; nil uses the qualified declaration. #### `transient` _field_ ```nupp transient: boolean? ``` Caller-writable. Omits this relationship from snapshots. #### `exclusive` _field_ ```nupp exclusive: boolean? ``` Caller-writable. Limits each source to one target when true. #### `sparse` _field_ ```nupp sparse: boolean? ``` Caller-writable. Selects entity-indexed edges instead of dense target columns. #### `reverseIndex` _field_ ```nupp reverseIndex: boolean? ``` Caller-writable. Maintains target-to-source lookup when true. #### `cascadeDelete` _field_ ```nupp cascadeDelete: boolean? ``` Caller-writable. Deletes sources with their target; requires both index and exclusivity. ### `RelationshipDefinition` _interface_ ```nupp interface RelationshipDefinition is Component ... ``` A payload relationship whose target selector retains the physical column type. #### Type parameters | Name | Description | | --- | --- | | `T` | | #### Members | Name | Kind | Description | | --- | --- | --- | | [`Value`](#tecs.ecs.RelationshipDefinition.Value) | field | | | [`Column`](#tecs.ecs.RelationshipDefinition.Column) | field | | | [`construct`](#tecs.ecs.RelationshipDefinition.construct) | method | | | [`defaultFactory`](#tecs.ecs.RelationshipDefinition.defaultFactory) | method | | | [`snapshotSave`](#tecs.ecs.RelationshipDefinition.snapshotSave) | method | | | [`snapshotLoad`](#tecs.ecs.RelationshipDefinition.snapshotLoad) | method | | | [`\_\_call`](#tecs.ecs.RelationshipDefinition.__call) | metamethod | | | [`targeting`](#tecs.ecs.RelationshipDefinition.targeting) | method | | #### `Value` _field_ ```nupp Value: associatedDecl ``` #### `Column` _field_ ```nupp Column: associatedDecl ``` #### `construct` _method_ ```nupp construct: function(...: any): T ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `...` | `any` | | ##### Returns | Type | Description | | --- | --- | | `T` | | #### `defaultFactory` _method_ ```nupp defaultFactory: function(): T ``` ##### Returns | Type | Description | | --- | --- | | `T` | | #### `snapshotSave` _method_ ```nupp snapshotSave: function(value: T): any ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `T` | | ##### Returns | Type | Description | | --- | --- | | `any` | | #### `snapshotLoad` _method_ ```nupp snapshotLoad: function(value: any, exclusive world: any): T ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `any` | | | `exclusive world` | `any` | | ##### Returns | Type | Description | | --- | --- | | `T` | | #### `__call` _metamethod_ ```nupp __call: function(self, ...: any): FFIInstance> ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `?` | `self` | | | `...` | `any` | | ##### Returns | Type | Description | | --- | --- | | `FFIInstance\\>` | | #### `targeting` _method_ ```nupp targeting: function(self: TypedRelationship, target: integer): TypedComponent ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `RelationshipDefinition\` | | | `target` | `integer` | | ##### Returns | Type | Description | | --- | --- | | `TypedComponent\` | | ### `RelationshipOptions` _type_ ```nupp type RelationshipOptions = { --- Caller-writable. Sets the stable process-wide relationship name. name: string, --- Caller-writable. Limits each source to one target when true; defaults to false. exclusive: boolean?, --- Caller-writable. Uses entity-indexed storage instead of target-specific --- archetypes when true. sparse: boolean?, --- Caller-writable. Maintains target-to-source lookup when true. reverseIndex: boolean?, --- Caller-writable. Deletes sources with their target; requires exclusive and --- reverseIndex. cascadeDelete: boolean?, --- Caller-writable. Adds missing definitions or shared instance values when an --- edge first adds this relationship. Tecs copies the list at registration. requires: {Input}?, --- Caller-writable. Omits this relationship from snapshots when true. transient: boolean? } ``` Construction and storage options for target-only relationships. ### `RelationshipPayload` _interface_ ```nupp sealed interface RelationshipPayload is Value ``` Bounds generic helpers to target-bearing declarations deriving the relationship contract. ### `RelationshipValue` _record_ ```nupp record RelationshipValue ... ``` A target-only relationship edge value. #### Members | Name | Kind | Description | | --- | --- | --- | | [`target`](#tecs.ecs.RelationshipValue.target) | field | Read-only. | #### `target` _field_ ```nupp target: integer ``` Read-only. Names the target; replace the edge through world:set to retarget it. ### `RelativeTransform2D` _struct_ ```nupp struct RelativeTransform2D ... ``` `@derive(nupp.derive.Debug)` Offsets an entity from the transform of the parent it names with `ChildOf`. #### Members | Name | Kind | Description | | --- | --- | --- | | [`x`](#tecs.ecs.RelativeTransform2D.x) | field | Caller-writable. | | [`y`](#tecs.ecs.RelativeTransform2D.y) | field | Caller-writable. | | [`z`](#tecs.ecs.RelativeTransform2D.z) | field | Caller-writable. | | [`rotation`](#tecs.ecs.RelativeTransform2D.rotation) | field | Caller-writable. | | [`scaleX`](#tecs.ecs.RelativeTransform2D.scaleX) | field | Caller-writable. | | [`scaleY`](#tecs.ecs.RelativeTransform2D.scaleY) | field | Caller-writable. | | [`originX`](#tecs.ecs.RelativeTransform2D.originX) | field | Caller-writable. | | [`originY`](#tecs.ecs.RelativeTransform2D.originY) | field | Caller-writable. | #### `x` _field_ ```nupp x: number ``` Caller-writable. Sets the horizontal offset from the parent, in the parent's rotated and scaled space. #### `y` _field_ ```nupp y: number ``` Caller-writable. Sets the vertical offset from the parent, in the parent's rotated and scaled space. #### `z` _field_ ```nupp z: number ``` Caller-writable. Sets the depth offset added to the parent's depth. #### `rotation` _field_ ```nupp rotation: number ``` Caller-writable. Sets the clockwise rotation in radians added to the parent's rotation. #### `scaleX` _field_ ```nupp scaleX: number ``` Caller-writable. Sets the horizontal scale multiplied by the parent's. #### `scaleY` _field_ ```nupp scaleY: number ``` Caller-writable. Sets the vertical scale multiplied by the parent's. #### `originX` _field_ ```nupp originX: number ``` Caller-writable. Sets the horizontal origin as a fraction of the entity's width, where zero is the left edge and one the right. The builtin composition carries this value and does not read it, because nothing in the transform knows the entity's size; a layout module that does read it is what gives it meaning. #### `originY` _field_ ```nupp originY: number ``` Caller-writable. Sets the vertical origin as a fraction of the entity's height, where zero is the top edge and one the bottom. The builtin composition carries this value and does not read it. ### `RunIf` _type_ ```nupp type RunIf = function(dt: number, exclusive world: World, systemName: string): boolean ``` A predicate receiving the phase delta, world and registered system name. ### `ScalarComponent` _record_ ```nupp record ScalarComponent is Component ... ``` A primitive-valued component definition. #### Type parameters | Name | Description | | --- | --- | | `T` | | #### Members | Name | Kind | Description | | --- | --- | --- | | [`Value`](#tecs.ecs.ScalarComponent.Value) | field | | | [`componentId`](#tecs.ecs.ScalarComponent.componentId) | field | | | [`componentName`](#tecs.ecs.ScalarComponent.componentName) | field | | | [`storageType`](#tecs.ecs.ScalarComponent.storageType) | field | | | [`transient`](#tecs.ecs.ScalarComponent.transient) | field | | | [`scalarKind`](#tecs.ecs.ScalarComponent.scalarKind) | field | | | [`scalarDefault`](#tecs.ecs.ScalarComponent.scalarDefault) | field | | | [`\_\_call`](#tecs.ecs.ScalarComponent.__call) | metamethod | | #### `Value` _field_ ```nupp Value: associatedDecl ``` #### `componentId` _field_ ```nupp componentId: integer ``` #### `componentName` _field_ ```nupp componentName: string ``` #### `storageType` _field_ ```nupp storageType: string ``` #### `transient` _field_ ```nupp transient: boolean ``` #### `scalarKind` _field_ ```nupp scalarKind: "number" | "boolean" | "string" ``` #### `scalarDefault` _field_ ```nupp scalarDefault: T ``` #### `__call` _metamethod_ ```nupp __call: function(self, value: T): ScalarInstance ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `?` | `self` | | | `value` | `T` | | ##### Returns | Type | Description | | --- | --- | | `ScalarInstance\` | | ### `ScalarComponentOptions` _type_ ```nupp type ScalarComponentOptions = NumberComponentOptions | BooleanComponentOptions | StringComponentOptions ``` Options accepted by the kind-correlated scalar component factory. ### `Snapshot` _record_ ```nupp record Snapshot ... ``` A detached, format-neutral world snapshot. #### Members | Name | Kind | Description | | --- | --- | --- | | [`version`](#tecs.ecs.Snapshot.version) | field | | | [`nextEntityId`](#tecs.ecs.Snapshot.nextEntityId) | field | | | [`entityCount`](#tecs.ecs.Snapshot.entityCount) | field | | | [`archetypeCount`](#tecs.ecs.Snapshot.archetypeCount) | field | | | [`componentTable`](#tecs.ecs.Snapshot.componentTable) | field | | | [`archetypes`](#tecs.ecs.Snapshot.archetypes) | field | | | [`data`](#tecs.ecs.Snapshot.data) | field | | | [`states`](#tecs.ecs.Snapshot.states) | field | | | [`format`](#tecs.ecs.Snapshot.format) | field | Read-only. | | [`buffer`](#tecs.ecs.Snapshot.buffer) | field | Read-only. | | [`pipeline`](#tecs.ecs.Snapshot.pipeline) | field | Read-only. | #### `version` _field_ ```nupp version: integer ``` #### `nextEntityId` _field_ ```nupp nextEntityId: integer ``` #### `entityCount` _field_ ```nupp entityCount: integer ``` #### `archetypeCount` _field_ ```nupp archetypeCount: integer ``` #### `componentTable` _field_ ```nupp componentTable: {SnapshotComponentEntry} ``` #### `archetypes` _field_ ```nupp archetypes: {SnapshotArchetype} ``` #### `data` _field_ ```nupp data: {SnapshotDataEntry} ``` #### `states` _field_ ```nupp states: {string} ``` #### `format` _field_ ```nupp format: ("binary" | "table")? ``` Read-only. Identifies binary output when a native buffer was requested. #### `buffer` _field_ ```nupp buffer: buffer.Buffer? ``` Read-only. Holds binary output; later saves into the same buffer overwrite it. #### `pipeline` _field_ ```nupp pipeline: { fixedAccumulator: number, phaseStates: {boolean}, disabledPhases: {[string]: boolean} }? ``` Read-only. Preserves fixed-step remainder and disabled phase names in table output. ### `SnapshotHandler` _type_ ```nupp type SnapshotHandler = { name: string, save: (function(exclusive world: World): any)?, load: (function(exclusive world: World, value: any): nil)?, finish: (function(exclusive world: World, prelude: SnapshotPrelude): nil)? } ``` A named custom snapshot participant. ### `SnapshotOptions` _type_ ```nupp type SnapshotOptions = { --- Caller-writable. Attaches unique named custom data. customData: {[string]: any}?, --- Caller-writable. Selects entities without automatic Disabled or Paused --- exclusions. filterQuery: query.Descriptor?, --- Caller-writable. Selects draw layers from zero through 31; entities without --- Transform2D always pass. layers: {integer}?, --- Caller-writable. Chooses binary framing or a detached table; nil retains table --- output. format: ("binary" | "table")?, --- Caller-writable. Supplies reusable binary output storage, reset at save time. buffer: buffer.Buffer?, --- Caller-writable. Writes binary output to this file and also returns its buffer. path: string? } ``` Options for adding custom snapshot data. ### `SnapshotPrelude` _record_ ```nupp record SnapshotPrelude ... ``` Metadata returned by a snapshot load. #### Members | Name | Kind | Description | | --- | --- | --- | | [`version`](#tecs.ecs.SnapshotPrelude.version) | field | Read-only. | | [`nextEntityId`](#tecs.ecs.SnapshotPrelude.nextEntityId) | field | Read-only. | | [`entityCount`](#tecs.ecs.SnapshotPrelude.entityCount) | field | Read-only. | | [`archetypeCount`](#tecs.ecs.SnapshotPrelude.archetypeCount) | field | Read-only. | | [`componentTable`](#tecs.ecs.SnapshotPrelude.componentTable) | field | Read-only. | #### `version` _field_ ```nupp version: integer ``` Read-only. Reports the ECS framing version, independently of game data versions. #### `nextEntityId` _field_ ```nupp nextEntityId: integer ``` Read-only. Reports the next fresh entity slot after restoration. #### `entityCount` _field_ ```nupp entityCount: integer ``` Read-only. Reports the number of saved entities. #### `archetypeCount` _field_ ```nupp archetypeCount: integer ``` Read-only. Reports the number of saved archetype frames. #### `componentTable` _field_ ```nupp componentTable: {SnapshotComponentEntry} ``` Read-only. Lists the saved component names and native layouts in frame-index order. ### `StartSnapshotLoad` _record_ ```nupp record StartSnapshotLoad ... ``` `@derive(events.Event)` `@event(name="StartSnapshotLoad")` Allows snapshot participants to subscribe to metadata during a load. #### Members | Name | Kind | Description | | --- | --- | --- | | [`prelude`](#tecs.ecs.StartSnapshotLoad.prelude) | field | Read-only. | | [`handlers`](#tecs.ecs.StartSnapshotLoad.handlers) | field | Engine-owned. | | [`onData`](#tecs.ecs.StartSnapshotLoad.onData) | method | Subscribes to one custom-data key for this load only. | #### `prelude` _field_ ```nupp prelude: SnapshotPrelude ``` Read-only. Describes the snapshot being restored. #### `handlers` _field_ ```nupp handlers: {[string]: {function(value: any)}} ``` Engine-owned. Supplies dispatch staging to event construction; use onData instead. #### `onData` _method_ ```nupp onData: function onData(self: StartSnapshotLoad, key: string, callback: function(value: any)): nil ``` Subscribes to one custom-data key for this load only. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `StartSnapshotLoad` | The call-scoped load event. | | `key` | `string` | The nonempty metadata key. | | `callback` | `function(value: any)` | The callback; multiple listeners receive the same key in registration order. | ##### Returns | Type | Description | | --- | --- | | `nil` | | ##### Raises | Type | Condition | | --- | --- | | `string` | when the key is empty. | ### `StateBlur` _record_ ```nupp record StateBlur ... ``` `@derive(events.Event)` `@event(name="StateBlur")` Fires after the current state loses focus. #### Members | Name | Kind | Description | | --- | --- | --- | | [`state`](#tecs.ecs.StateBlur.state) | field | | | [`pushed`](#tecs.ecs.StateBlur.pushed) | field | | #### `state` _field_ ```nupp state: string ``` #### `pushed` _field_ ```nupp pushed: string ``` ### `StateBlurChange` _type_ ```nupp type StateBlurChange = StateBlur ``` The payload emitted when a state loses focus. ### `StateChange` _type_ ```nupp type StateChange = StateEnter | StateExit ``` The payload emitted when a state enters or exits. ### `StateEnter` _record_ ```nupp record StateEnter ... ``` `@derive(events.Event)` `@event(name="StateEnter")` Fires after a state becomes active. #### Members | Name | Kind | Description | | --- | --- | --- | | [`state`](#tecs.ecs.StateEnter.state) | field | | #### `state` _field_ ```nupp state: string ``` ### `StateExit` _record_ ```nupp record StateExit ... ``` `@derive(events.Event)` `@event(name="StateExit")` Fires before a state leaves the stack. #### Members | Name | Kind | Description | | --- | --- | --- | | [`state`](#tecs.ecs.StateExit.state) | field | | #### `state` _field_ ```nupp state: string ``` ### `StateFocus` _record_ ```nupp record StateFocus ... ``` `@derive(events.Event)` `@event(name="StateFocus")` Fires after an uncovered state regains focus. #### Members | Name | Kind | Description | | --- | --- | --- | | [`state`](#tecs.ecs.StateFocus.state) | field | | | [`popped`](#tecs.ecs.StateFocus.popped) | field | | #### `state` _field_ ```nupp state: string ``` #### `popped` _field_ ```nupp popped: string ``` ### `StateFocusChange` _type_ ```nupp type StateFocusChange = StateFocus ``` The payload emitted when a state regains focus. ### `StatePolicy` _type_ ```nupp type StatePolicy = { onBlur: StatePolicyOperation?, onFocus: StatePolicyOperation?, onEnter: StatePolicyOperation?, onExit: StatePolicyOperation? } ``` Policy hooks for one world state. ### `System` _type_ ```nupp type System = function(dt: number, exclusive world: World, borrows scope: tasks.Scope) ``` A system body receiving elapsed time, its world, and the update task scope. ### `SystemConfig` _type_ ```nupp type SystemConfig = { --- Caller-writable. Names the system uniquely; nil requests an engine-owned name. name: string?, --- Caller-writable. Selects the leaf phase that dispatches the system. phase: phases.Phase, --- Caller-writable. Receives the phase delta, world and borrowed task scope. run: System, --- Caller-writable. Gates each dispatch; a disabled system does not evaluate it. runIf: RunIf?, --- Caller-writable. Names systems that must run later in this phase; missing and --- cross-phase names contribute no edge. The world copies the list. before: {string}?, --- Caller-writable. Names systems that must run earlier in this phase; missing and --- cross-phase names contribute no edge. The world copies the list. after: {string}?, --- Caller-writable. Publishes staged changes before evaluating runIf. commitBefore: boolean?, --- Caller-writable. Publishes staged changes after dispatch, even when runIf is --- false. commitAfter: boolean? } ``` Registration options for a frame system. ### `SystemInfo` _type_ ```nupp type SystemInfo = { --- Read-only. Names the registered system. name: string, --- Read-only. Names its dispatch phase. phase: phases.Phase, --- Read-only. Reports its position in the inspected schedule. position: integer, --- Read-only. Reports whether the scheduler permits dispatch. enabled: boolean, --- Read-only. Reports whether dispatch has an additional predicate. hasRunIf: boolean } ``` One registered system as reported in execution order. ### `TagComponentOptions` _type_ ```nupp type TagComponentOptions = { name: string, transient: boolean?, --- Caller-writable. Adds missing definitions or shared instance values, including --- transitive requirements. Tecs copies the list at registration. requires: {Input}? } ``` Options for a marker component with no per-entity value. ### `Transform2D` _struct_ ```nupp struct Transform2D ... ``` `@derive(nupp.derive.Debug)` Places an entity in the two-dimensional world. #### Members | Name | Kind | Description | | --- | --- | --- | | [`x`](#tecs.ecs.Transform2D.x) | field | Caller-writable. | | [`y`](#tecs.ecs.Transform2D.y) | field | Caller-writable. | | [`z`](#tecs.ecs.Transform2D.z) | field | Caller-writable. | | [`layer`](#tecs.ecs.Transform2D.layer) | field | Caller-writable. | | [`rotation`](#tecs.ecs.Transform2D.rotation) | field | Caller-writable. | | [`scaleX`](#tecs.ecs.Transform2D.scaleX) | field | Caller-writable. | | [`scaleY`](#tecs.ecs.Transform2D.scaleY) | field | Caller-writable. | #### `x` _field_ ```nupp x: number ``` Caller-writable. Sets the horizontal position in world units. #### `y` _field_ ```nupp y: number ``` Caller-writable. Sets the vertical position in world units. #### `z` _field_ ```nupp z: number ``` Caller-writable. Sets depth within the selected layer. #### `layer` _field_ ```nupp layer: integer ``` Caller-writable. Selects the integer draw layer. #### `rotation` _field_ ```nupp rotation: number ``` Caller-writable. Sets clockwise rotation in radians. #### `scaleX` _field_ ```nupp scaleX: number ``` Caller-writable. Sets horizontal scale in world units. #### `scaleY` _field_ ```nupp scaleY: number ``` Caller-writable. Sets vertical scale in world units. ### `Transform3D` _struct_ ```nupp struct Transform3D ... ``` `@derive(nupp.derive.Debug)` Places an entity in a right-handed 3D world using a quaternion and per-axis scale. #### Members | Name | Kind | Description | | --- | --- | --- | | [`x`](#tecs.ecs.Transform3D.x) | field | | | [`y`](#tecs.ecs.Transform3D.y) | field | | | [`z`](#tecs.ecs.Transform3D.z) | field | | | [`rotationX`](#tecs.ecs.Transform3D.rotationX) | field | | | [`rotationY`](#tecs.ecs.Transform3D.rotationY) | field | | | [`rotationZ`](#tecs.ecs.Transform3D.rotationZ) | field | | | [`rotationW`](#tecs.ecs.Transform3D.rotationW) | field | | | [`scaleX`](#tecs.ecs.Transform3D.scaleX) | field | | | [`scaleY`](#tecs.ecs.Transform3D.scaleY) | field | | | [`scaleZ`](#tecs.ecs.Transform3D.scaleZ) | field | | #### `x` _field_ ```nupp x: number ``` #### `y` _field_ ```nupp y: number ``` #### `z` _field_ ```nupp z: number ``` #### `rotationX` _field_ ```nupp rotationX: number ``` #### `rotationY` _field_ ```nupp rotationY: number ``` #### `rotationZ` _field_ ```nupp rotationZ: number ``` #### `rotationW` _field_ ```nupp rotationW: number ``` #### `scaleX` _field_ ```nupp scaleX: number ``` #### `scaleY` _field_ ```nupp scaleY: number ``` #### `scaleZ` _field_ ```nupp scaleZ: number ``` ### `TTL` _struct_ ```nupp struct TTL ... ``` `@derive(nupp.derive.Debug)` Counts down an entity's remaining lifetime. #### Members | Name | Kind | Description | | --- | --- | --- | | [`startingTime`](#tecs.ecs.TTL.startingTime) | field | Caller-writable. | | [`remaining`](#tecs.ecs.TTL.remaining) | field | Caller-writable. | | [`percentComplete`](#tecs.ecs.TTL.percentComplete) | method | Returns elapsed lifetime as a fraction from zero at spawn to one at expiry. | #### `startingTime` _field_ ```nupp startingTime: number ``` Caller-writable. Sets the lifetime the entity started with, in seconds, which is what `percentComplete` measures against. Raising `remaining` past this value leaves `percentComplete` negative, so refresh both when a pickup extends a timer. #### `remaining` _field_ ```nupp remaining: number ``` Caller-writable. Sets the seconds of fixed time left before the entity is despawned. Writing a larger value refreshes the timer. #### `percentComplete` _method_ ```nupp percentComplete: function percentComplete(self: TTL): number ``` Returns elapsed lifetime as a fraction from zero at spawn to one at expiry. A fresh `TTL` answers zero and an expired one answers one, so a fade or a shrink can drive straight off it. A value restored from a snapshot whose `startingTime` is zero also answers one, because nothing distinguishes it from having run out. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `TTL` | the lifetime to measure | ##### Returns | Type | Description | | --- | --- | | `number` | the completed fraction, clamped to the range zero through one | ### `World` _record_ ```nupp record World is Source ... ``` A Tecs world. #### Members | Name | Kind | Description | | --- | --- | --- | | [`allocator`](#tecs.ecs.World.allocator) | field | | | [`archetypes`](#tecs.ecs.World.archetypes) | field | | | [`archetypeById`](#tecs.ecs.World.archetypeById) | field | | | [`maxArchetypeId`](#tecs.ecs.World.maxArchetypeId) | field | | | [`freeArchetypeIds`](#tecs.ecs.World.freeArchetypeIds) | field | | | [`archetypeBySignature`](#tecs.ecs.World.archetypeBySignature) | field | | | [`componentArchetypes`](#tecs.ecs.World.componentArchetypes) | field | | | [`dirtyQueue`](#tecs.ecs.World.dirtyQueue) | field | | | [`pendingSpawns`](#tecs.ecs.World.pendingSpawns) | field | | | [`flatSpawns`](#tecs.ecs.World.flatSpawns) | field | | | [`flatSpawnCount`](#tecs.ecs.World.flatSpawnCount) | field | | | [`flatSealedCount`](#tecs.ecs.World.flatSealedCount) | field | | | [`spawnShapes`](#tecs.ecs.World.spawnShapes) | field | | | [`spawnScratch`](#tecs.ecs.World.spawnScratch) | field | | | [`flatMoves`](#tecs.ecs.World.flatMoves) | field | | | [`flatMoveCount`](#tecs.ecs.World.flatMoveCount) | field | | | [`flatMovesSealed`](#tecs.ecs.World.flatMovesSealed) | field | | | [`moveScratch`](#tecs.ecs.World.moveScratch) | field | | | [`mutationValues`](#tecs.ecs.World.mutationValues) | field | | | [`emptyValues`](#tecs.ecs.World.emptyValues) | field | | | [`pendingSegments`](#tecs.ecs.World.pendingSegments) | field | | | [`pendingSpawnBySlot`](#tecs.ecs.World.pendingSpawnBySlot) | field | | | [`spawnBatches`](#tecs.ecs.World.spawnBatches) | field | | | [`mutationBatches`](#tecs.ecs.World.mutationBatches) | field | | | [`pendingMoves`](#tecs.ecs.World.pendingMoves) | field | | | [`pendingMoveBySlot`](#tecs.ecs.World.pendingMoveBySlot) | field | | | [`publishingMove`](#tecs.ecs.World.publishingMove) | field | | | [`pendingDespawns`](#tecs.ecs.World.pendingDespawns) | field | | | [`pendingDespawnBySlot`](#tecs.ecs.World.pendingDespawnBySlot) | field | | | [`queries`](#tecs.ecs.World.queries) | field | | | [`queryOwner`](#tecs.ecs.World.queryOwner) | field | | | [`queryObservers`](#tecs.ecs.World.queryObservers) | field | | | [`relationshipIndexes`](#tecs.ecs.World.relationshipIndexes) | field | | | [`keyIndex`](#tecs.ecs.World.keyIndex) | field | | | [`systems`](#tecs.ecs.World.systems) | field | | | [`schedule`](#tecs.ecs.World.schedule) | field | | | [`scheduleDirty`](#tecs.ecs.World.scheduleDirty) | field | | | [`pipeline`](#tecs.ecs.World.pipeline) | field | | | [`customPhases`](#tecs.ecs.World.customPhases) | field | | | [`phaseOrder`](#tecs.ecs.World.phaseOrder) | field | | | [`systemNames`](#tecs.ecs.World.systemNames) | field | | | [`anonymousSystemCount`](#tecs.ecs.World.anonymousSystemCount) | field | | | [`disabledPhases`](#tecs.ecs.World.disabledPhases) | field | | | [`bundles`](#tecs.ecs.World.bundles) | field | | | [`snapshotHandlers`](#tecs.ecs.World.snapshotHandlers) | field | | | [`snapshotHandlerNames`](#tecs.ecs.World.snapshotHandlerNames) | field | | | [`randomRegistry`](#tecs.ecs.World.randomRegistry) | field | | | [`stateComponents`](#tecs.ecs.World.stateComponents) | field | | | [`statePolicies`](#tecs.ecs.World.statePolicies) | field | | | [`stateStack`](#tecs.ecs.World.stateStack) | field | | | [`autoStateComponent`](#tecs.ecs.World.autoStateComponent) | field | | | [`updating`](#tecs.ecs.World.updating) | field | | | [`observedEntities`](#tecs.ecs.World.observedEntities) | field | The entity addresses something has observed, so clearing every entity can clear their registrations without touching... | | [`transitionObserver`](#tecs.ecs.World.transitionObserver) | field | | | [`committing`](#tecs.ecs.World.committing) | field | | | [`runningSystem`](#tecs.ecs.World.runningSystem) | field | | | [`systemThread`](#tecs.ecs.World.systemThread) | field | | | [`commitRequested`](#tecs.ecs.World.commitRequested) | field | | | [`nominalFrameTime`](#tecs.ecs.World.nominalFrameTime) | field | | | [`fixedTimestep`](#tecs.ecs.World.fixedTimestep) | field | | | [`fixedAccumulator`](#tecs.ecs.World.fixedAccumulator) | field | | | [`fixedStepTotal`](#tecs.ecs.World.fixedStepTotal) | field | | | [`fixedMaxSteps`](#tecs.ecs.World.fixedMaxSteps) | field | | | [`fixedOverload`](#tecs.ecs.World.fixedOverload) | field | | | [`fixedTimeDropped`](#tecs.ecs.World.fixedTimeDropped) | field | | | [`fixedStepsDropped`](#tecs.ecs.World.fixedStepsDropped) | field | | | [`beforeFixedCallbacks`](#tecs.ecs.World.beforeFixedCallbacks) | field | | | [`afterFixedCallbacks`](#tecs.ecs.World.afterFixedCallbacks) | field | | | [`liveCount`](#tecs.ecs.World.liveCount) | field | | | [`archetypeCount`](#tecs.ecs.World.archetypeCount) | field | | | [`systemCount`](#tecs.ecs.World.systemCount) | field | | | [`observers`](#tecs.ecs.World.observers) | field | Observer registrations by address and event; observers.count is how many are live. | | [`resources`](#tecs.ecs.World.resources) | field | | | [`spawn`](#tecs.ecs.World.spawn) | method | | | [`spawnAt`](#tecs.ecs.World.spawnAt) | method | | | [`batchSpawn`](#tecs.ecs.World.batchSpawn) | method | Reserves a batch sharing one signature and initializes its rows at the next barrier. | | [`batchSpawnAt`](#tecs.ecs.World.batchSpawnAt) | method | Reserves supplied packed identities in order for a deferred batch spawn. | | [`batchSpawnAtRaw`](#tecs.ecs.World.batchSpawnAtRaw) | method | Reserves packed identities directly from a zero-based native double array. | | [`batchSet`](#tecs.ecs.World.batchSet) | method | Stages a value or deferred column writer for currently matching entities. | | [`batchRemove`](#tecs.ecs.World.batchRemove) | method | Stages component removal for the query's current committed members. | | [`batchDespawn`](#tecs.ecs.World.batchDespawn) | method | Stages normal teardown, events and cascading for currently matching entities. | | [`forEachArchetype`](#tecs.ecs.World.forEachArchetype) | method | Visits every archetype, including empty and disabled ones, in registry order. | | [`findArchetypes`](#tecs.ecs.World.findArchetypes) | method | Iterates registered archetypes containing a component, including empty ones. | | [`dirtyArchetypes`](#tecs.ecs.World.dirtyArchetypes) | method | Captures archetypes with dirty components in registry order. | | [`compact`](#tecs.ecs.World.compact) | method | Prunes empty dead-target archetypes and rebuilds storage that has lost rows. | | [`isAlive`](#tecs.ecs.World.isAlive) | method | | | [`has`](#tecs.ecs.World.has) | method | | | [`byKey`](#tecs.ecs.World.byKey) | method | | | [`requireKey`](#tecs.ecs.World.requireKey) | method | | | [`get`](#tecs.ecs.World.get) | field | | | [`getMut`](#tecs.ecs.World.getMut) | field | | | [`markComponentDirty`](#tecs.ecs.World.markComponentDirty) | method | | | [`relationshipSources`](#tecs.ecs.World.relationshipSources) | method | | | [`forEachRelationship`](#tecs.ecs.World.forEachRelationship) | field | Iterates a source entity's edges in target order. | | [`getFirstRelationship`](#tecs.ecs.World.getFirstRelationship) | field | Returns the first edge in target order. | | [`targets`](#tecs.ecs.World.targets) | method | Visits sources targeting an entity in ascending identifier order. | | [`traverse`](#tecs.ecs.World.traverse) | method | Traverses descendants depth first, visiting each identifier at most once. | | [`walkUp`](#tecs.ecs.World.walkUp) | method | Walks the first outgoing edge at each level, in target order. | | [`newQuery`](#tecs.ecs.World.newQuery) | method | Creates a query over committed entities, excluding Disabled by default. | | [`set`](#tecs.ecs.World.set) | method | | | [`remove`](#tecs.ecs.World.remove) | method | | | [`despawn`](#tecs.ecs.World.despawn) | method | | | [`commit`](#tecs.ecs.World.commit) | method | Publishes staged mutations synchronously, including work staged by observers. | | [`enqueueCommit`](#tecs.ecs.World.enqueueCommit) | method | Requests publication after the current system and its predicate return. | | [`randomStream`](#tecs.ecs.World.randomStream) | method | Returns this world's stable named Nupp random generator. | | [`seedRandom`](#tecs.ecs.World.seedRandom) | method | Restarts every named random stream without replacing captured generators. | | [`clearEntities`](#tecs.ecs.World.clearEntities) | method | Clears entity data and pending batches while preserving systems, queries and resources. | | [`addSystem`](#tecs.ecs.World.addSystem) | method | Registers a system for the next external dispatch, copying its constraints. | | [`registerPhase`](#tecs.ecs.World.registerPhase) | method | Registers a custom leaf or tree without adding it to the default frame loop. | | [`removeSystem`](#tecs.ecs.World.removeSystem) | method | | | [`listSystems`](#tecs.ecs.World.listSystems) | method | Reports the next schedule in phase and dependency order. | | [`setSystemEnabled`](#tecs.ecs.World.setSystemEnabled) | method | | | [`update`](#tecs.ecs.World.update) | method | | | [`startup`](#tecs.ecs.World.startup) | method | | | [`shutdown`](#tecs.ecs.World.shutdown) | method | | | [`runPhase`](#tecs.ecs.World.runPhase) | method | | | [`enablePhase`](#tecs.ecs.World.enablePhase) | method | | | [`disablePhase`](#tecs.ecs.World.disablePhase) | method | | | [`isPhaseEnabled`](#tecs.ecs.World.isPhaseEnabled) | method | | | [`getNominalFrameTime`](#tecs.ecs.World.getNominalFrameTime) | method | Returns the configured seconds per presentation tick. | | [`setNominalFrameTime`](#tecs.ecs.World.setNominalFrameTime) | method | Changes conversion for future sequence waits; existing deadlines stay fixed. | | [`getFixedTiming`](#tecs.ecs.World.getFixedTiming) | method | | | [`fixedStepCount`](#tecs.ecs.World.fixedStepCount) | method | | | [`getStats`](#tecs.ecs.World.getStats) | method | Reports current counts and accumulated fixed-step losses. | | [`createState`](#tecs.ecs.World.createState) | method | | | [`pushState`](#tecs.ecs.World.pushState) | method | | | [`popState`](#tecs.ecs.World.popState) | method | | | [`peekState`](#tecs.ecs.World.peekState) | method | | | [`listStates`](#tecs.ecs.World.listStates) | method | | | [`newBundle`](#tecs.ecs.World.newBundle) | method | | | [`spawnBundle`](#tecs.ecs.World.spawnBundle) | method | | | [`getBundles`](#tecs.ecs.World.getBundles) | method | | | [`getBundle`](#tecs.ecs.World.getBundle) | method | | | [`saveSnapshot`](#tecs.ecs.World.saveSnapshot) | method | Saves committed entities and durable world metadata in table or native binary form. | | [`loadSnapshot`](#tecs.ecs.World.loadSnapshot) | method | Replaces entity state while retaining registered runtime setup. | | [`addSnapshotHandler`](#tecs.ecs.World.addSnapshotHandler) | method | | | [`observe`](#tecs.ecs.World.observe) | method | | | [`observeOnce`](#tecs.ecs.World.observeOnce) | method | | | [`stopObserving`](#tecs.ecs.World.stopObserving) | method | | | [`hasObservers`](#tecs.ecs.World.hasObservers) | method | | | [`emit`](#tecs.ecs.World.emit) | method | | | [`deliver`](#tecs.ecs.World.deliver) | method | | | [`clearObservers`](#tecs.ecs.World.clearObservers) | method | | #### `allocator` _field_ ```nupp allocator: idallocator.IdAllocator ``` `@private` #### `archetypes` _field_ ```nupp archetypes: {archetype.Archetype} ``` `@private` #### `archetypeById` _field_ ```nupp archetypeById: {[integer]: archetype.Archetype} ``` `@private` #### `maxArchetypeId` _field_ ```nupp maxArchetypeId: integer ``` `@private` #### `freeArchetypeIds` _field_ ```nupp freeArchetypeIds: {integer} ``` `@private` #### `archetypeBySignature` _field_ ```nupp archetypeBySignature: {[string]: archetype.Archetype} ``` `@private` #### `componentArchetypes` _field_ ```nupp componentArchetypes: {[integer]: {archetype.Archetype}} ``` `@private` #### `dirtyQueue` _field_ ```nupp dirtyQueue: archetype.DirtyQueue ``` `@private` #### `pendingSpawns` _field_ ```nupp pendingSpawns: {PendingSpawn} ``` `@private` #### `flatSpawns` _field_ ```nupp flatSpawns: {any} ``` `@private` #### `flatSpawnCount` _field_ ```nupp flatSpawnCount: integer ``` `@private` #### `flatSealedCount` _field_ ```nupp flatSealedCount: integer ``` `@private` #### `spawnShapes` _field_ ```nupp spawnShapes: SpawnShape ``` `@private` #### `spawnScratch` _field_ ```nupp spawnScratch: {[integer]: any} ``` `@private` #### `flatMoves` _field_ ```nupp flatMoves: {any} ``` `@private` #### `flatMoveCount` _field_ ```nupp flatMoveCount: integer ``` `@private` #### `flatMovesSealed` _field_ ```nupp flatMovesSealed: integer ``` `@private` #### `moveScratch` _field_ ```nupp moveScratch: PendingMove ``` `@private` #### `mutationValues` _field_ ```nupp mutationValues: {[integer]: any} ``` `@private` #### `emptyValues` _field_ ```nupp emptyValues: {[integer]: any} ``` `@private` #### `pendingSegments` _field_ ```nupp pendingSegments: {PendingSegment} ``` `@private` #### `pendingSpawnBySlot` _field_ ```nupp pendingSpawnBySlot: {[integer]: PendingSpawn} ``` `@private` #### `spawnBatches` _field_ ```nupp spawnBatches: {SpawnBatch} ``` `@private` #### `mutationBatches` _field_ ```nupp mutationBatches: {MutationBatch} ``` `@private` #### `pendingMoves` _field_ ```nupp pendingMoves: {PendingMove} ``` `@private` #### `pendingMoveBySlot` _field_ ```nupp pendingMoveBySlot: {[integer]: PendingMove} ``` `@private` #### `publishingMove` _field_ ```nupp publishingMove: PendingMove? ``` `@private` #### `pendingDespawns` _field_ ```nupp pendingDespawns: {integer} ``` `@private` #### `pendingDespawnBySlot` _field_ ```nupp pendingDespawnBySlot: {[integer]: boolean} ``` `@private` #### `queries` _field_ ```nupp queries: {query.Query} ``` `@private` #### `queryOwner` _field_ ```nupp queryOwner: query.Owner ``` `@private` #### `queryObservers` _field_ ```nupp queryObservers: {query.Query} ``` `@private` #### `relationshipIndexes` _field_ ```nupp relationshipIndexes: {[integer]: inverseindex.InverseIndex} ``` `@private` #### `keyIndex` _field_ ```nupp keyIndex: {[string]: integer} ``` `@private` #### `systems` _field_ ```nupp systems: {RegisteredSystem} ``` `@private` #### `schedule` _field_ ```nupp schedule: {[phases.Phase]: {RegisteredSystem}} ``` `@private` #### `scheduleDirty` _field_ ```nupp scheduleDirty: boolean ``` `@private` #### `pipeline` _field_ ```nupp pipeline: Pipeline? ``` `@private` #### `customPhases` _field_ ```nupp customPhases: {[string]: phases.Definition} ``` `@private` #### `phaseOrder` _field_ ```nupp phaseOrder: {string} ``` `@private` #### `systemNames` _field_ ```nupp systemNames: {[string]: RegisteredSystem} ``` `@private` #### `anonymousSystemCount` _field_ ```nupp anonymousSystemCount: integer ``` `@private` #### `disabledPhases` _field_ ```nupp disabledPhases: {[string]: boolean} ``` `@private` #### `bundles` _field_ ```nupp bundles: {[string]: Bundle} ``` `@private` #### `snapshotHandlers` _field_ ```nupp snapshotHandlers: {SnapshotHandler} ``` `@private` #### `snapshotHandlerNames` _field_ ```nupp snapshotHandlerNames: {[string]: boolean} ``` `@private` #### `randomRegistry` _field_ ```nupp randomRegistry: randomstreams.Registry? ``` `@private` #### `stateComponents` _field_ ```nupp stateComponents: {[string]: components.Component} ``` `@private` #### `statePolicies` _field_ ```nupp statePolicies: {[string]: StatePolicy} ``` `@private` #### `stateStack` _field_ ```nupp stateStack: {string} ``` `@private` #### `autoStateComponent` _field_ ```nupp autoStateComponent: components.Component? ``` `@private` #### `updating` _field_ ```nupp updating: boolean ``` `@private` #### `observedEntities` _field_ ```nupp observedEntities: {[integer]: boolean} ``` `@private` The entity addresses something has observed, so clearing every entity can clear their registrations without touching the world's own. #### `transitionObserver` _field_ ```nupp transitionObserver: TransitionObserver? ``` `@private` #### `committing` _field_ ```nupp committing: boolean ``` `@private` #### `runningSystem` _field_ ```nupp runningSystem: boolean ``` `@private` #### `systemThread` _field_ ```nupp systemThread: thread? ``` `@private` #### `commitRequested` _field_ ```nupp commitRequested: boolean ``` `@private` #### `nominalFrameTime` _field_ ```nupp nominalFrameTime: number ``` `@private` #### `fixedTimestep` _field_ ```nupp fixedTimestep: number ``` `@private` #### `fixedAccumulator` _field_ ```nupp fixedAccumulator: number ``` `@private` #### `fixedStepTotal` _field_ ```nupp fixedStepTotal: integer ``` `@private` #### `fixedMaxSteps` _field_ ```nupp fixedMaxSteps: integer ``` `@private` #### `fixedOverload` _field_ ```nupp fixedOverload: FixedOverload ``` `@private` #### `fixedTimeDropped` _field_ ```nupp fixedTimeDropped: number ``` `@private` #### `fixedStepsDropped` _field_ ```nupp fixedStepsDropped: integer ``` `@private` #### `beforeFixedCallbacks` _field_ ```nupp beforeFixedCallbacks: {function(exclusive world: World)}? ``` `@private` #### `afterFixedCallbacks` _field_ ```nupp afterFixedCallbacks: {function(exclusive world: World)}? ``` `@private` #### `liveCount` _field_ ```nupp liveCount: integer ``` #### `archetypeCount` _field_ ```nupp archetypeCount: integer ``` #### `systemCount` _field_ ```nupp systemCount: integer ``` #### `observers` _field_ ```nupp observers: Observers ``` Observer registrations by address and event; `observers.count` is how many are live. #### `resources` _field_ ```nupp resources: Store ``` #### `spawn` _method_ ```nupp spawn: function(exclusive self: World, ...: components.Input): integer ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `...` | `components.Input` | | ##### Returns | Type | Description | | --- | --- | | `integer` | | #### `spawnAt` _method_ ```nupp spawnAt: function(exclusive self: World, id: integer, ...: components.Input): nil ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `id` | `integer` | | | `...` | `components.Input` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `batchSpawn` _method_ ```nupp batchSpawn: function( exclusive self: World, count: integer, inputs: {components.Input}, callback: BatchCallback? ): (integer?, {integer}?) ``` Reserves a batch sharing one signature and initializes its rows at the next barrier. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | The world to modify. | | `count` | `integer` | The positive number of entities to reserve. | | `inputs` | `{components.Input}` | The component definitions or values, including required defaults. | | `callback` | `BatchCallback?` | The optional initializer, called before membership and spawn events. | ##### Returns | Type | Description | | --- | --- | | `integer?` | Returns a first packed id and nil for a contiguous range, or nil and an explicit id list when slots or generations are non-contiguous. | | `{integer}?` | | ##### Raises | Type | Condition | | --- | --- | | `string` | for invalid count, exhausted capacity, bare relationships or EntityKey. | #### `batchSpawnAt` _method_ ```nupp batchSpawnAt: function( exclusive self: World, ids: {integer}, inputs: {components.Input}, callback: BatchCallback? ): nil ``` Reserves supplied packed identities in order for a deferred batch spawn. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | The world to modify. | | `ids` | `{integer}` | The identities to restore; an empty list does nothing. | | `inputs` | `{components.Input}` | The shared component signature and initial values. | | `callback` | `BatchCallback?` | The optional row initializer at publication. | ##### Returns | Type | Description | | --- | --- | | `nil` | | ##### Raises | Type | Condition | | --- | --- | | `string` | before reserving any id if one is invalid, duplicated or occupied, or the signature contains EntityKey or a bare relationship. | #### `batchSpawnAtRaw` _method_ ```nupp batchSpawnAtRaw: function( exclusive self: World, ids: number[?], count: integer, inputs: {components.Input}, callback: BatchCallback? ): nil ``` Reserves packed identities directly from a zero-based native double array. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | The world to modify. | | `ids` | `number\[?\]` | The borrowed array, retained until publication. Do not change its selected prefix before the barrier. | | `count` | `integer` | The number of identities in the prefix; zero does nothing. | | `inputs` | `{components.Input}` | The shared signature. Unlike ordinary batch spawns, this restoration path permits EntityKey, initialized before key registration. | | `callback` | `BatchCallback?` | The optional initializer, called before indexes and observers. | ##### Returns | Type | Description | | --- | --- | | `nil` | | ##### Raises | Type | Condition | | --- | --- | | `string` | before reservation for an invalid count, identity, duplicate, occupied slot, or bare relationship. | #### `batchSet` _method_ ```nupp batchSet: function( exclusive self: World, selection: query.Query, input: components.Input, callback: BatchCallback? ): nil ``` Stages a value or deferred column writer for currently matching entities. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | The world owning the query. | | `selection` | `query.Query` | The reusable query; membership is captured at this call. | | `input` | `components.Input` | The component value, or definition when supplying a callback. | | `callback` | `BatchCallback?` | The optional writer, called for each contiguous affected range. | ##### Returns | Type | Description | | --- | --- | | `nil` | | ##### Raises | Type | Condition | | --- | --- | | `string` | for a foreign query, EntityKey, or callback mode with an instance or relationship. Relationship values support constant mode. | #### `batchRemove` _method_ ```nupp batchRemove: function(exclusive self: World, selection: query.Query, input: components.Input): nil ``` Stages component removal for the query's current committed members. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | The world owning the query. | | `selection` | `query.Query` | The reusable query to capture now. | | `input` | `components.Input` | The component definition or a relationship value selecting one target. | ##### Returns | Type | Description | | --- | --- | | `nil` | | ##### Raises | Type | Condition | | --- | --- | | `string` | when the query belongs to another world. | #### `batchDespawn` _method_ ```nupp batchDespawn: function(exclusive self: World, selection: query.Query): nil ``` Stages normal teardown, events and cascading for currently matching entities. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | The world owning the query. | | `selection` | `query.Query` | The reusable query to capture now. | ##### Returns | Type | Description | | --- | --- | | `nil` | | ##### Raises | Type | Condition | | --- | --- | | `string` | when the query belongs to another world. | #### `forEachArchetype` _method_ ```nupp forEachArchetype: function(borrows self: World, callback: function(candidate: archetype.Archetype)): nil ``` Visits every archetype, including empty and disabled ones, in registry order. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | The world to inspect. | | `callback` | `function(candidate: archetype.Archetype)` | The callback; it must not commit or compact during this traversal. | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `findArchetypes` _method_ ```nupp findArchetypes: function( borrows self: World, component: components.Selector ): function(): (archetype.Archetype?, integer?, DoubleArray?) ``` Iterates registered archetypes containing a component, including empty ones. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | The world to inspect. | | `component` | `components.Selector` | The component used to select the index. | ##### Returns | Type | Description | | --- | --- | | `function(): (archetype.Archetype?, integer?, DoubleArray?)` | Returns an iterator over the live component index. | #### `dirtyArchetypes` _method_ ```nupp dirtyArchetypes: function(borrows self: World): function(): archetype.Archetype? ``` Captures archetypes with dirty components in registry order. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | The world to inspect. | ##### Returns | Type | Description | | --- | --- | | `function(): archetype.Archetype?` | Returns an independent iterator, including empty dirty archetypes. | #### `compact` _method_ ```nupp compact: function(exclusive self: World): (integer, integer) ``` Prunes empty dead-target archetypes and rebuilds storage that has lost rows. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | A quiet world with no pending mutations or active dispatch. | ##### Returns | Type | Description | | --- | --- | | `integer` | Returns the number of archetypes pruned and surviving stores rebuilt. | | `integer` | | ##### Raises | Type | Condition | | --- | --- | | `string` | during dispatch, publication, or with uncommitted work. | #### `isAlive` _method_ ```nupp isAlive: function(borrows self: World, id: integer): boolean ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | | | `id` | `integer` | | ##### Returns | Type | Description | | --- | --- | | `boolean` | | #### `has` _method_ ```nupp has: function(borrows self: World, id: integer, component: components.Selector): boolean ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | | | `id` | `integer` | | | `component` | `components.Selector` | | ##### Returns | Type | Description | | --- | --- | | `boolean` | | #### `byKey` _method_ ```nupp byKey: function(borrows self: World, key: string): integer? ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | | | `key` | `string` | | ##### Returns | Type | Description | | --- | --- | | `integer?` | | #### `requireKey` _method_ ```nupp requireKey: function(borrows self: World, key: string): integer ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | | | `key` | `string` | | ##### Returns | Type | Description | | --- | --- | | `integer` | | #### `get` _field_ ```nupp get: (function(borrows self: World, id: integer, component: C): C.Value?) & (function(borrows self: World, id: integer, component: Type): T?) ``` #### `getMut` _field_ ```nupp getMut: (function(exclusive self: World, id: integer, component: C): C.Value?) & (function(exclusive self: World, id: integer, component: Type): T?) ``` #### `markComponentDirty` _method_ ```nupp markComponentDirty: function(exclusive self: World, id: integer, component: components.Selector): nil ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `id` | `integer` | | | `component` | `components.Selector` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `relationshipSources` _method_ ```nupp relationshipSources: function(borrows self: World, relationship: components.Selector, target: integer): {integer} ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | | | `relationship` | `components.Selector` | | | `target` | `integer` | | ##### Returns | Type | Description | | --- | --- | | `{integer}` | | #### `forEachRelationship` _field_ ```nupp forEachRelationship: ( function( borrows self: World, id: integer, relationship: C, callback: function(value: C.Value) ): nil ) & ( function( borrows self: World, id: integer, relationship: Type, callback: function(value: T) ): nil ) ``` Iterates a source entity's edges in target order. #### `getFirstRelationship` _field_ ```nupp getFirstRelationship: ( function(borrows self: World, id: integer, relationship: C): C.Value? ) & ( function(borrows self: World, id: integer, relationship: Type): T? ) ``` Returns the first edge in target order. #### `targets` _method_ ```nupp targets: function( borrows self: World, target: integer, relationship: components.Selector, callback: function(source: integer, context: T), context: T ): nil ``` Visits sources targeting an entity in ascending identifier order. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | The world to inspect. | | `target` | `integer` | The target entity identifier. | | `relationship` | `components.Selector` | The reverse-indexed relationship. | | `callback` | `function(source: integer, context: T)` | The callback receiving each source and the caller's context. | | `context` | `T` | The caller-owned callback context. | ##### Returns | Type | Description | | --- | --- | | `nil` | | ##### Raises | Type | Condition | | --- | --- | | `string` | when the relationship has no reverse index. | #### `traverse` _method_ ```nupp traverse: function( borrows self: World, root: integer, relationship: components.Selector ): function(): (integer?, integer?) ``` Traverses descendants depth first, visiting each identifier at most once. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | The world to inspect. | | `root` | `integer` | The excluded root identifier. | | `relationship` | `components.Selector` | The reverse-indexed relationship. | ##### Returns | Type | Description | | --- | --- | | `function(): (integer?, integer?)` | Returns an iterator yielding depth and entity; direct children have depth zero. | ##### Raises | Type | Condition | | --- | --- | | `string` | when the relationship has no reverse index. | #### `walkUp` _method_ ```nupp walkUp: function( borrows self: World, id: integer, relationship: components.Selector, callback: function(ancestor: integer, depth: integer, context: T): boolean?, context: T, maxDepth: integer? ): nil ``` Walks the first outgoing edge at each level, in target order. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | The world to inspect. | | `id` | `integer` | The excluded starting entity. | | `relationship` | `components.Selector` | The relationship to follow. | | `callback` | `function(ancestor: integer, depth: integer, context: T): boolean?` | The callback receiving ancestor, depth starting at one, and context; false stops traversal. | | `context` | `T` | The caller-owned callback context. | | `maxDepth` | `integer?` | The positive depth limit, defaulting to 100. | ##### Returns | Type | Description | | --- | --- | | `nil` | | ##### Raises | Type | Condition | | --- | --- | | `string` | on a cycle or when the depth limit is exceeded. | #### `newQuery` _method_ ```nupp newQuery: function(exclusive self: World, descriptor: query.Descriptor?): query.Query ``` Creates a query over committed entities, excluding Disabled by default. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | The world that owns the query. | | `descriptor` | `query.Descriptor?` | The constraints and callbacks; nil matches enabled entities. | ##### Returns | Type | Description | | --- | --- | | `query.Query` | Returns a persistent query unless temp is true. | ##### Raises | Type | Condition | | --- | --- | | `string` | for an invalid query type or temporary membership callbacks. | #### `set` _method_ ```nupp set: function(exclusive self: World, id: integer, input: components.Input, value: any?): nil ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `id` | `integer` | | | `input` | `components.Input` | | | `value` | `any?` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `remove` _method_ ```nupp remove: function(exclusive self: World, id: integer, input: components.Input): nil ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `id` | `integer` | | | `input` | `components.Input` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `despawn` _method_ ```nupp despawn: function(exclusive self: World, id: integer): nil ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `id` | `integer` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `commit` _method_ ```nupp commit: function(exclusive self: World): nil ``` Publishes staged mutations synchronously, including work staged by observers. Reentrant calls during publication join the active drain. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | The world to publish; callers must leave query iteration first. | ##### Returns | Type | Description | | --- | --- | | `nil` | | ##### Raises | Type | Condition | | --- | --- | | `string` | when a publication callback raises. | #### `enqueueCommit` _method_ ```nupp enqueueCommit: function(exclusive self: World): nil ``` Requests publication after the current system and its predicate return. Repeated requests coalesce, including across suspension. Outside a system this publishes synchronously; publication callbacks join the active drain. A failed system cancels the request without publishing its staged work. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | The world whose pending mutations need a publication barrier. | ##### Returns | Type | Description | | --- | --- | | `nil` | | ##### Raises | Type | Condition | | --- | --- | | `string` | when a synchronous publication callback raises. | #### `randomStream` _method_ ```nupp randomStream: function(exclusive self: World, name: string): random.Xoshiro128 ``` Returns this world's stable named Nupp random generator. Stream names and the world seed determine independent sequences. The world snapshots generators automatically and restores captured objects in place. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | The world that owns the generator and its snapshot state. | | `name` | `string` | The non-empty stream name, preferably namespaced for its consumer. | ##### Returns | Type | Description | | --- | --- | | `random.Xoshiro128` | Returns the same mutable generator for each call with this name. | ##### Raises | Type | Condition | | --- | --- | | `string` | when the name is empty. | #### `seedRandom` _method_ ```nupp seedRandom: function(exclusive self: World, seed: integer): nil ``` Restarts every named random stream without replacing captured generators. Streams created later derive their seeds from this seed too. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | The world whose random sequences restart. | | `seed` | `integer` | The finite integer seed, interpreted as a 32-bit word. | ##### Returns | Type | Description | | --- | --- | | `nil` | | ##### Raises | Type | Condition | | --- | --- | | `string` | when the seed is not a finite integer. | #### `clearEntities` _method_ ```nupp clearEntities: function(exclusive self: World): nil ``` Clears entity data and pending batches while preserving systems, queries and resources. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | The world to reset; reserved identities are invalidated too. | ##### Returns | Type | Description | | --- | --- | | `nil` | | ##### Raises | Type | Condition | | --- | --- | | `string` | during publication. Use staged despawn from callbacks instead. | #### `addSystem` _method_ ```nupp addSystem: function(exclusive self: World, config: SystemConfig): string ``` Registers a system for the next external dispatch, copying its constraints. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | The world to modify. | | `config` | `SystemConfig` | The phase, body, optional ordering, gate and barriers. | ##### Returns | Type | Description | | --- | --- | | `string` | Returns the unique explicit or generated system name. | ##### Raises | Type | Condition | | --- | --- | | `string` | when another registered system carries that name. | #### `registerPhase` _method_ ```nupp registerPhase: function(exclusive self: World, phase: phases.Definition): nil ``` Registers a custom leaf or tree without adding it to the default frame loop. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | The world whose phase registry changes. | | `phase` | `phases.Definition` | The stable name, optional position and registered child names. | ##### Returns | Type | Description | | --- | --- | | `nil` | | ##### Raises | Type | Condition | | --- | --- | | `string` | for duplicate names, invalid positions, unknown children or registration during dispatch. | #### `removeSystem` _method_ ```nupp removeSystem: function(exclusive self: World, name: string): boolean ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `name` | `string` | | ##### Returns | Type | Description | | --- | --- | | `boolean` | | #### `listSystems` _method_ ```nupp listSystems: function(borrows self: World): {SystemInfo} ``` Reports the next schedule in phase and dependency order. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | The world to inspect without changing any active dispatch. | ##### Returns | Type | Description | | --- | --- | | `{SystemInfo}` | Returns caller-owned metadata, including disabled systems. | ##### Raises | Type | Condition | | --- | --- | | `string` | when any phase contains an ordering cycle. | #### `setSystemEnabled` _method_ ```nupp setSystemEnabled: function(exclusive self: World, name: string, enabled: boolean): (boolean, string?) ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `name` | `string` | | | `enabled` | `boolean` | | ##### Returns | Type | Description | | --- | --- | | `boolean` | | | `string?` | | #### `update` _method_ ```nupp update: function(exclusive self: World, dt: number): nil ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `dt` | `number` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `startup` _method_ ```nupp startup: function(exclusive self: World): nil ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `shutdown` _method_ ```nupp shutdown: function(exclusive self: World): nil ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `runPhase` _method_ ```nupp runPhase: function(exclusive self: World, phase: phases.Selection, dt: number?): nil ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `phase` | `phases.Selection` | | | `dt` | `number?` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `enablePhase` _method_ ```nupp enablePhase: function(exclusive self: World, phase: phases.Selection): nil ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `phase` | `phases.Selection` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `disablePhase` _method_ ```nupp disablePhase: function(exclusive self: World, phase: phases.Selection): nil ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `phase` | `phases.Selection` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `isPhaseEnabled` _method_ ```nupp isPhaseEnabled: function(borrows self: World, phase: phases.Phase): boolean ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | | | `phase` | `phases.Phase` | | ##### Returns | Type | Description | | --- | --- | | `boolean` | | #### `getNominalFrameTime` _method_ ```nupp getNominalFrameTime: function(borrows self: World): number ``` Returns the configured seconds per presentation tick. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | | ##### Returns | Type | Description | | --- | --- | | `number` | | #### `setNominalFrameTime` _method_ ```nupp setNominalFrameTime: function(exclusive self: World, seconds: number): nil ``` Changes conversion for future sequence waits; existing deadlines stay fixed. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `seconds` | `number` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `getFixedTiming` _method_ ```nupp getFixedTiming: function(borrows self: World): (number, number, number) ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | | ##### Returns | Type | Description | | --- | --- | | `number` | | | `number` | | | `number` | | #### `fixedStepCount` _method_ ```nupp fixedStepCount: function(borrows self: World): integer ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | | ##### Returns | Type | Description | | --- | --- | | `integer` | | #### `getStats` _method_ ```nupp getStats: function(borrows self: World, fill: WorldStats?): WorldStats ``` Reports current counts and accumulated fixed-step losses. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | The world to inspect. | | `fill` | `WorldStats?` | The optional caller-owned result to overwrite without allocating. | ##### Returns | Type | Description | | --- | --- | | `WorldStats` | Returns fill itself, or a new record when fill is absent. | #### `createState` _method_ ```nupp createState: function(exclusive self: World, name: string, policy: StatePolicy?): components.Component ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `name` | `string` | | | `policy` | `StatePolicy?` | | ##### Returns | Type | Description | | --- | --- | | `components.Component` | | #### `pushState` _method_ ```nupp pushState: function(exclusive self: World, name: string): nil ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `name` | `string` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `popState` _method_ ```nupp popState: function(exclusive self: World): nil ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `peekState` _method_ ```nupp peekState: function(borrows self: World): string? ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | | ##### Returns | Type | Description | | --- | --- | | `string?` | | #### `listStates` _method_ ```nupp listStates: function(borrows self: World): {string} ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | | ##### Returns | Type | Description | | --- | --- | | `{string}` | | #### `newBundle` _method_ ```nupp newBundle: function(self: World, name: string, definition: BundleDefinition?): Bundle ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `World` | | | `name` | `string` | | | `definition` | `BundleDefinition?` | | ##### Returns | Type | Description | | --- | --- | | `Bundle` | | #### `spawnBundle` _method_ ```nupp spawnBundle: function(exclusive self: World, name: string, ...: components.Input): integer ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `name` | `string` | | | `...` | `components.Input` | | ##### Returns | Type | Description | | --- | --- | | `integer` | | #### `getBundles` _method_ ```nupp getBundles: function(borrows self: World): {[string]: Bundle} ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | | ##### Returns | Type | Description | | --- | --- | | `{\[string\]: Bundle}` | | #### `getBundle` _method_ ```nupp getBundle: function(borrows self: World, name: string): Bundle? ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | | | `name` | `string` | | ##### Returns | Type | Description | | --- | --- | | `Bundle?` | | #### `saveSnapshot` _method_ ```nupp saveSnapshot: function(exclusive self: World, options: SnapshotOptions?): Snapshot ``` Saves committed entities and durable world metadata in table or native binary form. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | The world to save; staged mutations publish first. | | `options` | `SnapshotOptions?` | The optional format, reusable output, file, filters and custom metadata. | ##### Returns | Type | Description | | --- | --- | | `Snapshot` | Returns a detached table snapshot or a tagged binary buffer, according to format. | ##### Raises | Type | Condition | | --- | --- | | `string` | during publication or another suspended dispatch, for invalid options, duplicate or reserved metadata, unencodable values, or failed file output. | #### `loadSnapshot` _method_ ```nupp loadSnapshot: function(exclusive self: World, snapshot: any): SnapshotPrelude ``` Replaces entity state while retaining registered runtime setup. ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | The destination with component and state definitions already registered. | | `snapshot` | `any` | The current or version-one table, tagged output, byte string or non-consuming buffer. | ##### Returns | Type | Description | | --- | --- | | `SnapshotPrelude` | Returns the validated snapshot prelude. | ##### Raises | Type | Condition | | --- | --- | | `string` | during publication or another suspended dispatch, or for invalid framing, identities, schemas, state or codecs. | #### `addSnapshotHandler` _method_ ```nupp addSnapshotHandler: function(exclusive self: World, handler: SnapshotHandler): nil ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `handler` | `SnapshotHandler` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `observe` _method_ ```nupp observe: function( exclusive self: World, address: integer, event: Type, callback: Observer, id: string? ): nil ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `address` | `integer` | | | `event` | `Type\` | | | `callback` | `Observer\` | | | `id` | `string?` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `observeOnce` _method_ ```nupp observeOnce: function( exclusive self: World, address: integer, event: Type, callback: Observer, id: string? ): nil ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `address` | `integer` | | | `event` | `Type\` | | | `callback` | `Observer\` | | | `id` | `string?` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `stopObserving` _method_ ```nupp stopObserving: function( exclusive self: World, address: integer, event: Type, callbackOrId: Observer | string ): boolean ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `address` | `integer` | | | `event` | `Type\` | | | `callbackOrId` | `Observer\ | string` | | ##### Returns | Type | Description | | --- | --- | | `boolean` | | #### `hasObservers` _method_ ```nupp hasObservers: function(borrows self: World, address: integer, event: Type): boolean ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | | | `address` | `integer` | | | `event` | `Type\` | | ##### Returns | Type | Description | | --- | --- | | `boolean` | | #### `emit` _method_ ```nupp emit: function( exclusive self: World, address: integer, event: Type, ...: unpackof Construction(E) ): nil ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `address` | `integer` | | | `event` | `Type\` | | | `...` | `unpackof Construction(E)` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `deliver` _method_ ```nupp deliver: function(exclusive self: World, address: integer, event: Type, instance: E): nil ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `address` | `integer` | | | `event` | `Type\` | | | `instance` | `E` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | #### `clearObservers` _method_ ```nupp clearObservers: function(exclusive self: World, address: integer): nil ``` ##### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `address` | `integer` | | ##### Returns | Type | Description | | --- | --- | | `nil` | | ### `WorldConfig` _type_ ```nupp type WorldConfig = { --- Caller-writable. Sets seconds per presentation tick, defaulting to 1/60 even --- headless. nominalFrameTime: number?, maxEntities: integer?, timestep: number?, fixedMaxSteps: integer?, fixedOverload: entityworld.FixedOverload?, --- Caller-writable. Replaces the scheduler before built-in systems are installed. pipelineFactory: (function(): entityworld.Pipeline)? } ``` The options accepted by `newWorld`. ### `WorldStats` _record_ ```nupp record WorldStats ... ``` Fixed-step overload counters accumulated by a world. #### Members | Name | Kind | Description | | --- | --- | --- | | [`entities`](#tecs.ecs.WorldStats.entities) | field | | | [`archetypes`](#tecs.ecs.WorldStats.archetypes) | field | | | [`components`](#tecs.ecs.WorldStats.components) | field | | | [`systems`](#tecs.ecs.WorldStats.systems) | field | | | [`fixedTimeDropped`](#tecs.ecs.WorldStats.fixedTimeDropped) | field | | | [`fixedStepsDropped`](#tecs.ecs.WorldStats.fixedStepsDropped) | field | | #### `entities` _field_ ```nupp entities: integer ``` #### `archetypes` _field_ ```nupp archetypes: integer ``` #### `components` _field_ ```nupp components: integer ``` #### `systems` _field_ ```nupp systems: integer ``` #### `fixedTimeDropped` _field_ ```nupp fixedTimeDropped: number ``` #### `fixedStepsDropped` _field_ ```nupp fixedStepsDropped: integer ``` ## Functions ### `Component` _comptime function_ ```nupp @comptime function Component(info: nupp.derive.Info): nupp.derive.Result ``` `@comptime` Marks a record or struct as an ECS component and selects its physical storage. #### Arguments | Name | Type | Description | | --- | --- | --- | | `info` | `nupp.derive.Info` | The declaration being derived. | #### Returns | Type | Description | | --- | --- | | `nupp.derive.Result\` | Returns its metadata and reusable initializer recipe. | #### Raises | Type | Condition | | --- | --- | | `string` | when the declaration cannot supply a reusable initializer. | ### `declaredComponents` _function_ ```nupp function declaredComponents(): {[string]: Component} ``` Returns a fresh snapshot of every declared component. #### Returns | Type | Description | | --- | --- | | `{\[string\]: Component}` | the caller-owned name-to-component table | ### `definition` _function_ ```nupp function definition(declaration: Type): Component ``` Returns the registered definition for a derived component declaration. #### Type parameters | Name | Description | | --- | --- | | `T` | | #### Arguments | Name | Type | Description | | --- | --- | --- | | `declaration` | `Type\` | The component declaration to register if necessary. | #### Returns | Type | Description | | --- | --- | | `Component` | Returns its process-wide identity and storage metadata. | ### `findComponentById` _function_ ```nupp function findComponentById(id: integer): Component? ``` Returns a registered component by numeric id. #### Arguments | Name | Type | Description | | --- | --- | --- | | `id` | `integer` | the process-wide component id | #### Returns | Type | Description | | --- | --- | | `Component?` | the component, or nil when the id is unknown | ### `findComponentByName` _function_ ```nupp function findComponentByName(name: string): Component? ``` Returns a registered component by name. #### Arguments | Name | Type | Description | | --- | --- | --- | | `name` | `string` | the process-wide component name | #### Returns | Type | Description | | --- | --- | | `Component?` | the component, or nil when the name is unknown | ### `newComponent` _function_ ```nupp function newComponent(witness: Type, options: ComponentOptions?): ComponentDefinition ``` Registers a declaration with managed or native columns selected from its layout. The default identity of a derived declaration is cached. Configure it before its first use, or supply a distinct name to create another identity. #### Type parameters | Name | Description | | --- | --- | | `T` | | #### Arguments | Name | Type | Description | | --- | --- | --- | | `witness` | `Type\` | The record or struct declaration whose values this definition stores. | | `options` | `ComponentOptions\?` | The optional identity, constructor, defaults and snapshot policy. | #### Returns | Type | Description | | --- | --- | | `ComponentDefinition\` | Returns a callable definition with the declaration's exact column type. | #### Raises | Type | Condition | | --- | --- | | `string` | when the name is empty or already belongs to another definition. | | `string` | when a declaration has neither an initializer nor an explicit constructor. | | `string` | when a native layout is unsupported or snapshot codecs are incomplete. | | `string` | when a requirement is unregistered or names an untargeted relationship. | ### `newTagComponent` _function_ ```nupp function newTagComponent(options: TagComponentOptions): Component ``` Creates and registers a marker component with no per-entity value. #### Arguments | Name | Type | Description | | --- | --- | --- | | `options` | `TagComponentOptions` | the process-unique component name and snapshot policy | #### Returns | Type | Description | | --- | --- | | `Component` | the registered tag component | #### Raises | Type | Condition | | --- | --- | | `string` | when the name is empty or already registered | | `string` | when a requirement is unregistered or names an untargeted relationship. | ### `newWorld` _function_ ```nupp function newWorld(config: WorldConfig?): World ``` Creates an independent empty world carrying the builtin systems. The world arrives with `tecs.SnapshotTransforms`, `ttl`, `RelativeTransform2D` and `RelativeTransformDirtySampler` already registered, which is what makes a `TTL` expire and a `RelativeTransform2D` move its entity without a game installing anything. #### Arguments | Name | Type | Description | | --- | --- | --- | | `config` | `WorldConfig?` | the world settings, or nil for defaults | #### Returns | Type | Description | | --- | --- | | `World` | the empty world | #### Raises | Type | Condition | | --- | --- | | `string` | when a capacity or fixed-clock option is invalid | ### `Relationship` _comptime function_ ```nupp @comptime function Relationship(info: nupp.derive.Info): nupp.derive.Result ``` `@comptime` Marks a target-bearing record or struct as an ECS relationship. #### Arguments | Name | Type | Description | | --- | --- | --- | | `info` | `nupp.derive.Info` | The declaration being derived. | #### Returns | Type | Description | | --- | --- | | `nupp.derive.Result\` | Returns its metadata and reusable initializer recipe. | #### Raises | Type | Condition | | --- | --- | | `string` | when the target, policies or initializer are invalid. | ### `targeting` _function_ ```nupp function targeting(relationship: Type, target: integer): ComponentDefinition ``` Selects the typed dense column for one target of a derived relationship. #### Type parameters | Name | Description | | --- | --- | | `T` | | #### Arguments | Name | Type | Description | | --- | --- | --- | | `relationship` | `Type\` | The derived edge declaration. | | `target` | `integer` | The committed or reserved target identifier. | #### Returns | Type | Description | | --- | --- | | `ComponentDefinition\` | Returns a reusable selector with the edge's exact physical column type. | #### Raises | Type | Condition | | --- | --- | | `string` | when the relationship is sparse or the target is invalid. | ## Values ### `ChildOf` _variable_ ```nupp const ChildOf: RelationshipComponent ``` Relates one child entity to its parent. `world:spawn(ChildOf(parent))` places an entity under `parent`, and `world:set(child, ChildOf(other))` reparents it at the next barrier. The relationship is exclusive, reverse indexed and cascading: a child has one parent, `world:relationshipSources(ChildOf, parent)` answers with that parent's children, and despawning a parent despawns the tree beneath it. ### `DEFAULT_FIXED_MAX_STEPS` _variable_ ```nupp const DEFAULT_FIXED_MAX_STEPS: integer ``` The per-frame fixed-step limit used when `newWorld` receives no override. ### `DEFAULT_MAX_ENTITIES` _variable_ ```nupp const DEFAULT_MAX_ENTITIES: integer ``` The entity capacity used when `newWorld` receives no override. ### `DEFAULT_TIMESTEP` _variable_ ```nupp const DEFAULT_TIMESTEP: number ``` The fixed update interval used when `newWorld` receives no override. ### `Disabled` _variable_ ```nupp const Disabled: TagComponent ``` Marks entities disabled by a state policy. ### `EntityKey` _variable_ ```nupp const EntityKey: ScalarComponent ``` Stores a durable unique name for one entity. A key names at most one live entity, and `World.byKey` answers with the entity holding it. Claiming a key another live entity already holds raises, since nothing later could resolve which of the two a lookup means. The component is registered under the name `Key`, which is what a snapshot records. That spelling is a compatibility surface and does not follow this public name. ### `MAX_ENTITIES` _variable_ ```nupp const MAX_ENTITIES: integer ``` The greatest entity capacity supported by the packed id format. ### `Name` _variable_ ```nupp const Name: ScalarComponent ``` Names an entity for a human reader. A name is neither indexed nor unique. `EntityKey` is what a lookup resolves through; this is what a debug overlay prints. ### `newRelationship` _variable_ ```nupp const newRelationship: NewRelationship ``` Registers a target-only relationship or a record or struct payload declaration. The one-argument options form creates target-only edges. The declaration form selects managed or native payload storage without running a user constructor. #### Raises | Type | Condition | | --- | --- | | `string` | when cascade deletion lacks exclusivity or reverse indexing. | | `string` | when the name is invalid or already belongs to another definition. | | `string` | when a payload declaration does not provide a valid target field. | | `string` | when a native layout is unsupported or snapshot codecs are incomplete. | ### `newScalarComponent` _variable_ ```nupp const newScalarComponent: NewScalarComponent ``` Creates and registers a scalar component whose column stores raw values. #### Raises | Type | Condition | | --- | --- | | `string` | when the name is empty or already registered | ### `Paused` _variable_ ```nupp const Paused: TagComponent ``` Marks entities paused by a state policy. ### `PreviousTransform2D` _variable_ ```nupp const PreviousTransform2D: components.FFIComponent ``` Opts an entity into fixed-step presentation interpolation. Physics seeds this with the body's creation pose. The builtin snapshot system refreshes it before each fixed step; rendering never mutates simulation. ### `RelativeTransform2D` _variable_ ```nupp const RelativeTransform2D: components.FFIComponent ``` Constructs an offset from a parent's transform. Spawn it beside `Transform2D` and `ChildOf`. The builtin `RelativeTransform2D` system composes the parent's world transform with the offset and writes the result into the entity's own `Transform2D`, so a renderer, a query, or a physics body keeps reading one transform. ### `Transform2D` _variable_ ```nupp const Transform2D: components.FFIComponent ``` Constructs the shared two-dimensional transform component. ### `Transform3D` _variable_ ```nupp const Transform3D: components.FFIComponent ``` Constructs a 3D transform, defaulting to the identity at the origin. ### `TTL` _variable_ ```nupp const TTL: components.FFIComponent ``` Constructs a lifetime that despawns its entity when it runs out. `world:spawn(TTL(0.5))` gives an entity half a second of fixed time. The builtin `ttl` system spends it one fixed step at a time and despawns the entity at zero, and `ttl:percentComplete()` reports how much of the original budget is gone.