API reference

Returns

WorkAttempt | null

processRequirements

readonly processRequirements: (definition, station) => ProcessRequirements

Parameters

definition

string

station

Returns

ProcessRequirements

floorOperations

readonly floorOperations: (requests) => readonly FloorOperation[]

Parameters

requests

readonly FloorOperationRequest[]

Returns

readonly FloorOperation[]

Methods

flowFields()

flowFields(geometry): FlowNavigation

Session-owned shared navigation, derived from declared world geometry.

Parameters

geometry

FlowGeometry

Returns

query()

query<T>>(spec): readonly QueryRow<T>>[]

Type Parameters

T

T extends object

Parameters

spec

QuerySpec<T>

Returns

readonly QueryRow<T>[]

workMaterialFacts()

workMaterialFacts(): WorkMaterialFacts

One committed physical projection shared by all work phases in a step.

Returns

WorkMaterialFacts

worldPoses()

worldPoses(entities): readonly WorldPose[]

Parameters

entities

readonly EntityId[]

Returns

readonly WorldPose[]

routeCosts()

routeCosts(requests): readonly RouteCostResult[]

Parameters

requests

readonly RouteCostRequest[]

Returns

readonly RouteCostResult[]

routeToAny()

routeToAny(request): RouteToAnyResult

Parameters

request

RouteToAnyRequest

Returns

RouteToAnyResult

transferContacts()

transferContacts(request): { kind: "ready"; targets: readonly MoveDestination[]; } | { kind: "blocked"; reason: "sealed" | "unavailable-frame" | "no-contact"; }

Parameters

request

worker

container

ReadContext.workAttempts

Returns

{ kind: "ready"; targets: readonly MoveDestination[]; } | { kind: "blocked"; reason: "sealed" | "unavailable-frame" | "no-contact"; }

physicalContacts()

physicalContacts(cells): readonly PhysicalContact[]

Parameters

cells

readonly [number, number, number][]

Returns

readonly PhysicalContact[]

environmentFacts()

environmentFacts(): object

Returns

object

terrainRevision

terrainRevision: number

placementRevision

placementRevision: number

totalKg

totalKg: number

residualKg

residualKg: number

initialTotalKg

initialTotalKg: number

boundaryKg

boundaryKg: number

cells

cells: object[]

emissions

emissions: object[]

atmosphereSamples()

atmosphereSamples(cells): AtmosphereSamples

Returns modeled atmosphere at each cell; null means the receiver is unmodeled, not clean air.

Parameters

cells

readonly [number, number, number][]

Returns

AtmosphereSamples

constructionReadiness()

constructionReadiness(sites): readonly ConstructionReadiness[]

Parameters

sites

readonly EntityId[]

Returns

readonly ConstructionReadiness[]

constructionAccess()

constructionAccess(sites): readonly ConstructionAccess[]

Ordered structural, material, and work-contact facts for construction allocation.

Parameters

sites

readonly EntityId[]

Returns

readonly ConstructionAccess[]

deconstructionAccess()

deconstructionAccess(sites): readonly DeconstructionAccess[]

Parameters

sites

readonly EntityId[]

Returns

readonly DeconstructionAccess[]

terrainMaterials()

terrainMaterials(cells): readonly number[]

Parameters

cells

readonly [number, number, number][]

Returns

readonly number[]

terrainSurfaces()

terrainSurfaces(columns): readonly (Readonly<{ cell: readonly [number, number, number]; material: number; generatedTop: number; cover?: Readonly<{ kind: string; condition: string; height: string; }>; }> | null)[]

Parameters

columns

readonly [number, number][]

Returns

readonly (Readonly<{ cell: readonly [number, number, number]; material: number; generatedTop: number; cover?: Readonly<{ kind: string; condition: string; height: string; }>; }> | null)[]

structureSurfaces()

structureSurfaces(columns): readonly readonly StructureSurface[][]

Parameters

columns

readonly [number, number][]

Returns

readonly readonly StructureSurface[][]

waterContacts()

waterContacts(centers): readonly object[]

Parameters

centers

readonly [number, number, number][]

Returns

readonly object[]

ScopedAction

Properties

scope

readonly scope: ActionScope

request

readonly request: ActionRequest

ScopedCreate

Properties

scope

readonly scope: ActionScope

record

readonly record: EntityRecord

ScopedRemove

Properties

scope

readonly scope: ActionScope

entity

readonly entity: EntityId

CrowdMotion

Ground-plane crowd destination, advanced by the native simulation phase.

Properties

entity

readonly entity: EntityId

x

readonly x: number

z

readonly z: number

speed

readonly speed: number

WriteContext

Extends

ReadContext

Properties

clock

readonly clock: SimulationClock

Inherited from

ReadContext.clock

outcomes

readonly outcomes: readonly ActionOutcome[]

Inherited from

ReadContext.outcomes

random

readonly random: RandomSource

Inherited from

ReadContext.random

impacts

readonly impacts: readonly Impact[]

Inherited from

ReadContext.impacts

workAttempts?

readonly optional workAttempts?: (taskIds) => readonly WorkAttempt[]

Parameters

taskIds

readonly EntityId[]

Returns

readonly WorkAttempt[]

Inherited from

workAttemptForWorker

readonly workAttemptForWorker: (worker) => WorkAttempt | null

Parameters

processRequirements

readonly processRequirements: (definition, station) => ProcessRequirements

Parameters

definition

string

station

ReadContext.processRequirements

Returns

ProcessRequirements

Inherited from

floorOperations

readonly floorOperations: (requests) => readonly FloorOperation[]

Parameters

requests

readonly FloorOperationRequest[]

Returns

readonly FloorOperation[]

Inherited from

ReadContext.floorOperations

Methods

flowFields()

flowFields(geometry): FlowNavigation

Session-owned shared navigation, derived from declared world geometry.

Parameters

geometry

FlowGeometry

Returns

ReadContext.flowFields

Inherited from

query()

query<T>>(spec): readonly QueryRow<T>>[]

Type Parameters

T

T extends object

Parameters

spec

QuerySpec<T>

Returns

readonly QueryRow<T>[]

Inherited from

ReadContext.query

workMaterialFacts()

workMaterialFacts(): WorkMaterialFacts

One committed physical projection shared by all work phases in a step.

Returns

WorkMaterialFacts

Inherited from

ReadContext.workMaterialFacts

worldPoses()

worldPoses(entities): readonly WorldPose[]

Parameters

entities

readonly EntityId[]

Returns

readonly WorldPose[]

Inherited from

ReadContext.worldPoses

routeCosts()

routeCosts(requests): readonly RouteCostResult[]

Parameters

requests

readonly RouteCostRequest[]

Returns

readonly RouteCostResult[]

Inherited from

ReadContext.routeCosts

routeToAny()

routeToAny(request): RouteToAnyResult

Parameters

request

RouteToAnyRequest

Returns

RouteToAnyResult

Inherited from

ReadContext.routeToAny

transferContacts()

transferContacts(request): { kind: "ready"; targets: readonly MoveDestination[]; } | { kind: "blocked"; reason: "sealed" | "unavailable-frame" | "no-contact"; }

Parameters

request

worker

container

ReadContext.transferContacts

Returns

{ kind: "ready"; targets: readonly MoveDestination[]; } | { kind: "blocked"; reason: "sealed" | "unavailable-frame" | "no-contact"; }

Inherited from

physicalContacts()

physicalContacts(cells): readonly PhysicalContact[]

Parameters

cells

readonly [number, number, number][]

Returns

readonly PhysicalContact[]

Inherited from

ReadContext.physicalContacts

environmentFacts()

environmentFacts(): object

Returns

object

terrainRevision

terrainRevision: number

placementRevision

placementRevision: number

totalKg

totalKg: number

residualKg

residualKg: number

initialTotalKg

initialTotalKg: number

boundaryKg

boundaryKg: number

cells

cells: object[]

emissions

emissions: object[]

Inherited from

ReadContext.environmentFacts

atmosphereSamples()

atmosphereSamples(cells): AtmosphereSamples

Returns modeled atmosphere at each cell; null means the receiver is unmodeled, not clean air.

Parameters

cells

readonly [number, number, number][]

Returns

AtmosphereSamples

Inherited from

ReadContext.atmosphereSamples

constructionReadiness()

constructionReadiness(sites): readonly ConstructionReadiness[]

Parameters

sites

readonly EntityId[]

Returns

readonly ConstructionReadiness[]

Inherited from

ReadContext.constructionReadiness

constructionAccess()

constructionAccess(sites): readonly ConstructionAccess[]

Ordered structural, material, and work-contact facts for construction allocation.

Parameters

sites

readonly EntityId[]

Returns

readonly ConstructionAccess[]

Inherited from

ReadContext.constructionAccess

deconstructionAccess()

deconstructionAccess(sites): readonly DeconstructionAccess[]

Parameters

sites

readonly EntityId[]

Returns

readonly DeconstructionAccess[]

Inherited from

ReadContext.deconstructionAccess

terrainMaterials()

terrainMaterials(cells): readonly number[]

Parameters

cells

readonly [number, number, number][]

Returns

readonly number[]

Inherited from

ReadContext.terrainMaterials

terrainSurfaces()

terrainSurfaces(columns): readonly (Readonly<{ cell: readonly [number, number, number]; material: number; generatedTop: number; cover?: Readonly<{ kind: string; condition: string; height: string; }>; }> | null)[]

Parameters

columns

readonly [number, number][]

Returns

Inherited from

ReadContext.terrainSurfaces

structureSurfaces()

structureSurfaces(columns): readonly readonly StructureSurface[][]

Parameters

columns

readonly [number, number][]

Returns

readonly readonly StructureSurface[][]

Inherited from

ReadContext.structureSurfaces

waterContacts()

waterContacts(centers): readonly object[]

Parameters

centers

readonly [number, number, number][]

Returns

readonly object[]

Inherited from

ReadContext.waterContacts

checkpoint()

checkpoint(name): void

Ask the host to retain this committed simulation state for retry.

Parameters

name

string

Returns

void

write()

write<T>>(definition, entity, value): void

Type Parameters

T

T extends object

Parameters

definition

entity

value

T

Returns

void

action()

action(request, scope?): void

Parameters

request

scope?

ActionScope

Returns

void

createAuthoredEntity()

createAuthoredEntity(record, scope?): void

Parameters

record

EntityRecord

scope?

ActionScope

Returns

void

removeAuthoredEntity()

removeAuthoredEntity(id): void

Parameters

id

Returns

void

retireActor()

retireActor(id): void

Retire a physical actor in this committed step. Rules only.

Parameters

id

Returns

void

cue()

cue(cue): void

Author a bounded, presentation-only feedback cue for this committed step. Never changes simulation state; only surfaces when the game opts into presentation.feedback.

Parameters

cue

AuthoredFeedbackCue

Returns

void

SystemDefinition

Properties

id

readonly id: `${string}.${string}`

version

readonly version: number

reads

readonly reads: readonly ComponentDefinition<any>>[]

writes

readonly writes: readonly ComponentDefinition<any>>[]

every?

readonly optional every?: number

consumesImpacts?

readonly optional consumesImpacts?: boolean

run

readonly run: (context) => void

Parameters

context

WriteContext

Returns

void

ProjectileAim

Properties

origin

readonly origin: Vec3

muzzle

readonly muzzle: Vec3

inheritedVelocity

readonly inheritedVelocity: Vec3

radius

readonly radius: number

gravity

readonly gravity: number

penetration

readonly penetration: number

maxRange

readonly maxRange: number

maxLifetime

readonly maxLifetime: number

speed

readonly speed: number

CollisionFact

Properties

id

readonly id: EntityId

origin

readonly origin: Vec3

velocity

readonly velocity: Vec3

geometry

readonly geometry: "ball" | "cuboid"

radius

readonly radius: number

halfX

readonly halfX: number

halfY

readonly halfY: number

halfZ

readonly halfZ: number

yaw

readonly yaw: number

offsetX

readonly offsetX: number

offsetY

readonly offsetY: number

offsetZ

readonly offsetZ: number

material

readonly material: object

response

readonly response: "stop" | "pierce" | "ground"

resistance

readonly resistance: number

restitution

readonly restitution: number

friction

readonly friction: number

embedSpeed

readonly embedSpeed: number

RenderFact

Properties

activity?

readonly optional activity?: { kind: "dig" | "build" | "chop"; target: [number, number]; progress?: number; } | { kind: "delivery"; phase: "fetching" | "pickup" | "carrying" | "putting-down"; material: string; target: [number, number]; progress?: number; }

movement?

readonly optional movement?: { baseSpeed: number; effectiveSpeed: number; routed: boolean; } | null

Native movement speed selected for the current route; base speed survives the order.

view?

readonly optional view?: object

pickable?

readonly optional pickable?: boolean

cutawayTop?

readonly optional cutawayTop?: number

aim?

readonly optional aim?: ProjectileAim | null

collision?

readonly optional collision?: CollisionFact | null

projectile?

readonly optional projectile?: { velocity: Vec3; gravity: number; state: "flying" | "rolling" | "resting" | "embedded"; embedDepth: number; rollNormal: Vec3; penetration: number; } | null

id

readonly id: EntityId

pose?

readonly optional pose?: Pose

Resolved world pose, including any moving or rotated support.

local?

readonly optional local?: Pose

Native local pose; for supported entities this is relative to frame.

support?

readonly optional support?: EntityId | null

frame?

readonly optional frame?: EntityId

Observation frame for a supported entity; local is measured in this frame.

surface?

readonly optional surface?: SupportSurface | null

visual?

readonly optional visual?: string | null

appearance?

readonly optional appearance?: object

A rigged actor’s paper doll (vishnu.biped.v1): body profile, wardrobe slot → item, palette channel → swatch, and the cuts it has lost. Drawn instead of visual when present.

profile

readonly profile: string

slots

readonly slots: Readonly<Partial<Record<string, string>>>>>>

palette

readonly palette: Readonly<Partial<Record<string, string>>>>>>

severed

readonly severed: readonly string[]

limb?

readonly optional limb?: string

A loose limb: the cut it came off at (drawn from its severed bake).

gaze?

readonly optional gaze?: readonly [number, number]

Where the actor aims or looks, as a ground point [x, z]: its body faces it even while walking (the game’s presentation gazes).

act?

readonly optional act?: object

A one-shot state the actor is in (the game’s presentation acts).

state

readonly state: string

since

readonly since: number

seconds

readonly seconds: number

label?

readonly optional label?: string | null

placement?

readonly optional placement?: VisualPlacement

selected?

readonly optional selected?: boolean

hands?

readonly optional hands?: object

What the actor holds in its hands, from the native hands slot only. Held props and carry poses derive from this, never from inventory, job intent or a route.

lot

readonly lot: EntityId

kind

readonly kind: string

quantity

readonly quantity: number

container?

readonly optional container?: object

container.capacity

readonly capacity: number

container.contents

readonly contents: object

container.contents.items

readonly items: readonly object[]

container.contents.overflow?

readonly optional overflow?: boolean

inventory?

readonly optional inventory?: object

items

readonly items: readonly object[]

overflow?

readonly optional overflow?: boolean

direct?

readonly optional direct?: { stream: string; lastQueued: number; lastProcessed: number; speed: number; blocked: readonly [number, number, number][]; closedFaces: readonly object[]; bounds: { min_x: number; max_x: number; min_z: number; max_z: number; } | null; } | null

DeliveryActivity

Properties

kind

readonly kind: "delivery"

phase

readonly phase: DeliveryActivityPhase

material

readonly material: string

target

readonly target: readonly [number, number]

ActivityBinding

Properties

actor

readonly actor: EntityId

kind

readonly kind: "dig" | "build" | "chop"

target

readonly target: readonly [number, number]

progress?

readonly optional progress?: number

AtmosphereSample

Properties

volumeId

readonly volumeId: string

temperatureC

readonly temperatureC: number

smokeKgM3

readonly smokeKgM3: number

AtmosphereSamples

Properties

revision

readonly revision: number

geometryRevision

readonly geometryRevision: number

samples

readonly samples: readonly (AtmosphereSample | null)[]

ConstructionReadiness

Properties

site

readonly site: EntityId

status

readonly status: ConstructionReadinessStatus

reason?

readonly optional reason?: "missingStructuralSupport"

PlacementCandidate

Properties

site

readonly site: EntityId

catalog

readonly catalog: string

target

readonly target: ConstructionTarget

PlacementDecision

Properties

site

readonly site: EntityId

status

readonly status: "ready" | "rejected"

reason?

readonly optional reason?: string

PlacementDecisionResponse

Properties

revision

readonly revision: number

placementRevision

readonly placementRevision: number

decisions

readonly decisions: readonly PlacementDecision[]

ConstructionAccess

Properties

site

readonly site: EntityId

support

readonly support: ConstructionReadinessStatus

materialsReady

readonly materialsReady: boolean

blockedActors

readonly blockedActors: readonly EntityId[]

contacts

readonly contacts: readonly ConstructionAccessContact[]

SurfaceWaterContact

Properties

cell

readonly cell: readonly [number, number, number]

groundwaterHead

readonly groundwaterHead: number

TerrainPresentationDefinition

Properties

materials

readonly materials: readonly object[]

Content-owned art family for each physical material slot.

generatedCover?

readonly optional generatedCover?: (input) => Readonly<{ kind: string; condition: string; height: string; }> | null

Pure fresh-world cover projection. Later physical cover mutations override it.

Parameters

input

cell

readonly [number, number, number]

material

number

generatedTop

number

worldSeed

string

worldIdentity

string

Returns

Readonly<{ kind: string; condition: string; height: string; }> | null

KernelPort

Properties

partyJoinIdentity

readonly partyJoinIdentity: (bindingId) => PartyJoinIdentity

Parameters

bindingId

string

Returns

PartyJoinIdentity

floorOperations

readonly floorOperations: (requests) => readonly FloorOperation[]

Parameters

requests

readonly FloorOperationRequest[]

Returns

readonly FloorOperation[]

transferContacts

readonly transferContacts: (request) => { kind: "ready"; targets: readonly MoveDestination[]; } | { kind: "blocked"; reason: "sealed" | "unavailable-frame" | "no-contact"; }

Parameters

request

worker

container

Returns

{ kind: "ready"; targets: readonly MoveDestination[]; } | { kind: "blocked"; reason: "sealed" | "unavailable-frame" | "no-contact"; }

physicalContacts

readonly physicalContacts: (cells) => readonly PhysicalContact[]

Parameters

cells

readonly [number, number, number][]

Returns

readonly PhysicalContact[]

routeCosts

readonly routeCosts: (requests) => readonly RouteCostResult[]

Parameters

requests

readonly RouteCostRequest[]

Returns

readonly RouteCostResult[]

routeToAny

readonly routeToAny: (request) => RouteToAnyResult

Parameters

request

RouteToAnyRequest

Returns

RouteToAnyResult

dispose

readonly dispose: () => void

Returns

void

load

readonly load: (definition) => void

Parameters

definition

Uint8Array

Returns

void

loadEnvironment

readonly loadEnvironment: (definition) => void

Parameters

definition

Uint8Array

Returns

void

environmentFacts

readonly environmentFacts: () => object

Returns

object

terrainRevision

terrainRevision: number

placementRevision

placementRevision: number

totalKg

totalKg: number

residualKg

residualKg: number

initialTotalKg

initialTotalKg: number

boundaryKg

boundaryKg: number

cells

cells: object[]

emissions

emissions: object[]

atmosphereSamples

readonly atmosphereSamples: (cells) => AtmosphereSamples

Parameters

cells

readonly [number, number, number][]

Returns

AtmosphereSamples

constructionReadiness

readonly constructionReadiness: (sites) => readonly ConstructionReadiness[]

Read-only support projection for pending construction, resolved in one native batch.

Parameters

sites

readonly EntityId[]

Returns

readonly ConstructionReadiness[]

placementDecisions

readonly placementDecisions: (party, candidates) => PlacementDecisionResponse

Advisory native geometry decision; command admission always rechecks.

Parameters

party

PlacementDecisionResponse

candidates

readonly PlacementCandidate[]

Returns

constructionAccess

readonly constructionAccess: (sites) => readonly ConstructionAccess[]

Parameters

sites

readonly EntityId[]

Returns

readonly ConstructionAccess[]

deconstructionAccess

readonly deconstructionAccess: (sites) => readonly DeconstructionAccess[]

Parameters

sites

readonly EntityId[]

Returns

readonly DeconstructionAccess[]

terrainMaterials

readonly terrainMaterials: (cells) => readonly number[]

Parameters

cells

readonly [number, number, number][]

Returns

readonly number[]

terrainSurfaces

readonly terrainSurfaces: (columns) => readonly (Readonly<{ cell: readonly [number, number, number]; material: number; generatedTop: number; cover?: Readonly<{ kind: string; condition: string; height: string; }>; }> | null)[]

Parameters

columns

readonly [number, number][]

Returns

surfaceWaterTable

readonly surfaceWaterTable: (columns) => readonly (SurfaceWaterContact | null)[]

Parameters

columns

readonly [number, number][]

Returns

readonly (SurfaceWaterContact | null)[]

waterContacts

readonly waterContacts: (centers) => readonly object[]

Parameters

centers

readonly [number, number, number][]

Returns

readonly object[]

terrainChanges

readonly terrainChanges: (sinceRevision) => TerrainChangeSet

Parameters

sinceRevision

number

Returns

TerrainChangeSet

structureSurfaces

readonly structureSurfaces: (columns) => readonly readonly StructureSurface[][]

Parameters

columns

readonly [number, number][]

Returns

readonly readonly StructureSurface[][]

query

readonly query: <T>>(spec) => readonly QueryRow<T>>[]

Type Parameters

T

T extends object

Parameters

spec

QuerySpec<T>

Returns

readonly QueryRow<T>[]

workMaterialFacts

readonly workMaterialFacts: () => WorkMaterialFacts

Compact native owner projection for shared work/material planning.

Returns

WorkMaterialFacts

workAttempts

readonly workAttempts: (taskIds) => readonly WorkAttempt[]

Parameters

taskIds

readonly EntityId[]

Returns

readonly WorkAttempt[]

workAttemptForWorker

readonly workAttemptForWorker: (worker) => WorkAttempt | null

Parameters

worker

Returns

WorkAttempt | null

processRequirements

readonly processRequirements: (definition, station) => ProcessRequirements

Parameters

definition

string

station

GameCommandAvailability

Returns

ProcessRequirements

entityMembership

readonly entityMembership: (ids) => readonly boolean[]

Parameters

ids

readonly EntityId[]

Returns

readonly boolean[]

advanceCandidate

readonly advanceCandidate: (delta, writes, actions, options?) => AdvanceResult

Region-owned disposable attempt only: an error requires discarding the candidate.

Parameters

delta

number

writes

readonly WriteIntent[]

actions

readonly ScopedAction[]

options?

creates?

readonly ScopedCreate[]

removes?

readonly ScopedRemove[]

retires?

readonly EntityId[]

crowd?

readonly CrowdMotion[]

Returns

AdvanceResult

advance

readonly advance: (delta, writes, actions, options?) => AdvanceResult

Parameters

delta

number

writes

readonly WriteIntent[]

actions

readonly ScopedAction[]

options?

creates?

readonly ScopedCreate[]

removes?

readonly ScopedRemove[]

retires?

readonly EntityId[]

crowd?

readonly CrowdMotion[]

Returns

AdvanceResult

snapshot

readonly snapshot: () => KernelRecordSnapshot

Returns

KernelRecordSnapshot

capture

readonly capture: () => KernelRecordCaptureResult

Resident-only capture; do not mutate or expose its borrowed record bytes.

Returns

KernelRecordCaptureResult

acceptCapture

readonly acceptCapture: () => void

Called only after the Region transaction accepted the captured state.

Returns

void

restore

readonly restore: (snapshot) => void

Parameters

snapshot

KernelRecordSnapshot

Returns

void

renderFacts

readonly renderFacts: (limit?) => readonly RenderFact[]

Parameters

limit?

number

Returns

readonly RenderFact[]

worldPoses

readonly worldPoses: (entities) => readonly WorldPose[]

Parameters

entities

readonly EntityId[]

Returns

readonly WorldPose[]

GamePack

Properties

id

readonly id: string

version

readonly version: number

localScope?

readonly optional localScope?: CommandScope

localPartyBinding?

readonly optional localPartyBinding?: string

The instantiate-actors binding that seats the local player’s party (from players.local.bootstrap): the local “party” event and a per-viewer directControl: { person } resolve from it.

interest?

readonly optional interest?: object

A player viewer’s observation carries only render facts, presentation facts and cues within this many metres (xz distance) of an actor that viewer owns (see sdk/party ownedActorIds). Unset: unfiltered, as today. Mirrors page.interest.

radius

readonly radius: number

definition

readonly definition: Uint8Array

environmentDefinition?

readonly optional environmentDefinition?: Uint8Array<ArrayBufferLike>>

presentationWindow?

readonly optional presentationWindow?: object

minX

readonly minX: number

maxX

readonly maxX: number

minZ

readonly minZ: number

maxZ

readonly maxZ: number

terrainPresentation?

readonly optional terrainPresentation?: TerrainPresentationDefinition

Game-authored terrain vocabulary. The engine owns no grass or biome IDs.

components

readonly components: readonly ComponentDefinition<any>>[]

visualVariants?

readonly optional visualVariants?: readonly VisualVariantRule[]

Resolved into render facts; never written to the kernel or its digest.

actors?

readonly optional actors?: readonly ActorDefinition[]

Prepared content templates; native lifecycle owns their instantiation.

systems

readonly systems: readonly SystemDefinition[]

horde?

readonly optional horde?: HordeSimulation

presentation?

readonly optional presentation?: GamePresentation

bootstrapActions?

readonly optional bootstrapActions?: readonly ActionRequest[]

Fresh-world setup that must commit before the first player command.

opening?

readonly optional opening?: object

A fresh local world’s story start, played only when the session opts in: host actions (spawned scenery, say), then the local player’s commands (a pre-marked tree).

actions

readonly actions: readonly ActionRequest[]

commands

readonly commands: readonly object[]

initialActions?

readonly optional initialActions?: readonly ActionRequest[]

scenarios?

readonly optional scenarios?: Readonly<Record<string, GameScenario>>>>

Dev and test scenarios: a fresh local world started with one of these ids plays its host actions after the initial actions, then queues its commands. Worlds started without a scenario never see them.

partyJoin?

readonly optional partyJoin?: Readonly<{ footprint: readonly readonly [number, number][]; prepare: (spawn) => ActorInstantiationPlan; }>

commands?

readonly optional commands?: Readonly<Record<string, GameCommandDefinition>>>>

Heterogeneous command inputs are erased at the pack registry boundary.

persistentCharacters?

readonly optional persistentCharacters?: (context) => number

Persistent characters living in this world right now (a player’s, or an AI stand-in’s), read from committed state. The hosted engine keeps an always-ticking world’s clock self-renewing while this is greater than zero, so offline characters stay in danger; at zero the world may rest after an idle grace window. A pack that omits this never keeps a world ticking on character count alone.

Parameters

context

Pick<ReadContext, "query">

Returns

number

GameScenario

A named dev/test setup for a fresh world (see GamePack.scenarios).

Properties

actions

readonly actions: readonly ActionRequest[]

commands

readonly commands: readonly object[]

GameCommandResult

Properties

actions

readonly actions: readonly ActionRequest[]

writes

readonly writes: readonly WriteIntent[]

creates?

readonly optional creates?: readonly EntityRecord[]

removes?

readonly optional removes?: readonly EntityId[]

GameCommandDefinition

Properties

input

readonly input: ZodType

The sole parser for input entering this command.

title

readonly title: string

Semantic metadata shared by human and agent projections.

description

readonly description: string

localPresentation?

readonly optional localPresentation?: object

Client-local acquisition metadata for the existing Vishnu gestures.

bindings

readonly bindings: readonly Readonly<{ id: string; label: string; detail?: string; selection?: "entities" | Readonly<{ field: string; cardinality: "one"; }>; target?: "actor" | "terrain-cell" | "terrain-area" | "world-surface" | "world-edge"; component?: `${string}.${string}`; designation?: readonly ("entities" | "point" | "line" | "rectangle" | "edge-line")[]; footprint?: readonly readonly [number, number][]; placement?: "action-bar"; key?: string; preset?: JsonValue; }>[]

availability?

readonly optional availability?: (context) => GameCommandAvailability

Host-owned discoverability state, evaluated against the committed world.

Parameters

context

Pick<ReadContext, "query">

Returns

subjects?

readonly optional subjects?: (context) => readonly EntityId[]

Stable subjects for contextual UI projection, evaluated from authoritative state.

Parameters

context

Pick<ReadContext, "query">

Returns

readonly EntityId[]

lifecycle?

readonly optional lifecycle?: readonly ComponentDefinition<any>>[]

Authored record creation/removal only; does not grant progress writes.

reads?

readonly optional reads?: readonly ComponentDefinition<any>>[]

writes

readonly writes: readonly ComponentDefinition<any>>[]

invoke

readonly invoke: (context, input) => GameCommandResult

Erased invocation closes over the parsed handler input in the authoring factory.

Parameters

context

GameCommandContext

input

JsonValue | undefined

Returns

GameCommandResult

GamePackTransport

Properties

id

readonly id: string

version

readonly version: number

definition

readonly definition: Uint8Array

FeedbackSwing

A weapon trail on the world plane. Direction is normalized at intake; angle is the full sweep in radians and height is above the cue’s anchor. This draws contact intent; collision and damage remain simulation-owned.

Properties

direction

readonly direction: object

x

readonly x: number

z

readonly z: number

radius

readonly radius: number

angle

readonly angle: number

height

readonly height: number

ms

readonly ms: number

color

readonly color: string

SystemOptions

Properties

id

id: `${string}.${string}`

version

version: number

reads?

optional reads?: readonly ComponentDefinition<any>>[]

writes?

optional writes?: readonly ComponentDefinition<any>>[]

every?

optional every?: number

consumesImpacts?

optional consumesImpacts?: boolean

run

run: (context) => void

Parameters

context

WriteContext

Returns

void

ActorCapability

Properties

component

readonly component: ComponentDefinition<any>>

initial?

readonly optional initial?: object

ActorDefinitionCapability

Authoring-only capability compiled by an owning engine module.

Type Parameters

T

T extends object

Properties

kind

readonly kind: "actor-definition-capability"

id

readonly id: `${string}.${string}`

schema

readonly schema: ZodType<T>>

The sole parser for this capability’s authored value.

externalCreation?

readonly optional externalCreation?: boolean

Another owner creates this actor; omit it from direct spawn templates.

ActorDefinitionCapabilityValue

Properties

capability

readonly capability: ActorDefinitionCapability<any>>

value

readonly value: object

ActorInput

Properties

kind

readonly kind: "actor-input"

name

readonly name: string

type

readonly type: FieldType | "actor-reference"

ActorDefinition

Extends

ActorBuilder

Properties

id

readonly id: string

version

readonly version: number

capabilities

readonly capabilities: readonly ActorCapability[]

definitionCapabilities

readonly definitionCapabilities: readonly ActorDefinitionCapabilityValue[]

behaviors

readonly behaviors: readonly BehaviorDefinition[]

Methods

with()

Call Signature

with<T>>(component, initial?): ActorDefinition

Type Parameters

T

T extends object

Parameters

component

initial?

ActorInitial<T>

Returns

Inherited from

ActorBuilder.with

Call Signature

with<T>>(capability, value): ActorDefinition

Type Parameters

T

T extends object

Parameters

capability

ActorDefinitionCapability<T>

value

T

Returns

Inherited from

ActorBuilder.with

behaves()

behaves(…behaviors): ActorDefinition

Parameters

behaviors

…readonly BehaviorDefinition[]

Returns

BehaviorActionDefinition

Inherited from

ActorBuilder.behaves

PredicateDefinition

A named, deterministic question used by an authored behavior branch.

Properties

id

readonly id: `${string}.${string}`

reads

readonly reads: readonly ComponentDefinition<any>>[]

facts

readonly facts: readonly NativeFact[]

test

readonly test: (subject, context) => boolean

Parameters

subject

QueryRow

context

ReadContext

Returns

boolean

BehaviorActionDefinition

A named proposal producer. The existing system/session owners commit its work.

Properties

id

readonly id: `${string}.${string}`

reads

readonly reads: readonly ComponentDefinition<any>>[]

writes

readonly writes: readonly ComponentDefinition<any>>[]

facts

readonly facts: readonly NativeFact[]

exclusive?

readonly optional exclusive?: string

run

readonly run: (subject, context) => void

Parameters

subject

QueryRow

context

WriteContext

Returns

void

BehaviorDefinition

A prepared actor behavior. It is not a system: pack preparation installs it once for every actor that attaches it (installActorBehaviors).

Properties

kind

readonly kind: "behavior"

id

readonly id: `${string}.${string}`

version

readonly version: number

every?

readonly optional every?: number

consumesImpacts?

readonly optional consumesImpacts?: true

Whether its predicates and actions read the step’s projectile impacts.

subjects

readonly subjects: readonly ComponentDefinition<any>>[]

Components every attaching actor must carry.

BehaviorSelection

Methods

where()

where(…predicates): BehaviorSelection

Parameters

predicates

…readonly PredicateDefinition[]

Returns

BehaviorSelection

do()

do(action): void

Parameters

action

Returns

void

BehaviorScene

Methods

find()

find(…subjects): BehaviorSelection

Parameters

subjects

…readonly ComponentDefinition<any>[]

Returns

BehaviorSelection

BehaviorOptions

Properties

version?

readonly optional version?: number

every?

readonly optional every?: number

Run every n-th step instead of every step.

consumesImpacts?

readonly optional consumesImpacts?: boolean

Let its predicates and actions read context.impacts: the projectile impacts committed since this behavior last ran (a round hitting a body, a ball striking a hull). Each impact reaches the behavior once. Off by default, so a behavior that never asks sees no impacts.

ActorBuilder

Extended by

ActorDefinition

Methods

with()

Call Signature

with<T>>(component, initial?): ActorDefinition

Type Parameters

T

T extends object

Parameters

component

initial?

ActorInitial<T>

Returns

Call Signature

with<T>>(capability, value): ActorDefinition

Type Parameters

T

T extends object

Parameters

capability

ActorDefinitionCapability<T>

value

T

Returns

behaves()

behaves(…behaviors): ActorDefinition

Parameters

behaviors

…readonly BehaviorDefinition[]

Returns

BlueprintOpening

One opening on a module’s side; at counts cells along that side. style names the game’s own variant of it (a barred cell door), over the side’s style.

Properties

side

readonly side: BlueprintSide

at

readonly at: number

kind

readonly kind: BlueprintOpeningKind

style?

readonly optional style?: string

BlueprintModule

One room: size is [width along x, depth along z] in cells.

Properties

id

readonly id: string

size

readonly size: readonly [number, number]

openings

readonly openings: readonly BlueprintOpening[]

slots

readonly slots: Readonly<Record<string, readonly [number, number]>>

Named cells inside the room ([x, z] from its north-west corner) a game fills with containers, fixtures or actors.

sides

readonly sides: Readonly<Partial<Record<BlueprintSide, string>>>>>>

A style for every piece on a side (bars along a cell’s front): the game maps each style to its own buildables (compileBlueprint).

BlueprintPlacement

A module placed in a recipe: its north-west corner at at, then turned rotate quarter turns clockwise and mirrored east-west if asked.

Properties

module

readonly module: BlueprintModule

at

readonly at: readonly [number, number]

rotate?

readonly optional rotate?: 0 | 1 | 2 | 3

mirror?

readonly optional mirror?: boolean

BlueprintRecipe

Properties

modules

readonly modules: readonly BlueprintPlacement[]

BlueprintPiece

One wall, door or window: the face after cell along axis, in the style a room gave it (absent: the plain piece).

Properties

kind

readonly kind: "wall" | "window" | "door"

cell

readonly cell: readonly [number, number]

axis

readonly axis: "x" | "z"

style?

readonly optional style?: string

BlueprintFloor

One room cell covered by the kit’s floor buildable.

Properties

kind

readonly kind: "floor"

cell

readonly cell: readonly [number, number]

BlueprintRoom

Properties

index

readonly index: number

Index into the recipe’s modules.

module

readonly module: string

cells

readonly cells: readonly readonly [number, number][]

Its cells in the world, sorted.

BlueprintSlot

Properties

room

readonly room: number

module

readonly module: string

name

readonly name: string

at

readonly at: readonly [number, number]

Blueprint

An assembled building: its pieces, rooms and slots, in a fixed order.

Properties

pieces

readonly pieces: readonly BlueprintPiece[]

rooms

readonly rooms: readonly BlueprintRoom[]

slots

readonly slots: readonly BlueprintSlot[]

ConstructionOptions

Properties

buildables

readonly buildables: readonly ActorDefinition[]

Buildable actors, in build-bar order.

verticalMetres

readonly verticalMetres: number

Metres per vertical cell of the world these structures stand in.

namespace

readonly namespace: string

Id prefix for construction sites and floor replacements.

party

readonly party: (context) => EntityId

The party a player’s build command plans for.

Parameters

context

Pick<GameCommandContext, "query" | "scope">

Returns

restyle?

readonly optional restyle?: (context) => ReadonlyMap<EntityId, string>>

State-dependent art for particular sites (a lit hearth, say).

Parameters

context

Pick<ReadContext, "query" | "environmentFacts">

Returns

ReadonlyMap<EntityId, string>

ConstructionVisual

One staged construction sprite, ready for the visual projection.

Properties

id

readonly id: EntityId

cutawayTop

readonly cutawayTop: number

visual

readonly visual: string

label

readonly label: string

pickable

readonly pickable: true

placement?

readonly optional placement?: { kind: "edge"; edge: { cell: readonly [number, number, number]; axis: "x" | "z"; }; } | NonNullable<PlacementDatum | undefined> & { readonly orientation: CardinalOrientation; }

pose

readonly pose: object

position

readonly position: object

position.x

readonly x: number

position.y

readonly y: number

position.z

readonly z: number

facing

readonly facing: number

Construction

Everything the Construction extension derives from its buildables.

Properties

buildables

readonly buildables: readonly ActorDefinition[]

catalog

readonly catalog: ReadonlyMap<string, CompiledBuildable>>

placement

readonly placement: Readonly<Record<string, PlacementPresentation>>>>

Placement ghost art and facing per catalog id.

candidates

readonly candidates: (input) => readonly PlacementCandidate[]

Parameters

input

catalog

string = ...

orientation?

"north" | "east" | "south" | "west" = ...

target

{ cell: [number, number, number]; } | { area: { start: [number, number, number]; end: [number, number, number]; }; } | { edges: object[]; } = ...

Returns

readonly PlacementCandidate[]

build

readonly build: GameCommandDefinition

visuals

readonly visuals: (context) => readonly ConstructionVisual[]

Staged art from the site’s catalog and phase alone.

Parameters

context

Pick<ReadContext, "query">

Returns

readonly ConstructionVisual[]

presented

readonly presented: (context) => readonly ConstructionVisual[]

Staged art with the cartridge’s state-dependent restyling applied.

Parameters

context

Pick<ReadContext, "query" | "environmentFacts">

Returns

readonly ConstructionVisual[]

environment

readonly environment: (base) => EnvironmentDefinition

Add the buildables to a world’s structure catalog.

Parameters

base

EnvironmentDefinition

Returns

EnvironmentDefinition

VisualBinding

One sprite id’s art: a static art-bank frame, a bank figure, or a rigged paper doll. Data only; the client checks it when it draws.

Properties

kind

readonly kind: "static" | "figure" | "doll"

worldRole

readonly worldRole: "actor" | "floor" | "item" | "structure"

variants?

readonly optional variants?: Readonly<{ component: ComponentDefinition<any>>; field: string; cases: Readonly<Record<string, string>>>>; }>

Select another declared sprite from one committed authored field. An absent or unmapped value keeps this binding.

path?

readonly optional path?: BankPath

Static: the bank path, per-turn view paths, frames and anchor.

viewPaths?

readonly optional viewPaths?: readonly BankPath[]

frames?

readonly optional frames?: boolean

frameMs?

readonly optional frameMs?: number

Static frames: milliseconds per frame (default: the shared idle rate).

facing?

readonly optional facing?: boolean

anchor?

readonly optional anchor?: "pawnAnchor" | "propAnchor" | "vehicleAnchor"

drawsUpright?

readonly optional drawsUpright?: boolean

Order as an upright body rather than by its footprint.

key?

readonly optional key?: string

Figure: the bank figure key.

dollPoses?

readonly optional dollPoses?: Readonly<Record<string, Readonly<{ clip: string; held?: string; last?: boolean; }>>>

Doll: each pose’s paper-doll clip, and the item it holds meanwhile. walk and idle choose the gait clips (default: the clips of those names), so a cast can shamble or crawl. last holds the clip’s last frame instead of playing it (a body that has fallen and lies still).

motion?

readonly optional motion?: Readonly<{ kind: string; stride: number; localOffset?: Readonly<{ x: number; y: number; z: number; }>; }>

workPoses?

readonly optional workPoses?: Readonly<Record<string, string>>>>

gaitStride?

readonly optional gaitStride?: number

Doll: metres per gait step, so a walk or run cycle follows the ground covered (no foot sliding at any speed). Defaults to motion.stride.

actPoses?

readonly optional actPoses?: Readonly<Record<string, Readonly<{ clip: string; held?: string; }>>>

Doll: the clip for each one-shot act state (the presentation’s acts, such as a swing or a shot), played once over any gait.

deliveryPoses?

readonly optional deliveryPoses?: Readonly<Record<string, string>>>>

luminous?

readonly optional luminous?: Readonly<{ path: BankPath; }>

Static: self-lit art (flames, sparks, smoke) at path, drawn with the same facing, frames and anchor above the graded world, so a night mood never darkens or requantizes it. View only.

light?

readonly optional light?: Readonly<{ radius: number; color: number; flicker: number; }>

A view-only point light centered on this visual; never enters world state.

carryPoses?

readonly optional carryPoses?: Readonly<Record<string, string | Readonly<{ contentKind: string; empty: string; partial: string; full: string; }>>>

reactions?

readonly optional reactions?: Readonly<Record<string, Readonly<{ path: BankPath; duration: number; }>>>

edgeWall?

readonly optional edgeWall?: Readonly<{ kind: "segment"; stage: string; axis: "x" | "z"; junction: string; }>

A wall-like edge segment and the junction art its corners use.

CartridgeArtPackFiles

One checked cartridge art pack’s files, as bundler-resolved URLs (a build renames every file, so the pack names each page’s URL).

Properties

manifestUrl

readonly manifestUrl: string

pageUrls

readonly pageUrls: Readonly<Record<string, string>>>>

CartridgeShelf

How the hub shelf lists a cartridge. Presentation only.

Properties

order

readonly order: number

Lower numbers appear first. Games own their position, not the engine.

genre

readonly genre: string

blurb

readonly blurb: string

cover

readonly cover: object

src

readonly src: string

alt

readonly alt: string

SelectionCard

A selected object whose visual starts with visualPrefix gets its own named card in the selection panel.

Properties

visualPrefix

readonly visualPrefix: string

heading

readonly heading: string

note?

readonly optional note?: string

CartridgeAim

Aiming on the page, twin-stick style. pointer: a plain click on the world sends command with { at: { x, z } } (the clicked actor, or the ground at the direct-control actor’s height). arrows: a held arrow key sends { toward: { x, z } } (up is north) at once, then every repeatSeconds (default 0.25) while held, and arrows stop moving the direct-control actor. A gamepad’s right stick aims the same way, and its left stick drives the direct-control actor. hold: a held aim is a lease the game keeps firing on at its own cadence: each send is { toward: { x, z }, held: true }, and letting go sends { release: true }. The command decides what each one does.

Properties

command

readonly command: string

pointer?

readonly optional pointer?: boolean

arrows?

readonly optional arrows?: boolean

repeatSeconds?

readonly optional repeatSeconds?: number

hold?

readonly optional hold?: boolean

CartridgePage

What the player shell shows around the world. Read-only presentation.

Properties

subtitle

readonly subtitle: string

camera

readonly camera: CartridgeCameraPolicy

directControl?

readonly optional directControl?: CartridgeDirectControl

aim?

readonly optional aim?: CartridgeAim

accent?

readonly optional accent?: "moss" | "ember" | "tide"

The game’s accent over the shared game theme (default “moss”).

controlHelp?

readonly optional controlHelp?: string

dockKeys?

readonly optional dockKeys?: boolean

Show the persistent dock keys. Palettes and keyboard commands remain available.

audioBank?

readonly optional audioBank?: Readonly<{ samples: Readonly<Record<string, Readonly<{ urls: readonly string[]; gain: number; priority: number; }>>>; maxVoices?: number; }>

Sampled sounds under the shared audio owner, selected by feedback name.

lighting?

readonly optional lighting?: Readonly<{ sources?: readonly Readonly<{ visual: string; moods?: readonly ("day" | "dusk" | "night")[]; light: Readonly<{ radius: number; color: number; intensity: number; height: number; kind: "point"; }> | Readonly<{ radius: number; color: number; intensity: number; height: number; kind: "cone"; angle: number; }>; }>[]; occluders?: readonly Readonly<{ visual: string; height: number; }>[]; pulses?: readonly Readonly<{ cue: string; light: Readonly<{ radius: number; color: number; intensity: number; height: number; kind: "point"; }> | Readonly<{ radius: number; color: number; intensity: number; height: number; kind: "cone"; angle: number; }>; ms: number; }>[]; }>

Declared, view-only world lights and opaque construction states.

developerControls?

readonly optional developerControls?: boolean

Show the engine’s pixel-quality, voxel-layer and cutaway tools (default true). A finished game turns them off.

emptyDrag?

readonly optional emptyDrag?: "pan" | "select"

What a plain left drag that starts on empty ground does: box-select (the default) or pan the camera. Shift+drag always box-selects.

orderCommand?

readonly optional orderCommand?: string

The command a drafted selection’s secondary click issues.

selectionShortcuts?

readonly optional selectionShortcuts?: readonly object[]

windows

readonly windows: readonly CartridgeWindow[]

Declared game windows, opened by ui:<id> commands.

source?

readonly optional source?: string

Where the page links “View TypeScript source”.

visuals?

readonly optional visuals?: Readonly<Record<string, VisualBinding>>>>

The art for this cartridge’s sprite ids, merged over the engine’s.

artPacks?

readonly optional artPacks?: readonly CartridgeArtPackFiles[]

Its own checked art packs (each the pack.ts module the art baker, scripts/export-cartridge-art.mjs, writes); its visuals point into them by root.

icons?

readonly optional icons?: Readonly<Record<string, string>>>>

The page’s UI icons by key (inventory item art, say): window blocks name an icon by key, and the browser resolves it here, so a hosted world’s server never sends a file path.

effectArt?

readonly optional effectArt?: object

The art pack feedback cues draw from (splats, flashes, casings, bits, words): a cue names frames of it by bank path (art), and each frame lands on its world point by the pack’s anchors (the manifest’s anchors, or a separate anchorsUrl in the same contract). Without it, cues draw the view’s own placeholders.

pack

readonly pack: CartridgeArtPackFiles

anchorsUrl?

readonly optional anchorsUrl?: string

dolls?

readonly optional dolls?: Readonly<Record<string, URL>>>>

Its cast’s paper-doll pack: the pack.ts module the doll baker (scripts/export-paper-doll-art.mjs) writes beside the pack’s files.

spectator3d?

readonly optional spectator3d?: () => Promise<{ cast: Cast; heads: Readonly<Record<string, HeadBuilder>>>>; propScene?: (visual) => Scene<Object3DEventMap> > | null; }>

Loads authored live rig geometry only for an opted-in 3D spectator.

Returns

Promise<{ cast: Cast; heads: Readonly<Record<string, HeadBuilder>>; propScene?: (visual) => Scene<Object3DEventMap> | null; }>

shelf?

readonly optional shelf?: CartridgeShelf

selectionCards?

readonly optional selectionCards?: readonly SelectionCard[]

gainFeedbackFactPrefixes?

readonly optional gainFeedbackFactPrefixes?: readonly string[]

Inventory owners whose item gains are player-facing. Other stock changes (such as a ship’s ammunition locker) never produce floating gain labels.

sharedWorlds?

readonly optional sharedWorlds?: boolean

The hosted engine serves invitation-shared worlds for this cartridge.

clock?

readonly optional clock?: "always"

How a hosted world’s clock runs. "always": while the world is open it keeps ticking with nobody connected (offline characters stay in danger, the town keeps living). Default: it rests shortly after the last player leaves.

sharedClock?

readonly optional sharedClock?: "owner"

Who may pause and step a shared hosted world’s clock. "owner": the world’s owner (the principal who created its invitation) may pause and steer it; other participants cannot. Unset: nobody in a shared world may control the clock (it runs on its own schedule). Ignored outside a shared world (sharedWorlds); a personal hosted world’s own player always controls its clock regardless of this field.

interest?

readonly optional interest?: object

The first distance-based interest cut: a player viewer’s observation carries only render facts, presentation facts and cues within radius metres (xz distance) of their own actors. A player with no drawn actor (dead, or not yet spawned) sees around where their actors last stood, else their spawn marker, else nothing: never the whole world, which a waiting player could scout and relay to friends. Only the host and a granted spectator (spectators) see everything. Terrain, whistle and windows are unaffected.

radius

readonly radius: number

spectators?

readonly optional spectators?: true

The world grants a spectator role: players may mint read-only spectator links, and spectators see the whole world. Unset, a hosted world has no spectators at all.

placementVisuals?

readonly optional placementVisuals?: Readonly<Record<string, PlacementPresentation>>>>

Placement ghosts and candidates for build gestures, derived from the cartridge’s construction extension.

placementCandidates?

readonly optional placementCandidates?: (input) => readonly PlacementCandidate[]

Parameters

input

catalog

string = ...

orientation?

"north" | "east" | "south" | "west" = ...

target

{ cell: [number, number, number]; } | { area: { start: [number, number, number]; end: [number, number, number]; }; } | { edges: object[]; } = ...

Returns

readonly PlacementCandidate[]

look

readonly look: Look

The checked look: full colour, or a palette the view constrains to.

terrainLandform?

readonly optional terrainLandform?: EnvironmentPlateau

Authored floating plateau shape for the smooth terrain view.

terrainSea?

readonly optional terrainSea?: Readonly<{ bounds: EnvironmentBounds; seaLevel: number; shore: EnvironmentPlateau; }>

Admitted sea extent and shore for the terrain’s visual water surface.

CartridgeSpec

Properties

id

readonly id: string

Kebab-case identity; also the namespace for saves and URLs.

title

readonly title: string

version

readonly version: number

Bump when saved worlds can no longer restore with this content.

actors?

readonly optional actors?: readonly ActorDefinition[]

Spawnable templates. Their .behaves() attachments are installed once.

components?

readonly optional components?: readonly ComponentDefinition<any>>[]

Components used by commands, rules or the world. Authored components on the actors are collected automatically.

world

readonly world: object

materials

readonly materials: readonly object[]

stockpileProfiles?

readonly optional stockpileProfiles?: readonly object[]

terrain?

readonly optional terrain?: TerrainChoice

presentationWindow?

readonly optional presentationWindow?: object

presentationWindow.minX

readonly minX: number

presentationWindow.maxX

readonly maxX: number

presentationWindow.minZ

readonly minZ: number

presentationWindow.maxZ

readonly maxZ: number

characters?

readonly optional characters?: Characters

Rigged characters: appearance, wardrobe commands, dismemberment.

horde?

readonly optional horde?: HordeSimulation

Batched autonomous movement, independent of player action admission.

construction?

readonly optional construction?: Construction

Buildables: adds their structures, the build command and placement.

scene?

readonly optional scene?: readonly Placement[]

The fresh world: actors placed on the ground. Placed actors are also spawnable templates.

rules?

readonly optional rules?: readonly SystemDefinition[]

World-level systems. Actor behavior belongs on .behaves().

commands?

readonly optional commands?: Readonly<Record<string, GameCommandDefinition>>>>

seats?

readonly optional seats?: SeatDefinition

Goals, command grants and world view available to any authorized seat.

presentation?

readonly optional presentation?: GamePresentation

persistentCharacters?

readonly optional persistentCharacters?: (context) => number

Persistent characters living in this world right now (a player’s, or an AI stand-in’s), read from committed state. Declare this for a page.clock "always" cartridge so its hosted world’s clock keeps self-renewing while a character is present, and can rest once none remain.

Parameters

context

Pick<ReadContext, "query">

Returns

number

initialActions?

readonly optional initialActions?: readonly ActionRequest[]

Fresh-world setup (host spawns, say), committed when the world is born, before its first step, so a world waiting on its title shows its start. Every action must be accepted.

scenarios?

readonly optional scenarios?: Readonly<Record<string, { actions?: readonly ActionRequest[]; commands?: readonly object[]; }>>

Dev and test scenarios, by id: a fresh local world opened with ?scenario=<id> plays the scenario’s host actions after the initial actions, then its commands, as if the player gave them. A proof uses one to stage a moment (a zombie at the door) without the game checking for tests. Worlds started without a scenario never see them.

players?

readonly optional players?: object

join

readonly join: PartyJoinCapability

shared?

readonly optional shared?: object

A hosted shared world’s own setup, after initialActions and never in browser-local play (seats that stand-ins fill while players are missing, say).

shared.initialActions?

readonly optional initialActions?: readonly ActionRequest[]

shared.features?

readonly optional features?: Readonly<Partial<Record<"minded-seats", readonly ActionRequest[]>>>

Setups the host adds to a new shared world only while one of its engine features is switched on (minded-seats: players may hand their character to something that plays it for them while they are away; a host switch), after initialActions.

local

readonly local: object

Browser-local play: the local player’s scope and fresh-world setup.

local.scope

readonly scope: CommandScope

local.bootstrap

readonly bootstrap: readonly ActionRequest[]

local.opening?

readonly optional opening?: object

A fresh player world’s story start: host actions (spawned scenery), then commands the player “has already given”.

local.opening.actions?

readonly optional actions?: readonly ActionRequest[]

local.opening.commands?

readonly optional commands?: readonly object[]

page

readonly page: Omit<CartridgePage, "placementVisuals" | "placementCandidates" | "windows" | "look">>

ui?

readonly optional ui?: object

Small game windows (Mosaico frames styled by Caps), each with a Whistle command.

windows?

readonly optional windows?: readonly CartridgeWindow[]

mood?

readonly optional mood?: (world) => "day" | "dusk" | "night"

The light the world is shown in, read from committed state on every presentation (a game clock that is not simulation time, say). When given it replaces look.moods; it never changes the simulation.

Parameters

world

WindowWorld

Returns

"day" | "dusk" | "night"

look?

readonly optional look?: LookSpec

An optional palette constraint and mood. Omit it for full colour.

Cartridge

The checked, compiled cartridge. The only thing the Worker, page and host accept.

Properties

id

readonly id: string

title

readonly title: string

version

readonly version: number

pack

readonly pack: GamePack

Browser-local pack: the local player joins at world start.

hostPack

readonly hostPack: GamePack

Shared-world pack for the hosted engine: players join by command.

page

readonly page: CartridgePage

seats?

readonly optional seats?: SeatDefinition

sharedFeatures?

readonly optional sharedFeatures?: Readonly<Partial<Record<"minded-seats", readonly ActionRequest[]>>>

A shared world’s feature-gated setups (players.shared.features).

dismemberment?

readonly optional dismemberment?: object

Which cuts can come off and how the stump looks, when characters are on.

severable

severable: string[]

gore

gore: "moss" | "classic" | "off"

cast?

readonly optional cast?: Cast

The cartridge’s own cast, when characters are on; its paper-doll pack is page.dolls. The engine’s cast tools find a cast only here.

SceneEntity

Properties

id

readonly id: EntityId

components

readonly components: Readonly<Record<string, ComponentFields>>>>

CompiledBuildable

Properties

definition

readonly definition: EnvironmentStructureDefinition

placement

readonly placement: object

alignment

alignment: "fixed" | "stroke"

facing?

optional facing?: object

facing.north

north: number

facing.east

east: number

facing.south

south: number

facing.west

west: number

name

readonly name: string

sprites

readonly sprites: string

key?

readonly optional key?: string

palette?

readonly optional palette?: false

Set when players may not plan it (the definition’s palette).

ConstructionPlanOptions

Properties

party

readonly party: EntityId

definition

readonly definition: EnvironmentStructureDefinition

candidates

readonly candidates: readonly PlacementCandidate[]

existingSites

readonly existingSites: readonly EntityId[]

floorOperations

readonly floorOperations: (requests) => readonly FloorOperation[]

Parameters

requests

readonly object[]

Returns

readonly FloorOperation[]

replacementGenerations

readonly replacementGenerations: ReadonlyMap<EntityId, number>>

replacementId

readonly replacementId: (floor, generation) => EntityId

Parameters

floor

generation

number

Returns

AnchoredFeedback.height

ConstructionSiteState

Properties

catalog

catalog: string

targetKind

targetKind: "cell" | "edge"

targetX

targetX: number

targetY

targetY: number

targetZ

targetZ: number

targetDirection

targetDirection: "x" | "z" | CardinalOrientation

seconds

seconds: number

phase

phase: "working" | "planned" | "finished"

Diagnostic

Properties

code

readonly code: "VD001" | "VD002" | "VD003" | "VD004" | "VD005" | "VD006" | "VD007" | "VD008" | "VD009" | "VD010" | "VD011" | "VD012" | "VD013" | "VD014" | "VD015" | "VD016" | "VD017" | "VD020" | "VD021" | "VD022" | "VD023" | "VD024" | "VD025" | "VD030" | "VD031" | "VD032" | "VD033" | "VD034" | "VD040" | "VD041" | "VD050" | "VD051" | "VD052" | "VD060" | "VD061" | "VD070" | "VD071" | "VD072" | "VD073" | "VD074" | "VD080" | "VD083" | "VD082" | "VD081"

message

readonly message: string

One sentence naming the author’s ids, never engine internals.

hint

readonly hint: string

The fix, as an instruction.

path

readonly path: readonly (string | number)[]

Where in the cartridge spec, when known: ["scene", 3].

Effect

Type Parameters

T

T extends object

Properties

component

readonly component: ComponentDefinition<T & object>>

The record component (add it to the producing behavior’s writes).

Methods

emit()

emit(context, key, value, at): void

Record one effect at world time at; key (unique among one step’s records) and the time make its id.

Parameters

context

Pick<WriteContext, "createAuthoredEntity">

key

string

value

T

at

number

Returns

void

all()

all(context): T & object[]

Every live record, oldest first.

Parameters

context

Pick<ReadContext, "query">

Returns

T & object[]

since()

since(context, seen): T & object[]

Records newer than seen (a consumer’s marker), oldest first.

Parameters

context

Pick<ReadContext, "query">

seen

number

Returns

T & object[]

sweep()

sweep(context, now, keep): void

Remove records older than keep seconds (the producer only).

Parameters

context

Pick<ReadContext, "query"> & Pick<WriteContext, "removeAuthoredEntity">

now

number

keep

number

Returns

void

FeedbackStrength

A bounded response to contact strength; no simulation clock or RNG.

Properties

base

readonly base: number

perDamage?

readonly optional perDamage?: number

damageDivisor?

readonly optional damageDivisor?: number

killBonus?

readonly optional killBonus?: number

min

readonly min: number

max

readonly max: number

AnchoredFeedback

Extended by

ShotFeedback

Properties

height

readonly height: number

cue

readonly cue: AuthoredFeedbackCue

ShotFeedback

Extends

AnchoredFeedback

Properties

height

readonly height: number

Inherited from

cue

readonly cue: AuthoredFeedbackCue

Inherited from

AnchoredFeedback.cue

forward

readonly forward: number

recoil

readonly recoil: number

muzzleArt?

readonly optional muzzleArt?: readonly FeedbackArtPath[]

SwingFeedback

Properties

cue

readonly cue: AuthoredFeedbackCue

radius

readonly radius: number

angle

readonly angle: number

height

readonly height: number

ms

readonly ms: number

color

readonly color: string

ContactFeedback

Properties

height

readonly height: number

heavyDamage

readonly heavyDamage: number

ranged

readonly ranged: AuthoredFeedbackCue

melee

readonly melee: AuthoredFeedbackCue

heavy

readonly heavy: AuthoredFeedbackCue

kill

readonly kill: AuthoredFeedbackCue

headKill

readonly headKill: AuthoredFeedbackCue

hitstop

readonly hitstop: FeedbackStrength

shake

readonly shake: FeedbackStrength

slowMotion

readonly slowMotion: object

scale

readonly scale: number

killMs

readonly killMs: number

headMs

readonly headMs: number

bits

readonly bits: object

regular

readonly regular: FeedbackBitsKind

gore

readonly gore: FeedbackBitsKind

art?

readonly optional art?: readonly FeedbackArtPath[]

count

readonly count: FeedbackStrength

spread

readonly spread: FeedbackStrength

rumble

readonly rumble: object

strong

readonly strong: FeedbackStrength

weak

readonly weak: number

hitMs

readonly hitMs: number

killMs

readonly killMs: number

SplatFeedback

Properties

cue

readonly cue: AuthoredFeedbackCue

size

readonly size: FeedbackStrength

minSize

readonly minSize: number

maxSize

readonly maxSize: number

art

readonly art: readonly object[]

Ordered size bands, each with shape variants and their quarter turns.

seed

readonly seed: object

x

readonly x: number

z

readonly z: number

FeedbackProfile

Type Parameters

Weapon

Weapon extends string = string

Simple

Simple extends string = string

Swing

Swing extends string = string

Properties

contact?

readonly optional contact?: ContactFeedback

shots?

readonly optional shots?: Readonly<Record<Weapon, ShotFeedback>>>>

swings?

readonly optional swings?: Readonly<Record<Swing, SwingFeedback>>>>

splat?

readonly optional splat?: SplatFeedback

wound?

readonly optional wound?: object

height

readonly height: number

bites

readonly bites: readonly AuthoredFeedbackCue[]

claw

readonly claw: AuthoredFeedbackCue

simple?

readonly optional simple?: Readonly<Record<Simple, AnchoredFeedback>>>>

FlowBarrier

A structure standing across a face, and how much it would take.

Properties

site

readonly site: string

cost

readonly cost: number

FlowGeometry

Navigation facts: blocked cells and weighted breakable edges are game data.

Properties

profile

readonly profile: string

radius

readonly radius: number

terrainRevision

readonly terrainRevision: number

Change when terrain heights/passability change. Static worlds use zero.

blocked

readonly blocked: ReadonlySet<string>>

occupied

readonly occupied: ReadonlySet<string>>

edges

readonly edges: ReadonlyMap<string, FlowBarrier>>

FlowNavigation

Methods

height()

height(cell): number | undefined

Parameters

cell

Returns

number | undefined

crossing()

crossing(from, to): FlowBarrier | "corner" | null

Parameters

from

to

Returns

FlowBarrier | "corner" | null

next()

next(goal, from): { to: FlowCell; barrier: FlowBarrier | null; } | null

Parameters

goal

from

Returns

{ to: FlowCell; barrier: FlowBarrier | null; } | null

HordeSlot

Properties

id

readonly id: string

x

readonly x: number

z

readonly z: number

reach

readonly reach: number

HordeSlotBody

Properties

id

readonly id: EntityId

x

readonly x: number

z

readonly z: number

eligible

readonly eligible: readonly string[]

HordeSlotAssignment

Properties

slot

readonly slot: HordeSlot

arrived

readonly arrived: boolean

LookSpec

How a cartridge looks. Everything is optional: a cartridge without a palette renders in full colour, exactly as the engine always has.

look: { palette: "glomzy-07" }                       // a built-in palette
look: { palette: { id: "two-tone", name: "Two Tone", colors: ["#0f380f", "#cadc9f"] } }
look: { palette: parseLospecPalette("sweetie-16", hexFileText), mood: "dusk" }

Properties

palette?

readonly optional palette?: string | Palette

A built-in palette id, or a palette (see parseLospecPalette in @fungi.computer/vishnu-pixel for Lospec exports).

dither?

readonly optional dither?: Partial<PaletteDither>>

Ordered dithering between palette neighbours; omit for the default.

mood?

readonly optional mood?: "day" | "dusk" | "night"

The mood a fresh world is shown in (default day).

moods?

readonly optional moods?: readonly MoodStop[]

Moods by committed world time: from each stop’s at (simulation seconds) the view shows its mood, before the first stop mood. Stops rise strictly. Presentation only: the simulation never reads it. moods: [{ at: 20, mood: "night" }, { at: 100, mood: "day" }]

ambientLight?

readonly optional ambientLight?: Readonly<Record<"day" | "dusk" | "night", number>>>>

View-only brightness levels keyed by the world’s chosen mood.

ambientTint?

readonly optional ambientTint?: Readonly<Record<"day" | "dusk" | "night", readonly [number, number, number]>>

View-only RGB light multipliers (0..1), independent of palette mapping.

terrain?

readonly optional terrain?: "voxel" | "smooth"

Render voxel cells as authored faces or a sculpted surface net.

backdrop?

readonly optional backdrop?: "ocean"

Presentation-only horizon behind a bounded sea world.

MoodStop

From at simulation seconds on, the view shows mood.

Properties

at

readonly at: number

mood

readonly mood: "day" | "dusk" | "night"

PhaseClock

Extended by

PhaseAdvance

Type Parameters

Phase

Phase extends string

Properties

phase

readonly phase: Phase

cycle

readonly cycle: number

phaseAt

readonly phaseAt: number

PhaseAdvance

Extends

PhaseClock<Phase>

Type Parameters

Phase

Phase extends string

Properties

phase

readonly phase: Phase

Inherited from

PhaseClock.phase

cycle

readonly cycle: number

Inherited from

PhaseClock.cycle

phaseAt

readonly phaseAt: number

Inherited from

PhaseClock.phaseAt

completed

readonly completed: ReadonlyMap<Phase, number>>

Completed phases since the supplied clock, including skipped cycles.

Placement

One actor in the fresh world. Compiled by defineCartridge, never spawned.

Properties

actor

readonly actor: ActorDefinition

id

readonly id: EntityId

at

readonly at: Cell2

params

readonly params: ActorParams

surface?

readonly optional surface?: "sea"

CompiledScene

The fresh world compiled from a scene.

Properties

initial

readonly initial: readonly SceneEntity[]

placements

readonly placements: readonly InitialSurfacePlacement[]

EntityClass

Properties

relation

readonly relation: EntityRelation

kind

readonly kind: string

glyph

readonly glyph: string

state?

readonly optional state?: string

designated?

readonly optional designated?: boolean

job?

readonly optional job?: EntityId

SeatView

The same named world view is available to every authorized seat.

Properties

sightRadius

readonly sightRadius: number

verticalMetres

readonly verticalMetres: number

environment?

readonly optional environment?: Pick<EnvironmentDefinition, "processes" | "resourceSites">>

Methods

ownActors()?

optional ownActors(reads, scope): ReadonlyMap<EntityId, Omit<EntityClass, "relation">>>>

Parameters

reads

SeatReads

scope

CommandScope | undefined

Returns

ReadonlyMap<EntityId, Omit<EntityClass, "relation">>

terrainClass()

terrainClass(surface): TerrainClass

Parameters

surface

TerrainSurface

Returns

TerrainClass

classify()

classify(reads): ReadonlyMap<EntityId, EntityClass>>

Parameters

reads

SeatReads

Returns

ReadonlyMap<EntityId, EntityClass>

buildableTitle()

buildableTitle(catalog): string

Parameters

catalog

string

Returns

string

SeatGoal

A cartridge-authored challenge and its committed-state scoring rule.

Type Parameters

F

F extends SeatFacts = SeatFacts

Properties

id

readonly id: string

title

readonly title: string

cartridge

readonly cartridge: string

setting

readonly setting: string

seeds

readonly seeds: readonly number[]

turnBudget

readonly turnBudget: number

spendCapUsd

readonly spendCapUsd: number

maxSimSeconds

readonly maxSimSeconds: number

goal

readonly goal: string

Methods

facts()

facts(reads): F

Parameters

reads

SeatReads

Returns

F

outcome()

outcome(start, end): SeatOutcome<F>>

Parameters

start

F

end

F

Returns

SeatOutcome<F>

SeatDefinition

Properties

view

readonly view: SeatView

grants

readonly grants: Readonly<Record<string, readonly string[]>>

goals

readonly goals: readonly SeatGoal<Readonly<Record<string, number>>>>>>[]

VoxelTerrainChoice

Properties

kind

readonly kind: "voxel"

environment

readonly environment: EnvironmentDefinition

art

readonly art: TerrainPresentationDefinition

SeaTerrainChoice

Properties

kind

readonly kind: "sea"

environment

readonly environment: EnvironmentDefinition

art

readonly art: TerrainPresentationDefinition

CartridgeWindow

Extends

WindowDeclaration

Properties

kind

readonly kind: "window"

body

readonly body: WindowBody

id

id: string

Inherited from

WindowDeclaration.id

title

title: string

Inherited from

WindowDeclaration.title

surface

surface: "paper" | "chrome"

Inherited from

WindowDeclaration.surface

role

role: "end" | "goal" | "minimap" | "letter" | "context" | "panel" | "hud" | "actions"

Inherited from

WindowDeclaration.role

end?

optional end?: object

pause

pause: "local" | "none"

treatment

treatment: "plain" | "tape"

closeLabel

closeLabel: string

restartLabel

restartLabel: string

Inherited from

WindowDeclaration.end

key?

optional key?: string

Inherited from

WindowDeclaration.key

opens

opens: { on: "start"; } | { on: "command"; } | { on: "content"; repeat?: boolean; } | { on: "time"; seconds: number; }

Inherited from

WindowDeclaration.opens

size

size: object

width

width: number

height

height: number

Inherited from

WindowDeclaration.size

WorldSpec

What a cartridge’s world needs; meadow() fills it in.

Properties

materials

readonly materials: readonly object[]

terrain

readonly terrain: TerrainChoice

Type Aliases

EntityId

EntityId = string & object

Public boundary between authored TypeScript and the authoritative kernel.

Type Declaration

__entityId

readonly __entityId: unique symbol

ComponentId

ComponentId = `${string}.${string}`

GameId

GameId = string

RouteCostResult

RouteCostResult = { actor: EntityId; status: "reachable"; cost: number; } | { actor: EntityId; status: "unavailable"; reason: string; }

RouteToAnyResult

RouteToAnyResult = { actor: EntityId; status: "reachable"; targetIndex: number; cost: number; } | { actor: EntityId; status: "unavailable"; reason: string; }

FieldType

FieldType = "number" | "boolean" | "string" | "nullable-string" | "entity" | "nullable-entity"

RelationRemovalPolicy

RelationRemovalPolicy = "detach" | "restrict"

ComponentValue

ComponentValue<T> > = object

Type Parameters

T

T

Properties

id

readonly id: EntityId

value

readonly value: T

WriteIntent

WriteIntent = object

Properties

component

readonly component: ComponentId

entity

readonly entity: EntityId

value

readonly value: JsonValue

JobEntityBinding

JobEntityBinding = { kind: "exact"; value: EntityId; } | { kind: "result"; value: { step: string; slot: string; }; }

JobOperation

JobOperation = { kind: "finiteToItem"; source: JobEntityBinding; inputKind: string; inputQuantity: number; outputKind: string; outputQuantity: number; workSeconds: number; resultSlot: string; } | { kind: "itemToItems"; source: JobEntityBinding; inputKind: string; inputQuantity: number; outputKind: string; outputQuantity: number; workSeconds: number; resultSlot: string; }

JobContinuation

JobContinuation = "any-eligible" | "prefer-starter" | "bind-on-first-progress" | { assigned-actor: EntityId; }

CardinalOrientation

CardinalOrientation = "north" | "east" | "south" | "west"

EdgeTarget

EdgeTarget = object

Properties

cell

readonly cell: readonly [number, number, number]

axis

readonly axis: "x" | "z"

ConstructionTarget

ConstructionTarget = { kind: "cell"; cell: Vec3; orientation: CardinalOrientation; } | { kind: "edge"; edge: { cell: Vec3; axis: "x" | "z"; }; }

ActionRequest

ActionRequest = { kind: "instantiate-actors"; bindingId: string; expectedSequence: number; plan: ActorInstantiationPlan; } | { kind: "spawn-actor"; receipt: EntityId; definition: string; cause: string; arguments: Readonly<Record<string, SpawnArgument>>>>; surfaceColumn?: readonly [number, number]; } | { kind: "set-relation"; relation: ComponentId; source: EntityId; target: EntityId; } | { kind: "clear-relation"; relation: ComponentId; source: EntityId; } | { kind: "begin-work-attempt"; task: EntityId; worker: EntityId; operation: WorkActivityRef; } | { kind: "retarget-work-attempt"; task: EntityId; generation: number; sequence: number; destination: MoveDestination; } | { kind: "interrupt-work-attempt"; task: EntityId; generation: number; sequence: number; cause: WorkInterruptCause; } | { kind: "acknowledge-work-attempt"; task: EntityId; generation: number; sequence: number; } | { kind: "continue-work-attempt"; task: EntityId; generation: number; sequence: number; nextActivity: WorkActivityRef; } | { kind: "create-job"; id: EntityId; pool: EntityId; plan: JobPlan; } | { kind: "resume-job"; id: EntityId; pool: EntityId; plan: JobPlan; } | { kind: "cancel-job"; id: EntityId; } | { kind: "establish-resource-site"; operation: string; worker: EntityId; site: EntityId; definition: string; x: number; y: number; z: number; } | { kind: "tend-resource-site"; operation: string; worker: EntityId; site: EntityId; vessel: EntityId; } | { kind: "designate-resource"; order: EntityId; party: EntityId; definition: string; x: number; y: number; z: number; } | { kind: "request-field-water"; party: EntityId; material: string; portions: number; } | { kind: "request-process"; definition: string; station: EntityId; } | { kind: "admit-process"; process: EntityId; definition: string; station: EntityId; } | { kind: "designate-stockpile"; party: EntityId; zone: EntityId; cells: readonly object[]; } | { kind: "update-stockpile"; party: EntityId; zone: EntityId; filterProfile: string; priority: number; } | { kind: "clear-stockpile"; party: EntityId; zone: EntityId; cells: readonly object[]; } | { kind: "set-structure-open"; worker: EntityId; site: EntityId; open: boolean; } | { kind: "deconstruct"; worker: EntityId; site: EntityId; } | { kind: "break-structure"; site: EntityId; } | { kind: "plan-deconstruction"; site: EntityId; party: EntityId; } | { kind: "plan-constructions"; party: EntityId; plans: readonly PlacementCandidate[]; } | { kind: "prebuild-structures"; party: EntityId; plans: readonly PlacementCandidate[]; } | { kind: "plan-excavation"; party: EntityId; prefix: string; start: readonly [number, number, number]; end: readonly [number, number, number]; } | { kind: "cancel-excavation"; party: EntityId; area: { start: readonly [number, number, number]; end: readonly [number, number, number]; } | null; workers: readonly EntityId[]; } | { kind: "replace-floor"; orderId: EntityId; existingFloorId: EntityId; desiredCatalog: string; } | { kind: "bind-construction-stage"; site: EntityId; contact: Vec3 & object; } | { kind: "cancel-work"; entity: EntityId; } | { kind: "begin-direct"; entity: EntityId; stream: string; } | { kind: "begin-emission"; worker: EntityId; station: EntityId; } | { kind: "exchange-field-water"; operation: string; worker: EntityId; vessel: EntityId; x: number; y: number; z: number; direction: "withdraw" | "deposit"; portions: number; } | { kind: "direct-input"; entity: EntityId; stream: string; inputs: readonly object[]; } | { kind: "launch"; launcher: EntityId; ammunition: EntityId; velocity: Vec3; } | { kind: "displace"; entity: EntityId; delta: Vec3; } | { kind: "move"; entity: EntityId; destination: MoveDestination; facing?: number; speed?: number; } | { kind: "drop-lot"; entity: EntityId; lot: EntityId; } | { kind: "transfer"; lot: EntityId; from: EntityId; to: EntityId; quantity: number; } | { kind: "request-delivery"; source: EntityId; destination: EntityId; material: string; quantity: number; party: EntityId; } | { kind: "consume"; entity: EntityId; lot: EntityId; quantity: number; } | { kind: "extract-resource"; operation: string; worker: EntityId; source: EntityId; }

Union Members

Type Literal

{ kind: "instantiate-actors"; bindingId: string; expectedSequence: number; plan: ActorInstantiationPlan; }

Type Literal

{ kind: "spawn-actor"; receipt: EntityId; definition: string; cause: string; arguments: Readonly<Record<string, SpawnArgument>>; surfaceColumn?: readonly [number, number]; }

kind

readonly kind: "spawn-actor"

Ordinary spawn of one template outside party join. The receipt is the new entity’s id: replaying the same request is a no-op, a different request under a used receipt is refused. Host scope only.

receipt

readonly receipt: EntityId

definition

readonly definition: string

cause

readonly cause: string

arguments

readonly arguments: Readonly<Record<string, SpawnArgument>>>>

surfaceColumn?

readonly optional surfaceColumn?: readonly [number, number]

Type Literal

{ kind: "set-relation"; relation: ComponentId; source: EntityId; target: EntityId; }

Type Literal

{ kind: "clear-relation"; relation: ComponentId; source: EntityId; }

Type Literal

{ kind: "begin-work-attempt"; task: EntityId; worker: EntityId; operation: WorkActivityRef; }

Type Literal

{ kind: "retarget-work-attempt"; task: EntityId; generation: number; sequence: number; destination: MoveDestination; }

Type Literal

{ kind: "interrupt-work-attempt"; task: EntityId; generation: number; sequence: number; cause: WorkInterruptCause; }

Type Literal

{ kind: "acknowledge-work-attempt"; task: EntityId; generation: number; sequence: number; }

Type Literal

{ kind: "continue-work-attempt"; task: EntityId; generation: number; sequence: number; nextActivity: WorkActivityRef; }

Type Literal

{ kind: "create-job"; id: EntityId; pool: EntityId; plan: JobPlan; }

Type Literal

{ kind: "resume-job"; id: EntityId; pool: EntityId; plan: JobPlan; }

Type Literal

{ kind: "cancel-job"; id: EntityId; }

Type Literal

{ kind: "establish-resource-site"; operation: string; worker: EntityId; site: EntityId; definition: string; x: number; y: number; z: number; }

Type Literal

{ kind: "tend-resource-site"; operation: string; worker: EntityId; site: EntityId; vessel: EntityId; }

Type Literal

{ kind: "designate-resource"; order: EntityId; party: EntityId; definition: string; x: number; y: number; z: number; }

Type Literal

{ kind: "request-field-water"; party: EntityId; material: string; portions: number; }

Type Literal

{ kind: "request-process"; definition: string; station: EntityId; }

Type Literal

{ kind: "admit-process"; process: EntityId; definition: string; station: EntityId; }

Type Literal

{ kind: "designate-stockpile"; party: EntityId; zone: EntityId; cells: readonly object[]; }

Type Literal

{ kind: "update-stockpile"; party: EntityId; zone: EntityId; filterProfile: string; priority: number; }

Type Literal

{ kind: "clear-stockpile"; party: EntityId; zone: EntityId; cells: readonly object[]; }

Type Literal

{ kind: "set-structure-open"; worker: EntityId; site: EntityId; open: boolean; }

Type Literal

{ kind: "deconstruct"; worker: EntityId; site: EntityId; }

Type Literal

{ kind: "break-structure"; site: EntityId; }

kind

readonly kind: "break-structure"

Tear down a finished structure with no worker: it was broken.

site

readonly site: EntityId

Type Literal

{ kind: "plan-deconstruction"; site: EntityId; party: EntityId; }

Type Literal

{ kind: "plan-constructions"; party: EntityId; plans: readonly PlacementCandidate[]; }

Type Literal

{ kind: "prebuild-structures"; party: EntityId; plans: readonly PlacementCandidate[]; }

kind

readonly kind: "prebuild-structures"

Plan structures and finish them at once: a fresh world’s buildings.

party

readonly party: EntityId

plans

readonly plans: readonly PlacementCandidate[]

Type Literal

{ kind: "plan-excavation"; party: EntityId; prefix: string; start: readonly [number, number, number]; end: readonly [number, number, number]; }

Type Literal

{ kind: "cancel-excavation"; party: EntityId; area: { start: readonly [number, number, number]; end: readonly [number, number, number]; } | null; workers: readonly EntityId[]; }

Type Literal

{ kind: "replace-floor"; orderId: EntityId; existingFloorId: EntityId; desiredCatalog: string; }

Type Literal

{ kind: "bind-construction-stage"; site: EntityId; contact: Vec3 & object; }

Type Literal

{ kind: "cancel-work"; entity: EntityId; }

Type Literal

{ kind: "begin-direct"; entity: EntityId; stream: string; }

Type Literal

{ kind: "begin-emission"; worker: EntityId; station: EntityId; }

Type Literal

{ kind: "exchange-field-water"; operation: string; worker: EntityId; vessel: EntityId; x: number; y: number; z: number; direction: "withdraw" | "deposit"; portions: number; }

Type Literal

{ kind: "direct-input"; entity: EntityId; stream: string; inputs: readonly object[]; }

Type Literal

{ kind: "launch"; launcher: EntityId; ammunition: EntityId; velocity: Vec3; }

Type Literal

{ kind: "displace"; entity: EntityId; delta: Vec3; }

Type Literal

{ kind: "move"; entity: EntityId; destination: MoveDestination; facing?: number; speed?: number; }

Type Literal

{ kind: "drop-lot"; entity: EntityId; lot: EntityId; }

Type Literal

{ kind: "transfer"; lot: EntityId; from: EntityId; to: EntityId; quantity: number; }

Type Literal

{ kind: "request-delivery"; source: EntityId; destination: EntityId; material: string; quantity: number; party: EntityId; }

Type Literal

{ kind: "consume"; entity: EntityId; lot: EntityId; quantity: number; }

Type Literal

{ kind: "extract-resource"; operation: string; worker: EntityId; source: EntityId; }

WorkActivityRef

WorkActivityRef = { kind: "route"; destination: MoveDestination; } | { kind: "construction"; site: EntityId; contact: Vec3 & object; mode: "bind" | "work"; } | { kind: "excavation"; cell: readonly [number, number, number]; expectedMaterial: number; replacementMaterial: number; } | { kind: "deconstruction"; site: EntityId; contact: Vec3 & object; } | { kind: "process-attendance"; process: EntityId; } | { kind: "material-transfer"; lot: EntityId; from: EntityId; to: EntityId; quantity: number; } | { kind: "material-drop"; lot: EntityId; } | { kind: "resource-establish"; site: EntityId; definition: string; cell: readonly [number, number, number]; } | { kind: "resource-tend"; site: EntityId; vessel: EntityId; } | { kind: "resource-extract"; source: EntityId; } | { kind: "field-water"; vessel: EntityId; cell: readonly [number, number, number]; direction: "withdraw" | "deposit"; portions: number; } | { kind: "job-transform"; task: EntityId; contact: MoveDestination; }

WorkInterruptCause

WorkInterruptCause = "drafted" | "cancelled" | "workerUnavailable" | "accessLost"

WorkBlockReason

WorkBlockReason = "accessLost" | "missingInputs" | "capacityUnavailable" | "unsupportedStructure" | "workerUnavailable"

WorkOutcome

WorkOutcome = { kind: "completed"; } | { kind: "blocked"; reason: WorkBlockReason; } | { kind: "interrupted"; cause: WorkInterruptCause; }

WorkAttemptPhase

WorkAttemptPhase = { kind: "ready"; } | { kind: "executing"; operation: { attempt: WorkAttemptKey; sequence: number; }; activity: WorkActivityRef; } | { kind: "outcome"; operation: { attempt: WorkAttemptKey; sequence: number; }; activity: WorkActivityRef; result: WorkOutcome; } | { kind: "settling"; operation: { attempt: WorkAttemptKey; sequence: number; }; cause: WorkInterruptCause; }

ProcessInputPolicy

ProcessInputPolicy = "portion" | "whole-lot"

ProcessInputDisposition

ProcessInputDisposition = "consume" | "retain" | "emission-source"

NativeFact

NativeFact = Exclude<keyof ReadContext, "clock" | "outcomes" | "random" | "impacts" | "query">>

Native read doors available to authored decisions beyond ECS/query state.

CommandScope

CommandScope = { kind: "host"; } | { kind: "player"; player: string; }

PartyJoinIdentity

PartyJoinIdentity = Readonly<{ status: "existing" | "available"; sequence: number; player: string; party: EntityId; people: readonly EntityId[]; }>

SpawnArgument

SpawnArgument = Extract<ActorArgument, { kind: "value"; } | { kind: "existing"; }>

Spawn arguments bind values or existing entities; slots and joining players belong to party join.

ActorArgument

ActorArgument = { kind: "value"; value: string | number | boolean | null; } | { kind: "spawned"; slot: string; } | { kind: "existing"; id: EntityId; } | { kind: "joining-player"; }

ActorInstantiationPlan

ActorInstantiationPlan = Readonly<{ actors: readonly Readonly<{ slot: string; definition: string; arguments: Readonly<Record<string, ActorArgument>>>>; surfaceColumn?: readonly [number, number]; }>[]; initialMaterials: readonly Readonly<{ container: ActorArgument; kind: string; quantity: number; actorDefinition?: string; arguments?: Readonly<Record<string, ActorArgument>>>>; }>[]; partySlot: string; peopleSlots: readonly string[]; }>

PartyJoinCapability

PartyJoinCapability = Readonly<{ footprint: readonly readonly [number, number][]; prepare: (spawn) => ActorInstantiationPlan; }>

ActionScope

ActionScope = { kind: "host"; } | { kind: "player"; player: string; }

GameCommandContext

GameCommandContext = Pick<ReadContext, "query" | "physicalContacts" | "terrainMaterials" | "terrainSurfaces" | "structureSurfaces" | "transferContacts"> > & object

Type Declaration

scope

readonly scope: CommandScope

workAttempts

readonly workAttempts: (taskIds) => readonly WorkAttempt[]

Parameters

taskIds

readonly EntityId[]

Returns

readonly WorkAttempt[]

workAttemptForWorker

readonly workAttemptForWorker: (worker) => WorkAttempt | null

Parameters

worker

Returns

WorkAttempt | null

floorOperations

readonly floorOperations: (requests) => readonly FloorOperation[]

Parameters

requests

readonly FloorOperationRequest[]

Returns

readonly FloorOperation[]

VisualPlacement

VisualPlacement = { kind: "edge"; edge: EdgeTarget; } | { kind: "footprint"; footprint: readonly readonly [number, number][]; orientation: CardinalOrientation; } | { kind: "stair"; entrance: readonly [number, number, number]; landing: readonly [number, number, number]; orientation: CardinalOrientation; }

DeliveryActivityPhase

DeliveryActivityPhase = "fetching" | "pickup" | "carrying" | "putting-down"

fetching: walking to the source with empty hands; pickup: the tick custody moved into the hands; carrying: walking with the held load; putting-down: the tick the load left the hands.

ActivityKind

ActivityKind = "dig" | "build" | "chop" | "delivery"

KernelSnapshot

KernelSnapshot = KernelRecordSnapshot

ConstructionReadinessStatus

ConstructionReadinessStatus = "ready" | "waitingForSupport" | "unknown"

ConstructionAccessContact

ConstructionAccessContact = Vec3 & object

Type Declaration

frame

readonly frame: null

kind

readonly kind: "origin" | "landing"

DeconstructionAccess

DeconstructionAccess = object

Properties

site

readonly site: EntityId

status

readonly status: "ready" | "occupiedPort" | "structuralDependency" | "invalidGeometry"

contacts

readonly contacts: readonly ConstructionAccessContact[]

salvageQuantity

readonly salvageQuantity: number

workSeconds

readonly workSeconds: number

PhysicalContact

PhysicalContact = object

Properties

solid

readonly solid: boolean

sealedTop

readonly sealedTop: boolean

outside

readonly outside: boolean

TerrainSurface

TerrainSurface = z.infer<typeof terrainSurfaceSchema>>

TerrainSurfaceCover

TerrainSurfaceCover = NonNullable<TerrainSurface["cover"]>

StructureSurface

StructureSurface = object

Properties

cell

readonly cell: readonly [number, number, number]

FloorOperation

FloorOperation = { kind: "build"; } | { kind: "unchanged"; floor: EntityId; } | { kind: "replace"; floor: EntityId; } | { kind: "conflict"; floor: EntityId; } | { kind: "waiting-for-support"; } | { kind: "invalid"; reason: string; }

FloorOperationRequest

FloorOperationRequest = object

Properties

cell

readonly cell: readonly [number, number, number]

desiredCatalog

readonly desiredCatalog: string

TerrainChangeSet

TerrainChangeSet = { kind: "changed-columns"; revision: number; columns: readonly readonly [number, number][]; } | { kind: "full-reset"; revision: number; reason: "history" | "restored" | "stale"; }

GameLocalBinding

GameLocalBinding = Readonly<{ id: string; label: string; detail?: string; selection?: "entities" | Readonly<{ field: string; cardinality: "one"; }>; target?: "terrain-cell" | "terrain-area" | "world-surface" | "world-edge" | "actor"; component?: ComponentId; designation?: readonly ("point" | "line" | "rectangle" | "edge-line" | "entities")[]; footprint?: readonly readonly [number, number][]; placement?: "action-bar"; key?: string; preset?: JsonValue; }>

JsonValue

JsonValue = null | boolean | number | string | readonly JsonValue[] | {[key: string]: JsonValue; }

ComponentValues

ComponentValues = Readonly<Record<string, JsonValue>>>>

GameCommandAvailability

GameCommandAvailability = { status: "available"; } | { status: "unavailable"; reason: string; }

EnvironmentFacts

EnvironmentFacts = z.infer<typeof environmentFactsSchema>>

AuthoredFeedbackCue

AuthoredFeedbackCue = Omit<FeedbackPresentationCue, "sequence" | "time" | "kind">>

What WriteContext.cue() accepts: a feedback cue before the session stamps its sequence and commit time.

CartridgeAudio

CartridgeAudio = z.infer<typeof cartridgeAudioSchema>>

BlueprintSide

BlueprintSide = "north" | "south" | "east" | "west"

A side of a module: north is -z, south +z, west -x, east +x.

BlueprintOpeningKind

BlueprintOpeningKind = "door" | "window" | "doorway"

What an opening in a side is: a door, a window, or a doorway (an open gap into the room next door, which must be there).

CameraFollowPolicy

CameraFollowPolicy = z.infer<typeof cameraFollowSchema>>

CartridgeCameraPolicy

CartridgeCameraPolicy = z.infer<typeof cartridgeCameraSchema>>

VisualBindings

VisualBindings = Readonly<Record<string, VisualBinding>>>>

StaticVisualBinding

StaticVisualBinding = VisualBinding & object

A static frame by its path in the art (the bank’s, or a cartridge pack’s under its root).

Type Declaration

kind

readonly kind: "static"

worldRole

readonly worldRole: "floor" | "structure" | "item"

path

readonly path: BankPath

facing

readonly facing: boolean

The path ends in one frame per view turn (0 to 3).

frames?

readonly optional frames?: true

The path (after its view) ends in an animation’s frames.

anchor

readonly anchor: "propAnchor" | "vehicleAnchor"

CartridgeDirectControl

CartridgeDirectControl = { entity: string; } | { person: number; }

A cartridge-owned actor driven directly by the player’s movement keys. The world moves it in fixed steps. A walker with Traversal keeps its feet on the ground: it climbs or drops at most its step height, never steps onto no floor, and never passes a finished wall, a closed door or a filled cell. An open door lets it through. Moving it by route later starts from wherever it stands, even between cells.

Union Members

Type Literal

{ entity: string; }

One fixed actor, the same for every viewer.

Type Literal

{ person: number; }

Each viewer drives their own: this index into the people of the party the viewer joined with (players.join), or the local party.

HostFeature

HostFeature = typeof HOST_FEATURES[number]

ComponentFields

ComponentFields = Readonly<Record<string, JsonValue>>>>

One component’s field values as they cross into the kernel.

BuildableDefinition

BuildableDefinition = z.infer<typeof buildableDefinitionSchema>>

ConstructionProposalInput

ConstructionProposalInput = z.infer<typeof constructionProposalInput>>

DiagnosticCode

DiagnosticCode = keyof typeof DIAGNOSTICS

EffectFields

EffectFields<T> > = Readonly<Record<keyof T & string | "at" | "seq", "number" | "string" | "boolean">>>>

Fields declared by an effect, including its world time and step order.

Type Parameters

T

T extends object

FlowCell

FlowCell = readonly [number, number]

PresentationLight

PresentationLight = z.infer<typeof presentationLightSchema>>

CartridgeLighting

CartridgeLighting = z.infer<typeof cartridgeLightingSchema>>

Mood

Mood = typeof MOODS[number]

TerrainLook

TerrainLook = z.infer<typeof terrainLookSchema>>

Look

Look = { palette: null; ambientLight?: Readonly<Record<Mood, number>>>>; ambientTint?: Readonly<Record<Mood, readonly [number, number, number]>>; terrain: TerrainLook; backdrop?: "ocean"; } | { palette: Palette; dither: PaletteDither; mood: Mood; moods?: readonly MoodStop[]; ambientLight?: Readonly<Record<Mood, number>>>>; ambientTint?: Readonly<Record<Mood, readonly [number, number, number]>>; terrain: TerrainLook; backdrop?: "ocean"; }

A checked look: either full colour, or a palette with its dither and mood.

Union Members

Type Literal

{ palette: null; ambientLight?: Readonly<Record<Mood, number>>; ambientTint?: Readonly<Record<Mood, readonly [number, number, number]>>; terrain: TerrainLook; backdrop?: "ocean"; }

palette

readonly palette: null

ambientLight?

readonly optional ambientLight?: Readonly<Record<Mood, number>>>>

ambientTint?

readonly optional ambientTint?: Readonly<Record<Mood, readonly [number, number, number]>>

View-only RGB light multipliers (0..1), independent of palette mapping.

terrain

readonly terrain: TerrainLook

backdrop?

readonly optional backdrop?: "ocean"

Type Literal

{ palette: Palette; dither: PaletteDither; mood: Mood; moods?: readonly MoodStop[]; ambientLight?: Readonly<Record<Mood, number>>; ambientTint?: Readonly<Record<Mood, readonly [number, number, number]>>; terrain: TerrainLook; backdrop?: "ocean"; }

palette

readonly palette: Palette

dither

readonly dither: PaletteDither

mood

readonly mood: Mood

moods?

readonly optional moods?: readonly MoodStop[]

The checked schedule, when the cartridge gives one.

ambientLight?

readonly optional ambientLight?: Readonly<Record<Mood, number>>>>

ambientTint?

readonly optional ambientTint?: Readonly<Record<Mood, readonly [number, number, number]>>

View-only RGB light multipliers (0..1), independent of palette mapping.

terrain

readonly terrain: TerrainLook

backdrop?

readonly optional backdrop?: "ocean"

Cell2

Cell2 = readonly [number, number]

A ground cell: [x, z]. The actor settles onto the surface there.

ActorParams

ActorParams = Readonly<Record<string, string | number | boolean | null>>>>

Values for an actor’s declared inputs, by input name.

SeatFacts

SeatFacts = Readonly<Record<string, number>>>>

TerrainChoice

TerrainChoice = VoxelTerrainChoice | SeaTerrainChoice

WindowSurface

WindowSurface = "paper" | "chrome"

The two UI languages. paper is a window about the world (field-guide theme: inspector, letters, goals); chrome is the cartridge shell (plastic theme: menus, settings). Caps components and themes do all the styling.

WindowWorld

WindowWorld = Pick<ReadContext, "query" | "atmosphereSamples" | "constructionReadiness"> > & PresentationViewer

What a window body reads: the committed world, through typed queries, and who is looking. Each viewer gets their own pass: a player sees { kind: "player", player }, a host or spectator { kind: "host" }.

RunCommand

RunCommand = (command, input?) => void

The single command door: "garden:plantSeeds" or "ui:garden.goals".

Parameters

command

string

input?

JsonValue

Returns

void

WindowBody

WindowBody = (world) => readonly WindowBlock[]

Pure: world in, blocks out. It runs where the world lives (the Worker or the host) on every presentation, so only data crosses to the page.

Parameters

world

WindowWorld

Returns

readonly WindowBlock[]

WindowBlock

WindowBlock = z.infer<typeof windowBlockSchema>>

One block of a game window: plain data a person or a model can write.

WindowRole

WindowRole = z.infer<typeof windowRoleSchema>>

Where the shell shows a window.

WindowOpening

WindowOpening = z.infer<typeof windowOpeningSchema>>

When a window first opens on its own.

Variables

RESERVED_COMPONENTS

const RESERVED_COMPONENTS: readonly ["vishnu.party", "vishnu.owned-by", "vishnu.party-member", "vishnu.owned-by-party", "vishnu.stockpile-cell", "vishnu.storage-provider", "vishnu.position", "vishnu.body", "vishnu.traversal", "vishnu.container", "vishnu.sealed-container", "vishnu.ground-stock", "vishnu.construction-site", "vishnu.floor-replacement", "vishnu.lot", "vishnu.lot-water", "vishnu.hands", "vishnu.process-binding", "vishnu.finite-resource", "vishnu.resource-site", "vishnu.resource-order", "vishnu.excavation-work", "vishnu.excavation-order", "vishnu.deconstruction-work", "vishnu.supply-allocation", "vishnu.delivery-request", "vishnu.field-water-work", "vishnu.vessel-capability", "vishnu.work-policy", "vishnu.work-execution", "vishnu.work-schedule", "vishnu.job-task-work", "vishnu.destination", "vishnu.support", "vishnu.surface", "vishnu.obstacle", "vishnu.visual", "vishnu.collider", "vishnu.launcher", "vishnu.emitter", "vishnu.projectile", "vishnu.impact-material", "vishnu.owned-by-party", "vishnu.party-member"]

sampledSoundSchema

const sampledSoundSchema: ZodReadonly<ZodObject<{ urls: ZodReadonly<ZodArray<ZodString>>>>; gain: ZodNumber; priority: ZodNumber; }, $strict>>>>

A sampled replacement for one existing feedback sound name. URLs are resolved by the cartridge bundler; variants cycle without simulation RNG.

cartridgeAudioSchema

const cartridgeAudioSchema: ZodReadonly<ZodObject<{ samples: ZodReadonly<ZodRecord<ZodString, ZodReadonly<ZodObject<{ urls: ZodReadonly<ZodArray<ZodString>>>>; gain: ZodNumber; priority: ZodNumber; }, $strict>>>>>>>>; maxVoices: ZodOptional<ZodNumber>>; }, $strict>>>>

View-only audio bank. Omission preserves the engine’s procedural recipes. Named samples replace that recipe; a failed sample stays silent.

actorInput

const actorInput: Readonly<{ number: (name) => ActorInput; boolean: (name) => ActorInput; string: (name) => ActorInput; reference: (name) => ActorInput; optionalReference: (name) => ActorInput; }>

Declared instance inputs; templates bind these to checked component fields.

actorInputSchema

const actorInputSchema: ZodObject<{ kind: ZodLiteral<"actor-input">>; name: ZodString; type: ZodEnum<{ string: "string"; number: "number"; boolean: "boolean"; nullable-string: "nullable-string"; entity: "entity"; nullable-entity: "nullable-entity"; actor-reference: "actor-reference"; }>; }, $strict>>

Parses an actor input placeholder inside an initial component value.

ActorKind

const ActorKind: ComponentDefinition<{ definition: string; }>

Membership marker for actors that attach behaviors. Pack preparation adds it to every attaching template, so an installed behavior runs only for entities created from an actor that attached it, never for look-alikes.

cameraFollowSchema

const cameraFollowSchema: ZodReadonly<ZodObject<{ deadZone: ZodOptional<ZodNumber>>; halfLife: ZodOptional<ZodNumber>>; lookAhead: ZodOptional<ZodNumber>>; lookAheadSource: ZodOptional<ZodEnum<{ movement: "movement"; aim: "aim"; }>>; resumeDistance: ZodOptional<ZodNumber>>; }, $strict>>>>

Presentation tuning only; following never changes actor movement or aim.

cartridgeCameraSchema

const cartridgeCameraSchema: ZodReadonly<ZodObject<{ pan: ZodBoolean; rotate: ZodBoolean; follow: ZodOptional<ZodReadonly<ZodObject<{ deadZone: ZodOptional<ZodNumber>>; halfLife: ZodOptional<ZodNumber>>; lookAhead: ZodOptional<ZodNumber>>; lookAheadSource: ZodOptional<ZodEnum<{ movement: "movement"; aim: "aim"; }>>; resumeDistance: ZodOptional<ZodNumber>>; }, $strict>>>>>>; initialZoom: ZodOptional<ZodUnion<readonly [ZodLiteral<1>>, ZodLiteral<2>>, ZodLiteral<3>>, ZodLiteral<4>>]>>; cutaway: ZodOptional<ZodLiteral<"auto">>>>; }, $strict>>>>

Camera policy shared by cartridge authoring and the remote player boundary. Follow is opt-in for a direct-control actor; manual pan suspends it until movement resumes. Unset zoom preserves the engine’s desktop/phone defaults. Whole zoom levels keep pixel art crisp; the wheel remains player-controlled.

HOST_FEATURES

const HOST_FEATURES: readonly ["minded-seats"]

Engine features a host switches on for the shared worlds it opens.

Collider

const Collider: ComponentDefinition<{ geometry: "ball" | "cuboid"; radius: number; halfX: number; halfY: number; halfZ: number; yaw: number; offsetX: number; offsetY: number; offsetZ: number; }>

Physical collision dimensions are independent of a sprite’s bounds.

Launcher

const Launcher: ComponentDefinition<{ ammoKind: string; muzzleX: number; muzzleY: number; muzzleZ: number; maxSpeed: number; projectileRadius: number; maxRange: number; maxLifetime: number; projectileSprite: string; projectileLabel: string; gravity: number; penetration: number; }>

ImpactMaterial

const ImpactMaterial: ComponentDefinition<{ response: "stop" | "pierce" | "ground"; resistance: number; restitution: number; friction: number; embedSpeed: number; }>

Contact policy supplied by a game; collision geometry remains independent.

Body

const Body: ComponentDefinition<{ speed: number; }>

Native movement capability; game systems may query it but cannot write it.

Emitter

const Emitter: ComponentDefinition<{ catalog: string; }>

Native finite-emission capability; catalog admission remains native-owned.

Container

const Container: ComponentDefinition<{ capacity: number; }>

Native carrying capacity; authored systems may query but cannot write it.

Traversal

const Traversal: ComponentDefinition<{ clearanceCells: number; maxStepCells: number; }>

Authored walking geometry; native routing owns its interpretation and state.

Position

const Position: ComponentDefinition<{ x: number; y: number; z: number; facing: number; }>

Visual

const Visual: ComponentDefinition<{ sprite: string; label: string; }>

Native authored sprite identity. Presentation projections must not replace it.

Support

const Support: ComponentDefinition<{ entity: EntityId; }>

Surface

const Surface: ComponentDefinition<{ minX: number; maxX: number; minZ: number; maxZ: number; height: number; }>

MaterialLot

const MaterialLot: ComponentDefinition<{ quantity: number; kind: string; container: EntityId; }>

Hands

const Hands: ComponentDefinition<{ lot: EntityId; }>

Native hands slot: the one lot an actor holds and carries. Separate from the actor’s container (inventory); filled only by a pickup and emptied only by a deposit, drop or transfer of that lot. Absent means empty hands.

VesselCapability

const VesselCapability: ComponentDefinition<{ acceptsWater: boolean; }>

Native vessel eligibility; physical capability is authored as content and consumed by the native field-water planner.

LotWater

const LotWater: ComponentDefinition<{ waterKg: number; }>

SupplyAllocation

const SupplyAllocation: ComponentDefinition<{ requirementOwner: EntityId; requirementRole: string; requirementGeneration: number; party: EntityId; material: string; portion: EntityId; destination: EntityId; quantity: number; state: "reserved" | "delivered" | "cancelled"; }>

Native reservation for one exact material portion. Physical custody remains in MaterialLot; this record exposes the durable planner obligation.

DeliveryRequest

const DeliveryRequest: ComponentDefinition<{ source: EntityId; destination: EntityId; party: EntityId; material: string; quantity: number; deliveredQuantity: number; }>

Durable intent submitted with requestDelivery; native allocation rows expose reserved and delivered portions without authored worker choreography.

FiniteResource

const FiniteResource: ComponentDefinition<{ kind: string; quantity: number; }>

JobTaskWork

const JobTaskWork: ComponentDefinition<{ seconds: number; }>

Native durable effort for a generic job task; authored code may query it for progress presentation but cannot write it.

ResourceSite

const ResourceSite: ComponentDefinition<{ definition: string; stage: number; nextDue: number; }>

Destination

const Destination: ComponentDefinition<{ x: number; y: number; z: number; facing: number; frame: EntityId | null; }>

placedAt

const placedAt: Readonly<{ x: "at-x"; z: "at-z"; }>

A Position declared without values is bound where the actor is placed or spawned: these are the inputs the compiled template exposes for it.

ExcavationWork

const ExcavationWork: ComponentDefinition<{ x: number; y: number; z: number; expected: number; replacement: number; seconds: number; }>

Native progress is observable but cannot be written by authored systems.

ExcavationOrder

const ExcavationOrder: ComponentDefinition<{ cellX: number; cellY: number; cellZ: number; expected: number; status: "queued" | "blocked" | "cancelling"; reason: string; }>

Buildable

const Buildable: ActorDefinitionCapability<{ name: string; sprites: string; geometry: { kind: "fixture"; footprint: [number, number][]; } | { kind: "aperture"; height: number; openingBottom: number; openingHeight: number; closed?: boolean; } | { kind: "floor"; } | { kind: "cover"; } | { kind: "wall"; height: number; } | { kind: "stair"; run: number; rise: number; }; materials: object[]; workSeconds: number; workReachBelowCells: number; placement?: { alignment: "fixed" | "stroke"; facing?: { north: number; east: number; south: number; west: number; }; }; ports?: object[]; onRemove?: { salvage?: object[]; emptyPorts?: string[]; }; palette?: boolean; key?: string; }>

A structure actor is created by native construction, on its existing site identity.

constructionProposalInput

const constructionProposalInput: ZodObject<{ catalog: ZodString; orientation: ZodOptional<ZodEnum<{ north: "north"; east: "east"; south: "south"; west: "west"; }>>; target: ZodUnion<readonly [ZodObject<{ cell: ZodTuple<[ZodNumber, ZodNumber, ZodNumber], null>>; }, $strict>>, ZodObject<{ area: ZodObject<{ start: ZodTuple<[ZodNumber, ZodNumber, ZodNumber], null>>; end: ZodTuple<[ZodNumber, ZodNumber, ZodNumber], null>>; }, $strict>>; }, $strict>>, ZodObject<{ edges: ZodArray<ZodObject<{ cell: ZodTuple<[…, …, …], null>>; axis: ZodEnum<{ x: …; z: …; }>; }, $strict>>>>; }, $strict>>]>; }, $strict>>

Friendly gesture input. Physical admission remains native and transactional.

SealedContainer

const SealedContainer: ComponentDefinition<Record<string, never>>>>

Native custody is observable; authored writes cannot lock or unlock goods.

ConstructionSite

const ConstructionSite: ComponentDefinition<ConstructionSiteState>>

The site owns earned effort; active worker ownership lives in WorkAttempt.

FloorReplacement

const FloorReplacement: ComponentDefinition<{ version: number; targetFloor: EntityId; expectedCatalog: string; desiredCatalog: string; supportX: number; supportY: number; supportZ: number; phase: "cancelled" | "queued" | "working" | "completed"; }>

DeconstructionOrder

const DeconstructionOrder: ComponentDefinition<{ site: string; contactX: number; contactY: number; contactZ: number; salvageQuantity: number; workSeconds: number; status: "queued" | "blocked" | "complete"; reason: string; retryKey: string; }>

Native-owned teardown intent projected for game UI and save inspection.

DIAGNOSTICS

const DIAGNOSTICS: object

The stable catalog. A code never changes meaning once published.

Type Declaration

VD001

readonly VD001: "cartridge header is invalid" = "cartridge header is invalid"

VD002

readonly VD002: "a system is installed twice" = "a system is installed twice"

VD003

readonly VD003: "two components share an id" = "two components share an id"

VD004

readonly VD004: "a buildable is listed as an ordinary actor" = "a buildable is listed as an ordinary actor"

VD005

readonly VD005: "a build command is defined next to construction()" = "a build command is defined next to construction()"

VD006

readonly VD006: "buildables have no world to stand in" = "buildables have no world to stand in"

VD007

readonly VD007: "buildables need voxel terrain" = "buildables need voxel terrain"

VD008

readonly VD008: "terrain kind is unknown" = "terrain kind is unknown"

VD009

readonly VD009: "shelf presentation is invalid" = "shelf presentation is invalid"

VD010

readonly VD010: "an actor id is invalid" = "an actor id is invalid"

VD011

readonly VD011: "an actor has a component twice" = "an actor has a component twice"

VD012

readonly VD012: "an actor's initial value does not fit its component" = "an actor's initial value does not fit its component"

VD013

readonly VD013: "a behavior needs components its actor lacks" = "a behavior needs components its actor lacks"

VD014

readonly VD014: "an actor attaches a behavior twice" = "an actor attaches a behavior twice"

VD015

readonly VD015: "two different behaviors share an id" = "two different behaviors share an id"

VD016

readonly VD016: "an actor is defined twice in one cartridge" = "an actor is defined twice in one cartridge"

VD017

readonly VD017: "membership is set by hand" = "membership is set by hand"

VD020

readonly VD020: "a placed actor is missing a param" = "a placed actor is missing a param"

VD021

readonly VD021: "a placed actor is given an unknown param" = "a placed actor is given an unknown param"

VD022

readonly VD022: "the scene places one id twice" = "the scene places one id twice"

VD023

readonly VD023: "a placed actor has a component without values" = "a placed actor has a component without values"

VD024

readonly VD024: "a placed actor has no position" = "a placed actor has no position"

VD025

readonly VD025: "two placed actors have the same target cell" = "two placed actors have the same target cell"

VD030

readonly VD030: "a window id is not namespaced" = "a window id is not namespaced"

VD031

readonly VD031: "a window is declared twice" = "a window is declared twice"

VD032

readonly VD032: "two windows share a key" = "two windows share a key"

VD033

readonly VD033: "a control key is not one lowercase letter or digit" = "a control key is not one lowercase letter or digit"

VD034

readonly VD034: "two controls, windows or shell keys share a key" = "two controls, windows or shell keys share a key"

VD040

readonly VD040: "an actor given to construction() is not buildable" = "an actor given to construction() is not buildable"

VD041

readonly VD041: "a buildable is declared twice" = "a buildable is declared twice"

VD050

readonly VD050: "dismemberment settings are invalid" = "dismemberment settings are invalid"

VD051

readonly VD051: "a cast has no look of that name" = "a cast has no look of that name"

VD052

readonly VD052: "a cast is invalid" = "a cast is invalid"

VD060

readonly VD060: "a cartridge's look is invalid" = "a cartridge's look is invalid"

VD061

readonly VD061: "a game window's options are invalid" = "a game window's options are invalid"

VD070

readonly VD070: "a blueprint module is invalid" = "a blueprint module is invalid"

VD071

readonly VD071: "two blueprint rooms overlap" = "two blueprint rooms overlap"

VD072

readonly VD072: "a blueprint doorway leads outside" = "a blueprint doorway leads outside"

VD073

readonly VD073: "two blueprint rooms disagree about a shared wall" = "two blueprint rooms disagree about a shared wall"

VD074

readonly VD074: "a styled blueprint piece has no buildable" = "a styled blueprint piece has no buildable"

VD080

readonly VD080: "local play seats more than one party" = "local play seats more than one party"

VD083

readonly VD083: "world lighting presentation is invalid" = "world lighting presentation is invalid"

VD082

readonly VD082: "camera presentation is invalid" = "camera presentation is invalid"

VD081

readonly VD081: "page interest radius is invalid" = "page interest radius is invalid"

FLOW_NEIGHBOURS

const FLOW_NEIGHBOURS: readonly [readonly [0, 1], readonly [1, 0], readonly [0, -1], readonly [-1, 0], readonly [1, 1], readonly [1, -1], readonly [-1, 1], readonly [-1, -1]]

HordeTarget

const HordeTarget: ComponentDefinition<{ x: number; z: number; speed: number; active: boolean; profile: string; }>

Saved autonomous intent. An empty profile is a direct local destination.

presentationLightSchema

const presentationLightSchema: ZodDiscriminatedUnion<[ZodReadonly<ZodObject<{ radius: ZodNumber; color: ZodNumber; intensity: ZodNumber; height: ZodNumber; kind: ZodLiteral<"point">>; }, $strict>>>>, ZodReadonly<ZodObject<{ radius: ZodNumber; color: ZodNumber; intensity: ZodNumber; height: ZodNumber; kind: ZodLiteral<"cone">>; angle: ZodNumber; }, $strict>>>>], "kind">>

Presentation lights never participate in simulation sight or noise.

cartridgeLightingSchema

const cartridgeLightingSchema: ZodReadonly<ZodObject<{ sources: ZodOptional<ZodReadonly<ZodArray<ZodReadonly<ZodObject<{ visual: ZodString; moods: ZodOptional<ZodReadonly<…>>; light: ZodDiscriminatedUnion<[…, …], "kind">>; }, $strict>>>>>>>>>>; occluders: ZodOptional<ZodReadonly<ZodArray<ZodReadonly<ZodObject<{ visual: ZodString; height: ZodNumber; }, $strict>>>>>>>>>>; pulses: ZodOptional<ZodReadonly<ZodArray<ZodReadonly<ZodObject<{ cue: ZodString; light: ZodDiscriminatedUnion<[…, …], "kind">>; ms: ZodNumber; }, $strict>>>>>>>>>>; }, $strict>>>>

Small, bounded authoring data; select committed visuals, not game callbacks.

MOODS

const MOODS: readonly ["day", "dusk", "night"]

The light a world is shown in. Every mood’s sky and light come from the declared palette.

moodSchema

const moodSchema: ZodEnum<{ day: "day"; dusk: "dusk"; night: "night"; }>

Parses a mood from untrusted input (a URL parameter, a tool call).

terrainLookSchema

const terrainLookSchema: ZodEnum<{ voxel: "voxel"; smooth: "smooth"; }>

FULL_COLOUR

const FULL_COLOUR: Look

Full colour: no palette constraint.

Party

const Party: ComponentDefinition<Record<string, never>>>>

Gameplay group identity. Membership and ownership are separate facts.

OwnedBy

const OwnedBy: ComponentDefinition<{ player: string; }>

Stable player property. Access rules decide which operations it permits.

PartyMember

const PartyMember: ComponentDefinition<{ party: EntityId; }>

A person belongs to this party without duplicating their physical identity.

OwnedByParty

const OwnedByParty: ComponentDefinition<{ party: EntityId; }>

Party ownership for property and stationary stores.

StagedProcess

const StagedProcess: ComponentDefinition<{ version: number; definition: string; definitionVersion: number; station: EntityId; stageIndex: number; progressSeconds: number; enteredTick: number; phase: "blocked" | "complete" | "working" | "waiting"; blockedReason: string; }>

FieldWaterWork

const FieldWaterWork: ComponentDefinition<{ process: EntityId; role: string; generation: number; party: EntityId; destination: EntityId; material: string; retainInVessel: boolean; portions: number; vessel: EntityId | null; cellX: number; cellY: number; cellZ: number; lot: EntityId | null; }>

Native durable field-water acquisition intent. Once its lot is withdrawn, the native owner replaces this record with SupplyAllocation.

ResourceOrder

const ResourceOrder: ComponentDefinition<{ definition: string; cellX: number; cellY: number; cellZ: number; status: ResourceOrderStatus; progressSeconds: number; reason: string; }>

Engine-owned durable intent for one tended resource lifecycle.

Spawned

const Spawned: ComponentDefinition<{ cause: string; digest: string; }>

Where the kernel keeps a spawned entity’s cause and request digest.

terrainChoiceSchema

const terrainChoiceSchema: ZodDiscriminatedUnion<[ZodObject<{ kind: ZodLiteral<"voxel">>; environment: ZodCustom<EnvironmentDefinition, EnvironmentDefinition>>; art: ZodCustom<TerrainPresentationDefinition, TerrainPresentationDefinition>>; }, $strip>>, ZodObject<{ kind: ZodLiteral<"sea">>; environment: ZodCustom<EnvironmentDefinition, EnvironmentDefinition>>; art: ZodCustom<TerrainPresentationDefinition, TerrainPresentationDefinition>>; }, $strip>>], "kind">>

block

const block: Readonly<{ heading: (text) => object; text: (text) => object; check: (label, done) => object; stat: (label, value, glyph?) => object; meter: (label, value, max, tone, glyph?) => object; items: (label, grid, items) => object; action: (label, command, input?) => object; keyAction: (label, shortcut, command, input?) => object; clock: (label, options) => object; portrait: (name, status, mood?) => object; minimap: (label, grid, marks) => object; offer: (label, price, command, options) => object; recipe: (label, inputs, output, command, input?) => object; notice: (text, tone?) => object; group: (id, label, blocks, initiallyOpen) => { kind: "heading"; text: string; } | { kind: "text"; text: string; } | { kind: "check"; label: string; done: boolean; } | { kind: "stat"; label: string; value: string | number; glyph?: string; } | { kind: "meter"; label: string; value: number; max: number; tone?: "success" | "error" | "info" | "warning"; glyph?: string; } | { kind: "items"; label: string; columns: number; rows: number; items: object[]; } | { kind: "action"; label: string; command: string; input?: JSONType; shortcut?: string; } | { kind: "clock"; label: string; detail?: string; phase?: "day" | "dusk" | "night" | "dawn"; time?: boolean; } | { kind: "portrait"; name: string; status: string; mood?: "ok" | "warn" | "bad"; } | { kind: "minimap"; label: string; columns: number; rows: number; marks: object[]; } | { kind: "offer"; label: string; price: string; detail?: string; act?: string; command: string; input?: JSONType; } | { kind: "recipe"; label: string; inputs: object[]; output: { label: string; glyph: string; have?: number; need?: number; quantity?: number; }; command: string; input?: JSONType; } | { kind: "notice"; text: string; tone?: "success" | "error" | "info" | "warning"; } | { kind: "group"; id: string; label: string; initiallyOpen: boolean; blocks: ({ kind: "heading"; text: string; } | { kind: "text"; text: string; } | { kind: "check"; label: string; done: boolean; } | { kind: "stat"; label: string; value: string | number; glyph?: string; } | { kind: "meter"; label: string; value: number; max: number; tone?: "success" | "error" | "info" | "warning"; glyph?: string; } | { kind: "items"; label: string; columns: number; rows: number; items: object[]; } | { kind: "action"; label: string; command: string; input?: JSONType; shortcut?: string; } | { kind: "clock"; label: string; detail?: string; phase?: "day" | "dusk" | "night" | "dawn"; time?: boolean; } | { kind: "portrait"; name: string; status: string; mood?: "ok" | "warn" | "bad"; } | { kind: "minimap"; label: string; columns: number; rows: number; marks: object[]; } | { kind: "offer"; label: string; price: string; detail?: string; act?: string; command: string; input?: JSONType; } | { kind: "recipe"; label: string; inputs: object[]; output: { label: string; glyph: string; have?: number; need?: number; quantity?: number; }; command: string; input?: JSONType; } | { kind: "notice"; text: string; tone?: "success" | "error" | "info" | "warning"; })[]; }; }>

SHELL_KEYS

const SHELL_KEYS: ReadonlyMap<string, string>>

Keys the player shell already owns: the dock (Build, Orders, Zones) and the camera turn. A cartridge key may not shadow them.

WorkParticipation

const WorkParticipation: ComponentDefinition<{ automatic: boolean; }>

Player participation policy for the shared automatic work owner.

WorkPolicy

const WorkPolicy: ComponentDefinition<{ pool: string; priority: number; enabled: boolean; }>

WorkExecution

const WorkExecution: ComponentDefinition<{ pool: string; initiatingPlayer: string | null; policyId: string; }>

WorkSchedule

const WorkSchedule: ComponentDefinition<{ nextReviewTick: number; lastConsidered: number; }>

MEADOW_VERTICAL_METRES

const MEADOW_VERTICAL_METRES: 0.54 = 0.54

Metres per vertical terrain cell in the library worlds.

Functions

isReservedComponent()

isReservedComponent(id): boolean

Parameters

id

string

Returns

boolean

isNativeComponentSchema()

isNativeComponentSchema(id): boolean

Native registration and mutation authority are distinct. These schemas are installed by the kernel even when a pack does not use them. Some accept scoped authored policy/intent, so they must not become reserved writes.

Parameters

id

string

Returns

boolean

component()

component<T>>(id, options): ComponentDefinition<T>>

Type Parameters

T

T extends object

Parameters

id

`${string}.${string}`

options

version

number

fields

Readonly<Record<keyof T & string, FieldType>>

targetField?

keyof T & string

sourceRequires?

readonly `${string}.${string}`[]

targetRequires?

readonly `${string}.${string}`[]

onTargetRemoved?

RelationRemovalPolicy

allowSelf?

boolean

Returns

relation()

relation<T>>(id, options): ComponentDefinition<T>>

Type Parameters

T

T extends object

Parameters

id

`${string}.${string}`

options

version

number

fields

Readonly<Record<keyof T & string, FieldType>>

targetField

keyof T & string

sourceRequires?

readonly CapabilityReference[]

targetRequires?

readonly CapabilityReference[]

onTargetRemoved?

RelationRemovalPolicy

allowSelf?

boolean

Returns

setRelation()

setRelation<T>>(definition, source, target): ActionRequest

Type Parameters

T

T extends object

Parameters

definition

source

target

Returns

clearRelation()

clearRelation<T>>(definition, source): ActionRequest

Type Parameters

T

T extends object

Parameters

definition

source

Returns

query()

query<T>>(…components): QuerySpec<T>>

Type Parameters

T

T extends object

Parameters

components

…readonly ComponentDefinition<any>[]

Returns

QuerySpec<T>

system()

system(options): SystemDefinition

Parameters

options

SystemOptions

Returns

SystemDefinition

command()

command<TInput>>(options): GameCommandDefinition

Type Parameters

TInput

TInput

Parameters

options

Returns

GameCommandDefinition

entity()

entity(id): EntityId

Parameters

id

string

Returns

BehaviorActionDefinition

definitionCapability()

definitionCapability<T>>(id, options): ActorDefinitionCapability<T>>

Type Parameters

T

T extends object

Parameters

id

`${string}.${string}`

options

schema

ZodType<T>

externalCreation?

boolean

Returns

ActorDefinitionCapability<T>

predicate()

predicate(id, options): PredicateDefinition

Parameters

id

`${string}.${string}`

options

reads?

readonly ComponentDefinition<any>[]

facts?

readonly NativeFact[]

test

(subject, context) => boolean

Returns

PredicateDefinition

action()

action(id, options): BehaviorActionDefinition

Parameters

id

`${string}.${string}`

options

reads?

readonly ComponentDefinition<any>[]

writes?

readonly ComponentDefinition<any>[]

facts?

readonly NativeFact[]

exclusive?

string

run

(subject, context) => void

Returns

behavior()

behavior(id, define, options?): BehaviorDefinition

Prepare friendly behavior syntax into the existing checked system runtime. The callback records branches once; it never reads or mutates a live world.

Parameters

id

`${string}.${string}`

define

(scene) => void

options?

BehaviorOptions = {}

Returns

BehaviorDefinition

installActorBehaviors()

installActorBehaviors(actors): readonly SystemDefinition[]

Pack preparation: install every attached behavior exactly once, with its subject membership compiled from the actors that attached it. Distinct behaviors sharing one id fail here, before any world starts.

Parameters

actors

readonly ActorDefinition[]

Returns

readonly SystemDefinition[]

actor()

actor(id, options?): ActorDefinition

Compose an immutable actor definition; spawning remains an admitted world operation.

Parameters

id

string

options?

version?

number

Returns

blueprintModule()

blueprintModule(id, spec): BlueprintModule

Declare one room. Openings and slots are checked against its size.

Parameters

id

string

spec

size

readonly [number, number]

openings?

readonly BlueprintOpening[]

slots?

Readonly<Record<string, readonly [number, number]>>

tags?

readonly string[]

sides?

Readonly<Partial<Record<BlueprintSide, string>>>

Returns

BlueprintModule

assembleBlueprint()

assembleBlueprint(recipe): Blueprint

Join a recipe’s rooms into one building. Rooms may not overlap; a wall two rooms share becomes one piece; a doorway must open into another room, and two rooms must agree on what fills a shared wall.

Parameters

recipe

BlueprintRecipe

Returns

Blueprint

compileBlueprint()

compileBlueprint(blueprint, kit): object

A blueprint’s pieces as placement plans for a game’s own buildables. pieces names the buildable for each kind, and styles for each kind in a style (a styled piece with no buildable of its own is an error, never the plain one); groundAt gives the ground height (the support cell’s y) at a column. floor optionally names a buildable covering every room cell, emitted before the edge pieces. A piece over a column with no ground is left out and listed in unplaced.

Parameters

blueprint

Blueprint

kit

construction

Pick<Construction, "candidates">

pieces

Readonly<Record<BlueprintPiece["kind"], string>>

floor?

string

styles?

Readonly<Record<string, Readonly<Partial<Record<"wall" | "window" | "door", string>>>>>

groundAt

(x, z) => number | undefined

Returns

object

plans

readonly plans: readonly PlacementCandidate[]

unplaced

readonly unplaced: readonly (BlueprintPiece | BlueprintFloor)[]

prebuildBatches()

prebuildBatches(party, plans): readonly ActionRequest[]

Plans split into prebuild actions of at most 256 structures each.

Parameters

party

plans

readonly PlacementCandidate[]

Returns

readonly ActionRequest[]

buildable()

buildable(id, definition): ActorDefinition

Declare a buildable once. Its structure catalog entry, build-bar binding, placement ghost and staged art all derive from this one definition.

Parameters

id

string

definition

name

string = ...

The player-facing noun: “Build wall”, “stair north”.

sprites

string = ...

Sprite family; stages derive as ${sprites}.stakes|frame|finished (cells) or ${sprites}.segment.${stage}.${axis} (edges).

geometry

{ kind: "fixture"; footprint: [number, number][]; } | { kind: "aperture"; height: number; openingBottom: number; openingHeight: number; closed?: boolean; } | { kind: "floor"; } | { kind: "cover"; } | { kind: "wall"; height: number; } | { kind: "stair"; run: number; rise: number; } = environmentStructureGeometrySchema

materials

object[] = ...

workSeconds

number = ...

workReachBelowCells

number = ...

placement?

{ alignment: "fixed" | "stroke"; facing?: { north: number; east: number; south: number; west: number; }; } = ...

Optional gesture override. Omitted, the ghost, gesture and facing all derive from the geometry: boundaries stroke along a drag, everything else is fixed and turns through the four cardinal facings. Nobody authors a placement ghost; it is always the buildable’s own finished art.

placement.alignment

"fixed" | "stroke" = ...

placement.facing?

{ north: number; east: number; south: number; west: number; } = ...

placement.facing.north

number = ...

placement.facing.east

number = ...

placement.facing.south

number = ...

placement.facing.west

number = ...

ports?

object[] = ...

onRemove?

{ salvage?: object[]; emptyPorts?: string[]; } = ...

onRemove.salvage?

object[] = ...

onRemove.emptyPorts?

string[] = ...

palette?

boolean = ...

False: only a founding or a blueprint stands it (a cell’s bars, a police station’s cell door); players never plan one, so it has no build binding and the build command refuses it.

key?

string = ...

A key that picks this buildable while the build palette applies.

Returns

buildBindingDetail()

buildBindingDetail(compiled, orientation?): string

Compact build-bar copy: cost, size, gesture and facing.

Parameters

compiled

CompiledBuildable

orientation?

string

Returns

string

construction()

construction(options): Construction

The Construction extension: compile buildables once, derive every view. Its build command keeps at most 128 plans open (not yet finished) at once. Finished structures do not count toward that limit; the kernel’s caps on structure instances and cells bound how many a world can hold.

Parameters

options

ConstructionOptions

Returns

Construction

defineCartridge()

defineCartridge(spec): Cartridge

Compile one cartridge: install attached behaviors, collect components, encode the definition and environment, and derive the host variant. Every failure is thrown here, before any world starts.

Parameters

spec

CartridgeSpec

Returns

Cartridge

launch()

launch(launcher, ammunition, velocity): ActionRequest

Velocity is in world axes, relative to the launcher’s motion.

Parameters

launcher

ammunition

velocity

Returns

displace()

displace(entity, delta): ActionRequest

Bounded grounded knockback; the native owner checks obstacles and supports. A terrain walker (an actor with Traversal) is pushed as it would walk: the push stops at a wall, a closed door, a filled cell, a ledge past its step height or no floor, and the actor can be routed again from where it lands.

Parameters

entity

delta

Returns

beginEmission()

beginEmission(worker, station): ActionRequest

Parameters

worker

station

Returns

exchangeFieldWater()

exchangeFieldWater(operation, worker, vessel, cell, portions?): ActionRequest

Parameters

operation

string

worker

vessel

cell

x

number

y

number

z

number

portions?

number = 1

Returns

move()

move(entity, destination, facing?, speed?): ActionRequest

Parameters

entity

destination

facing?

number = 0

speed?

number

Returns

dropLot()

dropLot(entity, lot): ActionRequest

Parameters

entity

lot

Returns

transfer()

transfer(lot, from, to, quantity): ActionRequest

Parameters

lot

from

to

quantity

number

Returns

requestDelivery()

requestDelivery(request): ActionRequest

Parameters

request

source

destination

material

string

quantity

number

party

Returns

consume()

consume(entity, lot, quantity): ActionRequest

Parameters

entity

lot

quantity

number

Returns

extractResource()

extractResource(operation, worker, source): ActionRequest

Parameters

operation

string

worker

source

Returns

establishResourceSite()

establishResourceSite(operation, worker, site, definition, cell): ActionRequest

Parameters

operation

string

worker

site

definition

string

cell

x

number

y

number

z

number

Returns

tendResourceSite()

tendResourceSite(operation, worker, site, vessel): ActionRequest

Parameters

operation

string

worker

site

vessel

Returns

encodeDefinition()

encodeDefinition(game, components, initial?, materialCatalog, stockpileProfiles?, actors?): Uint8Array<ArrayBuffer>>

Parameters

game

string

components

readonly ComponentDefinition<any>[]

initial?

readonly SceneEntity[] = []

materialCatalog

readonly object[]

stockpileProfiles?

readonly object[] = []

actors?

readonly ActorDefinition[] = []

Returns

Uint8Array<ArrayBuffer>

cancelWork()

cancelWork(entity): ActionRequest

Parameters

entity

Returns

compileBuildable()

compileBuildable(actor): CompiledBuildable | null

Compile one actor capability set into the existing native structure owner.

Parameters

actor

ConstructionPlanOptions

Returns

CompiledBuildable | null

compileBuildableEnvironment()

compileBuildableEnvironment(environment, actors): EnvironmentDefinition

Add actor-authored structures to one environment and run its full validator.

Parameters

environment

EnvironmentDefinition

actors

readonly ActorDefinition[]

Returns

EnvironmentDefinition

constructionCandidates()

constructionCandidates(definition, alignment, raw, namespace): readonly PlacementCandidate[]

Compile a creator gesture into canonical physical proposals. The definition owns geometry; this layer owns normalization; native placement owns permission.

Parameters

definition

EnvironmentStructureDefinition

alignment

PlacementAlignment

raw

catalog

string = ...

orientation?

"north" | "east" | "south" | "west" = ...

target

{ cell: [number, number, number]; } | { area: { start: [number, number, number]; end: [number, number, number]; }; } | { edges: object[]; } = ...

namespace

string

Returns

readonly PlacementCandidate[]

constructionPlanActions()

constructionPlanActions(options): readonly ActionRequest[]

Turn checked proposals into ordinary engine actions. This resolves existing floors and duplicate sites; native action admission still rechecks all laws.

Parameters

options

Returns

readonly ActionRequest[]

constructionTarget()

constructionTarget(site): ConstructionTarget

Decode the native flat component wire into its exhaustive physical target.

Parameters

site

ConstructionSiteState

Returns

ConstructionTarget

constructionCell()

constructionCell(site): Vec3

Parameters

site

ConstructionSiteState

Returns

replaceFloor()

replaceFloor(orderId, existingFloorId, desiredCatalog): ActionRequest

Parameters

orderId

existingFloorId

desiredCatalog

string

Returns

planConstructions()

planConstructions(party, plans): ActionRequest

Parameters

party

plans

readonly PlacementCandidate[]

Returns

prebuildStructures()

prebuildStructures(party, plans): ActionRequest

Stand structures up at once, finished, with no work and no materials: the buildings a fresh world starts with (a town, a harbour, a starter base). They are ordinary finished sites afterwards: workers deconstruct them, rules break them. Issue it once (a starting rule with a saved flag, or the world’s opening actions); a restored world already has them. All the plans stand, or none do.

Parameters

party

plans

readonly PlacementCandidate[]

Returns

bindConstructionStage()

bindConstructionStage(site, contact): ActionRequest

Parameters

site

contact

Returns

setStructureOpen()

setStructureOpen(worker, site, open): ActionRequest

Request a desired aperture state; native contact and physical admission decide.

Parameters

worker

site

open

boolean

Returns

breakStructure()

breakStructure(site): ActionRequest

Break a finished structure: the native teardown deconstruction uses, but with no worker (a wall smashed, a door torn off, a dock blown apart). Any salvage the buildable declares lands as ground stock where it stood. The game decides when; the engine keeps no hit points of its own.

Parameters

site

Returns

deconstruct()

deconstruct(worker, site): ActionRequest

Parameters

worker

site

Returns

formatDiagnostic()

formatDiagnostic(diagnostic): string

VD013 <message>\n hint: <hint> — the terminal and overlay rendering.

Parameters

diagnostic

Diagnostic

Returns

string

fail()

fail(code, message, hint, path?): never

Throw one diagnostic.

Parameters

code

"VD001" | "VD002" | "VD003" | "VD004" | "VD005" | "VD006" | "VD007" | "VD008" | "VD009" | "VD010" | "VD011" | "VD012" | "VD013" | "VD014" | "VD015" | "VD016" | "VD017" | "VD020" | "VD021" | "VD022" | "VD023" | "VD024" | "VD025" | "VD030" | "VD031" | "VD032" | "VD033" | "VD034" | "VD040" | "VD041" | "VD050" | "VD051" | "VD052" | "VD060" | "VD061" | "VD070" | "VD071" | "VD072" | "VD073" | "VD074" | "VD080" | "VD083" | "VD082" | "VD081"

message

string

hint

string

path?

readonly (string | number)[] = []

Returns

never

effect()

effect<T>>(id, fields): Effect<T>>

Declare an effect record kind. Its records live keep seconds after the producer’s sweep; a consumer that runs every step sees each one once.

Type Parameters

T

T extends object

Parameters

id

`${string}.${string}`

fields

EffectFields<T>

Every field, at and seq included: { ..., at: "number", seq: "number" }.

Returns

Effect<T>

createFeedback()

createFeedback<Weapon, Simple, Swing>>(profile): Readonly<{ swing: AuthoredFeedbackCue; hit: AuthoredFeedbackCue; shot: AuthoredFeedbackCue; splatSize: number; splat: AuthoredFeedbackCue; wound: AuthoredFeedbackCue; cue: AuthoredFeedbackCue; }>

The engine constructs cues; the cartridge supplies only words, assets and tuning.

Type Parameters

Weapon

Weapon extends string

Simple

Simple extends string

Swing

Swing extends string

Parameters

profile

FeedbackProfile<Weapon, Simple, Swing>

Returns

Readonly<{ swing: AuthoredFeedbackCue; hit: AuthoredFeedbackCue; shot: AuthoredFeedbackCue; splatSize: number; splat: AuthoredFeedbackCue; wound: AuthoredFeedbackCue; cue: AuthoredFeedbackCue; }>

felt()

felt(cue, by): readonly AuthoredFeedbackCue[]

One cue split for a shared world: what everyone near it sees (the word, the flash, the sound, the bits), and what only by, the actor who landed it, fired it or took it, feels (the freeze, the slow-mo, the kick, the rumble, the screen tint). Another viewer sees the shared contact without their own screen stopping. Both name by as subject, so the owner’s client can match them to what it already predicted.

Parameters

cue

AuthoredFeedbackCue

by

string

Returns

readonly AuthoredFeedbackCue[]

hordeMovement()

hordeMovement(options?): HordeSimulation

Geometry is projected once per phase; all bodies share fields and neighbour lookup.

Parameters

options?

geometry?

{ reads: readonly `${string}.${string}`[]; project: readonly FlowGeometry[]; }

geometry.reads

readonly `${string}.${string}`[]

geometry.project

steering?

{ radius?: number; separation?: number; alignment?: number; neighbours?: number; candidates?: number; }

steering.radius?

number = ...

steering.separation?

number = ...

steering.alignment?

number = ...

steering.neighbours?

number = ...

steering.candidates?

number = ...

Returns

HordeSimulation

perceptionFrame()

perceptionFrame(input, geometry?): object

Immutable, step-local sensor frame. Games supply emitters, targets and geometry.

Parameters

input

targets

object[] = ...

sounds

object[] = ...

now

number = ...

soundBarrierLoss

number = ...

geometry?

sight

sound

Returns

object

targets

targets: readonly object[]

observe()

observe(input): object

Parameters

input

x

number = ...

z

number = ...

sight

number = ...

heardAfter

number = ...

noiseBoost

{ within: number; extra: number; } = ...

noiseBoost.within

number = ...

noiseBoost.extra

number = ...

Returns

object

visible

visible: { x: number; z: number; id: string; } | null

heard

heard: { x: number; z: number; radius: number; at: number; } | null

assignHordeSlots()

assignHordeSlots(input): ReadonlyMap<EntityId, HordeSlotAssignment>>

Nearest eligible bodies fill interchangeable slots; one body and one occupant per slot.

Parameters

input

slots

readonly HordeSlot[]

bodies

readonly HordeSlotBody[]

Returns

ReadonlyMap<EntityId, HordeSlotAssignment>

localSteering()

localSteering(input): object

Stateless local steering. Native collision remains the final movement authority.

Parameters

input

radius?

number = ...

separation?

number = ...

alignment?

number = ...

neighbours?

number = ...

candidates?

number = ...

Returns

object

advance()

advance(input): object

Parameters

input

readonly SteeringBody[]

Returns

object

motions

motions: CrowdMotion[]

neighbourChecks

neighbourChecks: number

resolveLook()

resolveLook(spec): Look

Check a cartridge’s look. Throws a coded VD diagnostic on a bad look.

Parameters

spec

LookSpec | undefined

Returns

Look

ambientLightForMood()

ambientLightForMood(look, mood): number

Brightness follows the one mood chosen by the cartridge’s presentation.

Parameters

look

Look

mood

"day" | "dusk" | "night"

Returns

number

moodAt()

moodAt(look, seconds): "day" | "dusk" | "night"

The mood a look shows at committed world time seconds: the last stop at or before it, else the look’s own mood. Full colour is always day.

Parameters

look

Look

seconds

number

Returns

"day" | "dusk" | "night"

instantiateActors()

instantiateActors(bindingId, expectedSequence, plan): ActionRequest

Parameters

bindingId

string

expectedSequence

number

plan

ActorInstantiationPlan

Returns

partyMemberIds()

partyMemberIds(read, viewer): ReadonlySet<EntityId>>

The people of a player viewer’s parties (PartyMember of a party whose OwnedBy names them): their characters, as distinct from other things they own (a party’s own bookkeeping marker, a stash).

Parameters

read

<T>(spec) => readonly QueryRow<T>[]

viewer

CommandScope

Returns

ReadonlySet<EntityId>

ownedActorIds()

ownedActorIds(read, viewer): ReadonlySet<EntityId>>

Parameters

read

<T>(spec) => readonly QueryRow<T>[]

viewer

CommandScope

Returns

ReadonlySet<EntityId>

definePhaseCycle()

definePhaseCycle<Phase>>(definitions): object

A repeating, simulation-time schedule. Games declare phases; the engine owns boundary progression. Only the returned clock needs to be saved.

Type Parameters

Phase

Phase extends string

Parameters

definitions

readonly object[]

Returns

object

seconds

seconds: number

duration

duration: (id) => number

Parameters

id

Phase

Returns

number

advance()

advance(clock, now): PhaseAdvance<Phase>>

Parameters

clock

PhaseClock<Phase>

now

number

Returns

PhaseAdvance<Phase>

requestProcess()

requestProcess(definition, station): object

Parameters

definition

string

station

Returns

object

kind

kind: "request-process"

definition

definition: string

station

station: EntityId

admitProcess()

admitProcess(process, definition, station): object

Parameters

process

definition

string

station

Returns

object

kind

kind: "admit-process"

process

process: EntityId

definition

definition: string

station

station: EntityId

place()

place(actor, options): Placement

Put an actor in the starting scene. id defaults to ${actor.id}.${n} in placement order; give one when other content refers to the entity.

Parameters

actor

options

at

Cell2

id?

string

params?

Readonly<Record<string, string | number | boolean | null>>

surface?

"sea"

Returns

Placement

compileScene()

compileScene(scene): CompiledScene

Compile placements into the fresh world’s records and surface settling.

Parameters

scene

readonly Placement[]

Returns

CompiledScene

spawn()

spawn(actor, options): ActionRequest

Spawn one actor into a running world (from a rule or a command). The receipt is the new entity’s id and makes the request idempotent.

Parameters

actor

options

receipt

string

cause

string

at

Cell2

params?

Readonly<Record<string, string | number | boolean | null>>

refs?

Readonly<Record<string, EntityId>>

Returns

TerrainPresentationDefinition

defineSeatGoal()

defineSeatGoal<F>>(goal): SeatGoal

Erase the goal’s fact shape after binding its scorer to that same shape.

Type Parameters

F

F extends Readonly<Record<string, number>>

Parameters

goal

SeatGoal<F>

Returns

SeatGoal

voxel()

voxel(input): VoxelTerrainChoice

Parameters

input

environment

EnvironmentDefinition

art

Returns

VoxelTerrainChoice

seaTerrain()

seaTerrain(input): SeaTerrainChoice

A voxel environment whose wet columns are presented at the sea line.

Parameters

input

environment

EnvironmentDefinition

art

TerrainPresentationDefinition

Returns

SeaTerrainChoice

actorTarget()

actorTarget(component): object

One actor target contract for the command parser, subject projection, and local click binding. Admission still belongs to the command’s run handler.

Parameters

component

ComponentDefinition<any>

Returns

object

input

readonly input: ZodObject<{ entity: ZodString; }>

subjects

readonly subjects: (context) => readonly EntityId[]

Parameters

context

Pick<ReadContext, "query">

Returns

readonly EntityId[]

binding

readonly binding: Pick<GameLocalBinding, "target" | "component">>

gameWindow()

gameWindow(id, spec): CartridgeWindow

Declare a game window as data. The game shell (@fungi.computer/vishnu-ui) draws it by its role with the shared kit (a floating Caps panel by default), and it gets a Whistle command ui:<id> so a key, the palette, a menu and a remote player all open it the same way.

Parameters

id

string

spec

object & object

Returns

CartridgeWindow

checkWindows()

checkWindows(windows): readonly CartridgeWindow[]

Cartridge-wide checks: unique ids and non-conflicting keys.

Parameters

windows

readonly CartridgeWindow[]

Returns

readonly CartridgeWindow[]

checkKeys()

checkKeys(windows, controls): void

Every single-key shortcut a cartridge declares (window keys and command control keys) is distinct and clear of the shell’s own keys.

Parameters

windows

readonly CartridgeWindow[]

controls

readonly object[]

Returns

void

windowContents()

windowContents(windows): (world) => readonly Readonly<{ id: string; blocks: readonly ({ kind: "heading"; text: string; } | { kind: "text"; text: string; } | { kind: "check"; label: string; done: boolean; } | { kind: "stat"; label: string; value: string | number; glyph?: string; } | { kind: "meter"; label: string; value: number; max: number; tone?: "success" | "error" | "info" | "warning"; glyph?: string; } | { kind: "items"; label: string; columns: number; rows: number; items: object[]; } | { kind: "action"; label: string; command: string; input?: JSONType; shortcut?: string; } | { kind: "clock"; label: string; detail?: string; phase?: "day" | "dusk" | "night" | "dawn"; time?: boolean; } | { kind: "portrait"; name: string; status: string; mood?: "ok" | "warn" | "bad"; } | { kind: "minimap"; label: string; columns: number; rows: number; marks: object[]; } | { kind: "offer"; label: string; price: string; detail?: string; act?: string; command: string; input?: JSONType; } | { kind: "recipe"; label: string; inputs: object[]; output: { label: string; glyph: string; have?: number; need?: number; quantity?: number; }; command: string; input?: JSONType; } | { kind: "notice"; text: string; tone?: "success" | "error" | "info" | "warning"; } | { kind: "group"; id: string; label: string; initiallyOpen: boolean; blocks: ({ kind: "heading"; text: string; } | { kind: "text"; text: string; } | { kind: "check"; label: string; done: boolean; } | { kind: "stat"; label: string; value: … | …; glyph?: … | …; } | { kind: "meter"; label: string; value: number; max: number; tone?: … | … | … | … | …; glyph?: … | …; } | { kind: "items"; label: string; columns: number; rows: number; items: …[]; } | { kind: "action"; label: string; command: string; input?: … | …; shortcut?: … | …; } | { kind: "clock"; label: string; detail?: … | …; phase?: … | … | … | … | …; time?: … | … | …; } | { kind: "portrait"; name: string; status: string; mood?: … | … | … | …; } | { kind: "minimap"; label: string; columns: number; rows: number; marks: …[]; } | { kind: "offer"; label: string; price: string; detail?: … | …; act?: … | …; command: string; input?: … | …; } | { kind: "recipe"; label: string; inputs: …[]; output: { label: …; glyph: …; have?: …; need?: …; quantity?: …; }; command: string; input?: … | …; } | { kind: "notice"; text: string; tone?: … | … | … | … | …; })[]; })[]; }>[]

Compile window bodies into the presentation projection.

Parameters

windows

readonly CartridgeWindow[]

Returns

(world) => readonly Readonly<{ id: string; blocks: readonly ({ kind: "heading"; text: string; } | { kind: "text"; text: string; } | { kind: "check"; label: string; done: boolean; } | { kind: "stat"; label: string; value: string | number; glyph?: string; } | { kind: "meter"; label: string; value: number; max: number; tone?: "success" | "error" | "info" | "warning"; glyph?: string; } | { kind: "items"; label: string; columns: number; rows: number; items: object[]; } | { kind: "action"; label: string; command: string; input?: JSONType; shortcut?: string; } | { kind: "clock"; label: string; detail?: string; phase?: "day" | "dusk" | "night" | "dawn"; time?: boolean; } | { kind: "portrait"; name: string; status: string; mood?: "ok" | "warn" | "bad"; } | { kind: "minimap"; label: string; columns: number; rows: number; marks: object[]; } | { kind: "offer"; label: string; price: string; detail?: string; act?: string; command: string; input?: JSONType; } | { kind: "recipe"; label: string; inputs: object[]; output: { label: string; glyph: string; have?: number; need?: number; quantity?: number; }; command: string; input?: JSONType; } | { kind: "notice"; text: string; tone?: "success" | "error" | "info" | "warning"; } | { kind: "group"; id: string; label: string; initiallyOpen: boolean; blocks: ({ kind: "heading"; text: string; } | { kind: "text"; text: string; } | { kind: "check"; label: string; done: boolean; } | { kind: "stat"; label: string; value: … | …; glyph?: … | …; } | { kind: "meter"; label: string; value: number; max: number; tone?: … | … | … | … | …; glyph?: … | …; } | { kind: "items"; label: string; columns: number; rows: number; items: …[]; } | { kind: "action"; label: string; command: string; input?: … | …; shortcut?: … | …; } | { kind: "clock"; label: string; detail?: … | …; phase?: … | … | … | … | …; time?: … | … | …; } | { kind: "portrait"; name: string; status: string; mood?: … | … | … | …; } | { kind: "minimap"; label: string; columns: number; rows: number; marks: …[]; } | { kind: "offer"; label: string; price: string; detail?: … | …; act?: … | …; command: string; input?: … | …; } | { kind: "recipe"; label: string; inputs: …[]; output: { label: …; glyph: …; have?: …; need?: …; quantity?: …; }; command: string; input?: … | …; } | { kind: "notice"; text: string; tone?: … | … | … | … | …; })[]; })[]; }>[]

workAttemptsFor()

workAttemptsFor(context, tasks): readonly WorkAttempt[]

Query native attempt ownership without leaking the port’s non-empty batch contract.

Parameters

context

Pick<ReadContext, "workAttempts">

tasks

readonly EntityId[]

Returns

readonly WorkAttempt[]

workAttempt()

workAttempt(context, task): WorkAttempt | null

Read the one native attempt projection for a task.

Parameters

context

Pick<ReadContext, "workAttempts">

task

Returns

WorkAttempt | null

beginRouteWorkAttempt()

beginRouteWorkAttempt(context, task, worker, destination): void

Parameters

context

Pick<WriteContext, "action">

task

worker

destination

Returns

void

interruptWorkAttempt()

interruptWorkAttempt(context, attempt, operationSequence, cause): void

Parameters

context

Pick<WriteContext, "action">

attempt

operationSequence

number

cause

WorkInterruptCause

Returns

void

retargetRouteWorkAttempt()

retargetRouteWorkAttempt(context, attempt, operationSequence, destination): void

Replace only the current route operation, preserving its attempt generation.

Parameters

context

Pick<WriteContext, "action">

attempt

operationSequence

number

destination

Returns

void

continueRouteWorkAttempt()

continueRouteWorkAttempt(context, attempt, operationSequence, destination): void

Parameters

context

Pick<WriteContext, "action"> & Pick<ReadContext, "workAttempts">

attempt

operationSequence

number

destination

Returns

void

acknowledgeWorkAttempt()

acknowledgeWorkAttempt(context, attempt, operationSequence): void

Acknowledge only the currently projected terminal operation.

Parameters

context

Pick<WriteContext, "action"> & Pick<ReadContext, "workAttempts">

attempt

operationSequence

number

Returns

void

continueDeconstructionWorkAttempt()

continueDeconstructionWorkAttempt(context, attempt, operationSequence, site, contact): void

Parameters

context

Pick<WriteContext, "action"> & Pick<ReadContext, "workAttempts">

attempt

operationSequence

number

site

ConstructionAccessContact

contact

Returns

void

continueResourceEstablishWorkAttempt()

continueResourceEstablishWorkAttempt(context, attempt, operationSequence, site, definition, cell): void

Parameters

context

Pick<WriteContext, "action"> & Pick<ReadContext, "workAttempts">

attempt

operationSequence

number

site

definition

string

cell

readonly [number, number, number]

Returns

void

continueResourceTendWorkAttempt()

continueResourceTendWorkAttempt(context, attempt, operationSequence, site, vessel): void

Parameters

context

Pick<WriteContext, "action"> & Pick<ReadContext, "workAttempts">

attempt

operationSequence

number

site

vessel

Returns

void

continueResourceExtractWorkAttempt()

continueResourceExtractWorkAttempt(context, attempt, operationSequence, source): void

Parameters

context

Pick<WriteContext, "action"> & Pick<ReadContext, "workAttempts">

attempt

operationSequence

number

source

Returns

void

continueFieldWaterWorkAttempt()

continueFieldWaterWorkAttempt(context, attempt, operationSequence, vessel, cell, direction, portions): void

Parameters

context

Pick<WriteContext, "action"> & Pick<ReadContext, "workAttempts">

attempt

operationSequence

number

vessel

cell

readonly [number, number, number]

direction

"withdraw" | "deposit"

portions

number

Returns

void

continueMaterialTransferAttempt()

continueMaterialTransferAttempt(context, attempt, operationSequence, lot, from, to, quantity): void

Continue one admitted attempt through the native material transfer owner.

Parameters

context

Pick<WriteContext, "action"> & Pick<ReadContext, "workAttempts">

attempt

operationSequence

number

lot

from

to

quantity

number

Returns

void

continueMaterialDropAttempt()

continueMaterialDropAttempt(context, attempt, operationSequence, lot): void

Continue an admitted attempt through the native ground-custody owner.

Parameters

context

Pick<WriteContext, "action"> & Pick<ReadContext, "workAttempts">

attempt

operationSequence

number

lot