API reference

See the generated API reference for the SDK exported from @fungi.computer/vishnu.

Exports

Kind	Export	Description
class	CartridgeError	Thrown by authoring factories and defineCartridge; carries every problem.
interface	Vec3
interface	MoveDestination
interface	RouteCostRequest
interface	RouteToAnyRequest
interface	WorkMaterialFacts
interface	Pose
interface	WorldPosition
interface	SupportSurface
interface	WorldPose
interface	ComponentDefinition
interface	VisualVariantRule	View-only selection of an art binding from one committed authored field.
interface	EntityRecord
interface	QuerySpec
interface	QueryRow
interface	QueryView	Retained, read-only membership in canonical identity order. Read values are shared immutable versions; make an explicit draft before editing a value. A view is a phase-local read capability, not an array or a saved world.
interface	JobStep
interface	JobPlan
interface	ActionResult
interface	Impact
interface	AdvanceResult
interface	ActionOutcome
interface	WorkAttemptKey
interface	WorkAttempt
interface	SimulationClock
interface	ProcessRequirements
interface	RandomSource
interface	ReadContext
interface	ScopedAction
interface	ScopedCreate
interface	ScopedRemove
interface	CrowdMotion	Ground-plane crowd destination, advanced by the native simulation phase.
interface	WriteContext
interface	SystemDefinition
interface	ProjectileAim
interface	CollisionFact
interface	RenderFact
interface	DeliveryActivity
interface	ActivityBinding
interface	AtmosphereSample
interface	AtmosphereSamples
interface	ConstructionReadiness
interface	PlacementCandidate
interface	PlacementDecision
interface	PlacementDecisionResponse
interface	ConstructionAccess
interface	SurfaceWaterContact
interface	TerrainPresentationDefinition
interface	ComponentReadChanges	Process-local acknowledgements of the native component reader, never save frontiers. Only the Session advances the slowest system’s read checkpoint.
interface	KernelPort
interface	InterestVisualGroup	Fixed visual groups are observed only when their complete footprint is in range.
interface	GamePack
interface	GameScenario	A named dev/test setup for a fresh world (see `GamePack.scenarios`).
interface	GameCommandResult
interface	GameCommandDefinition
interface	GamePackTransport
interface	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.
interface	SystemOptions
interface	ActorCapability
interface	ActorDefinitionCapability	Authoring-only capability compiled by an owning engine module.
interface	ActorDefinitionCapabilityValue
interface	ActorInput
interface	ActorDefinition
interface	PredicateDefinition	A named, deterministic question used by an authored behavior branch.
interface	BehaviorActionDefinition	A named proposal producer. The existing system/session owners commit its work.
interface	BehaviorDefinition	A prepared actor behavior. It is not a system: pack preparation installs it once for every actor that attaches it (`installActorBehaviors`).
interface	BehaviorSelection
interface	BehaviorScene
interface	BehaviorOptions
interface	ActorBuilder
interface	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.
interface	BlueprintModule	One room: `size` is [width along x, depth along z] in cells.
interface	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.
interface	BlueprintRecipe
interface	BlueprintPiece	One wall, door or window: the face after `cell` along `axis`, in the style a room gave it (absent: the plain piece).
interface	BlueprintRoom
interface	BlueprintSlot
interface	Blueprint	An assembled building: its pieces, rooms and slots, in a fixed order.
interface	BlueprintLevel	An authored storey. Room assembly and piece compilation have distinct owners.
interface	BlueprintStair	Stair origin on its lower level; the buildable declares its run and rise.
interface	BlueprintKit
interface	ConstructionOptions
interface	ConstructionVisual	One staged construction sprite, ready for the visual projection.
interface	Construction	Everything the Construction extension derives from its buildables.
interface	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.
interface	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).
interface	CartridgeShelf	How the hub shelf lists a cartridge. Presentation only.
interface	SelectionCard	A selected object whose visual starts with `visualPrefix` gets its own named card in the selection panel.
interface	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.
interface	CartridgePage	What the player shell shows around the world. Read-only presentation.
interface	CartridgeSpec
interface	Cartridge	The checked, compiled cartridge. The only thing the Worker, page and host accept.
interface	SceneEntity
interface	CompiledBuildable
interface	ConstructionPlanOptions
interface	ConstructionSiteState
interface	Diagnostic
interface	Effect
interface	FeedbackStrength	A bounded response to contact strength; no simulation clock or RNG.
interface	AnchoredFeedback
interface	ShotFeedback
interface	SwingFeedback
interface	ContactFeedback
interface	SplatFeedback
interface	FeedbackProfile
interface	FlowBarrier	A structure standing across a face, and how much it would take.
interface	FlowGeometry	Navigation facts: blocked cells and weighted breakable edges are game data.
interface	FlowNavigation
interface	HordeSlot
interface	HordeSlotBody
interface	HordeSlotAssignment
interface	LookSpec	How a cartridge looks. Everything is optional: a cartridge without a palette renders in full colour, exactly as the engine always has.
interface	MoodStop	From `at` simulation seconds on, the view shows `mood`.
interface	PhaseClock
interface	PhaseAdvance
interface	Placement	One actor in the fresh world. Compiled by defineCartridge, never spawned.
interface	CompiledScene	The fresh world compiled from a scene.
interface	EntityClass
interface	SeatView	The same named world view is available to every authorized seat.
interface	SeatGoal	A cartridge-authored challenge and its committed-state scoring rule.
interface	SeatDefinition
interface	VoxelTerrainChoice
interface	SeaTerrainChoice
interface	CartridgeWindow
interface	GenerationFingerprint
interface	WorldSpec	What a cartridge’s `world` needs; meadow() fills it in.
type alias	EntityId	Public boundary between authored TypeScript and the authoritative kernel.
type alias	ComponentId
type alias	GameId
type alias	RouteCostResult
type alias	RouteToAnyResult
type alias	FieldType
type alias	RelationRemovalPolicy
type alias	ComponentValue
type alias	WriteIntent
type alias	JobEntityBinding
type alias	JobOperation
type alias	JobContinuation
type alias	CardinalOrientation
type alias	EdgeTarget
type alias	ConstructionTarget
type alias	ActionRequest
type alias	WorkActivityRef
type alias	WorkInterruptCause
type alias	WorkBlockReason
type alias	WorkOutcome
type alias	WorkAttemptPhase
type alias	ProcessInputPolicy
type alias	ProcessInputDisposition
type alias	NativeFact	Native read doors available to authored decisions beyond ECS/query state.
type alias	CommandScope
type alias	PartyJoinIdentity
type alias	SpawnArgument	Spawn arguments bind values or existing entities; slots and joining players belong to party join.
type alias	ActorArgument
type alias	ActorInstantiationPlan
type alias	PartyJoinCapability
type alias	ActionScope
type alias	GameCommandContext
type alias	VisualPlacement
type alias	DeliveryActivityPhase	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.
type alias	ActivityKind
type alias	KernelSnapshot
type alias	ConstructionReadinessStatus
type alias	ConstructionAccessContact
type alias	DeconstructionAccess
type alias	PhysicalContact
type alias	TerrainSurface
type alias	TerrainSurfaceCover
type alias	StructureSurface
type alias	FloorOperation
type alias	FloorOperationRequest
type alias	TerrainChangeSet
type alias	GameLocalBinding
type alias	JsonValue
type alias	ComponentValues
type alias	GameCommandAvailability
type alias	EnvironmentFacts
type alias	AuthoredFeedbackCue	What `WriteContext.cue()` accepts: a feedback cue before the session stamps its sequence and commit time.
type alias	CartridgeAudio
type alias	CapabilityReference
type alias	ActorInitial
type alias	BlueprintSide	A side of a module: north is -z, south +z, west -x, east +x.
type alias	BlueprintOpeningKind	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).
type alias	CameraFollowPolicy
type alias	CartridgeCameraPolicy
type alias	BankPath
type alias	PailPoses
type alias	VisualBindings
type alias	StaticVisualBinding	A static frame by its path in the art (the bank’s, or a cartridge pack’s under its root).
type alias	CartridgeDirectControl	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.
type alias	HostFeature
type alias	ComponentFields	One component’s field values as they cross into the kernel.
type alias	BuildableDefinition
type alias	ConstructionProposalInput
type alias	DiagnosticCode
type alias	EffectFields	Fields declared by an effect, including its world time and step order.
type alias	FlowCell
type alias	PresentationLight
type alias	CartridgeLighting
type alias	Mood
type alias	TerrainLook
type alias	Look	A checked look: either full colour, or a palette with its dither and mood.
type alias	Cell2	A ground cell: [x, z]. The actor settles onto the surface there.
type alias	ActorParams	Values for an actor’s declared inputs, by input name.
type alias	SeatFacts
type alias	TerrainChoice
type alias	WindowWorld	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" }`.
type alias	RunCommand	The single command door: `"garden:plantSeeds"` or `"ui:garden.goals"`.
type alias	WindowBody	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.
type alias	WorldgenAssembly
type alias	RoomDefinition
type alias	BuildingDefinition
type alias	WorldgenCheck
type alias	BuildingLayout
type alias	BuildingGraph
type alias	CompileRequest
type alias	CompiledBuilding
type alias	GenerationIdentity
type alias	PopulationPolicy
type alias	ChunkPolicy
type alias	ChunkWindow
type alias	ChunkFacts
type alias	GenerationKey
type alias	ChunkPlan
type alias	WindowBlock	One block of a game window: plain data a person or a model can write.
type alias	WindowRole	Where the shell shows a window.
type alias	WindowOpening	When a window first opens on its own.
constant	RESERVED_COMPONENTS
constant	sampledSoundSchema	A sampled replacement for one existing feedback sound name. URLs are resolved by the cartridge bundler; variants cycle without simulation RNG.
constant	cartridgeAudioSchema	View-only audio bank. Omission preserves the engine’s procedural recipes. Named samples replace that recipe; a failed sample stays silent.
constant	actorInput	Declared instance inputs; templates bind these to checked component fields.
constant	actorInputSchema	Parses an actor input placeholder inside an initial component value.
constant	ActorKind	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.
constant	cameraFollowSchema	Presentation tuning only; following never changes actor movement or aim.
constant	cartridgeCameraSchema	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.
constant	HOST_FEATURES	Engine features a host switches on for the shared worlds it opens.
constant	Collider	Physical collision dimensions are independent of a sprite’s bounds.
constant	Launcher
constant	ImpactMaterial	Contact policy supplied by a game; collision geometry remains independent.
constant	Body	Native movement capability; game systems may query it but cannot write it.
constant	Emitter	Native finite-emission capability; catalog admission remains native-owned.
constant	Container	Native carrying capacity; authored systems may query but cannot write it.
constant	Traversal	Authored walking geometry; native routing owns its interpretation and state.
constant	Position
constant	Visual	Native authored sprite identity. Presentation projections must not replace it.
constant	Support
constant	Surface
constant	MaterialLot
constant	Hands	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.
constant	VesselCapability	Native vessel eligibility; physical capability is authored as content and consumed by the native field-water planner.
constant	LotWater
constant	SupplyAllocation	Native reservation for one exact material portion. Physical custody remains in MaterialLot; this record exposes the durable planner obligation.
constant	DeliveryRequest	Durable intent submitted with requestDelivery; native allocation rows expose reserved and delivered portions without authored worker choreography.
constant	FiniteResource
constant	JobTaskWork	Native durable effort for a generic job task; authored code may query it for progress presentation but cannot write it.
constant	ResourceSite
constant	Destination
constant	placedAt	A Position declared without values is bound where the actor is placed or spawned: these are the inputs the compiled template exposes for it.
constant	ExcavationWork	Native progress is observable but cannot be written by authored systems.
constant	ExcavationOrder
constant	Buildable	A structure actor is created by native construction, on its existing site identity.
constant	constructionProposalInput	Friendly gesture input. Physical admission remains native and transactional.
constant	SealedContainer	Native custody is observable; authored writes cannot lock or unlock goods.
constant	ConstructionSite	The site owns earned effort; active worker ownership lives in WorkAttempt.
constant	FloorReplacement
constant	DeconstructionOrder	Native-owned teardown intent projected for game UI and save inspection.
constant	DIAGNOSTICS	The stable catalog. A code never changes meaning once published.
constant	FLOW_NEIGHBOURS
constant	HordeTarget	Saved autonomous intent. An empty profile is a direct local destination.
constant	presentationLightSchema	Presentation lights never participate in simulation sight or noise.
constant	cartridgeLightingSchema	Small, bounded authoring data; select committed visuals, not game callbacks.
constant	MOODS	The light a world is shown in. Every mood’s sky and light come from the declared palette.
constant	moodSchema	Parses a mood from untrusted input (a URL parameter, a tool call).
constant	terrainLookSchema
constant	FULL_COLOUR	Full colour: no palette constraint.
constant	Party	Gameplay group identity. Membership and ownership are separate facts.
constant	OwnedBy	Stable player property. Access rules decide which operations it permits.
constant	PartyMember	A person belongs to this party without duplicating their physical identity.
constant	OwnedByParty	Party ownership for property and stationary stores.
constant	StagedProcess
constant	FieldWaterWork	Native durable field-water acquisition intent. Once its lot is withdrawn, the native owner replaces this record with SupplyAllocation.
constant	ResourceOrder	Engine-owned durable intent for one tended resource lifecycle.
constant	Spawned	Where the kernel keeps a spawned entity’s cause and request digest.
constant	terrainChoiceSchema
constant	block
constant	SHELL_KEYS	Keys the player shell already owns: the dock (Build, Orders, Zones) and the camera turn. A cartridge key may not shadow them.
constant	WorkParticipation	Player participation policy for the shared automatic work owner.
constant	WorkPolicy
constant	WorkExecution
constant	WorkSchedule
constant	worldgenAssemblySchema
constant	roomDefinitionSchema
constant	buildingDefinitionSchema
constant	worldgenCheckSchema
constant	buildingLayoutSchema
constant	buildingGraphSchema
constant	compileRequestSchema
constant	generationIdentitySchema
constant	populationPolicySchema
constant	chunkPolicySchema
constant	chunkWindowSchema
constant	chunkFactsSchema
constant	generationKeySchema
constant	generationKeyResultSchema
constant	chunkPlanSchema
constant	MEADOW_VERTICAL_METRES	Metres per vertical terrain cell in the library worlds.
function	isReservedComponent()
function	isNativeComponentSchema()	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.
function	component()
function	relation()	Register a one-target relation through the same component definition path.
function	setRelation()
function	clearRelation()
function	query()
function	system()
function	command()
function	entity()
function	definitionCapability()
function	predicate()
function	action()
function	behavior()	Prepare friendly behavior syntax into the existing checked system runtime. The callback records branches once; it never reads or mutates a live world.
function	installActorBehaviors()	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.
function	actor()	Compose an immutable actor definition; spawning remains an admitted world operation.
function	blueprintModule()	Declare one room. Openings and slots are checked against its size.
function	assembleBlueprint()	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.
function	compileBlueprint()	Compile a ground-level blueprint through the same native owner as storeys.
function	compileBlueprintLevels()	Rust compiles floors, facades, roofs and stairs bottom-up, leaves stairwells open and rejects unsupported upper rooms. TS supplies declarations and samples; construction keeps its existing site identity and transactional admission.
function	prebuildBatches()	Plans split into prebuild actions of at most 256 structures each.
function	buildable()	Declare a buildable once. Its structure catalog entry, build-bar binding, placement ghost and staged art all derive from this one definition.
function	buildBindingDetail()	Compact build-bar copy: cost, size, gesture and facing.
function	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.
function	defineCartridge()	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.
function	launch()	Velocity is in world axes, relative to the launcher’s motion.
function	displace()	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.
function	beginEmission()
function	exchangeFieldWater()
function	move()
function	dropLot()
function	transfer()
function	requestDelivery()
function	consume()
function	extractResource()
function	establishResourceSite()
function	tendResourceSite()
function	encodeDefinition()
function	cancelWork()
function	compileBuildable()	Compile one actor capability set into the existing native structure owner.
function	compileBuildableEnvironment()	Add actor-authored structures to one environment and run its full validator.
function	constructionCandidates()	Compile a creator gesture into canonical physical proposals. The definition owns geometry; this layer owns normalization; native placement owns permission.
function	constructionPlanActions()	Turn checked proposals into ordinary engine actions. This resolves existing floors and duplicate sites; native action admission still rechecks all laws.
function	constructionTarget()	Decode the native flat component wire into its exhaustive physical target.
function	constructionCell()
function	replaceFloor()
function	planConstructions()
function	prebuildStructures()	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.
function	bindConstructionStage()
function	setStructureOpen()	Request a desired aperture state; native contact and physical admission decide.
function	breakStructure()	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.
function	deconstruct()
function	formatDiagnostic()	`VD013 <message>\n hint: <hint>` — the terminal and overlay rendering.
function	fail()	Throw one diagnostic.
function	effect()	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.
function	createFeedback()	The engine constructs cues; the cartridge supplies only words, assets and tuning.
function	felt()	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.
function	hordeMovement()	Geometry is projected once per phase; all bodies share fields and neighbour lookup.
function	perceptionFrame()	Immutable, step-local sensor frame. Games supply emitters, targets and geometry.
function	assignHordeSlots()	Nearest eligible bodies fill interchangeable slots; one body and one occupant per slot.
function	localSteering()	Stateless local steering. Native collision remains the final movement authority.
function	resolveLook()	Check a cartridge’s look. Throws a coded VD diagnostic on a bad look.
function	ambientLightForMood()	Brightness follows the one mood chosen by the cartridge’s presentation.
function	moodAt()	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.
function	instantiateActors()
function	partyMemberIds()	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).
function	ownedActorIds()
function	definePhaseCycle()	A repeating, simulation-time schedule. Games declare phases; the engine owns boundary progression. Only the returned clock needs to be saved.
function	requestProcess()
function	admitProcess()
function	place()	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.
function	compileScene()	Compile placements into the fresh world’s records and surface settling.
function	spawn()	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. A cell chooses terrain height; a native standing contact preserves its support height and is checked for clearance and occupancy before spawning.
function	defineSeatGoal()	Erase the goal’s fact shape after binding its scorer to that same shape.
function	voxel()
function	seaTerrain()	A voxel environment whose wet columns are presented at the sea line.
function	actorTarget()	One actor target contract for the command parser, subject projection, and local click binding. Admission still belongs to the command’s run handler.
function	gameWindow()	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.
function	checkWindows()	Cartridge-wide checks: unique ids and non-conflicting keys.
function	checkKeys()	Every single-key shortcut a cartridge declares (window keys and command control keys) is distinct and clear of the shell’s own keys.
function	windowContents()	Compile window bodies into the presentation projection.
function	workAttemptsFor()	Query native attempt ownership without leaking the port’s non-empty batch contract.
function	workAttempt()	Read the one native attempt projection for a task.
function	beginRouteWorkAttempt()
function	interruptWorkAttempt()
function	retargetRouteWorkAttempt()	Replace only the current route operation, preserving its attempt generation.
function	continueRouteWorkAttempt()
function	acknowledgeWorkAttempt()	Acknowledge only the currently projected terminal operation.
function	continueDeconstructionWorkAttempt()
function	continueResourceEstablishWorkAttempt()
function	continueResourceTendWorkAttempt()
function	continueResourceExtractWorkAttempt()
function	continueFieldWaterWorkAttempt()
function	continueMaterialTransferAttempt()	Continue one admitted attempt through the native material transfer owner.
function	continueMaterialDropAttempt()	Continue an admitted attempt through the native ground-custody owner.
function	checkRoom()	JSON syntax and authored geometry are decoded together at the native boundary.
function	checkBuilding()
function	compileBuilding()	Rust compiles all geometry and bounded host actions; the action owner decodes them.
function	parseGenerationKey()	serde parses authoring JSON; Zod parses the kernel’s typed wire result.
function	planChunk()
function	chunkGroundAt()	Bounded presentation cache; generation and road geometry stay native.
function	compileChunkLot()	Uses the same native layout/rotation/compiler as first-wake construction.
function	meadow()	A generated grassy world: soil over stone, rolling from `seed`, `radius` cells out from the origin. Everything a cartridge’s `world` needs.
function	sea()	A chart sea with a rectangular sand shore in native terrain.

CartridgeErrorclass

Thrown by authoring factories and defineCartridge; carries every problem.

Extends

Error

Constructors

Constructor

new CartridgeError(diagnostics): CartridgeError;

Parameters

Parameter	Type
`diagnostics`	`readonly Diagnostic[]`

Returns

CartridgeError

Overrides

Error.constructor;

Properties

diagnostics

readonly diagnostics: readonly Diagnostic[];

Vec3interface

Properties

x

readonly x: number;

y

readonly y: number;

z

readonly z: number;

MoveDestinationinterface

Extends

Vec3

Properties

x

readonly x: number;

Inherited from

Vec3.x

y

readonly y: number;

Inherited from

Vec3.y

z

readonly z: number;

Inherited from

Vec3.z

frame

readonly frame: EntityId | null;

RouteCostRequestinterface

Properties

actor

readonly actor: EntityId;

target

readonly target: MoveDestination;

excavationTarget?

readonly optional excavationTarget?: readonly [number, number, number];

Native excavation contact must be possible from the proposed approach.

RouteToAnyRequestinterface

Properties

actor

readonly actor: EntityId;

targets

readonly targets: readonly MoveDestination[];

excavationTarget?

readonly optional excavationTarget?: readonly [number, number, number];

Native excavation contact must be possible from the selected approach.

WorkMaterialFactsinterface

Properties

version

readonly version: 1;

containers

readonly containers: readonly object[];

lots

readonly lots: readonly object[];

Poseinterface

Properties

position

readonly position: Vec3;

facing

readonly facing: number;

WorldPositioninterface

Extends

Vec3

Properties

x

readonly x: number;

Inherited from

Vec3.x

y

readonly y: number;

Inherited from

Vec3.y

z

readonly z: number;

Inherited from

Vec3.z

facing

readonly facing: number;

SupportSurfaceinterface

Properties

minX

readonly minX: number;

maxX

readonly maxX: number;

minZ

readonly minZ: number;

maxZ

readonly maxZ: number;

height

readonly height: number;

WorldPoseinterface

Properties

id

readonly id: EntityId;

local

readonly local: WorldPosition;

world

readonly world: WorldPosition;

support

readonly support: EntityId | null;

surface

readonly surface: SupportSurface | null;

ComponentDefinitioninterface

Type Parameters

Type Parameter
`T` extends `object`

Properties

id

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

version

readonly version: number;

fields

readonly fields: Readonly<Record<keyof T & string, FieldType>>;

targetField?

readonly optional targetField?: keyof T & string;

The single entity field targeted by this registered relation, when present.

sourceRequires?

readonly optional sourceRequires?: readonly `${string}.${string}`[];

Capability IDs required on the source and target relation endpoints.

targetRequires?

readonly optional targetRequires?: readonly `${string}.${string}`[];

onTargetRemoved?

readonly optional onTargetRemoved?: RelationRemovalPolicy;

allowSelf?

readonly optional allowSelf?: boolean;

validate

readonly validate: (value) => value is T;

Parameters

Parameter	Type
`value`	`T \| JsonValue`

Returns

value is T

VisualVariantRuleinterface

View-only selection of an art binding from one committed authored field.

Properties

visual

readonly visual: string;

component

readonly component: ComponentDefinition<any>;

field

readonly field: string;

cases

readonly cases: Readonly<Record<string, string>>;

EntityRecordinterface

Properties

id

readonly id: EntityId;

components

readonly components: Readonly<Record<ComponentId, ComponentValues>>;

QuerySpecinterface

Type Parameters

Type Parameter	Default type
`T` extends `object`	`object`

Properties

components

readonly components: readonly ComponentDefinition<any>[];

__value?

readonly optional __value?: T;

QueryRowinterface

Type Parameters

Type Parameter	Default type
`_T` extends `object`	`object`

Properties

id

readonly id: EntityId;

get

readonly get: <V>(definition) => Readonly<V>;

Type Parameters

Type Parameter
`V` extends `object`

Parameters

Parameter	Type
`definition`	`ComponentDefinition<V>`

Returns

Readonly<V>

QueryViewinterface

Retained, read-only membership in canonical identity order. Read values are shared immutable versions; make an explicit draft before editing a value. A view is a phase-local read capability, not an array or a saved world.

Extends

Iterable<QueryRow<T>>

Type Parameters

Type Parameter	Default type
`T` extends `object`	`object`

Properties

size

readonly size: number;

Methods

get()

get(id): QueryRow<T> | undefined;

Parameters

Parameter	Type
`id`	`string`

Returns

QueryRow<T> | undefined

first()

first(): QueryRow<T> | undefined;

Returns

QueryRow<T> | undefined

JobStepinterface

Properties

key

readonly key: string;

after

readonly after: string | null;

operation

readonly operation: JobOperation;

continuation?

readonly optional continuation?: JobContinuation;

JobPlaninterface

Properties

definition

readonly definition: string;

definitionVersion

readonly definitionVersion: number;

steps

readonly steps: readonly JobStep[];

ActionResultinterface

Properties

accepted

readonly accepted: boolean;

reason?

readonly optional reason?: string | null;

projectileId?

readonly optional projectileId?: EntityId;

launchPoint?

readonly optional launchPoint?: Vec3;

entityId?

readonly optional entityId?: EntityId;

revision

readonly revision: number;

attempt?

readonly optional attempt?: WorkAttemptKey;

Impactinterface

Properties

id

readonly id: string;

sequence

readonly sequence: number;

projectileId?

readonly optional projectileId?: EntityId;

sourceId

readonly sourceId: EntityId;

targetId

readonly targetId: EntityId;

time

readonly time: number;

point

readonly point: Vec3;

normal

readonly normal: Vec3;

velocity

readonly velocity: Vec3;

AdvanceResultinterface

Properties

revision

readonly revision: number;

results

readonly results: readonly ActionResult[];

impacts

readonly impacts: readonly Impact[];

ActionOutcomeinterface

Properties

action

readonly action: ActionRequest;

result

readonly result: ActionResult;

WorkAttemptKeyinterface

Properties

task

readonly task: EntityId;

generation

readonly generation: number;

WorkAttemptinterface

Properties

continuationOwner

readonly continuationOwner: "external" | "native";

key

readonly key: WorkAttemptKey;

worker

readonly worker: EntityId;

execution

readonly execution: WorkExecution;

phase

readonly phase: WorkAttemptPhase;

SimulationClockinterface

Properties

now

readonly now: number;

delta

readonly delta: number;

tick

readonly tick: number;

ProcessRequirementsinterface

Properties

definition

readonly definition: string;

version

readonly version: number;

stationCatalog

readonly stationCatalog: string;

inputs

readonly inputs: readonly object[];

stages

readonly stages: readonly object[];

phase

readonly phase: "blocked" | "complete" | "working" | "waiting";

RandomSourceinterface

Methods

next()

next(): number;

Returns

number

ReadContextinterface

Extended by

WriteContext

Properties

clock

readonly clock: SimulationClock;

outcomes

readonly outcomes: readonly ActionOutcome[];

random

readonly random: RandomSource;

impacts

readonly impacts: readonly Impact[];

workAttempts?

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

Parameters

Parameter	Type
`taskIds`	`readonly EntityId[]`

Returns

readonly WorkAttempt[]

workAttemptForWorker

readonly workAttemptForWorker: (worker) => WorkAttempt | null;

Parameters

Parameter	Type
`worker`	`EntityId`

Returns

WorkAttempt | null

processRequirements

readonly processRequirements: (definition, station) => ProcessRequirements;

Parameters

Parameter	Type
`definition`	`string`
`station`	`EntityId`

Returns

ProcessRequirements

floorOperations

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

Parameters

Parameter	Type
`requests`	`readonly FloorOperationRequest[]`

Returns

readonly FloorOperation[]

Methods

flowFields()

flowFields(geometry): FlowNavigation;

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

Parameters

Parameter	Type
`geometry`	`FlowGeometry`

Returns

FlowNavigation

query()

query<T>(spec): QueryView<T>;

Type Parameters

Type Parameter
`T` extends `object`

Parameters

Parameter	Type
`spec`	`QuerySpec<T>`

Returns

QueryView<T>

workMaterialFacts()

workMaterialFacts(): WorkMaterialFacts;

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

Returns

WorkMaterialFacts

worldPoses()

worldPoses(entities): readonly WorldPose[];

Parameters

Parameter	Type
`entities`	`readonly EntityId[]`

Returns

readonly WorldPose[]

routeCosts()

routeCosts(requests): readonly RouteCostResult[];

Parameters

Parameter	Type
`requests`	`readonly RouteCostRequest[]`

Returns

readonly RouteCostResult[]

routeToAny()

routeToAny(request): RouteToAnyResult;

Parameters

Parameter	Type
`request`	`RouteToAnyRequest`

Returns

RouteToAnyResult

transferContacts()

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

Parameters

Parameter	Type
`request`	`{ worker: EntityId; container: EntityId; }`
`request.worker`	`EntityId`
`request.container`	`EntityId`

Returns

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

physicalContacts()

physicalContacts(cells): readonly PhysicalContact[];

Parameters

Parameter	Type
`cells`	`readonly [number, number, number][]`

Returns

readonly PhysicalContact[]

environmentFacts()

environmentFacts(): object;

Returns

object

Name	Type	Default value
`terrainRevision`	`number`	-
`chunks?`	`object`	-
`chunks.policy`	`object`	`chunkPolicySchema`
`chunks.policy.identity`	`object`	`generationIdentitySchema`
`chunks.policy.identity.seed`	`string`	-
`chunks.policy.identity.version`	`"worldgen-v1"`	-
`chunks.policy.identity.kitHash`	`string`	-
`chunks.policy.focusComponent`	`string`	-
`chunks.policy.chunkCells`	`number`	-
`chunks.policy.windowCells`	`number`	-
`chunks.policy.prefetchRings`	`number`	-
`chunks.policy.batchesPerStep`	`number`	-
`chunks.policy.population?`	`object`	-
`chunks.policy.population.party`	`string`	-
`chunks.policy.population.townRadius`	`number`	-
`chunks.policy.population.fringeChunks`	`number`	-
`chunks.policy.population.fringePercent`	`number`	-
`chunks.policy.population.ruralPercent`	`number`	-
`chunks.policy.population.decorationPiecesPerStep`	`number`	-
`chunks.policy.population.rooms`	`object[]`	-
`chunks.policy.population.slotKinds`	`string[]`	-
`chunks.policy.population.buildings`	`object[]`	-
`chunks.policy.population.kit`	`object`	`compileRequestSchema.shape.kit`
`chunks.policy.population.kit.wall`	`string`	-
`chunks.policy.population.kit.door`	`string`	-
`chunks.policy.population.kit.window`	`string`	-
`chunks.policy.population.kit.floor`	`string`	-
`chunks.policy.population.kit.roof`	`string`	-
`chunks.policy.population.kit.stair`	`string`	-
`chunks.policy.population.kit.styles`	`Record<string, { wall: string; door: string; window: string; }>`	-
`chunks.defaultWindow`	`object`	`chunkWindowSchema`
`chunks.defaultWindow.minX`	`number`	-
`chunks.defaultWindow.maxX`	`number`	-
`chunks.defaultWindow.minZ`	`number`	-
`chunks.defaultWindow.maxZ`	`number`	-
`chunks.windows`	`object[]`	-
`chunks.materializedCount`	`number`	-
`chunks.exhausted`	`boolean`	-
`chunks.queuedCount`	`number`	-
`placementRevision`	`number`	-
`totalKg`	`number`	-
`residualKg`	`number`	-
`initialTotalKg`	`number`	-
`boundaryKg`	`number`	-
`cells`	`object[]`	-
`emissions`	`object[]`	-

atmosphereSamples()

atmosphereSamples(cells): AtmosphereSamples;

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

Parameters

Parameter	Type
`cells`	`readonly [number, number, number][]`

Returns

AtmosphereSamples

constructionReadiness()

constructionReadiness(sites): readonly ConstructionReadiness[];

Parameters

Parameter	Type
`sites`	`readonly EntityId[]`

Returns

readonly ConstructionReadiness[]

constructionAccess()

constructionAccess(sites): readonly ConstructionAccess[];

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

Parameters

Parameter	Type
`sites`	`readonly EntityId[]`

Returns

readonly ConstructionAccess[]

deconstructionAccess()

deconstructionAccess(sites): readonly DeconstructionAccess[];

Parameters

Parameter	Type
`sites`	`readonly EntityId[]`

Returns

readonly DeconstructionAccess[]

terrainMaterials()

terrainMaterials(cells): readonly number[];

Parameters

Parameter	Type
`cells`	`readonly [number, number, number][]`

Returns

readonly number[]

terrainSurfaces()

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

Parameters

Parameter	Type
`columns`	`readonly [number, number][]`

Returns

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

structureSurfaces()

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

Visible horizontal faces, including non-standing covers; not movement authority.

Parameters

Parameter	Type
`columns`	`readonly [number, number][]`

Returns

readonly readonly StructureSurface[][]

waterContacts()

waterContacts(centers): readonly object[];

Parameters

Parameter	Type
`centers`	`readonly [number, number, number][]`

Returns

readonly object[]

ScopedActioninterface

Properties

scope

readonly scope: ActionScope;

request

readonly request: ActionRequest;

ScopedCreateinterface

Properties

scope

readonly scope: ActionScope;

record

readonly record: EntityRecord;

ScopedRemoveinterface

Properties

scope

readonly scope: ActionScope;

entity

readonly entity: EntityId;

CrowdMotioninterface

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;

WriteContextinterface

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

Parameter	Type
`taskIds`	`readonly EntityId[]`

Returns

readonly WorkAttempt[]

Inherited from

ReadContext.workAttempts

workAttemptForWorker

readonly workAttemptForWorker: (worker) => WorkAttempt | null;

Parameters

Parameter	Type
`worker`	`EntityId`

Returns

WorkAttempt | null

Inherited from

ReadContext.workAttemptForWorker

processRequirements

readonly processRequirements: (definition, station) => ProcessRequirements;

Parameters

Parameter	Type
`definition`	`string`
`station`	`EntityId`

Returns

ProcessRequirements

Inherited from

ReadContext.processRequirements

floorOperations

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

Parameters

Parameter	Type
`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

Parameter	Type
`geometry`	`FlowGeometry`

Returns

FlowNavigation

Inherited from

ReadContext.flowFields

query()

query<T>(spec): QueryView<T>;

Type Parameters

Type Parameter
`T` extends `object`

Parameters

Parameter	Type
`spec`	`QuerySpec<T>`

Returns

QueryView<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

Parameter	Type
`entities`	`readonly EntityId[]`

Returns

readonly WorldPose[]

Inherited from

ReadContext.worldPoses

routeCosts()

routeCosts(requests): readonly RouteCostResult[];

Parameters

Parameter	Type
`requests`	`readonly RouteCostRequest[]`

Returns

readonly RouteCostResult[]

Inherited from

ReadContext.routeCosts

routeToAny()

routeToAny(request): RouteToAnyResult;

Parameters

Parameter	Type
`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

Parameter	Type
`request`	`{ worker: EntityId; container: EntityId; }`
`request.worker`	`EntityId`
`request.container`	`EntityId`

Returns

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

Inherited from

ReadContext.transferContacts

physicalContacts()

physicalContacts(cells): readonly PhysicalContact[];

Parameters

Parameter	Type
`cells`	`readonly [number, number, number][]`

Returns

readonly PhysicalContact[]

Inherited from

ReadContext.physicalContacts

environmentFacts()

environmentFacts(): object;

Returns

object

Name	Type	Default value
`terrainRevision`	`number`	-
`chunks?`	`object`	-
`chunks.policy`	`object`	`chunkPolicySchema`
`chunks.policy.identity`	`object`	`generationIdentitySchema`
`chunks.policy.identity.seed`	`string`	-
`chunks.policy.identity.version`	`"worldgen-v1"`	-
`chunks.policy.identity.kitHash`	`string`	-
`chunks.policy.focusComponent`	`string`	-
`chunks.policy.chunkCells`	`number`	-
`chunks.policy.windowCells`	`number`	-
`chunks.policy.prefetchRings`	`number`	-
`chunks.policy.batchesPerStep`	`number`	-
`chunks.policy.population?`	`object`	-
`chunks.policy.population.party`	`string`	-
`chunks.policy.population.townRadius`	`number`	-
`chunks.policy.population.fringeChunks`	`number`	-
`chunks.policy.population.fringePercent`	`number`	-
`chunks.policy.population.ruralPercent`	`number`	-
`chunks.policy.population.decorationPiecesPerStep`	`number`	-
`chunks.policy.population.rooms`	`object[]`	-
`chunks.policy.population.slotKinds`	`string[]`	-
`chunks.policy.population.buildings`	`object[]`	-
`chunks.policy.population.kit`	`object`	`compileRequestSchema.shape.kit`
`chunks.policy.population.kit.wall`	`string`	-
`chunks.policy.population.kit.door`	`string`	-
`chunks.policy.population.kit.window`	`string`	-
`chunks.policy.population.kit.floor`	`string`	-
`chunks.policy.population.kit.roof`	`string`	-
`chunks.policy.population.kit.stair`	`string`	-
`chunks.policy.population.kit.styles`	`Record<string, { wall: string; door: string; window: string; }>`	-
`chunks.defaultWindow`	`object`	`chunkWindowSchema`
`chunks.defaultWindow.minX`	`number`	-
`chunks.defaultWindow.maxX`	`number`	-
`chunks.defaultWindow.minZ`	`number`	-
`chunks.defaultWindow.maxZ`	`number`	-
`chunks.windows`	`object[]`	-
`chunks.materializedCount`	`number`	-
`chunks.exhausted`	`boolean`	-
`chunks.queuedCount`	`number`	-
`placementRevision`	`number`	-
`totalKg`	`number`	-
`residualKg`	`number`	-
`initialTotalKg`	`number`	-
`boundaryKg`	`number`	-
`cells`	`object[]`	-
`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

Parameter	Type
`cells`	`readonly [number, number, number][]`

Returns

AtmosphereSamples

Inherited from

ReadContext.atmosphereSamples

constructionReadiness()

constructionReadiness(sites): readonly ConstructionReadiness[];

Parameters

Parameter	Type
`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

Parameter	Type
`sites`	`readonly EntityId[]`

Returns

readonly ConstructionAccess[]

Inherited from

ReadContext.constructionAccess

deconstructionAccess()

deconstructionAccess(sites): readonly DeconstructionAccess[];

Parameters

Parameter	Type
`sites`	`readonly EntityId[]`

Returns

readonly DeconstructionAccess[]

Inherited from

ReadContext.deconstructionAccess

terrainMaterials()

terrainMaterials(cells): readonly number[];

Parameters

Parameter	Type
`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;
  art?: string;
  cover?: Readonly<{
     kind: string;
     condition: string;
     height: string;
  }>;
}>
  | null)[];

Parameters

Parameter	Type
`columns`	`readonly [number, number][]`

Returns

Inherited from

ReadContext.terrainSurfaces

structureSurfaces()

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

Visible horizontal faces, including non-standing covers; not movement authority.

Parameters

Parameter	Type
`columns`	`readonly [number, number][]`

Returns

readonly readonly StructureSurface[][]

Inherited from

ReadContext.structureSurfaces

waterContacts()

waterContacts(centers): readonly object[];

Parameters

Parameter	Type
`centers`	`readonly [number, number, number][]`

Returns

readonly object[]

Inherited from

ReadContext.waterContacts

changed()

changed<T>(spec): QueryView<T>;

Matching rows added or changed since this system’s last successful run. A new/restored world starts with all matching rows. Like query, reads are phase-local and include admitted pending edits.

Type Parameters

Type Parameter
`T` extends `object`

Parameters

Parameter	Type
`spec`	`QuerySpec<T>`

Returns

QueryView<T>

removed()

removed<T>(component): readonly EntityId[];

Component removals since this system’s last successful run in this world. Includes current pending removals. Restore establishes a new baseline, not historical removal replay; this is not a durable event stream.

Type Parameters

Type Parameter
`T` extends `object`

Parameters

Parameter	Type
`component`	`ComponentDefinition<T>`

Returns

readonly EntityId[]

checkpoint()

checkpoint(name): void;

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

Parameters

Parameter	Type
`name`	`string`

Returns

void

write()

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

Type Parameters

Type Parameter
`T` extends `object`

Parameters

Parameter	Type
`definition`	`ComponentDefinition<T>`
`entity`	`EntityId`
`value`	`T`

Returns

void

action()

action(request, scope?): void;

Parameters

Parameter	Type
`request`	`ActionRequest`
`scope?`	`ActionScope`

Returns

void

createAuthoredEntity()

createAuthoredEntity(record, scope?): void;

Parameters

Parameter	Type
`record`	`EntityRecord`
`scope?`	`ActionScope`

Returns

void

removeAuthoredEntity()

removeAuthoredEntity(id): void;

Parameters

Parameter	Type
`id`	`EntityId`

Returns

void

retireActor()

retireActor(id): void;

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

Parameters

Parameter	Type
`id`	`EntityId`

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

Parameter	Type
`cue`	`AuthoredFeedbackCue`

Returns

void

SystemDefinitioninterface

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

Parameter	Type
`context`	`WriteContext`

Returns

void

ProjectileAiminterface

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;

CollisionFactinterface

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: "ground" | "stop" | "pierce";

resistance

readonly resistance: number;

restitution

readonly restitution: number;

friction

readonly friction: number;

embedSpeed

readonly embedSpeed: number;

RenderFactinterface

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;

DeliveryActivityinterface

Properties

kind

readonly kind: "delivery";

phase

readonly phase: DeliveryActivityPhase;

material

readonly material: string;

target

readonly target: readonly [number, number];

ActivityBindinginterface

Properties

actor

readonly actor: EntityId;

kind

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

target

readonly target: readonly [number, number];

progress?

readonly optional progress?: number;

AtmosphereSampleinterface

Properties

volumeId

readonly volumeId: string;

temperatureC

readonly temperatureC: number;

smokeKgM3

readonly smokeKgM3: number;

AtmosphereSamplesinterface

Properties

revision

readonly revision: number;

geometryRevision

readonly geometryRevision: number;

samples

readonly samples: readonly (AtmosphereSample | null)[];

ConstructionReadinessinterface

Properties

site

readonly site: EntityId;

status

readonly status: ConstructionReadinessStatus;

reason?

readonly optional reason?: "missingStructuralSupport";

PlacementCandidateinterface

Properties

site

readonly site: EntityId;

catalog

readonly catalog: string;

target

readonly target: ConstructionTarget;

PlacementDecisioninterface

Properties

site

readonly site: EntityId;

status

readonly status: "ready" | "rejected";

reason?

readonly optional reason?: string;

PlacementDecisionResponseinterface

Properties

revision

readonly revision: number;

placementRevision

readonly placementRevision: number;

decisions

readonly decisions: readonly PlacementDecision[];

ConstructionAccessinterface

Properties

site

readonly site: EntityId;

support

readonly support: ConstructionReadinessStatus;

materialsReady

readonly materialsReady: boolean;

blockedActors

readonly blockedActors: readonly EntityId[];

contacts

readonly contacts: readonly ConstructionAccessContact[];

SurfaceWaterContactinterface

Properties

cell

readonly cell: readonly [number, number, number];

groundwaterHead

readonly groundwaterHead: number;

TerrainPresentationDefinitioninterface

Properties

materials

readonly materials: readonly object[];

Content-owned art family for each physical material slot.

generatedArt?

readonly optional generatedArt?: (input) => string | null;

Content-owned appearance of unchanged generated ground, never physical material.

Parameters

Parameter	Type
`input`	`{ cell: readonly [number, number, number]; material: number; worldSeed: string; worldIdentity: string; }`
`input.cell`	`readonly [number, number, number]`
`input.material`	`number`
`input.worldSeed`	`string`
`input.worldIdentity`	`string`

Returns

string | null

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

Parameter	Type
`input`	`{ cell: readonly [number, number, number]; material: number; generatedTop: number; worldSeed: string; worldIdentity: string; }`
`input.cell`	`readonly [number, number, number]`
`input.material`	`number`
`input.generatedTop`	`number`
`input.worldSeed`	`string`
`input.worldIdentity`	`string`

Returns

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

ComponentReadChangesinterface

Process-local acknowledgements of the native component reader, never save frontiers. Only the Session advances the slowest system’s read checkpoint.

Properties

version

readonly version: number;

Methods

changed()

changed<T>(spec, since): readonly EntityId[];

Type Parameters

Type Parameter
`T` extends `object`

Parameters

Parameter	Type
`spec`	`QuerySpec<T>`
`since`	`number`

Returns

readonly EntityId[]

removed()

removed<T>(component, since): readonly EntityId[];

Type Parameters

Type Parameter
`T` extends `object`

Parameters

Parameter	Type
`component`	`ComponentDefinition<T>`
`since`	`number`

Returns

readonly EntityId[]

release()

release(through): void;

Parameters

Parameter	Type
`through`	`number`

Returns

void

KernelPortinterface

Properties

componentReads

readonly componentReads: ComponentReadChanges;

partyJoinIdentity

readonly partyJoinIdentity: (bindingId) => PartyJoinIdentity;

Parameters

Parameter	Type
`bindingId`	`string`

Returns

PartyJoinIdentity

floorOperations

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

Parameters

Parameter	Type
`requests`	`readonly FloorOperationRequest[]`

Returns

readonly FloorOperation[]

transferContacts

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

Parameters

Parameter	Type
`request`	`{ worker: EntityId; container: EntityId; }`
`request.worker`	`EntityId`
`request.container`	`EntityId`

Returns

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

physicalContacts

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

Parameters

Parameter	Type
`cells`	`readonly [number, number, number][]`

Returns

readonly PhysicalContact[]

routeCosts

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

Parameters

Parameter	Type
`requests`	`readonly RouteCostRequest[]`

Returns

readonly RouteCostResult[]

routeToAny

readonly routeToAny: (request) => RouteToAnyResult;

Parameters

Parameter	Type
`request`	`RouteToAnyRequest`

Returns

RouteToAnyResult

dispose

readonly dispose: () => void;

Returns

void

load

readonly load: (definition) => void;

Parameters

Parameter	Type
`definition`	`Uint8Array`

Returns

void

loadEnvironment

readonly loadEnvironment: (definition) => void;

Parameters

Parameter	Type
`definition`	`Uint8Array`

Returns

void

environmentFacts

readonly environmentFacts: () => object;

Returns

object

Name	Type	Default value
`terrainRevision`	`number`	-
`chunks?`	`object`	-
`chunks.policy`	`object`	`chunkPolicySchema`
`chunks.policy.identity`	`object`	`generationIdentitySchema`
`chunks.policy.identity.seed`	`string`	-
`chunks.policy.identity.version`	`"worldgen-v1"`	-
`chunks.policy.identity.kitHash`	`string`	-
`chunks.policy.focusComponent`	`string`	-
`chunks.policy.chunkCells`	`number`	-
`chunks.policy.windowCells`	`number`	-
`chunks.policy.prefetchRings`	`number`	-
`chunks.policy.batchesPerStep`	`number`	-
`chunks.policy.population?`	`object`	-
`chunks.policy.population.party`	`string`	-
`chunks.policy.population.townRadius`	`number`	-
`chunks.policy.population.fringeChunks`	`number`	-
`chunks.policy.population.fringePercent`	`number`	-
`chunks.policy.population.ruralPercent`	`number`	-
`chunks.policy.population.decorationPiecesPerStep`	`number`	-
`chunks.policy.population.rooms`	`object[]`	-
`chunks.policy.population.slotKinds`	`string[]`	-
`chunks.policy.population.buildings`	`object[]`	-
`chunks.policy.population.kit`	`object`	`compileRequestSchema.shape.kit`
`chunks.policy.population.kit.wall`	`string`	-
`chunks.policy.population.kit.door`	`string`	-
`chunks.policy.population.kit.window`	`string`	-
`chunks.policy.population.kit.floor`	`string`	-
`chunks.policy.population.kit.roof`	`string`	-
`chunks.policy.population.kit.stair`	`string`	-
`chunks.policy.population.kit.styles`	`Record<string, { wall: string; door: string; window: string; }>`	-
`chunks.defaultWindow`	`object`	`chunkWindowSchema`
`chunks.defaultWindow.minX`	`number`	-
`chunks.defaultWindow.maxX`	`number`	-
`chunks.defaultWindow.minZ`	`number`	-
`chunks.defaultWindow.maxZ`	`number`	-
`chunks.windows`	`object[]`	-
`chunks.materializedCount`	`number`	-
`chunks.exhausted`	`boolean`	-
`chunks.queuedCount`	`number`	-
`placementRevision`	`number`	-
`totalKg`	`number`	-
`residualKg`	`number`	-
`initialTotalKg`	`number`	-
`boundaryKg`	`number`	-
`cells`	`object[]`	-
`emissions`	`object[]`	-

atmosphereSamples

readonly atmosphereSamples: (cells) => AtmosphereSamples;

Parameters

Parameter	Type
`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

Parameter	Type
`sites`	`readonly EntityId[]`

Returns

readonly ConstructionReadiness[]

placementDecisions

readonly placementDecisions: (party, candidates) => PlacementDecisionResponse;

Advisory native geometry decision; command admission always rechecks.

Parameters

Parameter	Type
`party`	`EntityId`
`candidates`	`readonly PlacementCandidate[]`

Returns

PlacementDecisionResponse

constructionAccess

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

Parameters

Parameter	Type
`sites`	`readonly EntityId[]`

Returns

readonly ConstructionAccess[]

deconstructionAccess

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

Parameters

Parameter	Type
`sites`	`readonly EntityId[]`

Returns

readonly DeconstructionAccess[]

terrainMaterials

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

Parameters

Parameter	Type
`cells`	`readonly [number, number, number][]`

Returns

readonly number[]

terrainSurfaces

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

Parameters

Parameter	Type
`columns`	`readonly [number, number][]`

Returns

surfaceWaterTable

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

Parameters

Parameter	Type
`columns`	`readonly [number, number][]`

Returns

readonly (SurfaceWaterContact | null)[]

waterContacts

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

Parameters

Parameter	Type
`centers`	`readonly [number, number, number][]`

Returns

readonly object[]

terrainChanges

readonly terrainChanges: (sinceRevision) => TerrainChangeSet;

Parameters

Parameter	Type
`sinceRevision`	`number`

Returns

TerrainChangeSet

structureSurfaces

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

Parameters

Parameter	Type
`columns`	`readonly [number, number][]`

Returns

readonly readonly StructureSurface[][]

query

readonly query: <T>(spec) => QueryView<T>;

Rows whose get returns a value its component definition has checked. Values may be shared between calls; callers copy before editing.

Type Parameters

Type Parameter
`T` extends `object`

Parameters

Parameter	Type
`spec`	`QuerySpec<T>`

Returns

QueryView<T>

workMaterialFacts

readonly workMaterialFacts: () => WorkMaterialFacts;

Compact native owner projection for shared work/material planning.

Returns

WorkMaterialFacts

workAttempts

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

Parameters

Parameter	Type
`taskIds`	`readonly EntityId[]`

Returns

readonly WorkAttempt[]

workAttemptForWorker

readonly workAttemptForWorker: (worker) => WorkAttempt | null;

Parameters

Parameter	Type
`worker`	`EntityId`

Returns

WorkAttempt | null

processRequirements

readonly processRequirements: (definition, station) => ProcessRequirements;

Parameters

Parameter	Type
`definition`	`string`
`station`	`EntityId`

Returns

ProcessRequirements

entityMembership

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

Parameters

Parameter	Type
`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

Parameter	Type
`delta`	`number`
`writes`	`readonly WriteIntent[]`
`actions`	`readonly ScopedAction[]`
`options?`	`{ creates?: readonly ScopedCreate[]; removes?: readonly ScopedRemove[]; retires?: readonly EntityId[]; crowd?: readonly CrowdMotion[]; }`
`options.creates?`	`readonly ScopedCreate[]`
`options.removes?`	`readonly ScopedRemove[]`
`options.retires?`	`readonly EntityId[]`
`options.crowd?`	`readonly CrowdMotion[]`

Returns

AdvanceResult

advance

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

Parameters

Parameter	Type
`delta`	`number`
`writes`	`readonly WriteIntent[]`
`actions`	`readonly ScopedAction[]`
`options?`	`{ creates?: readonly ScopedCreate[]; removes?: readonly ScopedRemove[]; retires?: readonly EntityId[]; crowd?: readonly CrowdMotion[]; }`
`options.creates?`	`readonly ScopedCreate[]`
`options.removes?`	`readonly ScopedRemove[]`
`options.retires?`	`readonly EntityId[]`
`options.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

Parameter	Type
`snapshot`	`KernelRecordSnapshot`

Returns

void

renderFacts

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

Retained immutable native records. Observation copies the selected public frame; consumers must replace records rather than mutate their fields.

Parameters

Parameter	Type
`limit?`	`number`

Returns

readonly RenderFact[]

worldPoses

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

Parameters

Parameter	Type
`entities`	`readonly EntityId[]`

Returns

readonly WorldPose[]

InterestVisualGroupinterface

Fixed visual groups are observed only when their complete footprint is in range.

Properties

minX

readonly minX: number;

maxX

readonly maxX: number;

minZ

readonly minZ: number;

maxZ

readonly maxZ: number;

visuals

readonly visuals: readonly string[];

ready?

readonly optional ready?: boolean;

Withhold every piece until the generated building is complete.

GamePackinterface

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;

groups?

readonly optional groups?: readonly InterestVisualGroup[];

dynamicGroups?

readonly optional dynamicGroups?: (context) => readonly InterestVisualGroup[];

Parameters

Parameter	Type
`context`	`Pick<ReadContext, "query">`

Returns

readonly InterestVisualGroup[]

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

Parameter	Type
`context`	`Pick<ReadContext, "query">`

Returns

number

GameScenariointerface

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

Properties

actions

readonly actions: readonly ActionRequest[];

commands

readonly commands: readonly object[];

GameCommandResultinterface

Properties

actions

readonly actions: readonly ActionRequest[];

writes

readonly writes: readonly WriteIntent[];

creates?

readonly optional creates?: readonly EntityRecord[];

removes?

readonly optional removes?: readonly EntityId[];

GameCommandDefinitioninterface

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

Parameter	Type
`context`	`Pick<ReadContext, "query">`

Returns

GameCommandAvailability

subjects?

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

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

Parameters

Parameter	Type
`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

Parameter	Type
`context`	`GameCommandContext`
`input`	`JsonValue \| undefined`

Returns

GameCommandResult

GamePackTransportinterface

Properties

id

readonly id: string;

version

readonly version: number;

definition

readonly definition: Uint8Array;

FeedbackSwinginterface

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;

SystemOptionsinterface

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

Parameter	Type
`context`	`WriteContext`

Returns

void

ActorCapabilityinterface

Properties

component

readonly component: ComponentDefinition<any>;

initial?

readonly optional initial?: object;

ActorDefinitionCapabilityinterface

Authoring-only capability compiled by an owning engine module.

Type Parameters

Type Parameter
`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.

ActorDefinitionCapabilityValueinterface

Properties

capability

readonly capability: ActorDefinitionCapability<any>;

value

readonly value: object;

ActorInputinterface

Properties

kind

readonly kind: "actor-input";

name

readonly name: string;

type

readonly type: FieldType | "actor-reference";

ActorDefinitioninterface

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

Type Parameter
`T` extends `object`

Parameters

Parameter	Type
`component`	`ComponentDefinition<T>`
`initial?`	`ActorInitial<T>`

Returns

ActorDefinition

Inherited from

ActorBuilder.with

Call Signature

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

Type Parameters

Type Parameter
`T` extends `object`

Parameters

Parameter	Type
`capability`	`ActorDefinitionCapability<T>`
`value`	`T`

Returns

ActorDefinition

Inherited from

ActorBuilder.with

behaves()

behaves(...behaviors): ActorDefinition;

Parameters

Parameter	Type
…`behaviors`	`readonly BehaviorDefinition[]`

Returns

ActorDefinition

Inherited from

ActorBuilder.behaves

PredicateDefinitioninterface

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

Parameter	Type
`subject`	`QueryRow`
`context`	`ReadContext`

Returns

boolean

BehaviorActionDefinitioninterface

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

Parameter	Type
`subject`	`QueryRow`
`context`	`WriteContext`

Returns

void

BehaviorDefinitioninterface

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.

BehaviorSelectioninterface

Methods

where()

where(...predicates): BehaviorSelection;

Parameters

Parameter	Type
…`predicates`	`readonly PredicateDefinition[]`

Returns

BehaviorSelection

do()

do(action): void;

Parameters

Parameter	Type
`action`	`BehaviorActionDefinition`

Returns

void

BehaviorSceneinterface

Methods

find()

find(...subjects): BehaviorSelection;

Parameters

Parameter	Type
…`subjects`	`readonly ComponentDefinition<any>[]`

Returns

BehaviorSelection

BehaviorOptionsinterface

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.

ActorBuilderinterface

Extended by

ActorDefinition

Methods

with()

Call Signature

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

Type Parameters

Type Parameter
`T` extends `object`

Parameters

Parameter	Type
`component`	`ComponentDefinition<T>`
`initial?`	`ActorInitial<T>`

Returns

ActorDefinition

Call Signature

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

Type Parameters

Type Parameter
`T` extends `object`

Parameters

Parameter	Type
`capability`	`ActorDefinitionCapability<T>`
`value`	`T`

Returns

ActorDefinition

behaves()

behaves(...behaviors): ActorDefinition;

Parameters

Parameter	Type
…`behaviors`	`readonly BehaviorDefinition[]`

Returns

ActorDefinition

BlueprintOpeninginterface

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;

BlueprintModuleinterface

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).

BlueprintPlacementinterface

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;

BlueprintRecipeinterface

Properties

modules

readonly modules: readonly BlueprintPlacement[];

BlueprintPieceinterface

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: "door" | "window" | "wall";

cell

readonly cell: readonly [number, number];

axis

readonly axis: "x" | "z";

style?

readonly optional style?: string;

BlueprintRoominterface

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.

BlueprintSlotinterface

Properties

room

readonly room: number;

module

readonly module: string;

name

readonly name: string;

at

readonly at: readonly [number, number];

Blueprintinterface

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[];

BlueprintLevelinterface

An authored storey. Room assembly and piece compilation have distinct owners.

Properties

level

readonly level: 0 | 1 | 2;

blueprint

readonly blueprint: Blueprint;

BlueprintStairinterface

Stair origin on its lower level; the buildable declares its run and rise.

Properties

level

readonly level: 0 | 1;

cell

readonly cell: readonly [number, number];

facing

readonly facing: BlueprintSide;

BlueprintKitinterface

Properties

construction

readonly construction: Pick<Construction, "candidates" | "catalog">;

pieces

readonly pieces: Readonly<Record<BlueprintPiece["kind"], string>>;

floor?

readonly optional floor?: string;

roof?

readonly optional roof?: string;

stair?

readonly optional stair?: string;

stairs?

readonly optional stairs?: readonly BlueprintStair[];

storeyRows?

readonly optional storeyRows?: number;

styles?

readonly optional styles?: Readonly<Record<string, Readonly<Partial<Record<"door" | "window" | "wall", string>>>>>;

groundAt

readonly groundAt: (x, z) => number | undefined;

Native terrain’s support row at each authored column.

Parameters

Parameter	Type
`x`	`number`
`z`	`number`

Returns

number | undefined

ConstructionOptionsinterface

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

Parameter	Type
`context`	`Pick<GameCommandContext, "query" \| "scope">`

Returns

EntityId

restyle?

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

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

Parameters

Parameter	Type
`context`	`Pick<ReadContext, "query" \| "environmentFacts">`

Returns

ReadonlyMap<EntityId, string>

ConstructionVisualinterface

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;

Constructioninterface

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

Parameter	Type
`input`	`{ catalog: string; orientation?: "north" \| "east" \| "south" \| "west"; target: \| { cell: [number, number, number]; } \| { area: { start: [number, number, number]; end: [number, number, number]; }; } \| { edges: object[]; }; }`
`input.catalog`	`string`
`input.orientation?`	`"north" \| "east" \| "south" \| "west"`
`input.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

Parameter	Type
`context`	`Pick<ReadContext, "query">`

Returns

readonly ConstructionVisual[]

presented

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

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

Parameters

Parameter	Type
`context`	`Pick<ReadContext, "query" \| "environmentFacts">`

Returns

readonly ConstructionVisual[]

environment

readonly environment: (base) => EnvironmentDefinition;

Add the buildables to a world’s structure catalog.

Parameters

Parameter	Type
`base`	`EnvironmentDefinition`

Returns

EnvironmentDefinition

VisualBindinginterface

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.

CartridgeArtPackFilesinterface

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;

partsUrl?

readonly optional partsUrl?: string;

Checked render fragments of existing frames; never physical occupants.

pageUrls

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

CartridgeShelfinterface

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.

localOnly?

readonly optional localOnly?: true;

A local scene has no hosted world; keep its shelf launch browser-local.

genre

readonly genre: string;

blurb

readonly blurb: string;

cover

readonly cover: object;

src

readonly src: string;

alt

readonly alt: string;

SelectionCardinterface

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;

CartridgeAiminterface

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;

CartridgePageinterface

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

Properties

subtitle

readonly subtitle: string;

savedWorldNotice?

readonly optional savedWorldNotice?: string;

Player-facing copy when an earlier saved world starts fresh.

camera

readonly camera: CartridgeCameraPolicy;

directControl?

readonly optional directControl?: CartridgeDirectControl;

aim?

readonly optional aim?: CartridgeAim;

theme?

readonly optional theme?:
  | "vishnu"
  | "light"
  | "dark"
  | "codec"
  | "embed"
  | "readout"
  | "readout-night"
  | "latte"
  | "mocha"
  | "field-guide"
  | "field-guide-night"
  | "embed-dark"
  | "phosphor"
  | "paper"
  | "ember"
  | "tide"
  | "tape"
  | "sunrise"
  | "pirate-radio"
  | "pirate-radio-night"
  | "consulting"
  | "consulting-ink"
  | "consulting-night"
  | "consulting-night-ink"
  | "consulting-riso-latte"
  | "consulting-riso-latte-ink"
  | "consulting-riso-glomzy"
  | "consulting-riso-glomzy-ink"
  | "coin"
  | "coin-night"
  | "chamfer";

A tint or complete Stipe palette over the shared game paper.

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.

groundArt?

readonly optional groundArt?: object;

Checked static top frames projected onto native smooth ground, not actors.

pack

readonly pack: CartridgeArtPackFiles;

families

readonly families: Readonly<Record<string, readonly (string | number)[]>>;

Each named family supplies two one-metre top frames through the prop camera.

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;

groups?

readonly optional groups?: readonly InterestVisualGroup[];

dynamicGroups?

readonly optional dynamicGroups?: (context) => readonly InterestVisualGroup[];

Parameters

Parameter	Type
`context`	`Pick<ReadContext, "query">`

Returns

readonly InterestVisualGroup[]

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

Parameter	Type
`input`	`{ catalog: string; orientation?: "north" \| "east" \| "south" \| "west"; target: \| { cell: [number, number, number]; } \| { area: { start: [number, number, number]; end: [number, number, number]; }; } \| { edges: object[]; }; }`
`input.catalog`	`string`
`input.orientation?`	`"north" \| "east" \| "south" \| "west"`
`input.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.

CartridgeSpecinterface

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

Parameter	Type
`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 (Maosaico 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

Parameter	Type
`world`	`WindowWorld`

Returns

"day" | "dusk" | "night"

look?

readonly optional look?: LookSpec;

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

Cartridgeinterface

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.

SceneEntityinterface

Properties

id

readonly id: EntityId;

components

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

CompiledBuildableinterface

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).

ConstructionPlanOptionsinterface

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

Parameter	Type
`requests`	`readonly object[]`

Returns

readonly FloorOperation[]

replacementGenerations

readonly replacementGenerations: ReadonlyMap<EntityId, number>;

replacementId

readonly replacementId: (floor, generation) => EntityId;

Parameters

Parameter	Type
`floor`	`EntityId`
`generation`	`number`

Returns

EntityId

ConstructionSiteStateinterface

Properties

catalog

catalog: string;

targetKind

targetKind: "edge" | "cell";

targetX

targetX: number;

targetY

targetY: number;

targetZ

targetZ: number;

targetDirection

targetDirection: "x" | "z" | CardinalOrientation;

seconds

seconds: number;

phase

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

Diagnosticinterface

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"
  | "VD085"
  | "VD086"
  | "VD087"
  | "VD088"
  | "VD089"
  | "VD090"
  | "VD091"
  | "VD081"
  | "VD092"
  | "VD084";

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].

Effectinterface

Type Parameters

Type Parameter
`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

Parameter	Type
`context`	`Pick<WriteContext, "createAuthoredEntity">`
`key`	`string`
`value`	`T`
`at`	`number`

Returns

void

all()

all(context): T & object[];

Every live record, oldest first.

Parameters

Parameter	Type
`context`	`Pick<ReadContext, "query">`

Returns

T & object[]

since()

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

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

Parameters

Parameter	Type
`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

Parameter	Type
`context`	`Pick<ReadContext, "query"> & Pick<WriteContext, "removeAuthoredEntity">`
`now`	`number`
`keep`	`number`

Returns

void

FeedbackStrengthinterface

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;

AnchoredFeedbackinterface

Extended by

ShotFeedback

Properties

height

readonly height: number;

cue

readonly cue: AuthoredFeedbackCue;

ShotFeedbackinterface

Extends

AnchoredFeedback

Properties

height

readonly height: number;

Inherited from

AnchoredFeedback.height

cue

readonly cue: AuthoredFeedbackCue;

Inherited from

AnchoredFeedback.cue

forward

readonly forward: number;

recoil

readonly recoil: number;

muzzleArt?

readonly optional muzzleArt?: readonly FeedbackArtPath[];

SwingFeedbackinterface

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;

ContactFeedbackinterface

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;

SplatFeedbackinterface

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;

FeedbackProfileinterface

Type Parameters

Type Parameter	Default type
`Weapon` extends `string`	`string`
`Simple` extends `string`	`string`
`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>>;

FlowBarrierinterface

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

Properties

site

readonly site: string;

cost

readonly cost: number;

FlowGeometryinterface

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

Properties

profile

readonly profile: string;

radius

readonly radius: number;

center

readonly center: FlowCell;

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>;

FlowNavigationinterface

Methods

height()

height(cell): number | undefined;

Parameters

Parameter	Type
`cell`	`FlowCell`

Returns

number | undefined

crossing()

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

Parameters

Parameter	Type
`from`	`FlowCell`
`to`	`FlowCell`

Returns

FlowBarrier | "corner" | null

next()

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

Parameters

Parameter	Type
`goal`	`FlowCell`
`from`	`FlowCell`

Returns

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

HordeSlotinterface

Properties

id

readonly id: string;

x

readonly x: number;

z

readonly z: number;

reach

readonly reach: number;

HordeSlotBodyinterface

Properties

id

readonly id: EntityId;

x

readonly x: number;

z

readonly z: number;

eligible

readonly eligible: readonly string[];

HordeSlotAssignmentinterface

Properties

slot

readonly slot: HordeSlot;

arrived

readonly arrived: boolean;

LookSpecinterface

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.

MoodStopinterface

From at simulation seconds on, the view shows mood.

Properties

at

readonly at: number;

mood

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

PhaseClockinterface

Extended by

PhaseAdvance

Type Parameters

Type Parameter
`Phase` extends `string`

Properties

phase

readonly phase: Phase;

cycle

readonly cycle: number;

phaseAt

readonly phaseAt: number;

PhaseAdvanceinterface

Extends

PhaseClock<Phase>

Type Parameters

Type Parameter
`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.

Placementinterface

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";

CompiledSceneinterface

The fresh world compiled from a scene.

Properties

initial

readonly initial: readonly SceneEntity[];

placements

readonly placements: readonly InitialSurfacePlacement[];

EntityClassinterface

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;

SeatViewinterface

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

Parameter	Type
`reads`	`SeatReads`
`scope`	`CommandScope \| undefined`

Returns

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

terrainClass()

terrainClass(surface): TerrainClass;

Parameters

Parameter	Type
`surface`	`TerrainSurface`

Returns

TerrainClass

classify()

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

Parameters

Parameter	Type
`reads`	`SeatReads`

Returns

ReadonlyMap<EntityId, EntityClass>

buildableTitle()

buildableTitle(catalog): string;

Parameters

Parameter	Type
`catalog`	`string`

Returns

string

SeatGoalinterface

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

Type Parameters

Type Parameter	Default type
`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

Parameter	Type
`reads`	`SeatReads`

Returns

F

outcome()

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

Parameters

Parameter	Type
`start`	`F`
`end`	`F`

Returns

SeatOutcome<F>

SeatDefinitioninterface

Properties

view

readonly view: SeatView;

grants

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

goals

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

VoxelTerrainChoiceinterface

Properties

kind

readonly kind: "voxel";

environment

readonly environment: EnvironmentDefinition;

art

readonly art: TerrainPresentationDefinition;

SeaTerrainChoiceinterface

Properties

kind

readonly kind: "sea";

environment

readonly environment: EnvironmentDefinition;

art

readonly art: TerrainPresentationDefinition;

CartridgeWindowinterface

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;

theme?

optional theme?:
  | "vishnu"
  | "light"
  | "dark"
  | "codec"
  | "embed"
  | "readout"
  | "readout-night"
  | "latte"
  | "mocha"
  | "field-guide"
  | "field-guide-night"
  | "embed-dark"
  | "phosphor"
  | "paper"
  | "ember"
  | "tide"
  | "tape"
  | "sunrise"
  | "pirate-radio"
  | "pirate-radio-night"
  | "consulting"
  | "consulting-ink"
  | "consulting-night"
  | "consulting-night-ink"
  | "consulting-riso-latte"
  | "consulting-riso-latte-ink"
  | "consulting-riso-glomzy"
  | "consulting-riso-glomzy-ink"
  | "coin"
  | "coin-night"
  | "chamfer";

Inherited from

WindowDeclaration.theme;

role

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

Inherited from

WindowDeclaration.role;

end?

optional end?: object;

pause

pause: "local" | "none";

illustration?

optional illustration?: "dawn" | "recording";

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: "presented-content";
  repeat?: boolean;
}
  | {
  on: "time";
  seconds: number;
};

Inherited from

WindowDeclaration.opens;

size

size: object;

width

width: number;

height

height: number;

Inherited from

WindowDeclaration.size;

GenerationFingerprintinterface

Properties

key

readonly key: object;

identity

identity: object = generationIdentitySchema;

identity.seed

seed: string;

identity.version

version: "worldgen-v1";

identity.kitHash

kitHash: string;

layer

layer: string;

id

id: string;

digest

readonly digest: string;

WorldSpecinterface

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

Properties

materials

readonly materials: readonly object[];

terrain

readonly terrain: TerrainChoice;

EntityIdtype alias

type EntityId = string & object;

Public boundary between authored TypeScript and the authoritative kernel.

Type Declaration

Name	Type
`__entityId`	`unique symbol`

ComponentIdtype alias

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

GameIdtype alias

type GameId = string;

RouteCostResulttype alias

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

RouteToAnyResulttype alias

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

FieldTypetype alias

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

RelationRemovalPolicytype alias

type RelationRemovalPolicy = "detach" | "restrict";

ComponentValuetype alias

type ComponentValue<T> = object;

Type Parameters

Type Parameter
`T`

Properties

id

readonly id: EntityId;

value

readonly value: T;

WriteIntenttype alias

type WriteIntent = object;

Properties

component

readonly component: ComponentId;

entity

readonly entity: EntityId;

value

readonly value: JsonValue;

JobEntityBindingtype alias

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

JobOperationtype alias

type 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;
    };

JobContinuationtype alias

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

CardinalOrientationtype alias

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

EdgeTargettype alias

type EdgeTarget = object;

Properties

cell

readonly cell: readonly [number, number, number];

axis

readonly axis: "x" | "z";

ConstructionTargettype alias

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

ActionRequesttype alias

type ActionRequest =
  | {
      kind: "wake-chunks";
    }
  | {
      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];
      standingAt?: Vec3 & object;
    }
  | {
      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: "wake-chunks";
}

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];
  standingAt?: Vec3 & object;
}

Name	Type	Description
`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`	`EntityId`	-
`definition`	`string`	-
`cause`	`string`	-
`arguments`	`Readonly<Record<string, SpawnArgument>>`	-
`surfaceColumn?`	`readonly [number, number]`	-
`standingAt?`	`Vec3 & object`	Native standing contact, retaining its support height.

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;
}

Name	Type	Description
`kind`	`"break-structure"`	Tear down a finished structure with no worker: it was broken.
`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[];
}

Name	Type	Description
`kind`	`"prebuild-structures"`	Plan structures and finish them at once: a fresh world’s buildings.
`party`	`EntityId`	-
`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;
}

WorkActivityReftype alias

type 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;
    };

WorkInterruptCausetype alias

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

WorkBlockReasontype alias

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

WorkOutcometype alias

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

WorkAttemptPhasetype alias

type 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;
    };

ProcessInputPolicytype alias

type ProcessInputPolicy = "portion" | "whole-lot";

ProcessInputDispositiontype alias

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

NativeFacttype alias

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

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

CommandScopetype alias

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

PartyJoinIdentitytype alias

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

SpawnArgumenttype alias

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

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

ActorArgumenttype alias

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

ActorInstantiationPlantype alias

type 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[];
}>;

PartyJoinCapabilitytype alias

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

ActionScopetype alias

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

GameCommandContexttype alias

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

Type Declaration

Name	Type
`scope`	`CommandScope`
`workAttempts()`	`(taskIds) => readonly WorkAttempt[]`
`workAttemptForWorker()`	`(worker) => WorkAttempt \| null`
`floorOperations()`	`(requests) => readonly FloorOperation[]`

VisualPlacementtype alias

type 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;
    };

DeliveryActivityPhasetype alias

type 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.

ActivityKindtype alias

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

KernelSnapshottype alias

type KernelSnapshot = KernelRecordSnapshot;

ConstructionReadinessStatustype alias

type ConstructionReadinessStatus = "ready" | "waitingForSupport" | "unknown";

ConstructionAccessContacttype alias

type ConstructionAccessContact = Vec3 & object;

Type Declaration

Name	Type
`frame`	`null`
`kind`	`"origin" \| "landing"`

DeconstructionAccesstype alias

type 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;

PhysicalContacttype alias

type PhysicalContact = object;

Properties

solid

readonly solid: boolean;

sealedTop

readonly sealedTop: boolean;

outside

readonly outside: boolean;

TerrainSurfacetype alias

type TerrainSurface = z.infer<typeof terrainSurfaceSchema>;

TerrainSurfaceCovertype alias

type TerrainSurfaceCover = NonNullable<TerrainSurface["cover"]>;

StructureSurfacetype alias

type StructureSurface = object;

Properties

cell

readonly cell: readonly [number, number, number];

FloorOperationtype alias

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

FloorOperationRequesttype alias

type FloorOperationRequest = object;

Properties

cell

readonly cell: readonly [number, number, number];

desiredCatalog

readonly desiredCatalog: string;

TerrainChangeSettype alias

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

GameLocalBindingtype alias

type 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;
}>;

JsonValuetype alias

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

ComponentValuestype alias

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

GameCommandAvailabilitytype alias

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

EnvironmentFactstype alias

type EnvironmentFacts = z.infer<typeof environmentFactsSchema>;

AuthoredFeedbackCuetype alias

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

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

CartridgeAudiotype alias

type CartridgeAudio = z.infer<typeof cartridgeAudioSchema>;

CapabilityReferencetype alias

type CapabilityReference = ComponentDefinition<any> | ComponentId;

ActorInitialtype alias

type ActorInitial<T> = { readonly [K in keyof T]: T[K] | ActorInput };

Type Parameters

Type Parameter
`T` extends `object`

BlueprintSidetype alias

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

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

BlueprintOpeningKindtype alias

type 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).

CameraFollowPolicytype alias

type CameraFollowPolicy = z.infer<typeof cameraFollowSchema>;

CartridgeCameraPolicytype alias

type CartridgeCameraPolicy = z.infer<typeof cartridgeCameraSchema>;

BankPathtype alias

type BankPath = readonly (string | number)[];

PailPosestype alias

type PailPoses = Readonly<{
  contentKind: string;
  empty: string;
  partial: string;
  full: string;
}>;

VisualBindingstype alias

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

StaticVisualBindingtype alias

type 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

Name	Type	Description
`kind`	`"static"`	-
`worldRole`	`"floor" \| "structure" \| "item"`	-
`path`	`BankPath`	-
`facing`	`boolean`	The path ends in one frame per view turn (0 to 3).
`frames?`	`true`	The path (after its view) ends in an animation’s frames.
`anchor`	`"propAnchor" \| "vehicleAnchor"`	-

CartridgeDirectControltype alias

type 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.

HostFeaturetype alias

type HostFeature = (typeof HOST_FEATURES)[number];

ComponentFieldstype alias

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

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

BuildableDefinitiontype alias

type BuildableDefinition = z.infer<typeof buildableDefinitionSchema>;

ConstructionProposalInputtype alias

type ConstructionProposalInput = z.infer<typeof constructionProposalInput>;

DiagnosticCodetype alias

type DiagnosticCode = keyof typeof DIAGNOSTICS;

EffectFieldstype alias

type 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

Type Parameter
`T` extends `object`

FlowCelltype alias

type FlowCell = readonly [number, number];

PresentationLighttype alias

type PresentationLight = z.infer<typeof presentationLightSchema>;

CartridgeLightingtype alias

type CartridgeLighting = z.infer<typeof cartridgeLightingSchema>;

Moodtype alias

type Mood = (typeof MOODS)[number];

TerrainLooktype alias

type TerrainLook = z.infer<typeof terrainLookSchema>;

Looktype alias

type 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";
}

Name	Type	Description
`palette`	`null`	-
`ambientLight?`	`Readonly<Record<Mood, number>>`	-
`ambientTint?`	`Readonly<Record<Mood, readonly [number, number, number]>>`	View-only RGB light multipliers (0..1), independent of palette mapping.
`terrain`	`TerrainLook`	-
`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";
}

Name	Type	Description
`palette`	`Palette`	-
`dither`	`PaletteDither`	-
`mood`	`Mood`	-
`moods?`	`readonly MoodStop[]`	The checked schedule, when the cartridge gives one.
`ambientLight?`	`Readonly<Record<Mood, number>>`	-
`ambientTint?`	`Readonly<Record<Mood, readonly [number, number, number]>>`	View-only RGB light multipliers (0..1), independent of palette mapping.
`terrain`	`TerrainLook`	-
`backdrop?`	`"ocean"`	-

Cell2type alias

type Cell2 = readonly [number, number];

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

ActorParamstype alias

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

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

SeatFactstype alias

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

TerrainChoicetype alias

type TerrainChoice = VoxelTerrainChoice | SeaTerrainChoice;

WindowWorldtype alias

type 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" }.

RunCommandtype alias

type RunCommand = (command, input?) => void;

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

Parameters

Parameter	Type
`command`	`string`
`input?`	`JsonValue`

Returns

void

WindowBodytype alias

type 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

Parameter	Type
`world`	`WindowWorld`

Returns

readonly WindowBlock[]

WorldgenAssemblytype alias

type WorldgenAssembly = z.infer<typeof worldgenAssemblySchema>;

RoomDefinitiontype alias

type RoomDefinition = z.infer<typeof roomDefinitionSchema>;

BuildingDefinitiontype alias

type BuildingDefinition = z.infer<typeof buildingDefinitionSchema>;

WorldgenChecktype alias

type WorldgenCheck = Extract<
  z.infer<typeof worldgenCheckSchema>,
  {
    status: "valid";
  }
>;

BuildingLayouttype alias

type BuildingLayout = z.infer<typeof buildingLayoutSchema>;

BuildingGraphtype alias

type BuildingGraph = z.infer<typeof buildingGraphSchema>;

CompileRequesttype alias

type CompileRequest = z.infer<typeof compileRequestSchema>;

CompiledBuildingtype alias

type CompiledBuilding = z.infer<typeof compiledBuilding>;

GenerationIdentitytype alias

type GenerationIdentity = z.infer<typeof generationIdentitySchema>;

PopulationPolicytype alias

type PopulationPolicy = z.infer<typeof populationPolicySchema>;

ChunkPolicytype alias

type ChunkPolicy = z.infer<typeof chunkPolicySchema>;

ChunkWindowtype alias

type ChunkWindow = z.infer<typeof chunkWindowSchema>;

ChunkFactstype alias

type ChunkFacts = z.infer<typeof chunkFactsSchema>;

GenerationKeytype alias

type GenerationKey = z.infer<typeof generationKeySchema>;

ChunkPlantype alias

type ChunkPlan = z.infer<typeof chunkPlanSchema>;

WindowBlocktype alias

type WindowBlock = z.infer<typeof windowBlockSchema>;

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

WindowRoletype alias

type WindowRole = z.infer<typeof windowRoleSchema>;

Where the shell shows a window.

WindowOpeningtype alias

type WindowOpening = z.infer<typeof windowOpeningSchema>;

When a window first opens on its own.

RESERVED_COMPONENTSconstant

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",
];

sampledSoundSchemaconstant

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.

cartridgeAudioSchemaconstant

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.

actorInputconstant

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.

actorInputSchemaconstant

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.

ActorKindconstant

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.

cameraFollowSchemaconstant

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.

cartridgeCameraSchemaconstant

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_FEATURESconstant

const HOST_FEATURES: readonly ["minded-seats"];

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

Colliderconstant

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.

Launcherconstant

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;
}>;

ImpactMaterialconstant

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

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

Bodyconstant

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

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

Emitterconstant

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

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

Containerconstant

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

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

Traversalconstant

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

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

Positionconstant

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

Visualconstant

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

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

Supportconstant

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

Surfaceconstant

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

MaterialLotconstant

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

Handsconstant

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.

VesselCapabilityconstant

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

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

LotWaterconstant

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

SupplyAllocationconstant

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.

DeliveryRequestconstant

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.

FiniteResourceconstant

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

JobTaskWorkconstant

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.

ResourceSiteconstant

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

Destinationconstant

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

placedAtconstant

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.

ExcavationWorkconstant

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.

ExcavationOrderconstant

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

Buildableconstant

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.

constructionProposalInputconstant

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.

SealedContainerconstant

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

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

ConstructionSiteconstant

const ConstructionSite: ComponentDefinition<ConstructionSiteState>;

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

FloorReplacementconstant

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

DeconstructionOrderconstant

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.

DIAGNOSTICSconstant

const DIAGNOSTICS: object;

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

Type Declaration

FLOW_NEIGHBOURSconstant

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],
];

HordeTargetconstant

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

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

presentationLightSchemaconstant

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.

cartridgeLightingSchemaconstant

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.

MOODSconstant

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

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

moodSchemaconstant

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

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

terrainLookSchemaconstant

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

FULL_COLOURconstant

const FULL_COLOUR: Look;

Full colour: no palette constraint.

Partyconstant

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

Gameplay group identity. Membership and ownership are separate facts.

OwnedByconstant

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

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

PartyMemberconstant

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

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

OwnedByPartyconstant

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

Party ownership for property and stationary stores.

StagedProcessconstant

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

FieldWaterWorkconstant

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.

ResourceOrderconstant

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.

Spawnedconstant

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

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

terrainChoiceSchemaconstant

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"
>;

blockconstant

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_KEYSconstant

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.

WorkParticipationconstant

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

Player participation policy for the shared automatic work owner.

WorkPolicyconstant

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

WorkExecutionconstant

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

WorkScheduleconstant

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

worldgenAssemblySchemaconstant

const worldgenAssemblySchema: ZodObject<{
  floors: ZodArray<ZodObject<{
     level: ZodNumber;
     cells: ZodArray<ZodTuple<[ZodNumber, ZodNumber], null>>;
  }, $strict>>;
  levels: ZodArray<ZodObject<{
     level: ZodNumber;
     blueprint: ZodObject<{
        pieces: ZodArray<ZodObject<{
           kind: ZodEnum<...>;
           cell: ZodTuple<..., ...>;
           axis: ZodEnum<...>;
           style: ZodOptional<...>;
        }, $strict>>;
        rooms: ZodArray<ZodObject<{
           index: ZodNumber;
           module: ZodString;
           tags: ZodArray<...>;
           cells: ZodArray<...>;
        }, $strict>>;
        slots: ZodArray<ZodObject<{
           room: ZodNumber;
           module: ZodString;
           name: ZodString;
           at: ZodTuple<..., ...>;
        }, $strict>>;
     }, $strict>;
  }, $strict>>;
  stairs: ZodArray<ZodObject<{
     level: ZodNumber;
     cell: ZodTuple<[ZodNumber, ZodNumber], null>;
     facing: ZodEnum<{
        north: "north";
        east: "east";
        south: "south";
        west: "west";
     }>;
  }, $strict>>;
}, $strict>;

roomDefinitionSchemaconstant

const roomDefinitionSchema: ZodObject<{
  id: ZodString;
  pool: ZodArray<ZodString>;
  footprint: ZodEnum<{
     1x1: "1x1";
     2x1: "2x1";
     2x2: "2x2";
     L3: "L3";
     corridor2: "corridor2";
     corridor3: "corridor3";
  }>;
  level: ZodEnum<{
     any: "any";
     ground: "ground";
     upper: "upper";
  }>;
  edges: ZodRecord<ZodString, ZodTuple<[ZodEnum<{
     door: "door";
     archway: "archway";
     window: "window";
     wall: "wall";
   }>, ZodEnum<{
     door: "door";
     archway: "archway";
     window: "window";
     wall: "wall";
   }>, ZodEnum<{
     door: "door";
     archway: "archway";
     window: "window";
     wall: "wall";
  }>], null>>;
  stairs: ZodDefault<ZodArray<ZodObject<{
     kind: ZodEnum<{
        up: "up";
        down: "down";
     }>;
     bay: ZodTuple<[ZodNumber, ZodNumber], null>;
     facing: ZodEnum<{
        north: "north";
        east: "east";
        south: "south";
        west: "west";
     }>;
  }, $strict>>>;
  slots: ZodRecord<ZodString, ZodObject<{
     at: ZodTuple<[ZodNumber, ZodNumber], null>;
     kind: ZodString;
  }, $strict>>;
  styles: ZodDefault<ZodRecord<ZodEnum<{
     north: "north";
     east: "east";
     south: "south";
     west: "west";
  }> & $partial, ZodString>>;
}, $strict>;

buildingDefinitionSchemaconstant

const buildingDefinitionSchema: ZodObject<
  {
    rooms: ZodArray<
      ZodObject<
        {
          id: ZodString;
          room: ZodString;
          at: ZodTuple<[ZodNumber, ZodNumber], null>;
          level: ZodNumber;
          rotate: ZodDefault<ZodNumber>;
          mirror: ZodDefault<ZodBoolean>;
        },
        $strict
      >
    >;
    entry: ZodObject<
      {
        node: ZodString;
        edge: ZodString;
      },
      $strict
    >;
    frontage: ZodEnum<{
      north: "north";
      east: "east";
      south: "south";
      west: "west";
    }>;
  },
  $strict
>;

worldgenCheckSchemaconstant

const worldgenCheckSchema: ZodDiscriminatedUnion<[ZodObject<{
  status: ZodLiteral<"valid">;
  value: ZodUnion<readonly [ZodObject<{
     id: ZodString;
     pool: ZodArray<ZodString>;
     footprint: ZodEnum<{
        1x1: "1x1";
        2x1: "2x1";
        2x2: "2x2";
        L3: "L3";
        corridor2: "corridor2";
        corridor3: "corridor3";
     }>;
     level: ZodEnum<{
        any: "any";
        ground: "ground";
        upper: "upper";
     }>;
     edges: ZodRecord<ZodString, ZodTuple<[..., ..., ...], null>>;
     stairs: ZodDefault<ZodArray<ZodObject<..., ...>>>;
     slots: ZodRecord<ZodString, ZodObject<{
        at: ...;
        kind: ...;
     }, $strict>>;
     styles: ZodDefault<ZodRecord<... & ..., ZodString>>;
   }, $strict>, ZodObject<{
     rooms: ZodArray<ZodObject<{
        id: ...;
        room: ...;
        at: ...;
        level: ...;
        rotate: ...;
        mirror: ...;
     }, $strict>>;
     entry: ZodObject<{
        node: ZodString;
        edge: ZodString;
     }, $strict>;
     frontage: ZodEnum<{
        north: "north";
        east: "east";
        south: "south";
        west: "west";
     }>;
  }, $strict>]>;
  preview: ZodObject<{
     floors: ZodArray<ZodObject<{
        level: ZodNumber;
        cells: ZodArray<ZodTuple<..., ...>>;
     }, $strict>>;
     levels: ZodArray<ZodObject<{
        level: ZodNumber;
        blueprint: ZodObject<{
           pieces: ...;
           rooms: ...;
           slots: ...;
        }, $strict>;
     }, $strict>>;
     stairs: ZodArray<ZodObject<{
        level: ZodNumber;
        cell: ZodTuple<[..., ...], null>;
        facing: ZodEnum<{
           north: ...;
           east: ...;
           south: ...;
           west: ...;
        }>;
     }, $strict>>;
  }, $strict>;
  neighbours: ZodArray<ZodObject<{
     room: ZodString;
     at: ZodTuple<[ZodNumber, ZodNumber], null>;
     rotate: ZodNumber;
     mirror: ZodBoolean;
     preview: ZodObject<{
        floors: ZodArray<ZodObject<..., ...>>;
        levels: ZodArray<ZodObject<..., ...>>;
        stairs: ZodArray<ZodObject<..., ...>>;
     }, $strict>;
  }, $strict>>;
}, $strict>, ZodObject<{
  status: ZodLiteral<"invalid">;
  diagnostics: ZodArray<ZodObject<{
     code: ZodEnum<{
        VD085: "VD085";
        VD086: "VD086";
        VD087: "VD087";
        VD088: "VD088";
        VD089: "VD089";
        VD090: "VD090";
        VD091: "VD091";
     }>;
     message: ZodString;
     hint: ZodString;
     path: ZodString;
  }, $strict>>;
}, $strict>], "status">;

buildingLayoutSchemaconstant

const buildingLayoutSchema: ZodObject<{
  rooms: ZodArray<ZodObject<{
     id: ZodString;
     room: ZodObject<{
        id: ZodString;
        pool: ZodArray<ZodString>;
        footprint: ZodEnum<{
           1x1: "1x1";
           2x1: "2x1";
           2x2: "2x2";
           L3: "L3";
           corridor2: "corridor2";
           corridor3: "corridor3";
        }>;
        level: ZodEnum<{
           any: "any";
           ground: "ground";
           upper: "upper";
        }>;
        edges: ZodRecord<ZodString, ZodTuple<[ZodEnum<...>, ZodEnum<...>, ZodEnum<...>], null>>;
        stairs: ZodDefault<ZodArray<ZodObject<{
           kind: ...;
           bay: ...;
           facing: ...;
        }, $strict>>>;
        slots: ZodRecord<ZodString, ZodObject<{
           at: ZodTuple<..., ...>;
           kind: ZodString;
        }, $strict>>;
        styles: ZodDefault<ZodRecord<ZodEnum<...> & $partial, ZodString>>;
     }, $strict>;
     at: ZodTuple<[ZodInt, ZodInt], null>;
     level: ZodInt;
     rotate: ZodDefault<ZodInt>;
     mirror: ZodDefault<ZodBoolean>;
  }, $strict>>;
  entry: ZodObject<{
     node: ZodString;
     edge: ZodString;
  }, $strict>;
  frontage: ZodEnum<{
     north: "north";
     east: "east";
     south: "south";
     west: "west";
  }>;
  slotKinds: ZodArray<ZodString>;
}, $strict>;

buildingGraphSchemaconstant

const buildingGraphSchema: ZodObject<
  {
    type: ZodString;
    storeys: ZodInt;
    nodes: ZodArray<
      ZodObject<
        {
          id: ZodString;
          pool: ZodString;
          count: ZodOptional<ZodNullable<ZodTuple<[ZodInt, ZodInt], null>>>;
          level: ZodInt;
        },
        $strict
      >
    >;
    edges: ZodArray<
      ZodObject<
        {
          from: ZodString;
          to: ZodString;
          via: ZodEnum<{
            door: "door";
            archway: "archway";
            stairs: "stairs";
          }>;
        },
        $strict
      >
    >;
    entry: ZodObject<
      {
        node: ZodString;
        faces: ZodLiteral<"frontage">;
      },
      $strict
    >;
  },
  $strict
>;

compileRequestSchemaconstant

const compileRequestSchema: ZodObject<{
  id: ZodString;
  party: ZodString;
  origin: ZodObject<{
     x: ZodNumber;
     y: ZodInt;
     z: ZodNumber;
  }, $strict>;
  layout: ZodObject<{
     rooms: ZodArray<ZodObject<{
        id: ZodString;
        room: ZodObject<{
           id: ZodString;
           pool: ZodArray<ZodString>;
           footprint: ZodEnum<{
              1x1: ...;
              2x1: ...;
              2x2: ...;
              L3: ...;
              corridor2: ...;
              corridor3: ...;
           }>;
           level: ZodEnum<{
              any: ...;
              ground: ...;
              upper: ...;
           }>;
           edges: ZodRecord<ZodString, ZodTuple<..., ...>>;
           stairs: ZodDefault<ZodArray<...>>;
           slots: ZodRecord<ZodString, ZodObject<..., ...>>;
           styles: ZodDefault<ZodRecord<..., ...>>;
        }, $strict>;
        at: ZodTuple<[ZodInt, ZodInt], null>;
        level: ZodInt;
        rotate: ZodDefault<ZodInt>;
        mirror: ZodDefault<ZodBoolean>;
     }, $strict>>;
     entry: ZodObject<{
        node: ZodString;
        edge: ZodString;
     }, $strict>;
     frontage: ZodEnum<{
        north: "north";
        east: "east";
        south: "south";
        west: "west";
     }>;
     slotKinds: ZodArray<ZodString>;
  }, $strict>;
  kit: ZodObject<{
     wall: ZodString;
     door: ZodString;
     window: ZodString;
     floor: ZodString;
     roof: ZodString;
     stair: ZodString;
     styles: ZodDefault<ZodRecord<ZodString, ZodObject<{
        wall: ZodString;
        door: ZodString;
        window: ZodString;
     }, $strict>>>;
  }, $strict>;
}, $strict>;

generationIdentitySchemaconstant

const generationIdentitySchema: ZodObject<
  {
    seed: ZodString;
    version: ZodLiteral<"worldgen-v1">;
    kitHash: ZodString;
  },
  $strict
>;

populationPolicySchemaconstant

const populationPolicySchema: ZodObject<{
  party: ZodString;
  townRadius: ZodInt;
  fringeChunks: ZodInt;
  fringePercent: ZodInt;
  ruralPercent: ZodInt;
  decorationPiecesPerStep: ZodDefault<ZodInt>;
  rooms: ZodArray<ZodObject<{
     id: ZodString;
     pool: ZodArray<ZodString>;
     footprint: ZodEnum<{
        1x1: "1x1";
        2x1: "2x1";
        2x2: "2x2";
        L3: "L3";
        corridor2: "corridor2";
        corridor3: "corridor3";
     }>;
     level: ZodEnum<{
        any: "any";
        ground: "ground";
        upper: "upper";
     }>;
     edges: ZodRecord<ZodString, ZodTuple<[ZodEnum<{
        door: "door";
        archway: "archway";
        window: "window";
        wall: "wall";
      }>, ZodEnum<{
        door: "door";
        archway: "archway";
        window: "window";
        wall: "wall";
      }>, ZodEnum<{
        door: "door";
        archway: "archway";
        window: "window";
        wall: "wall";
     }>], null>>;
     stairs: ZodDefault<ZodArray<ZodObject<{
        kind: ZodEnum<{
           up: ...;
           down: ...;
        }>;
        bay: ZodTuple<[..., ...], null>;
        facing: ZodEnum<{
           north: ...;
           east: ...;
           south: ...;
           west: ...;
        }>;
     }, $strict>>>;
     slots: ZodRecord<ZodString, ZodObject<{
        at: ZodTuple<[ZodNumber, ZodNumber], null>;
        kind: ZodString;
     }, $strict>>;
     styles: ZodDefault<ZodRecord<ZodEnum<{
        north: "north";
        east: "east";
        south: "south";
        west: "west";
     }> & $partial, ZodString>>;
  }, $strict>>;
  slotKinds: ZodArray<ZodString>;
  buildings: ZodArray<ZodObject<{
     id: ZodString;
     weight: ZodInt;
     building: ZodObject<{
        rooms: ZodArray<ZodObject<{
           id: ZodString;
           room: ZodString;
           at: ZodTuple<..., ...>;
           level: ZodNumber;
           rotate: ZodDefault<...>;
           mirror: ZodDefault<...>;
        }, $strict>>;
        entry: ZodObject<{
           node: ZodString;
           edge: ZodString;
        }, $strict>;
        frontage: ZodEnum<{
           north: "north";
           east: "east";
           south: "south";
           west: "west";
        }>;
     }, $strict>;
  }, $strict>>;
  kit: ZodObject<{
     wall: ZodString;
     door: ZodString;
     window: ZodString;
     floor: ZodString;
     roof: ZodString;
     stair: ZodString;
     styles: ZodDefault<ZodRecord<ZodString, ZodObject<{
        wall: ZodString;
        door: ZodString;
        window: ZodString;
     }, $strict>>>;
  }, $strict>;
}, $strict>;

chunkPolicySchemaconstant

const chunkPolicySchema: ZodObject<{
  identity: ZodObject<{
     seed: ZodString;
     version: ZodLiteral<"worldgen-v1">;
     kitHash: ZodString;
  }, $strict>;
  focusComponent: ZodString;
  chunkCells: ZodInt;
  windowCells: ZodInt;
  prefetchRings: ZodInt;
  batchesPerStep: ZodInt;
  population: ZodOptional<ZodObject<{
     party: ZodString;
     townRadius: ZodInt;
     fringeChunks: ZodInt;
     fringePercent: ZodInt;
     ruralPercent: ZodInt;
     decorationPiecesPerStep: ZodDefault<ZodInt>;
     rooms: ZodArray<ZodObject<{
        id: ZodString;
        pool: ZodArray<ZodString>;
        footprint: ZodEnum<{
           1x1: "1x1";
           2x1: "2x1";
           2x2: "2x2";
           L3: "L3";
           corridor2: "corridor2";
           corridor3: "corridor3";
        }>;
        level: ZodEnum<{
           any: "any";
           ground: "ground";
           upper: "upper";
        }>;
        edges: ZodRecord<ZodString, ZodTuple<[..., ..., ...], null>>;
        stairs: ZodDefault<ZodArray<ZodObject<..., ...>>>;
        slots: ZodRecord<ZodString, ZodObject<{
           at: ...;
           kind: ...;
        }, $strict>>;
        styles: ZodDefault<ZodRecord<... & ..., ZodString>>;
     }, $strict>>;
     slotKinds: ZodArray<ZodString>;
     buildings: ZodArray<ZodObject<{
        id: ZodString;
        weight: ZodInt;
        building: ZodObject<{
           rooms: ZodArray<...>;
           entry: ZodObject<..., ...>;
           frontage: ZodEnum<...>;
        }, $strict>;
     }, $strict>>;
     kit: ZodObject<{
        wall: ZodString;
        door: ZodString;
        window: ZodString;
        floor: ZodString;
        roof: ZodString;
        stair: ZodString;
        styles: ZodDefault<ZodRecord<ZodString, ZodObject<{
           wall: ...;
           door: ...;
           window: ...;
        }, $strict>>>;
     }, $strict>;
  }, $strict>>;
}, $strict>;

chunkWindowSchemaconstant

const chunkWindowSchema: ZodObject<
  {
    minX: ZodInt;
    maxX: ZodInt;
    minZ: ZodInt;
    maxZ: ZodInt;
  },
  $strict
>;

chunkFactsSchemaconstant

const chunkFactsSchema: ZodObject<{
  policy: ZodObject<{
     identity: ZodObject<{
        seed: ZodString;
        version: ZodLiteral<"worldgen-v1">;
        kitHash: ZodString;
     }, $strict>;
     focusComponent: ZodString;
     chunkCells: ZodInt;
     windowCells: ZodInt;
     prefetchRings: ZodInt;
     batchesPerStep: ZodInt;
     population: ZodOptional<ZodObject<{
        party: ZodString;
        townRadius: ZodInt;
        fringeChunks: ZodInt;
        fringePercent: ZodInt;
        ruralPercent: ZodInt;
        decorationPiecesPerStep: ZodDefault<ZodInt>;
        rooms: ZodArray<ZodObject<{
           id: ZodString;
           pool: ZodArray<...>;
           footprint: ZodEnum<...>;
           level: ZodEnum<...>;
           edges: ZodRecord<..., ...>;
           stairs: ZodDefault<...>;
           slots: ZodRecord<..., ...>;
           styles: ZodDefault<...>;
        }, $strict>>;
        slotKinds: ZodArray<ZodString>;
        buildings: ZodArray<ZodObject<{
           id: ZodString;
           weight: ZodInt;
           building: ZodObject<..., ...>;
        }, $strict>>;
        kit: ZodObject<{
           wall: ZodString;
           door: ZodString;
           window: ZodString;
           floor: ZodString;
           roof: ZodString;
           stair: ZodString;
           styles: ZodDefault<ZodRecord<..., ...>>;
        }, $strict>;
     }, $strict>>;
  }, $strict>;
  defaultWindow: ZodObject<{
     minX: ZodInt;
     maxX: ZodInt;
     minZ: ZodInt;
     maxZ: ZodInt;
  }, $strict>;
  windows: ZodArray<ZodObject<{
     actor: ZodString;
     window: ZodObject<{
        minX: ZodInt;
        maxX: ZodInt;
        minZ: ZodInt;
        maxZ: ZodInt;
     }, $strict>;
  }, $strict>>;
  materializedCount: ZodInt;
  exhausted: ZodBoolean;
  queuedCount: ZodInt;
}, $strict>;

generationKeySchemaconstant

const generationKeySchema: ZodObject<
  {
    identity: ZodObject<
      {
        seed: ZodString;
        version: ZodLiteral<"worldgen-v1">;
        kitHash: ZodString;
      },
      $strict
    >;
    layer: ZodString;
    id: ZodString;
  },
  $strict
>;

generationKeyResultSchemaconstant

const generationKeyResultSchema: ZodDiscriminatedUnion<
  [
    ZodObject<
      {
        status: ZodLiteral<"valid">;
        key: ZodObject<
          {
            identity: ZodObject<
              {
                seed: ZodString;
                version: ZodLiteral<"worldgen-v1">;
                kitHash: ZodString;
              },
              $strict
            >;
            layer: ZodString;
            id: ZodString;
          },
          $strict
        >;
        digest: ZodString;
      },
      $strict
    >,
    ZodObject<
      {
        status: ZodLiteral<"invalid">;
        code: ZodLiteral<"VD084">;
        message: ZodString;
        hint: ZodString;
      },
      $strict
    >,
  ],
  "status"
>;

chunkPlanSchemaconstant

const chunkPlanSchema: ZodObject<
  {
    key: ZodObject<
      {
        x: ZodInt;
        z: ZodInt;
      },
      $strict
    >;
    roads: ZodArray<
      ZodObject<
        {
          minX: ZodInt;
          maxX: ZodInt;
          minZ: ZodInt;
          maxZ: ZodInt;
        },
        $strict
      >
    >;
    lots: ZodArray<
      ZodObject<
        {
          id: ZodString;
          building: ZodString;
          origin: ZodTuple<[ZodInt, ZodInt], null>;
          rotate: ZodInt;
          mirror: ZodBoolean;
        },
        $strict
      >
    >;
  },
  $strict
>;

MEADOW_VERTICAL_METRESconstant

const MEADOW_VERTICAL_METRES: 0.54 = 0.54;

Metres per vertical terrain cell in the library worlds.

isReservedComponent()function

function isReservedComponent(id): boolean;

Parameters

Parameter	Type
`id`	`string`

Returns

boolean

isNativeComponentSchema()function

function 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

Parameter	Type
`id`	`string`

Returns

boolean

component()function

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

Type Parameters

Type Parameter
`T` extends `object`

Parameters

Parameter	Type
`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; }
`options.version`	`number`
`options.fields`	`Readonly<Record<keyof T & string, FieldType>>`
`options.targetField?`	`keyof T & string`
`options.sourceRequires?`	readonly `${string}.${string}`[]
`options.targetRequires?`	readonly `${string}.${string}`[]
`options.onTargetRemoved?`	`RelationRemovalPolicy`
`options.allowSelf?`	`boolean`

Returns

ComponentDefinition<T>

relation()function

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

Type Parameters

Type Parameter
`T` extends `object`

Parameters

Parameter	Type
`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; }`
`options.version`	`number`
`options.fields`	`Readonly<Record<keyof T & string, FieldType>>`
`options.targetField`	`keyof T & string`
`options.sourceRequires?`	`readonly CapabilityReference[]`
`options.targetRequires?`	`readonly CapabilityReference[]`
`options.onTargetRemoved?`	`RelationRemovalPolicy`
`options.allowSelf?`	`boolean`

Returns

ComponentDefinition<T>

setRelation()function

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

Type Parameters

Type Parameter
`T` extends `object`

Parameters

Parameter	Type
`definition`	`ComponentDefinition<T>`
`source`	`EntityId`
`target`	`EntityId`

Returns

ActionRequest

clearRelation()function

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

Type Parameters

Type Parameter
`T` extends `object`

Parameters

Parameter	Type
`definition`	`ComponentDefinition<T>`
`source`	`EntityId`

Returns

ActionRequest

query()function

function query<T>(...components): QuerySpec<T>;

Type Parameters

Type Parameter
`T` extends `object`

Parameters

Parameter	Type
…`components`	`readonly ComponentDefinition<any>[]`

Returns

QuerySpec<T>

system()function

function system(options): SystemDefinition;

Parameters

Parameter	Type
`options`	`SystemOptions`

Returns

SystemDefinition

command()function

function command<TInput>(options): GameCommandDefinition;

Type Parameters

Type Parameter
`TInput`

Parameters

Parameter	Type
`options`	`Omit<GameCommandDefinition, \| "input" \| "title" \| "description" \| "subjects" \| "invoke" \| "category" \| "availability"> & object`

Returns

GameCommandDefinition

entity()function

function entity(id): EntityId;

Parameters

Parameter	Type
`id`	`string`

Returns

EntityId

definitionCapability()function

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

Type Parameters

Type Parameter
`T` extends `object`

Parameters

Parameter	Type
`id`	`${string}.${string}`
`options`	`{ schema: ZodType<T>; externalCreation?: boolean; }`
`options.schema`	`ZodType<T>`
`options.externalCreation?`	`boolean`

Returns

ActorDefinitionCapability<T>

predicate()function

function predicate(id, options): PredicateDefinition;

Parameters

Parameter	Type
`id`	`${string}.${string}`
`options`	`{ reads?: readonly ComponentDefinition<any>[]; facts?: readonly NativeFact[]; test: (subject, context) => boolean; }`
`options.reads?`	`readonly ComponentDefinition<any>[]`
`options.facts?`	`readonly NativeFact[]`
`options.test`	`(subject, context) => boolean`

Returns

PredicateDefinition

action()function

function action(id, options): BehaviorActionDefinition;

Parameters

Parameter	Type
`id`	`${string}.${string}`
`options`	`{ reads?: readonly ComponentDefinition<any>[]; writes?: readonly ComponentDefinition<any>[]; facts?: readonly NativeFact[]; exclusive?: string; run: (subject, context) => void; }`
`options.reads?`	`readonly ComponentDefinition<any>[]`
`options.writes?`	`readonly ComponentDefinition<any>[]`
`options.facts?`	`readonly NativeFact[]`
`options.exclusive?`	`string`
`options.run`	`(subject, context) => void`

Returns

BehaviorActionDefinition

behavior()function

function 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

Parameter	Type
`id`	`${string}.${string}`
`define`	`(scene) => void`
`options`	`BehaviorOptions`

Returns

BehaviorDefinition

installActorBehaviors()function

function 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

Parameter	Type
`actors`	`readonly ActorDefinition[]`

Returns

readonly SystemDefinition[]

actor()function

function actor(id, options?): ActorDefinition;

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

Parameters

Parameter	Type
`id`	`string`
`options`	`{ version?: number; }`
`options.version?`	`number`

Returns

ActorDefinition

blueprintModule()function

function blueprintModule(id, spec): BlueprintModule;

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

Parameters

Parameter	Type
`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>>>; }`
`spec.size`	`readonly [number, number]`
`spec.openings?`	`readonly BlueprintOpening[]`
`spec.slots?`	`Readonly<Record<string, readonly [number, number]>>`
`spec.tags?`	`readonly string[]`
`spec.sides?`	`Readonly<Partial<Record<BlueprintSide, string>>>`

Returns

BlueprintModule

assembleBlueprint()function

function 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

Parameter	Type
`recipe`	`BlueprintRecipe`

Returns

Blueprint

compileBlueprint()function

function compileBlueprint(blueprint, kit): object;

Compile a ground-level blueprint through the same native owner as storeys.

Parameters

Parameter	Type
`blueprint`	`Blueprint`
`kit`	`BlueprintKit`

Returns

object

Name	Type
`plans`	`readonly PlacementCandidate[]`
`unplaced`	`readonly object[]`

compileBlueprintLevels()function

function compileBlueprintLevels(levels, kit): object;

Rust compiles floors, facades, roofs and stairs bottom-up, leaves stairwells open and rejects unsupported upper rooms. TS supplies declarations and samples; construction keeps its existing site identity and transactional admission.

Parameters

Parameter	Type
`levels`	`readonly BlueprintLevel[]`
`kit`	`BlueprintKit`

Returns

object

Name	Type
`plans`	`readonly PlacementCandidate[]`
`unplaced`	`readonly object[]`

prebuildBatches()function

function prebuildBatches(party, plans): readonly ActionRequest[];

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

Parameters

Parameter	Type
`party`	`EntityId`
`plans`	`readonly PlacementCandidate[]`

Returns

readonly ActionRequest[]

buildable()function

function 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

Parameter	Type	Description
`id`	`string`	-
`definition`	{ 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; }	-
`definition.name`	`string`	The player-facing noun: “Build wall”, “stair north”.
`definition.sprites`	`string`	Sprite family; stages derive as `${sprites}.stakes	frame	finished`(cells) or`${sprites}.segment.${stage}.${axis}` (edges).
`definition.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; }`	-
`definition.materials`	`object[]`	-
`definition.workSeconds`	`number`	-
`definition.workReachBelowCells`	`number`	-
`definition.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.
`definition.placement.alignment`	`"fixed" \| "stroke"`	-
`definition.placement.facing?`	`{ north: number; east: number; south: number; west: number; }`	-
`definition.placement.facing.north`	`number`	-
`definition.placement.facing.east`	`number`	-
`definition.placement.facing.south`	`number`	-
`definition.placement.facing.west`	`number`	-
`definition.ports?`	`object[]`	-
`definition.onRemove?`	`{ salvage?: object[]; emptyPorts?: string[]; }`	-
`definition.onRemove.salvage?`	`object[]`	-
`definition.onRemove.emptyPorts?`	`string[]`	-
`definition.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.
`definition.key?`	`string`	A key that picks this buildable while the build palette applies.

Returns

ActorDefinition

buildBindingDetail()function

function buildBindingDetail(compiled, orientation?): string;

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

Parameters

Parameter	Type
`compiled`	`CompiledBuildable`
`orientation?`	`string`

Returns

string

construction()function

function 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

Parameter	Type
`options`	`ConstructionOptions`

Returns

Construction

defineCartridge()function

function 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

Parameter	Type
`spec`	`CartridgeSpec`

Returns

Cartridge

launch()function

function launch(launcher, ammunition, velocity): ActionRequest;

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

Parameters

Parameter	Type
`launcher`	`EntityId`
`ammunition`	`EntityId`
`velocity`	`Vec3`

Returns

ActionRequest

displace()function

function 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

Parameter	Type
`entity`	`EntityId`
`delta`	`Vec3`

Returns

ActionRequest

beginEmission()function

function beginEmission(worker, station): ActionRequest;

Parameters

Parameter	Type
`worker`	`EntityId`
`station`	`EntityId`

Returns

ActionRequest

exchangeFieldWater()function

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

Parameters

Parameter	Type	Default value
`operation`	`string`	`undefined`
`worker`	`EntityId`	`undefined`
`vessel`	`EntityId`	`undefined`
`cell`	`{ x: number; y: number; z: number; }`	`undefined`
`cell.x`	`number`	`undefined`
`cell.y`	`number`	`undefined`
`cell.z`	`number`	`undefined`
`portions`	`number`	`1`

Returns

ActionRequest

move()function

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

Parameters

Parameter	Type	Default value
`entity`	`EntityId`	`undefined`
`destination`	`MoveDestination`	`undefined`
`facing`	`number`	`0`
`speed?`	`number`	`undefined`

Returns

ActionRequest

dropLot()function

function dropLot(entity, lot): ActionRequest;

Parameters

Parameter	Type
`entity`	`EntityId`
`lot`	`EntityId`

Returns

ActionRequest

transfer()function

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

Parameters

Parameter	Type
`lot`	`EntityId`
`from`	`EntityId`
`to`	`EntityId`
`quantity`	`number`

Returns

ActionRequest

requestDelivery()function

function requestDelivery(request): ActionRequest;

Parameters

Parameter	Type
`request`	`{ source: EntityId; destination: EntityId; material: string; quantity: number; party: EntityId; }`
`request.source`	`EntityId`
`request.destination`	`EntityId`
`request.material`	`string`
`request.quantity`	`number`
`request.party`	`EntityId`

Returns

ActionRequest

consume()function

function consume(entity, lot, quantity): ActionRequest;

Parameters

Parameter	Type
`entity`	`EntityId`
`lot`	`EntityId`
`quantity`	`number`

Returns

ActionRequest

extractResource()function

function extractResource(operation, worker, source): ActionRequest;

Parameters

Parameter	Type
`operation`	`string`
`worker`	`EntityId`
`source`	`EntityId`

Returns

ActionRequest

establishResourceSite()function

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

Parameters

Parameter	Type
`operation`	`string`
`worker`	`EntityId`
`site`	`EntityId`
`definition`	`string`
`cell`	`{ x: number; y: number; z: number; }`
`cell.x`	`number`
`cell.y`	`number`
`cell.z`	`number`

Returns

ActionRequest

tendResourceSite()function

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

Parameters

Parameter	Type
`operation`	`string`
`worker`	`EntityId`
`site`	`EntityId`
`vessel`	`EntityId`

Returns

ActionRequest

encodeDefinition()function

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

Parameters

Parameter	Type	Default value
`game`	`string`	`undefined`
`components`	`readonly ComponentDefinition<any>[]`	`undefined`
`initial`	`readonly SceneEntity[]`	`[]`
`materialCatalog`	`readonly object[]`	`undefined`
`stockpileProfiles`	`readonly object[]`	`[]`
`actors`	`readonly ActorDefinition[]`	`[]`

Returns

Uint8Array<ArrayBuffer>

cancelWork()function

function cancelWork(entity): ActionRequest;

Parameters

Parameter	Type
`entity`	`EntityId`

Returns

ActionRequest

compileBuildable()function

function compileBuildable(actor): CompiledBuildable | null;

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

Parameters

Parameter	Type
`actor`	`ActorDefinition`

Returns

CompiledBuildable | null

compileBuildableEnvironment()function

function compileBuildableEnvironment(
  environment,
  actors,
): EnvironmentDefinition;

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

Parameters

Parameter	Type
`environment`	`EnvironmentDefinition`
`actors`	`readonly ActorDefinition[]`

Returns

EnvironmentDefinition

constructionCandidates()function

function 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

Parameter	Type
`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[]; }; }`
`raw.catalog`	`string`
`raw.orientation?`	`"north" \| "east" \| "south" \| "west"`
`raw.target`	`\| { cell: [number, number, number]; } \| { area: { start: [number, number, number]; end: [number, number, number]; }; } \| { edges: object[]; }`
`namespace`	`string`

Returns

readonly PlacementCandidate[]

constructionPlanActions()function

function 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

Parameter	Type
`options`	`ConstructionPlanOptions`

Returns

readonly ActionRequest[]

constructionTarget()function

function constructionTarget(site): ConstructionTarget;

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

Parameters

Parameter	Type
`site`	`ConstructionSiteState`

Returns

ConstructionTarget

constructionCell()function

function constructionCell(site): Vec3;

Parameters

Parameter	Type
`site`	`ConstructionSiteState`

Returns

Vec3

replaceFloor()function

function replaceFloor(orderId, existingFloorId, desiredCatalog): ActionRequest;

Parameters

Parameter	Type
`orderId`	`EntityId`
`existingFloorId`	`EntityId`
`desiredCatalog`	`string`

Returns

ActionRequest

planConstructions()function

function planConstructions(party, plans): ActionRequest;

Parameters

Parameter	Type
`party`	`EntityId`
`plans`	`readonly PlacementCandidate[]`

Returns

ActionRequest

prebuildStructures()function

function 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

Parameter	Type
`party`	`EntityId`
`plans`	`readonly PlacementCandidate[]`

Returns

ActionRequest

bindConstructionStage()function

function bindConstructionStage(site, contact): ActionRequest;

Parameters

Parameter	Type
`site`	`EntityId`
`contact`	`Vec3`

Returns

ActionRequest

setStructureOpen()function

function setStructureOpen(worker, site, open): ActionRequest;

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

Parameters

Parameter	Type
`worker`	`EntityId`
`site`	`EntityId`
`open`	`boolean`

Returns

ActionRequest

breakStructure()function

function 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

Parameter	Type
`site`	`EntityId`

Returns

ActionRequest

deconstruct()function

function deconstruct(worker, site): ActionRequest;

Parameters

Parameter	Type
`worker`	`EntityId`
`site`	`EntityId`

Returns

ActionRequest

formatDiagnostic()function

function formatDiagnostic(diagnostic): string;

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

Parameters

Parameter	Type
`diagnostic`	`Diagnostic`

Returns

string

fail()function

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

Throw one diagnostic.

Parameters

Parameter	Type	Default value
`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" \| "VD085" \| "VD086" \| "VD087" \| "VD088" \| "VD089" \| "VD090" \| "VD091" \| "VD081" \| "VD092" \| "VD084"	`undefined`
`message`	`string`	`undefined`
`hint`	`string`	`undefined`
`path`	`readonly (string \| number)[]`	`[]`

Returns

never

effect()function

function 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

Type Parameter
`T` extends `object`

Parameters

Parameter	Type	Description
`id`	`${string}.${string}`	-
`fields`	`EffectFields<T>`	Every field, `at` and `seq` included: `{ ..., at: "number", seq: "number" }`.

Returns

Effect<T>

createFeedback()function

function 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

Type Parameter
`Weapon` extends `string`
`Simple` extends `string`
`Swing` extends `string`

Parameters

Parameter	Type
`profile`	`FeedbackProfile<Weapon, Simple, Swing>`

Returns

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

felt()function

function 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

Parameter	Type
`cue`	`AuthoredFeedbackCue`
`by`	`string`

Returns

readonly AuthoredFeedbackCue[]

hordeMovement()function

function hordeMovement(options?): HordeSimulation;

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

Parameters

Parameter	Type
`options`	{ geometry?: { reads: readonly `${string}.${string}`[]; project: readonly FlowGeometry[]; }; steering?: { radius?: number; separation?: number; alignment?: number; neighbours?: number; candidates?: number; }; }
`options.geometry?`	{ reads: readonly `${string}.${string}`[]; project: readonly FlowGeometry[]; }
`options.geometry.reads`	readonly `${string}.${string}`[]
`options.geometry.project`
`options.steering?`	`{ radius?: number; separation?: number; alignment?: number; neighbours?: number; candidates?: number; }`
`options.steering.radius?`	`number`
`options.steering.separation?`	`number`
`options.steering.alignment?`	`number`
`options.steering.neighbours?`	`number`
`options.steering.candidates?`	`number`

Returns

HordeSimulation

perceptionFrame()function

function perceptionFrame(input, geometry?): object;

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

Parameters

Parameter	Type
`input`	`{ targets: object[]; sounds: object[]; now: number; soundBarrierLoss: number; }`
`input.targets`	`object[]`
`input.sounds?`	`object[]`
`input.now?`	`number`
`input.soundBarrierLoss?`	`number`
`geometry?`	`{ sight: FlowNavigation; sound: FlowNavigation; }`
`geometry.sight?`	`FlowNavigation`
`geometry.sound?`	`FlowNavigation`

Returns

object

Name	Type
`targets`	`readonly object[]`
`observe()`	`(input) => object`

assignHordeSlots()function

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

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

Parameters

Parameter	Type
`input`	`{ slots: readonly HordeSlot[]; bodies: readonly HordeSlotBody[]; }`
`input.slots`	`readonly HordeSlot[]`
`input.bodies`	`readonly HordeSlotBody[]`

Returns

ReadonlyMap<EntityId, HordeSlotAssignment>

localSteering()function

function localSteering(input): object;

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

Parameters

Parameter	Type
`input`	`{ radius?: number; separation?: number; alignment?: number; neighbours?: number; candidates?: number; }`
`input.radius?`	`number`
`input.separation?`	`number`
`input.alignment?`	`number`
`input.neighbours?`	`number`
`input.candidates?`	`number`

Returns

object

Name	Type
`advance()`	`(input) => object`

resolveLook()function

function resolveLook(spec): Look;

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

Parameters

Parameter	Type
`spec`	`LookSpec \| undefined`

Returns

Look

ambientLightForMood()function

function ambientLightForMood(look, mood): number;

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

Parameters

Parameter	Type
`look`	`Look`
`mood`	`"day" \| "dusk" \| "night"`

Returns

number

moodAt()function

function 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

Parameter	Type
`look`	`Look`
`seconds`	`number`

Returns

"day" | "dusk" | "night"

instantiateActors()function

function instantiateActors(bindingId, expectedSequence, plan): ActionRequest;

Parameters

Parameter	Type
`bindingId`	`string`
`expectedSequence`	`number`
`plan`	`ActorInstantiationPlan`

Returns

ActionRequest

partyMemberIds()function

function 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

Parameter	Type
`read`	`<T>(spec) => QueryView<T>`
`viewer`	`CommandScope`

Returns

ReadonlySet<EntityId>

ownedActorIds()function

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

Parameters

Parameter	Type
`read`	`<T>(spec) => QueryView<T>`
`viewer`	`CommandScope`

Returns

ReadonlySet<EntityId>

definePhaseCycle()function

function 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

Type Parameter
`Phase` extends `string`

Parameters

Parameter	Type
`definitions`	`readonly object[]`

Returns

object

Name	Type
`seconds`	`number`
`duration()`	`(id) => number`
`advance()`	`(clock, now) => PhaseAdvance<Phase>`

requestProcess()function

function requestProcess(definition, station): object;

Parameters

Parameter	Type
`definition`	`string`
`station`	`EntityId`

Returns

object

Name	Type
`kind`	`"request-process"`
`definition`	`string`
`station`	`EntityId`

admitProcess()function

function admitProcess(process, definition, station): object;

Parameters

Parameter	Type
`process`	`EntityId`
`definition`	`string`
`station`	`EntityId`

Returns

object

Name	Type
`kind`	`"admit-process"`
`process`	`EntityId`
`definition`	`string`
`station`	`EntityId`

place()function

function 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

Parameter	Type
`actor`	`ActorDefinition`
`options`	`{ at: Cell2; id?: string; params?: Readonly<Record<string, string \| number \| boolean \| null>>; surface?: "sea"; }`
`options.at`	`Cell2`
`options.id?`	`string`
`options.params?`	`Readonly<Record<string, string \| number \| boolean \| null>>`
`options.surface?`	`"sea"`

Returns

Placement

compileScene()function

function compileScene(scene): CompiledScene;

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

Parameters

Parameter	Type
`scene`	`readonly Placement[]`

Returns

CompiledScene

spawn()function

function 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. A cell chooses terrain height; a native standing contact preserves its support height and is checked for clearance and occupancy before spawning.

Parameters

Parameter	Type
`actor`	`ActorDefinition`
`options`	`{ receipt: string; cause: string; at: Cell2 \| Vec3 & object; params?: Readonly<Record<string, string \| number \| boolean \| null>>; refs?: Readonly<Record<string, EntityId>>; }`
`options.receipt`	`string`
`options.cause`	`string`
`options.at`	`Cell2 \| Vec3 & object`
`options.params?`	`Readonly<Record<string, string \| number \| boolean \| null>>`
`options.refs?`	`Readonly<Record<string, EntityId>>`

Returns

ActionRequest

defineSeatGoal()function

function defineSeatGoal<F>(goal): SeatGoal;

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

Type Parameters

Type Parameter
`F` extends `Readonly`<`Record`<`string`, `number`>>

Parameters

Parameter	Type
`goal`	`SeatGoal<F>`

Returns

SeatGoal

voxel()function

function voxel(input): VoxelTerrainChoice;

Parameters

Parameter	Type
`input`	`{ environment: EnvironmentDefinition; art: TerrainPresentationDefinition; }`
`input.environment`	`EnvironmentDefinition`
`input.art`	`TerrainPresentationDefinition`

Returns

VoxelTerrainChoice

seaTerrain()function

function seaTerrain(input): SeaTerrainChoice;

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

Parameters

Parameter	Type
`input`	`{ environment: EnvironmentDefinition; art: TerrainPresentationDefinition; }`
`input.environment`	`EnvironmentDefinition`
`input.art`	`TerrainPresentationDefinition`

Returns

SeaTerrainChoice

actorTarget()function

function actorTarget<T>(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.

Type Parameters

Type Parameter
`T` extends `object`

Parameters

Parameter	Type
`component`	`ComponentDefinition<T>`

Returns

object

Name	Type
`input`	`ZodObject<{ entity: ZodString; }>`
`subjects()`	`(context) => readonly EntityId[]`
`binding`	`Pick<GameLocalBinding, "target" \| "component">`

gameWindow()function

function 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

Parameter	Type
`id`	`string`
`spec`	`object & object`

Returns

CartridgeWindow

checkWindows()function

function checkWindows(windows): readonly CartridgeWindow[];

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

Parameters

Parameter	Type
`windows`	`readonly CartridgeWindow[]`

Returns

readonly CartridgeWindow[]

checkKeys()function

function 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

Parameter	Type
`windows`	`readonly CartridgeWindow[]`
`controls`	`readonly object[]`

Returns

void

windowContents()function

function 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

Parameter	Type
`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()function

function workAttemptsFor(context, tasks): readonly WorkAttempt[];

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

Parameters

Parameter	Type
`context`	`Pick<ReadContext, "workAttempts">`
`tasks`	`readonly EntityId[]`

Returns

readonly WorkAttempt[]

workAttempt()function

function workAttempt(context, task): WorkAttempt | null;

Read the one native attempt projection for a task.

Parameters

Parameter	Type
`context`	`Pick<ReadContext, "workAttempts">`
`task`	`EntityId`

Returns

WorkAttempt | null

beginRouteWorkAttempt()function

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

Parameters

Parameter	Type
`context`	`Pick<WriteContext, "action">`
`task`	`EntityId`
`worker`	`EntityId`
`destination`	`MoveDestination`

Returns

void

interruptWorkAttempt()function

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

Parameters

Parameter	Type
`context`	`Pick<WriteContext, "action">`
`attempt`	`WorkAttemptKey`
`operationSequence`	`number`
`cause`	`WorkInterruptCause`

Returns

void

retargetRouteWorkAttempt()function

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

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

Parameters

Parameter	Type
`context`	`Pick<WriteContext, "action">`
`attempt`	`WorkAttemptKey`
`operationSequence`	`number`
`destination`	`MoveDestination`

Returns

void

continueRouteWorkAttempt()function

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

Parameters

Parameter	Type
`context`	`Pick<WriteContext, "action"> & Pick<ReadContext, "workAttempts">`
`attempt`	`WorkAttemptKey`
`operationSequence`	`number`
`destination`	`MoveDestination`

Returns

void

acknowledgeWorkAttempt()function

function acknowledgeWorkAttempt(context, attempt, operationSequence): void;

Acknowledge only the currently projected terminal operation.

Parameters

Parameter	Type
`context`	`Pick<WriteContext, "action"> & Pick<ReadContext, "workAttempts">`
`attempt`	`WorkAttemptKey`
`operationSequence`	`number`

Returns

void

continueDeconstructionWorkAttempt()function

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

Parameters

Parameter	Type
`context`	`Pick<WriteContext, "action"> & Pick<ReadContext, "workAttempts">`
`attempt`	`WorkAttemptKey`
`operationSequence`	`number`
`site`	`EntityId`
`contact`	`ConstructionAccessContact`

Returns

void

continueResourceEstablishWorkAttempt()function

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

Parameters

Parameter	Type
`context`	`Pick<WriteContext, "action"> & Pick<ReadContext, "workAttempts">`
`attempt`	`WorkAttemptKey`
`operationSequence`	`number`
`site`	`EntityId`
`definition`	`string`
`cell`	`readonly [number, number, number]`

Returns

void

continueResourceTendWorkAttempt()function

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

Parameters

Parameter	Type
`context`	`Pick<WriteContext, "action"> & Pick<ReadContext, "workAttempts">`
`attempt`	`WorkAttemptKey`
`operationSequence`	`number`
`site`	`EntityId`
`vessel`	`EntityId`

Returns

void

continueResourceExtractWorkAttempt()function

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

Parameters

Parameter	Type
`context`	`Pick<WriteContext, "action"> & Pick<ReadContext, "workAttempts">`
`attempt`	`WorkAttemptKey`
`operationSequence`	`number`
`source`	`EntityId`

Returns

void

continueFieldWaterWorkAttempt()function

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

Parameters

Parameter	Type
`context`	`Pick<WriteContext, "action"> & Pick<ReadContext, "workAttempts">`
`attempt`	`WorkAttemptKey`
`operationSequence`	`number`
`vessel`	`EntityId`
`cell`	`readonly [number, number, number]`
`direction`	`"withdraw" \| "deposit"`
`portions`	`number`

Returns

void

continueMaterialTransferAttempt()function

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

Continue one admitted attempt through the native material transfer owner.

Parameters

Parameter	Type
`context`	`Pick<WriteContext, "action"> & Pick<ReadContext, "workAttempts">`
`attempt`	`WorkAttemptKey`
`operationSequence`	`number`
`lot`	`EntityId`
`from`	`EntityId`
`to`	`EntityId`
`quantity`	`number`

Returns

void

continueMaterialDropAttempt()function

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

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

Parameters

Parameter	Type
`context`	`Pick<WriteContext, "action"> & Pick<ReadContext, "workAttempts">`
`attempt`	`WorkAttemptKey`
`operationSequence`	`number`
`lot`	`EntityId`

Returns

void

checkRoom()function

function checkRoom(json, context): object;

JSON syntax and authored geometry are decoded together at the native boundary.

Parameters

Parameter	Type
`json`	`string`
`context`	`string`

Returns

object

Name	Type	Default value
`status`	`"valid"`	-
`value`	\| { id: string; pool: string[]; footprint: "1x1" \| "2x1" \| "2x2" \| "L3" \| "corridor2" \| "corridor3"; level: "any" \| "ground" \| "upper"; edges: Record<string, ["door" \| "archway" \| "window" \| "wall", "door" \| "archway" \| "window" \| "wall", "door" \| "archway" \| "window" \| "wall"]>; stairs: object[]; slots: Record<string, { at: [number, number]; kind: string; }>; styles: Partial<Record<"north" \| "east" \| "south" \| "west", string>>; } \| { rooms: object[]; entry: { node: string; edge: string; }; frontage: "north" \| "east" \| "south" \| "west"; }	-
`preview`	`object`	`worldgenAssemblySchema`
`preview.floors`	`object[]`	-
`preview.levels`	`object[]`	-
`preview.stairs`	`object[]`	-
`neighbours`	`object[]`	-

checkBuilding()function

function checkBuilding(json, context): object;

Parameters

Parameter	Type
`json`	`string`
`context`	`string`

Returns

object

Name	Type	Default value
`status`	`"valid"`	-
`value`	\| { id: string; pool: string[]; footprint: "1x1" \| "2x1" \| "2x2" \| "L3" \| "corridor2" \| "corridor3"; level: "any" \| "ground" \| "upper"; edges: Record<string, ["door" \| "archway" \| "window" \| "wall", "door" \| "archway" \| "window" \| "wall", "door" \| "archway" \| "window" \| "wall"]>; stairs: object[]; slots: Record<string, { at: [number, number]; kind: string; }>; styles: Partial<Record<"north" \| "east" \| "south" \| "west", string>>; } \| { rooms: object[]; entry: { node: string; edge: string; }; frontage: "north" \| "east" \| "south" \| "west"; }	-
`preview`	`object`	`worldgenAssemblySchema`
`preview.floors`	`object[]`	-
`preview.levels`	`object[]`	-
`preview.stairs`	`object[]`	-
`neighbours`	`object[]`	-

compileBuilding()function

function compileBuilding(request): object;

Rust compiles all geometry and bounded host actions; the action owner decodes them.

Parameters

Parameter	Type
`request`	`{ id: string; party: string; origin: { x: number; y: number; z: number; }; layout: { rooms: object[]; entry: { node: string; edge: string; }; frontage: "north" \| "east" \| "south" \| "west"; slotKinds: string[]; }; kit: { wall: string; door: string; window: string; floor: string; roof: string; stair: string; styles: Record<string, { wall: string; door: string; window: string; }>; }; }`
`request.id`	`string`
`request.party`	`string`
`request.origin`	`{ x: number; y: number; z: number; }`
`request.origin.x`	`number`
`request.origin.y`	`number`
`request.origin.z`	`number`
`request.layout`	`{ rooms: object[]; entry: { node: string; edge: string; }; frontage: "north" \| "east" \| "south" \| "west"; slotKinds: string[]; }`
`request.layout.rooms`	`object[]`
`request.layout.entry`	`{ node: string; edge: string; }`
`request.layout.entry.node`	`string`
`request.layout.entry.edge`	`string`
`request.layout.frontage`	`"north" \| "east" \| "south" \| "west"`
`request.layout.slotKinds`	`string[]`
`request.kit`	`{ wall: string; door: string; window: string; floor: string; roof: string; stair: string; styles: Record<string, { wall: string; door: string; window: string; }>; }`
`request.kit.wall`	`string`
`request.kit.door`	`string`
`request.kit.window`	`string`
`request.kit.floor`	`string`
`request.kit.roof`	`string`
`request.kit.stair`	`string`
`request.kit.styles`	`Record<string, { wall: string; door: string; window: string; }>`

Returns

object

Name	Type
`batches`	`object[]`
`slots`	`object[]`

parseGenerationKey()function

function parseGenerationKey(json): GenerationFingerprint;

serde parses authoring JSON; Zod parses the kernel’s typed wire result.

Parameters

Parameter	Type
`json`	`string`

Returns

GenerationFingerprint

planChunk()function

function planChunk(policy, key): object;

Parameters

Parameter	Type
`policy`	{ identity: { seed: string; version: "worldgen-v1"; kitHash: string; }; focusComponent: string; chunkCells: number; windowCells: number; prefetchRings: number; batchesPerStep: number; population?: { party: string; townRadius: number; fringeChunks: number; fringePercent: number; ruralPercent: number; decorationPiecesPerStep: number; rooms: object[]; slotKinds: string[]; buildings: object[]; kit: { wall: string; door: string; window: string; floor: string; roof: string; stair: string; styles: Record<string, { wall: string; door: string; window: string; }>; }; }; }
`policy.identity`	`{ seed: string; version: "worldgen-v1"; kitHash: string; }`
`policy.identity.seed`	`string`
`policy.identity.version`	`"worldgen-v1"`
`policy.identity.kitHash`	`string`
`policy.focusComponent`	`string`
`policy.chunkCells`	`number`
`policy.windowCells`	`number`
`policy.prefetchRings`	`number`
`policy.batchesPerStep`	`number`
`policy.population?`	`{ party: string; townRadius: number; fringeChunks: number; fringePercent: number; ruralPercent: number; decorationPiecesPerStep: number; rooms: object[]; slotKinds: string[]; buildings: object[]; kit: { wall: string; door: string; window: string; floor: string; roof: string; stair: string; styles: Record<string, { wall: string; door: string; window: string; }>; }; }`
`policy.population.party`	`string`
`policy.population.townRadius`	`number`
`policy.population.fringeChunks`	`number`
`policy.population.fringePercent`	`number`
`policy.population.ruralPercent`	`number`
`policy.population.decorationPiecesPerStep`	`number`
`policy.population.rooms`	`object[]`
`policy.population.slotKinds`	`string[]`
`policy.population.buildings`	`object[]`
`policy.population.kit`	`{ wall: string; door: string; window: string; floor: string; roof: string; stair: string; styles: Record<string, { wall: string; door: string; window: string; }>; }`
`policy.population.kit.wall`	`string`
`policy.population.kit.door`	`string`
`policy.population.kit.window`	`string`
`policy.population.kit.floor`	`string`
`policy.population.kit.roof`	`string`
`policy.population.kit.stair`	`string`
`policy.population.kit.styles`	`Record<string, { wall: string; door: string; window: string; }>`
`key`	`{ x: number; z: number; }`
`key.x`	`number`
`key.z`	`number`

Returns

object

Name	Type	Default value
`key`	`object`	`chunkKeySchema`
`key.x`	`number`	-
`key.z`	`number`	-
`roads`	`object[]`	-
`lots`	`object[]`	-

chunkGroundAt()function

function chunkGroundAt(policy): (x, z) => "grass" | "gravel";

Bounded presentation cache; generation and road geometry stay native.

Parameters

Parameter	Type
`policy`	{ identity: { seed: string; version: "worldgen-v1"; kitHash: string; }; focusComponent: string; chunkCells: number; windowCells: number; prefetchRings: number; batchesPerStep: number; population?: { party: string; townRadius: number; fringeChunks: number; fringePercent: number; ruralPercent: number; decorationPiecesPerStep: number; rooms: object[]; slotKinds: string[]; buildings: object[]; kit: { wall: string; door: string; window: string; floor: string; roof: string; stair: string; styles: Record<string, { wall: string; door: string; window: string; }>; }; }; }
`policy.identity`	`{ seed: string; version: "worldgen-v1"; kitHash: string; }`
`policy.identity.seed`	`string`
`policy.identity.version`	`"worldgen-v1"`
`policy.identity.kitHash`	`string`
`policy.focusComponent`	`string`
`policy.chunkCells`	`number`
`policy.windowCells`	`number`
`policy.prefetchRings`	`number`
`policy.batchesPerStep`	`number`
`policy.population?`	`{ party: string; townRadius: number; fringeChunks: number; fringePercent: number; ruralPercent: number; decorationPiecesPerStep: number; rooms: object[]; slotKinds: string[]; buildings: object[]; kit: { wall: string; door: string; window: string; floor: string; roof: string; stair: string; styles: Record<string, { wall: string; door: string; window: string; }>; }; }`
`policy.population.party`	`string`
`policy.population.townRadius`	`number`
`policy.population.fringeChunks`	`number`
`policy.population.fringePercent`	`number`
`policy.population.ruralPercent`	`number`
`policy.population.decorationPiecesPerStep`	`number`
`policy.population.rooms`	`object[]`
`policy.population.slotKinds`	`string[]`
`policy.population.buildings`	`object[]`
`policy.population.kit`	`{ wall: string; door: string; window: string; floor: string; roof: string; stair: string; styles: Record<string, { wall: string; door: string; window: string; }>; }`
`policy.population.kit.wall`	`string`
`policy.population.kit.door`	`string`
`policy.population.kit.window`	`string`
`policy.population.kit.floor`	`string`
`policy.population.kit.roof`	`string`
`policy.population.kit.stair`	`string`
`policy.population.kit.styles`	`Record<string, { wall: string; door: string; window: string; }>`

Returns

(x, z) => "grass" | "gravel"

compileChunkLot()function

function compileChunkLot(policy, key, support): object;

Uses the same native layout/rotation/compiler as first-wake construction.

Parameters

Parameter	Type
`policy`	{ identity: { seed: string; version: "worldgen-v1"; kitHash: string; }; focusComponent: string; chunkCells: number; windowCells: number; prefetchRings: number; batchesPerStep: number; population?: { party: string; townRadius: number; fringeChunks: number; fringePercent: number; ruralPercent: number; decorationPiecesPerStep: number; rooms: object[]; slotKinds: string[]; buildings: object[]; kit: { wall: string; door: string; window: string; floor: string; roof: string; stair: string; styles: Record<string, { wall: string; door: string; window: string; }>; }; }; }
`policy.identity`	`{ seed: string; version: "worldgen-v1"; kitHash: string; }`
`policy.identity.seed`	`string`
`policy.identity.version`	`"worldgen-v1"`
`policy.identity.kitHash`	`string`
`policy.focusComponent`	`string`
`policy.chunkCells`	`number`
`policy.windowCells`	`number`
`policy.prefetchRings`	`number`
`policy.batchesPerStep`	`number`
`policy.population?`	`{ party: string; townRadius: number; fringeChunks: number; fringePercent: number; ruralPercent: number; decorationPiecesPerStep: number; rooms: object[]; slotKinds: string[]; buildings: object[]; kit: { wall: string; door: string; window: string; floor: string; roof: string; stair: string; styles: Record<string, { wall: string; door: string; window: string; }>; }; }`
`policy.population.party`	`string`
`policy.population.townRadius`	`number`
`policy.population.fringeChunks`	`number`
`policy.population.fringePercent`	`number`
`policy.population.ruralPercent`	`number`
`policy.population.decorationPiecesPerStep`	`number`
`policy.population.rooms`	`object[]`
`policy.population.slotKinds`	`string[]`
`policy.population.buildings`	`object[]`
`policy.population.kit`	`{ wall: string; door: string; window: string; floor: string; roof: string; stair: string; styles: Record<string, { wall: string; door: string; window: string; }>; }`
`policy.population.kit.wall`	`string`
`policy.population.kit.door`	`string`
`policy.population.kit.window`	`string`
`policy.population.kit.floor`	`string`
`policy.population.kit.roof`	`string`
`policy.population.kit.stair`	`string`
`policy.population.kit.styles`	`Record<string, { wall: string; door: string; window: string; }>`
`key`	`{ x: number; z: number; }`
`key.x`	`number`
`key.z`	`number`
`support`	`number`

Returns

object

Name	Type
`batches`	`object[]`
`slots`	`object[]`

meadow()function

function meadow(options?): WorldSpec;

A generated grassy world: soil over stone, rolling from seed, radius cells out from the origin. Everything a cartridge’s world needs.

Parameters

Parameter	Type
`options`	{ seed: string; radius?: number; chunks?: { identity: { seed: string; version: "worldgen-v1"; kitHash: string; }; focusComponent: string; chunkCells: number; windowCells: number; prefetchRings: number; batchesPerStep: number; population?: { party: string; townRadius: number; fringeChunks: number; fringePercent: number; ruralPercent: number; decorationPiecesPerStep: number; rooms: object[]; slotKinds: string[]; buildings: object[]; kit: { wall: string; door: string; window: string; floor: string; roof: string; stair: string; styles: Record<string, { wall: string; door: string; window: string; }>; }; }; }; }
`options.seed`	`string`
`options.radius?`	`number`
`options.chunks?`	{ identity: { seed: string; version: "worldgen-v1"; kitHash: string; }; focusComponent: string; chunkCells: number; windowCells: number; prefetchRings: number; batchesPerStep: number; population?: { party: string; townRadius: number; fringeChunks: number; fringePercent: number; ruralPercent: number; decorationPiecesPerStep: number; rooms: object[]; slotKinds: string[]; buildings: object[]; kit: { wall: string; door: string; window: string; floor: string; roof: string; stair: string; styles: Record<string, { wall: string; door: string; window: string; }>; }; }; }
`options.chunks.identity`	`{ seed: string; version: "worldgen-v1"; kitHash: string; }`
`options.chunks.identity.seed`	`string`
`options.chunks.identity.version`	`"worldgen-v1"`
`options.chunks.identity.kitHash`	`string`
`options.chunks.focusComponent`	`string`
`options.chunks.chunkCells`	`number`
`options.chunks.windowCells`	`number`
`options.chunks.prefetchRings`	`number`
`options.chunks.batchesPerStep`	`number`
`options.chunks.population?`	`{ party: string; townRadius: number; fringeChunks: number; fringePercent: number; ruralPercent: number; decorationPiecesPerStep: number; rooms: object[]; slotKinds: string[]; buildings: object[]; kit: { wall: string; door: string; window: string; floor: string; roof: string; stair: string; styles: Record<string, { wall: string; door: string; window: string; }>; }; }`
`options.chunks.population.party`	`string`
`options.chunks.population.townRadius`	`number`
`options.chunks.population.fringeChunks`	`number`
`options.chunks.population.fringePercent`	`number`
`options.chunks.population.ruralPercent`	`number`
`options.chunks.population.decorationPiecesPerStep`	`number`
`options.chunks.population.rooms`	`object[]`
`options.chunks.population.slotKinds`	`string[]`
`options.chunks.population.buildings`	`object[]`
`options.chunks.population.kit`	`{ wall: string; door: string; window: string; floor: string; roof: string; stair: string; styles: Record<string, { wall: string; door: string; window: string; }>; }`
`options.chunks.population.kit.wall`	`string`
`options.chunks.population.kit.door`	`string`
`options.chunks.population.kit.window`	`string`
`options.chunks.population.kit.floor`	`string`
`options.chunks.population.kit.roof`	`string`
`options.chunks.population.kit.stair`	`string`
`options.chunks.population.kit.styles`	`Record<string, { wall: string; door: string; window: string; }>`

Returns

WorldSpec

sea()function

function sea(options): WorldSpec;

A chart sea with a rectangular sand shore in native terrain.

Parameters

Parameter	Type
`options`	`{ seed: string; radius?: number; shore: { minX: number; maxX: number; minZ: number; maxZ: number; }; }`
`options.seed`	`string`
`options.radius?`	`number`
`options.shore`	`{ minX: number; maxX: number; minZ: number; maxZ: number; }`
`options.shore.minX`	`number`
`options.shore.maxX`	`number`
`options.shore.minZ`	`number`
`options.shore.maxZ`	`number`

Returns

WorldSpec

Name	Type	Default value
`VD001`	`"cartridge header is invalid"`	`"cartridge header is invalid"`
`VD002`	`"a system is installed twice"`	`"a system is installed twice"`
`VD003`	`"two components share an id"`	`"two components share an id"`
`VD004`	`"a buildable is listed as an ordinary actor"`	`"a buildable is listed as an ordinary actor"`
`VD005`	`"a build command is defined next to construction()"`	`"a build command is defined next to construction()"`
`VD006`	`"buildables have no world to stand in"`	`"buildables have no world to stand in"`
`VD007`	`"buildables need voxel terrain"`	`"buildables need voxel terrain"`
`VD008`	`"terrain kind is unknown"`	`"terrain kind is unknown"`
`VD009`	`"shelf presentation is invalid"`	`"shelf presentation is invalid"`
`VD010`	`"an actor id is invalid"`	`"an actor id is invalid"`
`VD011`	`"an actor has a component twice"`	`"an actor has a component twice"`
`VD012`	`"an actor's initial value does not fit its component"`	`"an actor's initial value does not fit its component"`
`VD013`	`"a behavior needs components its actor lacks"`	`"a behavior needs components its actor lacks"`
`VD014`	`"an actor attaches a behavior twice"`	`"an actor attaches a behavior twice"`
`VD015`	`"two different behaviors share an id"`	`"two different behaviors share an id"`
`VD016`	`"an actor is defined twice in one cartridge"`	`"an actor is defined twice in one cartridge"`
`VD017`	`"membership is set by hand"`	`"membership is set by hand"`
`VD020`	`"a placed actor is missing a param"`	`"a placed actor is missing a param"`
`VD021`	`"a placed actor is given an unknown param"`	`"a placed actor is given an unknown param"`
`VD022`	`"the scene places one id twice"`	`"the scene places one id twice"`
`VD023`	`"a placed actor has a component without values"`	`"a placed actor has a component without values"`
`VD024`	`"a placed actor has no position"`	`"a placed actor has no position"`
`VD025`	`"two placed actors have the same target cell"`	`"two placed actors have the same target cell"`
`VD030`	`"a window id is not namespaced"`	`"a window id is not namespaced"`
`VD031`	`"a window is declared twice"`	`"a window is declared twice"`
`VD032`	`"two windows share a key"`	`"two windows share a key"`
`VD033`	`"a control key is not one lowercase letter or digit"`	`"a control key is not one lowercase letter or digit"`
`VD034`	`"two controls, windows or shell keys share a key"`	`"two controls, windows or shell keys share a key"`
`VD040`	`"an actor given to construction() is not buildable"`	`"an actor given to construction() is not buildable"`
`VD041`	`"a buildable is declared twice"`	`"a buildable is declared twice"`
`VD050`	`"dismemberment settings are invalid"`	`"dismemberment settings are invalid"`
`VD051`	`"a cast has no look of that name"`	`"a cast has no look of that name"`
`VD052`	`"a cast is invalid"`	`"a cast is invalid"`
`VD060`	`"a cartridge's look is invalid"`	`"a cartridge's look is invalid"`
`VD061`	`"a game window's options are invalid"`	`"a game window's options are invalid"`
`VD070`	`"a blueprint module is invalid"`	`"a blueprint module is invalid"`
`VD071`	`"two blueprint rooms overlap"`	`"two blueprint rooms overlap"`
`VD072`	`"a blueprint doorway leads outside"`	`"a blueprint doorway leads outside"`
`VD073`	`"two blueprint rooms disagree about a shared wall"`	`"two blueprint rooms disagree about a shared wall"`
`VD074`	`"a styled blueprint piece has no buildable"`	`"a styled blueprint piece has no buildable"`
`VD080`	`"local play seats more than one party"`	`"local play seats more than one party"`
`VD083`	`"world lighting presentation is invalid"`	`"world lighting presentation is invalid"`
`VD082`	`"camera presentation is invalid"`	`"camera presentation is invalid"`
`VD085`	`"a worldgen room footprint or bay edge is invalid"`	`"a worldgen room footprint or bay edge is invalid"`
`VD086`	`"worldgen rooms disagree at a shared edge"`	`"worldgen rooms disagree at a shared edge"`
`VD087`	`"worldgen stairs or stairwells do not match"`	`"worldgen stairs or stairwells do not match"`
`VD088`	`"an upper worldgen bay is unsupported"`	`"an upper worldgen bay is unsupported"`
`VD089`	`"a worldgen room is unreachable or its entry misses the frontage"`	`"a worldgen room is unreachable or its entry misses the frontage"`
`VD090`	`"a worldgen slot kind is undeclared"`	`"a worldgen slot kind is undeclared"`
`VD091`	`"a worldgen building exceeds its piece limit"`	`"a worldgen building exceeds its piece limit"`
`VD081`	`"page interest radius is invalid"`	`"page interest radius is invalid"`
`VD092`	`"blueprint compilation is invalid"`	`"blueprint compilation is invalid"`
`VD084`	`"generation key is invalid"`	`"generation key is invalid"`

API reference

Exports

CartridgeErrorCclass

Extends

Constructors

Constructor

Parameters

Returns

Overrides

Properties

diagnostics

Vec3Iinterface

Extended by

Properties

x

y

z

MoveDestinationIinterface

Extends

Properties

x

Inherited from

y

Inherited from

z

Inherited from

frame

RouteCostRequestIinterface

Properties

actor

target

excavationTarget?

RouteToAnyRequestIinterface

Properties

actor

targets

excavationTarget?

WorkMaterialFactsIinterface

Properties

version

containers

lots

PoseIinterface

Properties

position

facing

WorldPositionIinterface

Extends

Properties

x

Inherited from

y

Inherited from

z

Inherited from

facing

SupportSurfaceIinterface

Properties

minX

maxX

minZ

maxZ

height

WorldPoseIinterface

Properties

id

local

world

support

surface

ComponentDefinitionIinterface

Type Parameters

Properties

id

version

fields

targetField?

sourceRequires?

targetRequires?

onTargetRemoved?

CartridgeErrorclass

Vec3interface

MoveDestinationinterface

RouteCostRequestinterface

RouteToAnyRequestinterface

WorkMaterialFactsinterface

Poseinterface

WorldPositioninterface

SupportSurfaceinterface

WorldPoseinterface

ComponentDefinitioninterface

VisualVariantRuleinterface

EntityRecordinterface

QuerySpecinterface

QueryRowinterface

QueryViewinterface

JobStepinterface

JobPlaninterface

ActionResultinterface

Impactinterface