# `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, nupp.derive.Serde) local struct Velocity x: number = 0 y: number = 0 end local world = tecs.ecs.newWorld() world:batchSpawn(1000, {Velocity}) world:commit() for candidate, count in world:newQuery({include = {Velocity}}):iter() do local column = assert(candidate:getMut(Velocity)) unsafe do for row = 1, assert(count) do column[row].x += 1 end end end ``` Built-in transforms, tint, shape material, camera, lights, animation, sound, physics values and numeric UI components use this storage and derive `nupp.derive.Debug` and `nupp.derive.Serde`. Derived methods work on constructed values and borrowed rows without changing column layout. Use `nupp.serde.json():prepare(nupp.serde.of(Velocity))` for a typed JSON codec; Nupp's separate `nupp.derive.JSON` provider currently admits records only. Generic Serde encoding describes physical component fields, whereas world snapshots use the component's registered codecs. Asset-bearing built-ins keep their custom name-based codecs and never persist process-local IDs as assets. `get` and `getMut` return `T[?]` for a native component, and the existing managed array for a table or scalar component. Native rows use the same **one-based** indices as the query's entity list; row zero is padding. Use the query count, not `#column`, `pairs`, `ipairs`, or table library operations on a native column. Direct C-array indexing requires Nupp's `unsafe` scope. `world:get` still returns one typed struct value, and `world:getMut` marks the owning column dirty first. Native column assignments copy bytes, including inline fixed arrays. Entities never share these inline rows, even when they receive the same constructed input or requirement. Struct values returned by reads are live row references, not owned copies. Column views and row references expire at the next structural publication, compaction, clear, or snapshot restore. Reacquire them afterwards. Never retain a native row reference across such a boundary or use `commit` inside its loop. Automatic codecs support numeric and boolean fields and fixed arrays of those types. Nested structs and pointers are also supported with custom codecs or `transient = true`; their owners must keep pointed-to storage alive. Unions, bitfields and variable arrays are rejected. Never persist process-local pointer addresses. Table snapshots have automatic field codecs; arrays are saved one-based and signed/unsigned 64-bit integers are saved as exact decimal strings. Optional `save` and either `load` or world-aware `deserialize` hooks must be supplied together. They replace automatic codecs and disable native raw encoding in both directions so custom behavior is never silently bypassed. Transient and required components follow the ordinary ECS rules. Binary snapshots copy eligible native columns directly and migrate older scalar layouts using their saved field fingerprints. Derive `tecs.ecs.Relationship` on a target-bearing record or struct. Optional `@relationship` settings configure its name, exclusivity, sparse placement, reverse indexing, cascades and transient snapshot policy. Use `tecs.ecs.targeting(EdgeType, target)` for a dense target-specific selector. Native relationships use the same field policy and support exclusive or multiple targets, reverse lookup, cascades and sparse or dense edge placement. Its struct must contain a `target: number` field. Dense `targeting()` selectors return native columns. A wildcard relationship column is a managed array of references to its first native edge, not another copy of that edge. Sparse edge lists likewise retain native values. Changes through wildcard, target-specific and relationship-iteration access therefore reach the same payload. Sparse relationships retain constructed edge objects. Reusing one edge instance for several sources shares that payload; construct separate instances for independent values and mark every affected source dirty after mutating a deliberately shared payload. ## Component requirements Every component factory accepts `requires`, including scalar components and both relationship factories. A requirement is a component definition or a constructed [`tecs.ecs.ComponentInput`](#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.Random` owned by the world. The world seed and the non-empty stream name determine its sequence, independently of which other streams exist or how many values they draw. Repeated calls return the same generator. Use namespaced names and capture streams during setup. ```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 `nupp.random.newRandom`. Generators are mutable and must not be shared across concurrent workers. The first stream or seed call enables snapshot persistence under `tecs.random`. This reserved key, its `{seed, streams}` payload and the byte-based name-to-seed mapping are persistence contracts. Each saved stream contains four signed 32-bit state words. Saving neither advances the generators nor leaves a live view into them. Loading a snapshot restores already-captured generators in place, creates saved streams not yet requested, and restarts existing streams absent from the save using the restored world seed. A fresh world needs no initialization call before loading saved random data. Random state restores after entity publication and before custom snapshot handlers run. Malformed random payloads raise before the world clears entities or changes generators. Unsigned 32-bit saved words are accepted and normalized too. A snapshot without `tecs.random` leaves current streams and the seed unchanged. Clearing entities also leaves them alone. Runtime closures such as timer predicates are not snapshot state: giving `runif.every` a world stream restores its future random draws, but does not rewind the timer's elapsed time. The `tecs.random` key cannot be supplied through custom data or a snapshot handler. Installing audio uses the `tecs.audio` stream for pitch variance automatically; standalone mixers retain their own independent Nupp generators. ## System scheduling `registerPhase({name = "game.Custom"})` registers a custom leaf; `children` makes an ordered tree of registered names. `position` selects its inspection-registry position, not automatic execution in the default frame. Run the tree explicitly with `runPhase`, or provide `WorldConfig.pipelineFactory` to replace scheduling. The custom `Pipeline` receives the world's task scope, owns system ordering and phase barriers, and receives all registration, phase-control and inspection calls. Its fixed remainder and phase-enabled flags participate in snapshots. `addSystem` accepts `before` and `after` lists of system names. Constraints apply only within one leaf phase; missing names and names in other phases contribute no edge. Self references are ignored and duplicate edges count once. Among systems whose dependencies are satisfied, the earliest registered runs first. Disabled systems retain their position and ordering edges. The world copies constraint lists. It rebuilds the schedule after registration changes, validating every phase before the next dispatch publishes staged work or runs any system. A cycle raises with its phase and blocked system names. `listSystems()` reports dependency order and also raises for a cycle. Remove a conflicting system to repair the schedule; enabling or disabling cannot repair it. An update, startup, shutdown or explicit `runPhase` captures one schedule at its entry. A system added during that dispatch starts on the next external dispatch, even if its phase has not run yet. Removal and enable/disable changes affect remaining dispatches immediately. Listing during a dispatch describes the next schedule without changing the active one. Ordering does not introduce structural barriers: request `commitBefore` or `commitAfter` when a same-phase dependency also requires publication of staged entities. Call `world:enqueueCommit()` when that extra barrier is conditional on work performed by a system. Requests from its body or `runIf` predicate coalesce into one publication after the body returns, or after a false predicate skips it, before the next system runs. Suspension does not end the system: its query view stays unchanged until it returns. Requests alone never publish midway through iteration. A publication callback may request another commit without recursion; the active drain includes its staged work. Outside a running system, `enqueueCommit()` publishes synchronously, including child work settling after dispatch. Leave any query iterator before calling it there. Explicit `commit()` remains synchronous even inside a system. If a body or predicate raises, the dispatcher clears its request without introducing a barrier during unwinding; pending mutations remain staged for a later commit. Publication failures retain already published rows and discard unpublished work, as with any other commit failure. ```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.Random` directly. The first interval is unjittered and later intervals clamp to one percent of the base interval. Pass a named world stream to snapshot its random state; there is no implicit stream or automatic timer rewind when an entity snapshot is restored. ## Submodules | Module | Description | | --- | --- | | `tecs.ecs.phases` | The ordered frame phase constants. | | `tecs.ecs.runif` | Provides timer, state and logical predicates for system dispatch. | ## Constructors ### `newComponent` _constructor_ ```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 - Raises when the name is empty or already belongs to another definition. - Raises when a declaration has neither an initializer nor an explicit constructor. - Raises when a native layout is unsupported or snapshot codecs are incomplete. - Raises when a requirement is unregistered or names an untargeted relationship. ### `newTagComponent` _constructor_ ```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 - when the name is empty or already registered - Raises when a requirement is unregistered or names an untargeted relationship. ### `newWorld` _constructor_ ```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 - when a capacity or fixed-clock option is invalid ## Types ### `Archetype` _record_ ```nupp record Archetype id: integer signature: string componentIds: {[integer]: boolean} components: {components.Component} entities: entitycolumn.DoubleArray columns: {[integer]: any} addEntityObserver: function(self: Archetype, observer: EntityObserver): nil structuralDescribed: function(self: Archetype, count: integer): boolean structuralAdded: function(self: Archetype): integer structuralTouched: function(self: Archetype): ({integer}, integer) valueCount: function(self: Archetype): integer trackValueCount: function(self: Archetype, component: components.Selector): nil set: function(self: Archetype, row: integer, input: components.Input): nil get: (function(self: Archetype, component: C): C.Column?) & (function(self: Archetype, component: Type): derived.Column(T, derived.Edge)?) getMut: (function(self: Archetype, component: C): C.Column?) & (function(self: Archetype, component: Type): derived.Column(T, derived.Edge)?) isComponentDirty: function(self: Archetype, component: components.Selector): boolean anyComponentDirty: function(self: Archetype): boolean markComponentDirty: function(self: Archetype, component: components.Selector): nil markAllComponentsDirty: function(self: Archetype): nil clearDirtyComponents: function(self: Archetype): nil dirtyComponents: function(self: Archetype): function(): components.Component? structuralCount: function(self: Archetype): integer writeCount: function(self: Archetype, component: components.Selector): integer forEachRelationship: ( function( self: Archetype, relationship: C, row: integer, callback: function(value: C.Value) ): nil ) & ( function( self: Archetype, relationship: Type, row: integer, callback: function(value: T) ): nil ) getFirstRelationship: ( function(self: Archetype, relationship: C, row: integer): C.Value? ) & (function(self: Archetype, relationship: Type, row: integer): T?) end ``` A dense archetype returned by query iteration. #### Methods ##### `addEntityObserver` ```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` ```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` ```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` ```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` ```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` ```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` ```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 - Raises when the row or component is absent, or the input changes relationship membership or a durable key. ##### `isComponentDirty` ```nupp isComponentDirty: function(self: Archetype, component: components.Selector): boolean ``` Reports whether one component changed since the last world update. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Archetype` | | | `component` | `components.Selector` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | ##### `anyComponentDirty` ```nupp anyComponentDirty: function(self: Archetype): boolean ``` Reports whether any component in this archetype is dirty. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Archetype` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | ##### `markComponentDirty` ```nupp markComponentDirty: function(self: Archetype, component: components.Selector): nil ``` Marks one present component dirty. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Archetype` | | | `component` | `components.Selector` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `markAllComponentsDirty` ```nupp markAllComponentsDirty: function(self: Archetype): nil ``` Marks every component in the archetype dirty after a structural change. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Archetype` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `clearDirtyComponents` ```nupp clearDirtyComponents: function(self: Archetype): nil ``` Clears every component dirty mark. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Archetype` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `dirtyComponents` ```nupp dirtyComponents: function(self: Archetype): function(): components.Component? ``` Iterates dirty components in canonical archetype order. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Archetype` | | ###### Returns | Type | Description | | --- | --- | | `function(): components.Component?` | | ##### `structuralCount` ```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` ```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` | | #### Fields ##### `id` ```nupp id: integer ``` ##### `signature` ```nupp signature: string ``` ##### `componentIds` ```nupp componentIds: {[integer]: boolean} ``` ##### `components` ```nupp components: {components.Component} ``` ##### `entities` ```nupp entities: entitycolumn.DoubleArray ``` ##### `columns` ```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. ##### `get` ```nupp get: (function(self: Archetype, component: C): C.Column?) & (function(self: Archetype, component: Type): derived.Column(T, derived.Edge)?) ``` ##### `getMut` ```nupp getMut: (function(self: Archetype, component: C): C.Column?) & (function(self: Archetype, component: Type): derived.Column(T, derived.Edge)?) ``` ##### `forEachRelationship` ```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` ```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 archetype: archetype.Archetype end ``` `@derive(events.Event)` `@event(name="ArchetypeCreated")` Reports newly registered archetypes at the world's zero address. #### Fields ##### `archetype` ```nupp archetype: archetype.Archetype ``` Read-only. Identifies the new archetype, available for lifecycle observation. ### `ArchetypeEntityObserver` _interface_ ```nupp interface ArchetypeEntityObserver onEntitiesAdded: ( function( self: EntityObserver, value: Archetype, first: integer, last: integer, count: integer, source: Archetype? ) )? onEntitiesRemoved: ( function( self: EntityObserver, value: Archetype, first: integer, last: integer, count: integer, target: Archetype? ) )? onEntityMove: (function(self: EntityObserver, value: Archetype, entity: integer, fromRow: integer, toRow: integer))? onActivated: (function(self: EntityObserver, value: Archetype))? onDeactivated: (function(self: EntityObserver, value: Archetype))? onArchetypeDestroyed: (function(self: EntityObserver, value: Archetype))? end ``` Receives row and lifetime notifications from one archetype. #### Fields ##### `onEntitiesAdded` ```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` ```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` ```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` ```nupp onActivated: (function(self: EntityObserver, value: Archetype))? ``` Caller-writable. Runs when the archetype becomes nonempty. ##### `onDeactivated` ```nupp onDeactivated: (function(self: EntityObserver, value: Archetype))? ``` Caller-writable. Runs when the archetype becomes empty. ##### `onArchetypeDestroyed` ```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 name: string required: {string} defaulted: {string} spawn: function(self: Bundle, ...: components.Input): integer end ``` A reusable world-bound spawn shape. #### Methods ##### `spawn` ```nupp spawn: function(self: Bundle, ...: components.Input): integer ``` Reserves an entity using this bundle's required and defaulted components. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `Bundle` | | | `...` | `components.Input` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ###### Raises - when a required input is missing, out of order, or extra #### Fields ##### `name` ```nupp name: string ``` ##### `required` ```nupp required: {string} ``` ##### `defaulted` ```nupp defaulted: {string} ``` ### `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 associated type Value = self associated type Column = {self.Value} componentId: integer componentName: string storageType: string transient: boolean end ``` A process-wide component definition. #### Fields ##### `Value` ```nupp Value: associatedDecl ``` ##### `Column` ```nupp Column: associatedDecl ``` ##### `componentId` ```nupp componentId: integer ``` ##### `componentName` ```nupp componentName: string ``` ##### `storageType` ```nupp storageType: string ``` ##### `transient` ```nupp transient: boolean ``` ### `component` _record_ ```nupp record component name: string? transient: boolean? end ``` `@annotation(targets={"record","struct"})` Configures a derived component's persisted identity and snapshot policy. #### Fields ##### `name` ```nupp name: string? ``` Caller-writable. Pins the persisted name; nil uses the qualified declaration. ##### `transient` ```nupp transient: boolean? ``` Caller-writable. Omits this component's values from snapshots. ### `ComponentDefinition` _interface_ ```nupp interface ComponentDefinition is Component associated type Value == T associated type Column == derived.StorageColumn(T) construct: function(...: any): T defaultFactory: function(): T snapshotSave: function(value: T): any snapshotLoad: function(value: any, exclusive world: any): T metamethod __call: function(self, ...: any): FFIInstance> end ``` A named definition with its column type selected from the value declaration. #### Type parameters | Name | Description | | --- | --- | | `T` | | #### Methods ##### `construct` ```nupp construct: function(...: any): T ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `...` | `any` | | ###### Returns | Type | Description | | --- | --- | | `T` | | ##### `defaultFactory` ```nupp defaultFactory: function(): T ``` ###### Returns | Type | Description | | --- | --- | | `T` | | ##### `snapshotSave` ```nupp snapshotSave: function(value: T): any ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `T` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `snapshotLoad` ```nupp snapshotLoad: function(value: any, exclusive world: any): T ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `any` | | | `exclusive world` | `any` | | ###### Returns | Type | Description | | --- | --- | | `T` | | ##### `__call` ```nupp __call: function(self, ...: any): FFIInstance> ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `?` | `self` | | | `...` | `any` | | ###### Returns | Type | Description | | --- | --- | | `FFIInstance\\>` | | #### Fields ##### `Value` ```nupp Value: associatedDecl ``` ##### `Column` ```nupp Column: associatedDecl ``` ### `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 end ``` Bounds generic helpers to records or structs deriving the component contract. ### `DoubleArray` _type_ ```nupp type DoubleArray = DoubleArray2 ``` Exposes the native, one-based packed entity ID column and its exact length. ### `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 prelude: SnapshotPrelude end ``` `@derive(events.Event)` `@event(name="FinishSnapshotLoad")` Reports completion of snapshot metadata restoration. #### Fields ##### `prelude` ```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 entity: integer source: archetype.Archetype row: integer requestedDespawns: {integer} function get(borrows self: OnDespawn, component: C): C.Value? end function despawn(self: OnDespawn, entity: integer): nil end end ``` `@derive(events.Event)` `@event(name="OnDespawn")` Fires at the entity address and address zero immediately before removal. #### Methods ##### `get` ```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` ```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` | | #### Fields ##### `entity` ```nupp entity: integer ``` ##### `source` ```nupp source: archetype.Archetype ``` Engine-owned. Identifies the entity's last committed archetype. ##### `row` ```nupp row: integer ``` Engine-owned. Identifies the entity's zero-based row before removal. ##### `requestedDespawns` ```nupp requestedDespawns: {integer} ``` Engine-owned. Collects dependent entities observers ask to despawn. ### `OnSnapshotSave` _record_ ```nupp record OnSnapshotSave data: {[string]: any} excluded: {components.Component} function addData(self: OnSnapshotSave, key: string, value: any): nil end function exclude(self: OnSnapshotSave, component: components.Selector): nil end end ``` `@derive(events.Event)` `@event(name="OnSnapshotSave")` Allows snapshot participants to attach metadata and exclude regenerated entities. #### Methods ##### `addData` ```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 - Raises when a key is empty or repeated. ##### `exclude` ```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` | | #### Fields ##### `data` ```nupp data: {[string]: any} ``` Engine-owned. Supplies save staging to event construction; use addData instead. ##### `excluded` ```nupp excluded: {components.Component} ``` Engine-owned. Supplies exclusion staging to event construction; use exclude instead. ### `OnSpawn` _record_ ```nupp record OnSpawn entity: integer end ``` `@derive(events.Event)` `@event(name="OnSpawn")` Fires at address zero after an entity becomes committed and alive. #### Fields ##### `entity` ```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 count: integer fixedTimestep: number fixedMaxSteps: integer fixedOverload: FixedOverload fixedAccumulator: number fixedStepCount: integer fixedTimeDropped: number fixedStepsDropped: integer phaseStates: {boolean} update: function(self: Pipeline, dt: number, exclusive world: World, borrows scope: tasks.Scope): nil run: function( self: Pipeline, phase: phases.Selection, dt: number, exclusive world: World, borrows scope: tasks.Scope ): nil addSystem: function(self: Pipeline, config: SystemConfig): string removeSystem: function(self: Pipeline, name: string): boolean listSystems: function(self: Pipeline): {SystemInfo} setSystemEnabled: function(self: Pipeline, name: string, enabled: boolean): (boolean, string?) enablePhase: function(self: Pipeline, phase: phases.Selection): nil disablePhase: function(self: Pipeline, phase: phases.Selection): nil isPhaseEnabled: function(self: Pipeline, phase: phases.Phase): boolean registerPhase: function(self: Pipeline, phase: phases.Definition): nil end ``` Implements custom scheduling while the world owns entities and task scopes. #### Methods ##### `update` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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` ```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` | | #### Fields ##### `count` ```nupp count: integer ``` Read-only. Reports the registered system count. ##### `fixedTimestep` ```nupp fixedTimestep: number ``` Read-only. Reports the fixed-step duration in seconds. ##### `fixedMaxSteps` ```nupp fixedMaxSteps: integer ``` Read-only. Limits catch-up iterations in one frame. ##### `fixedOverload` ```nupp fixedOverload: FixedOverload ``` Read-only. Selects drop or accumulate for excess fixed time. ##### `fixedAccumulator` ```nupp fixedAccumulator: number ``` Engine-owned. Stores the fixed remainder; snapshot restore writes it. ##### `fixedStepCount` ```nupp fixedStepCount: integer ``` Read-only. Reports completed fixed iterations. ##### `fixedTimeDropped` ```nupp fixedTimeDropped: number ``` Read-only. Reports abandoned fixed time in seconds. ##### `fixedStepsDropped` ```nupp fixedStepsDropped: integer ``` Read-only. Reports abandoned whole fixed steps. ##### `phaseStates` ```nupp phaseStates: {boolean} ``` Engine-owned. Stores enabled flags by registered phase position; snapshots restore it. ### `PreviousTransform2D` _struct_ ```nupp struct PreviousTransform2D x: number y: number rotation: number end ``` `@derive(nupp.derive.Debug, nupp.derive.Serde)` Stores the position and rotation before the current fixed step. #### Fields ##### `x` ```nupp x: number ``` Engine-owned. Stores the previous horizontal position in world units. ##### `y` ```nupp y: number ``` Engine-owned. Stores the previous vertical position in world units. ##### `rotation` ```nupp rotation: number ``` Engine-owned. Stores the previous clockwise rotation in radians. ### `Query` _record_ ```nupp record Query descriptor: Descriptor iter: function(self: Query): (IterFn, Query, archetype.Archetype?) groups: function(self: Query): (GroupsIterFn, Query, integer?) group: function(self: Query, groupId: integer): (GroupIterFn, GroupState, archetype.Archetype?) getGroup: function(self: Query, candidate: archetype.Archetype): integer? getGroupCount: function(self: Query, groupId: integer): integer count: function(self: Query): integer end ``` A reusable archetype query. #### Methods ##### `iter` ```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` ```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` ```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` ```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` ```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` ```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. | #### Fields ##### `descriptor` ```nupp descriptor: Descriptor ``` Read-only. Describes the normalized query; mutation after construction is unsupported. ### `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: {components.Selector}?, --- Caller-writable. Requires at least one listed component; an empty list adds no --- constraint. includeAny: {components.Selector}?, --- Caller-writable. Rejects every listed component. exclude: {components.Selector}?, --- Caller-writable. Receives entering rows after publication, including initial --- members. onEntitiesAdded: MembershipCallback?, --- Caller-writable. Receives departing rows while their old values remain readable. onEntitiesRemoved: MembershipCallback?, --- Caller-writable. Retains only initially matching archetypes, with live rows, and --- forbids callbacks. temp: boolean?, --- Caller-writable. Assigns each matching archetype an integer group once. groupBy: (function(candidate: archetype.Archetype): integer)? } ``` Membership constraints, grouping and notifications for a reusable query. ### `Relationship` _record_ ```nupp record Relationship is Component associated type Value = RelationshipValue componentId: integer componentName: string storageType: string transient: boolean exclusive: boolean reverseIndex: boolean cascadeDelete: boolean sparse: boolean metamethod __call: function(self, target: integer): RelationshipInstance targeting: function(self: RelationshipComponent, target: integer): RelationshipComponent end ``` A target-only entity relationship with selectable cardinality and storage. #### Methods ##### `__call` ```nupp __call: function(self, target: integer): RelationshipInstance ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `?` | `self` | | | `target` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `RelationshipInstance` | | ##### `targeting` ```nupp targeting: function(self: RelationshipComponent, target: integer): RelationshipComponent ``` Returns a component matching one target of this dense relationship. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `RelationshipComponent` | The relationship definition. | | `target` | `integer` | The packed target entity identifier. | ###### Returns | Type | Description | | --- | --- | | `RelationshipComponent` | Returns a stable target-specific component definition. | ###### Raises - Raises when the relationship uses sparse storage or the target is invalid. #### Fields ##### `Value` ```nupp Value: associatedDecl ``` ##### `componentId` ```nupp componentId: integer ``` ##### `componentName` ```nupp componentName: string ``` ##### `storageType` ```nupp storageType: string ``` ##### `transient` ```nupp transient: boolean ``` ##### `exclusive` ```nupp exclusive: boolean ``` ##### `reverseIndex` ```nupp reverseIndex: boolean ``` ##### `cascadeDelete` ```nupp cascadeDelete: boolean ``` ##### `sparse` ```nupp sparse: boolean ``` Read-only. Selects entity-indexed edge storage; false selects target-specific dense columns. ### `relationship` _record_ ```nupp record relationship name: string? transient: boolean? exclusive: boolean? sparse: boolean? reverseIndex: boolean? cascadeDelete: boolean? end ``` `@annotation(targets={"record","struct"})` Configures a derived relationship's identity, cardinality and storage policy. #### Fields ##### `name` ```nupp name: string? ``` Caller-writable. Pins the persisted name; nil uses the qualified declaration. ##### `transient` ```nupp transient: boolean? ``` Caller-writable. Omits this relationship from snapshots. ##### `exclusive` ```nupp exclusive: boolean? ``` Caller-writable. Limits each source to one target when true. ##### `sparse` ```nupp sparse: boolean? ``` Caller-writable. Selects entity-indexed edges instead of dense target columns. ##### `reverseIndex` ```nupp reverseIndex: boolean? ``` Caller-writable. Maintains target-to-source lookup when true. ##### `cascadeDelete` ```nupp cascadeDelete: boolean? ``` Caller-writable. Deletes sources with their target; requires both index and exclusivity. ### `RelationshipDefinition` _interface_ ```nupp interface RelationshipDefinition is Component associated type Value == T associated type Column == {T} construct: function(...: any): T defaultFactory: function(): T snapshotSave: function(value: T): any snapshotLoad: function(value: any, exclusive world: any): T metamethod __call: function(self, ...: any): FFIInstance> targeting: function(self: TypedRelationship, target: integer): TypedComponent end ``` A payload relationship whose target selector retains the physical column type. #### Type parameters | Name | Description | | --- | --- | | `T` | | #### Methods ##### `construct` ```nupp construct: function(...: any): T ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `...` | `any` | | ###### Returns | Type | Description | | --- | --- | | `T` | | ##### `defaultFactory` ```nupp defaultFactory: function(): T ``` ###### Returns | Type | Description | | --- | --- | | `T` | | ##### `snapshotSave` ```nupp snapshotSave: function(value: T): any ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `T` | | ###### Returns | Type | Description | | --- | --- | | `any` | | ##### `snapshotLoad` ```nupp snapshotLoad: function(value: any, exclusive world: any): T ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `value` | `any` | | | `exclusive world` | `any` | | ###### Returns | Type | Description | | --- | --- | | `T` | | ##### `__call` ```nupp __call: function(self, ...: any): FFIInstance> ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `?` | `self` | | | `...` | `any` | | ###### Returns | Type | Description | | --- | --- | | `FFIInstance\\>` | | ##### `targeting` ```nupp targeting: function(self: TypedRelationship, target: integer): TypedComponent ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `TypedRelationship\` | | | `target` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `TypedComponent\` | | #### Fields ##### `Value` ```nupp Value: associatedDecl ``` ##### `Column` ```nupp Column: associatedDecl ``` ### `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 end ``` Bounds generic helpers to target-bearing declarations deriving the relationship contract. ### `RelationshipValue` _record_ ```nupp record RelationshipValue target: integer end ``` A target-only relationship edge value. #### Fields ##### `target` ```nupp target: integer ``` Read-only. Names the target; replace the edge through world:set to retarget it. ### `RelativeTransform2D` _struct_ ```nupp struct RelativeTransform2D x: number y: number z: number rotation: number scaleX: number scaleY: number originX: number originY: number end ``` `@derive(nupp.derive.Debug, nupp.derive.Serde)` Offsets an entity from the transform of the parent it names with `ChildOf`. #### Fields ##### `x` ```nupp x: number ``` Caller-writable. Sets the horizontal offset from the parent, in the parent's rotated and scaled space. ##### `y` ```nupp y: number ``` Caller-writable. Sets the vertical offset from the parent, in the parent's rotated and scaled space. ##### `z` ```nupp z: number ``` Caller-writable. Sets the depth offset added to the parent's depth. ##### `rotation` ```nupp rotation: number ``` Caller-writable. Sets the clockwise rotation in radians added to the parent's rotation. ##### `scaleX` ```nupp scaleX: number ``` Caller-writable. Sets the horizontal scale multiplied by the parent's. ##### `scaleY` ```nupp scaleY: number ``` Caller-writable. Sets the vertical scale multiplied by the parent's. ##### `originX` ```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` ```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 associated type Value = T componentId: integer componentName: string storageType: string transient: boolean scalarKind: "number" | "boolean" | "string" scalarDefault: T metamethod __call: function(self, value: T): ScalarInstance end ``` A primitive-valued component definition. #### Type parameters | Name | Description | | --- | --- | | `T` | | #### Methods ##### `__call` ```nupp __call: function(self, value: T): ScalarInstance ``` ###### Arguments | Name | Type | Description | | --- | --- | --- | | `?` | `self` | | | `value` | `T` | | ###### Returns | Type | Description | | --- | --- | | `ScalarInstance\` | | #### Fields ##### `Value` ```nupp Value: associatedDecl ``` ##### `componentId` ```nupp componentId: integer ``` ##### `componentName` ```nupp componentName: string ``` ##### `storageType` ```nupp storageType: string ``` ##### `transient` ```nupp transient: boolean ``` ##### `scalarKind` ```nupp scalarKind: "number" | "boolean" | "string" ``` ##### `scalarDefault` ```nupp scalarDefault: T ``` ### `ScalarComponentOptions` _type_ ```nupp type ScalarComponentOptions = NumberComponentOptions | BooleanComponentOptions | StringComponentOptions ``` Options accepted by the kind-correlated scalar component factory. ### `Snapshot` _record_ ```nupp record Snapshot version: integer nextEntityId: integer entityCount: integer archetypeCount: integer componentTable: {SnapshotComponentEntry} archetypes: {SnapshotArchetype} data: {SnapshotDataEntry} states: {string} format: ("binary" | "table")? buffer: buffer.Buffer? pipeline: { fixedAccumulator: number, phaseStates: {boolean}, disabledPhases: {[string]: boolean} }? end ``` A detached, format-neutral world snapshot. #### Fields ##### `version` ```nupp version: integer ``` ##### `nextEntityId` ```nupp nextEntityId: integer ``` ##### `entityCount` ```nupp entityCount: integer ``` ##### `archetypeCount` ```nupp archetypeCount: integer ``` ##### `componentTable` ```nupp componentTable: {SnapshotComponentEntry} ``` ##### `archetypes` ```nupp archetypes: {SnapshotArchetype} ``` ##### `data` ```nupp data: {SnapshotDataEntry} ``` ##### `states` ```nupp states: {string} ``` ##### `format` ```nupp format: ("binary" | "table")? ``` Read-only. Identifies binary output when a native buffer was requested. ##### `buffer` ```nupp buffer: buffer.Buffer? ``` Read-only. Holds binary output; later saves into the same buffer overwrite it. ##### `pipeline` ```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 version: integer nextEntityId: integer entityCount: integer archetypeCount: integer componentTable: {SnapshotComponentEntry} end ``` Metadata returned by a snapshot load. #### Fields ##### `version` ```nupp version: integer ``` Read-only. Reports the ECS framing version, independently of game data versions. ##### `nextEntityId` ```nupp nextEntityId: integer ``` Read-only. Reports the next fresh entity slot after restoration. ##### `entityCount` ```nupp entityCount: integer ``` Read-only. Reports the number of saved entities. ##### `archetypeCount` ```nupp archetypeCount: integer ``` Read-only. Reports the number of saved archetype frames. ##### `componentTable` ```nupp componentTable: {SnapshotComponentEntry} ``` Read-only. Lists the saved component names and native layouts in frame-index order. ### `StartSnapshotLoad` _record_ ```nupp record StartSnapshotLoad prelude: SnapshotPrelude handlers: {[string]: {function(value: any)}} function onData(self: StartSnapshotLoad, key: string, callback: function(value: any)): nil end end ``` `@derive(events.Event)` `@event(name="StartSnapshotLoad")` Allows snapshot participants to subscribe to metadata during a load. #### Methods ##### `onData` ```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 - Raises when the key is empty. #### Fields ##### `prelude` ```nupp prelude: SnapshotPrelude ``` Read-only. Describes the snapshot being restored. ##### `handlers` ```nupp handlers: {[string]: {function(value: any)}} ``` Engine-owned. Supplies dispatch staging to event construction; use onData instead. ### `StateBlur` _record_ ```nupp record StateBlur state: string pushed: string end ``` `@derive(events.Event)` `@event(name="StateBlur")` Fires after the current state loses focus. #### Fields ##### `state` ```nupp state: string ``` ##### `pushed` ```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 state: string end ``` `@derive(events.Event)` `@event(name="StateEnter")` Fires after a state becomes active. #### Fields ##### `state` ```nupp state: string ``` ### `StateExit` _record_ ```nupp record StateExit state: string end ``` `@derive(events.Event)` `@event(name="StateExit")` Fires before a state leaves the stack. #### Fields ##### `state` ```nupp state: string ``` ### `StateFocus` _record_ ```nupp record StateFocus state: string popped: string end ``` `@derive(events.Event)` `@event(name="StateFocus")` Fires after an uncovered state regains focus. #### Fields ##### `state` ```nupp state: string ``` ##### `popped` ```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 x: number y: number z: number layer: integer rotation: number scaleX: number scaleY: number end ``` `@derive(nupp.derive.Debug, nupp.derive.Serde)` Places an entity in the two-dimensional world. #### Fields ##### `x` ```nupp x: number ``` Caller-writable. Sets the horizontal position in world units. ##### `y` ```nupp y: number ``` Caller-writable. Sets the vertical position in world units. ##### `z` ```nupp z: number ``` Caller-writable. Sets depth within the selected layer. ##### `layer` ```nupp layer: integer ``` Caller-writable. Selects the integer draw layer. ##### `rotation` ```nupp rotation: number ``` Caller-writable. Sets clockwise rotation in radians. ##### `scaleX` ```nupp scaleX: number ``` Caller-writable. Sets horizontal scale in world units. ##### `scaleY` ```nupp scaleY: number ``` Caller-writable. Sets vertical scale in world units. ### `Transform3D` _type_ ```nupp type Transform3D = Transform3D2 ``` Places an entity in a right-handed 3D world using a quaternion and per-axis scale. ### `TTL` _struct_ ```nupp struct TTL startingTime: number remaining: number function percentComplete(self: TTL): number end end ``` `@derive(nupp.derive.Debug, nupp.derive.Serde)` Counts down an entity's remaining lifetime. #### Methods ##### `percentComplete` ```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 | #### Fields ##### `startingTime` ```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` ```nupp remaining: number ``` Caller-writable. Sets the seconds of fixed time left before the entity is despawned. Writing a larger value refreshes the timer. ### `World` _record_ ```nupp record World is Source liveCount: integer archetypeCount: integer systemCount: integer observers: Observers resources: Store spawn: function(exclusive self: World, ...: components.Input): integer spawnAt: function(exclusive self: World, id: integer, ...: components.Input): nil batchSpawn: function( exclusive self: World, count: integer, inputs: {components.Input}, callback: BatchCallback? ): (integer?, {integer}?) batchSpawnAt: function( exclusive self: World, ids: {integer}, inputs: {components.Input}, callback: BatchCallback? ): nil batchSpawnAtRaw: function( exclusive self: World, ids: number[?], count: integer, inputs: {components.Input}, callback: BatchCallback? ): nil batchSet: function( exclusive self: World, selection: query.Query, input: components.Input, callback: BatchCallback? ): nil batchRemove: function(exclusive self: World, selection: query.Query, input: components.Input): nil batchDespawn: function(exclusive self: World, selection: query.Query): nil forEachArchetype: function(borrows self: World, callback: function(candidate: archetype.Archetype)): nil findArchetypes: function( borrows self: World, component: components.Selector ): function(): (archetype.Archetype?, integer?, DoubleArray?) dirtyArchetypes: function(borrows self: World): function(): archetype.Archetype? compact: function(exclusive self: World): (integer, integer) isAlive: function(borrows self: World, id: integer): boolean has: function(borrows self: World, id: integer, component: components.Selector): boolean byKey: function(borrows self: World, key: string): integer? requireKey: function(borrows self: World, key: string): integer get: (function(borrows self: World, id: integer, component: C): C.Value?) & (function(borrows self: World, id: integer, component: Type): T?) getMut: (function(exclusive self: World, id: integer, component: C): C.Value?) & (function(exclusive self: World, id: integer, component: Type): T?) markComponentDirty: function(exclusive self: World, id: integer, component: components.Selector): nil relationshipSources: function(borrows self: World, relationship: components.Selector, target: integer): {integer} 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 ) getFirstRelationship: ( function(borrows self: World, id: integer, relationship: C): C.Value? ) & (function(borrows self: World, id: integer, relationship: Type): T?) targets: function( borrows self: World, target: integer, relationship: components.Selector, callback: function(source: integer, context: T), context: T ): nil traverse: function( borrows self: World, root: integer, relationship: components.Selector ): function(): (integer?, integer?) walkUp: function( borrows self: World, id: integer, relationship: components.Selector, callback: function(ancestor: integer, depth: integer, context: T): boolean?, context: T, maxDepth: integer? ): nil newQuery: function(exclusive self: World, descriptor: query.Descriptor?): query.Query set: function(exclusive self: World, id: integer, input: components.Input, value: any?): nil remove: function(exclusive self: World, id: integer, input: components.Input): nil despawn: function(exclusive self: World, id: integer): nil commit: function(exclusive self: World): nil enqueueCommit: function(exclusive self: World): nil randomStream: function(exclusive self: World, name: string): random.Random seedRandom: function(exclusive self: World, seed: integer): nil clearEntities: function(exclusive self: World): nil addSystem: function(exclusive self: World, config: SystemConfig): string registerPhase: function(exclusive self: World, phase: phases.Definition): nil removeSystem: function(exclusive self: World, name: string): boolean listSystems: function(borrows self: World): {SystemInfo} setSystemEnabled: function(exclusive self: World, name: string, enabled: boolean): (boolean, string?) update: function(exclusive self: World, dt: number): nil startup: function(exclusive self: World): nil shutdown: function(exclusive self: World): nil runPhase: function(exclusive self: World, phase: phases.Selection, dt: number?): nil enablePhase: function(exclusive self: World, phase: phases.Selection): nil disablePhase: function(exclusive self: World, phase: phases.Selection): nil isPhaseEnabled: function(borrows self: World, phase: phases.Phase): boolean getNominalFrameTime: function(borrows self: World): number setNominalFrameTime: function(exclusive self: World, seconds: number): nil getFixedTiming: function(borrows self: World): (number, number, number) fixedStepCount: function(borrows self: World): integer getStats: function(borrows self: World, fill: WorldStats?): WorldStats createState: function(exclusive self: World, name: string, policy: StatePolicy?): components.Component pushState: function(exclusive self: World, name: string): nil popState: function(exclusive self: World): nil peekState: function(borrows self: World): string? listStates: function(borrows self: World): {string} newBundle: function(self: World, name: string, definition: BundleDefinition?): Bundle spawnBundle: function(exclusive self: World, name: string, ...: components.Input): integer getBundles: function(borrows self: World): {[string]: Bundle} getBundle: function(borrows self: World, name: string): Bundle? saveSnapshot: function(exclusive self: World, options: SnapshotOptions?): Snapshot loadSnapshot: function(exclusive self: World, snapshot: any): SnapshotPrelude addSnapshotHandler: function(exclusive self: World, handler: SnapshotHandler): nil observe: function( exclusive self: World, address: integer, event: Type, callback: Observer, id: string? ): nil observeOnce: function( exclusive self: World, address: integer, event: Type, callback: Observer, id: string? ): nil stopObserving: function( exclusive self: World, address: integer, event: Type, callbackOrId: Observer | string ): boolean hasObservers: function(borrows self: World, address: integer, event: Type): boolean emit: function( exclusive self: World, address: integer, event: Type, ...: unpackof Construction(E) ): nil deliver: function(exclusive self: World, address: integer, event: Type, instance: E): nil clearObservers: function(exclusive self: World, address: integer): nil end ``` A Tecs world. #### Methods ##### `spawn` ```nupp spawn: function(exclusive self: World, ...: components.Input): integer ``` Reserves a new entity and stages it for the next barrier. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `...` | `components.Input` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ###### Raises - when the world has exhausted its fixed entity capacity ##### `spawnAt` ```nupp spawnAt: function(exclusive self: World, id: integer, ...: components.Input): nil ``` Reserves an externally supplied packed id for the next barrier. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `id` | `integer` | | | `...` | `components.Input` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ###### Raises - when the id is out of range or its slot is already reserved or alive ##### `batchSpawn` ```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 - Raises for invalid count, exhausted capacity, bare relationships or EntityKey. ##### `batchSpawnAt` ```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 - Raises before reserving any id if one is invalid, duplicated or occupied, or the signature contains EntityKey or a bare relationship. ##### `batchSpawnAtRaw` ```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 - Raises before reservation for an invalid count, identity, duplicate, occupied slot, or bare relationship. ##### `batchSet` ```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 - Raises for a foreign query, EntityKey, or callback mode with an instance or relationship. Relationship values support constant mode. ##### `batchRemove` ```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 - Raises when the query belongs to another world. ##### `batchDespawn` ```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 - Raises when the query belongs to another world. ##### `forEachArchetype` ```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` ```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` ```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` ```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 - Raises during dispatch, publication, or with uncommitted work. ##### `isAlive` ```nupp isAlive: function(borrows self: World, id: integer): boolean ``` Reports whether an entity is committed and alive. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | | | `id` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | ##### `has` ```nupp has: function(borrows self: World, id: integer, component: components.Selector): boolean ``` Reports whether a committed entity carries a component. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | | | `id` | `integer` | | | `component` | `components.Selector` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | ##### `byKey` ```nupp byKey: function(borrows self: World, key: string): integer? ``` Returns the live entity carrying one durable key. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | | | `key` | `string` | | ###### Returns | Type | Description | | --- | --- | | `integer?` | | ##### `requireKey` ```nupp requireKey: function(borrows self: World, key: string): integer ``` Returns the live entity carrying one durable key, or raises. Use this where a missing key means the caller built the world wrong, and `byKey` where its absence is an ordinary answer. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | | | `key` | `string` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ###### Raises - when no live entity carries the key ##### `markComponentDirty` ```nupp markComponentDirty: function(exclusive self: World, id: integer, component: components.Selector): nil ``` Marks a committed entity's component dirty after an out-of-band write. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `id` | `integer` | | | `component` | `components.Selector` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `relationshipSources` ```nupp relationshipSources: function(borrows self: World, relationship: components.Selector, target: integer): {integer} ``` Returns the sources currently linked to one relationship target. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | | | `relationship` | `components.Selector` | | | `target` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `{integer}` | | ###### Raises - Raises when the component is not a relationship with a reverse index. ##### `targets` ```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 - Raises when the relationship has no reverse index. ##### `traverse` ```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 - Raises when the relationship has no reverse index. ##### `walkUp` ```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 - Raises on a cycle or when the depth limit is exceeded. ##### `newQuery` ```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 - Raises for an invalid query type or temporary membership callbacks. ##### `set` ```nupp set: function(exclusive self: World, id: integer, input: components.Input, value: any?): nil ``` Stages a component value to be present at the next barrier. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `id` | `integer` | | | `input` | `components.Input` | | | `value` | `any?` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ###### Raises - Raises when a relationship has no valid target-bearing value. ##### `remove` ```nupp remove: function(exclusive self: World, id: integer, input: components.Input): nil ``` Stages a tag component to be absent at the next barrier. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `id` | `integer` | | | `input` | `components.Input` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `despawn` ```nupp despawn: function(exclusive self: World, id: integer): nil ``` Stages a live or newly reserved entity for removal. Dead, invalid, and stale ids are silent no-ops. Repeating the same despawn is also a no-op. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `id` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `commit` ```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 - Raises when a publication callback raises. ##### `enqueueCommit` ```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 - Raises when a synchronous publication callback raises. ##### `randomStream` ```nupp randomStream: function(exclusive self: World, name: string): random.Random ``` 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.Random` | Returns the same mutable generator for each call with this name. | ###### Raises - Raises when the name is empty. ##### `seedRandom` ```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 - Raises when the seed is not a finite integer. ##### `clearEntities` ```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 - Raises during publication. Use staged despawn from callbacks instead. ##### `addSystem` ```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 - Raises when another registered system carries that name. ##### `registerPhase` ```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 - Raises for duplicate names, invalid positions, unknown children or registration during dispatch. ##### `removeSystem` ```nupp removeSystem: function(exclusive self: World, name: string): boolean ``` Removes a system by name. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `name` | `string` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | ##### `listSystems` ```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 - Raises when any phase contains an ordering cycle. ##### `setSystemEnabled` ```nupp setSystemEnabled: function(exclusive self: World, name: string, enabled: boolean): (boolean, string?) ``` Enables or disables a registered system without removing it. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `name` | `string` | | | `enabled` | `boolean` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | | `string?` | | ##### `update` ```nupp update: function(exclusive self: World, dt: number): nil ``` Runs one logical frame update and its structural barriers. A barrier publishes work staged before the update, after every phase, and wherever a system explicitly requests one. Every update owns a structured `nupp.tasks` scope. A suspension-aware call may park the update through the surrounding host handler, and child work started through the system's third argument settles before the update returns. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `dt` | `number` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ###### Raises - when dt is negative or NaN, or when a system raises ##### `startup` ```nupp startup: function(exclusive self: World): nil ``` Runs the three startup phases in order. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ###### Raises - when another dispatch is active or a startup system raises ##### `shutdown` ```nupp shutdown: function(exclusive self: World): nil ``` Runs the three shutdown phases in order. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ###### Raises - when another dispatch is active or a shutdown system raises ##### `runPhase` ```nupp runPhase: function(exclusive self: World, phase: phases.Selection, dt: number?): nil ``` Runs one leaf phase without advancing the fixed clock or clearing dirty bits. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `phase` | `phases.Selection` | | | `dt` | `number?` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ###### Raises - when another dispatch is active or a system raises ##### `enablePhase` ```nupp enablePhase: function(exclusive self: World, phase: phases.Selection): nil ``` Enables a leaf phase or every leaf in a predefined group. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `phase` | `phases.Selection` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `disablePhase` ```nupp disablePhase: function(exclusive self: World, phase: phases.Selection): nil ``` Disables a leaf phase or every leaf in a predefined group. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `phase` | `phases.Selection` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ##### `isPhaseEnabled` ```nupp isPhaseEnabled: function(borrows self: World, phase: phases.Phase): boolean ``` Reports whether a leaf phase currently dispatches systems. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | | | `phase` | `phases.Phase` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | ##### `getNominalFrameTime` ```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` ```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` | | ###### Raises - when seconds is not positive and finite. ##### `getFixedTiming` ```nupp getFixedTiming: function(borrows self: World): (number, number, number) ``` Returns fixed-step timing for interpolation consumers. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | | ###### Returns | Type | Description | | --- | --- | | `number` | | | `number` | | | `number` | | ##### `fixedStepCount` ```nupp fixedStepCount: function(borrows self: World): integer ``` Returns the fixed steps run since the world was created. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ##### `getStats` ```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` ```nupp createState: function(exclusive self: World, name: string, policy: StatePolicy?): components.Component ``` Registers a named state and returns its auto-tag component. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `name` | `string` | | | `policy` | `StatePolicy?` | | ###### Returns | Type | Description | | --- | --- | | `components.Component` | | ###### Raises - when the name is empty or already registered in this world ##### `pushState` ```nupp pushState: function(exclusive self: World, name: string): nil ``` Pushes a registered state and makes it the auto-tagging state. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `name` | `string` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ###### Raises - when the state is unknown ##### `popState` ```nupp popState: function(exclusive self: World): nil ``` Pops the active state and focuses the state below it. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ###### Raises - when the state stack is empty ##### `peekState` ```nupp peekState: function(borrows self: World): string? ``` Returns the active state name. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | | ###### Returns | Type | Description | | --- | --- | | `string?` | | ##### `listStates` ```nupp listStates: function(borrows self: World): {string} ``` Returns a bottom-first copy of the state stack. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | | ###### Returns | Type | Description | | --- | --- | | `{string}` | | ##### `newBundle` ```nupp newBundle: function(self: World, name: string, definition: BundleDefinition?): Bundle ``` Creates and registers a reusable spawn bundle. The receiver is plain rather than `exclusive`, because the bundle keeps the world it spawns into and so outlives a call-scoped borrow of it. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `self` | `World` | | | `name` | `string` | | | `definition` | `BundleDefinition?` | | ###### Returns | Type | Description | | --- | --- | | `Bundle` | | ###### Raises - when the name or component declaration is invalid ##### `spawnBundle` ```nupp spawnBundle: function(exclusive self: World, name: string, ...: components.Input): integer ``` Spawns from a registered bundle by name. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `name` | `string` | | | `...` | `components.Input` | | ###### Returns | Type | Description | | --- | --- | | `integer` | | ###### Raises - when the bundle is unknown or its required inputs are invalid ##### `getBundles` ```nupp getBundles: function(borrows self: World): {[string]: Bundle} ``` Returns a caller-owned snapshot of registered bundles. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | | ###### Returns | Type | Description | | --- | --- | | `{\[string\]: Bundle}` | | ##### `getBundle` ```nupp getBundle: function(borrows self: World, name: string): Bundle? ``` Returns a registered bundle by name. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | | | `name` | `string` | | ###### Returns | Type | Description | | --- | --- | | `Bundle?` | | ##### `saveSnapshot` ```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 - Raises during publication or another suspended dispatch, for invalid options, duplicate or reserved metadata, unencodable values, or failed file output. ##### `loadSnapshot` ```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 - Raises during publication or another suspended dispatch, or for invalid framing, identities, schemas, state or codecs. ##### `addSnapshotHandler` ```nupp addSnapshotHandler: function(exclusive self: World, handler: SnapshotHandler): nil ``` Registers a named custom snapshot participant. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `handler` | `SnapshotHandler` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ###### Raises - when the key is empty, already registered, or reserved as tecs.random ##### `observe` ```nupp observe: function( exclusive self: World, address: integer, event: Type, callback: Observer, id: string? ): nil ``` Registers an addressed typed-event observer. Observers run in registration order and receive only the borrowed event. A name lets `stopObserving` remove the registration by name; a name already observing this event at this address is an error. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `address` | `integer` | | | `event` | `Type\` | | | `callback` | `Observer\` | | | `id` | `string?` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ###### Raises - when the same name already observes this event and address ##### `observeOnce` ```nupp observeOnce: function( exclusive self: World, address: integer, event: Type, callback: Observer, id: string? ): nil ``` Registers an observer consumed before its first delivery. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `address` | `integer` | | | `event` | `Type\` | | | `callback` | `Observer\` | | | `id` | `string?` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ###### Raises - when the same name already observes this event and address ##### `stopObserving` ```nupp stopObserving: function( exclusive self: World, address: integer, event: Type, callbackOrId: Observer | string ): boolean ``` Removes observers at one address and event. Given a name, the first registration with that name goes; given the callback, every registration of it. A removal during a delivery takes effect at once for anything the delivery has not yet reached. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `address` | `integer` | | | `event` | `Type\` | | | `callbackOrId` | `Observer\ | string` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | ##### `hasObservers` ```nupp hasObservers: function(borrows self: World, address: integer, event: Type): boolean ``` Reports whether an address has an observer for an event. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `borrows self` | `World` | | | `address` | `integer` | | | `event` | `Type\` | | ###### Returns | Type | Description | | --- | --- | | `boolean` | | ##### `emit` ```nupp emit: function( exclusive self: World, address: integer, event: Type, ...: unpackof Construction(E) ): nil ``` Constructs an event into the world's storage and delivers it to one address. Nothing is constructed when nothing observes the event there. Observers run in registration order, see each other's writes, and cannot keep the event; the storage returns to the world when the delivery leaves, whether it returned, raised, or was cancelled while an observer was suspended. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `address` | `integer` | | | `event` | `Type\` | | | `...` | `unpackof Construction(E)` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ###### Raises - what an observer raised, after the storage is released ##### `deliver` ```nupp deliver: function(exclusive self: World, address: integer, event: Type, instance: E): nil ``` Delivers an event instance the caller already holds. The instance stays the caller's, and what observers wrote to it is there when the delivery returns, which is what a bubbling delivery reads back. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `address` | `integer` | | | `event` | `Type\` | | | `instance` | `E` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | ###### Raises - what an observer raised ##### `clearObservers` ```nupp clearObservers: function(exclusive self: World, address: integer): nil ``` Clears every event observer at one address. ###### Arguments | Name | Type | Description | | --- | --- | --- | | `exclusive self` | `World` | | | `address` | `integer` | | ###### Returns | Type | Description | | --- | --- | | `nil` | | #### Fields ##### `liveCount` ```nupp liveCount: integer ``` ##### `archetypeCount` ```nupp archetypeCount: integer ``` ##### `systemCount` ```nupp systemCount: integer ``` ##### `observers` ```nupp observers: Observers ``` Observer registrations by address and event; `observers.count` is how many are live. ##### `resources` ```nupp resources: Store ``` ##### `get` ```nupp get: (function(borrows self: World, id: integer, component: C): C.Value?) & (function(borrows self: World, id: integer, component: Type): T?) ``` ##### `getMut` ```nupp getMut: (function(exclusive self: World, id: integer, component: C): C.Value?) & (function(exclusive self: World, id: integer, component: Type): T?) ``` ##### `forEachRelationship` ```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` ```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. ### `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 entities: integer archetypes: integer components: integer systems: integer fixedTimeDropped: number fixedStepsDropped: integer end ``` Fixed-step overload counters accumulated by a world. #### Fields ##### `entities` ```nupp entities: integer ``` ##### `archetypes` ```nupp archetypes: integer ``` ##### `components` ```nupp components: integer ``` ##### `systems` ```nupp systems: integer ``` ##### `fixedTimeDropped` ```nupp fixedTimeDropped: number ``` ##### `fixedStepsDropped` ```nupp fixedStepsDropped: integer ``` ## Functions ### `Component` _comptime function_ ```nupp comptime function Component(info: nupp.derive.Info): nupp.derive.Result ``` 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 - Raises 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 | ### `Relationship` _comptime function_ ```nupp comptime function Relationship(info: nupp.derive.Info): nupp.derive.Result ``` 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 - Raises 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 - Raises 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 - Raises when cascade deletion lacks exclusivity or reverse indexing. - Raises when the name is invalid or already belongs to another definition. - Raises when a payload declaration does not provide a valid target field. - Raises 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 - 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.