Reference: Script Nodes

Gessa behavior is canonically a Script IR: a typed graph of nodes. The TypeScript script SDK is a projection of that same surface, so a ctx.* call and a script node are two views of one contract. This page is a thin pointer to both generated references (the node catalog and the SDK surface) and explains how to read them. Until a dedicated SDK page exists, this is also where the SDK reference is anchored. It does not restate the generated tables.

Canonical sources

Both are Tier-2 generated artifacts. Read them directly; do not hand-edit them.

• docs/spec/generated/script-node-catalog.md: the canonical Script IR node declarations (event, core, and host nodes) and their SDK host mapping.
• docs/spec/generated/script-sdk.md: the generated Script SDK surface (ScriptContext and its host interfaces).

The Tier-1 sources of truth are code: packages/script-nodes (with packages/script-codegen and the Script IR) for nodes, and packages/script-sdk for the SDK. The references are produced by the scripts/gen-script-node-docs.ts and scripts/gen-sdk-docs.ts generators (run via npm run gen-docs) and verified by npm run gen-docs:check. A family of check:script-* gates (for example check:script-node-surface-contract, check:gessascript-roundtrip, and check:script-effect-contracts) keeps the node surface, its visual/source parity, and its effect declarations honest.

What the node catalog contains

The node catalog opens with counts, then category and host tables, then per-node detail.

• Counts table. Node totals by kind: event, core, and host. The current per-kind counts and total live in the generated node catalog's counts table.
• Categories table. Every node grouped by domain: Audio, Components, Control, Debug, Events, Match, Multiplayer, Persistence, Physics, Platform, Team, UI, Values, and World, with the node ids in each.
• SDK Hosts table. The crucial cross-reference: each host node mapped to its SDK path, plus per-node contract flags: Deterministic, Metered, Risk (read, write, effect), Effect tags (for example writeState, requiresAuthority, nonRollbackable), and Permissions (for example component:write).

Representative nodes (verified ids from the file): event.start and event.tick (lifecycle events), core.if and core.sequence (control flow), host.world.spawn and host.world.despawn (world mutation), host.entity.patch_component (component write), and host.physics.occupancy_query (a physics query). For the full list, read the generated file.

What the SDK reference contains

The SDK reference documents the TypeScript surface scripts actually call.

• ScriptContext table. The canonical aggregate available to a script as ctx, key by key: for example ctx.entity (an EntityAccessor), ctx.physics (a PhysicsHost), ctx.world, ctx.events, ctx.warehouse, ctx.audio, and value fields like ctx.delta and ctx.trigger.
• Host Interfaces table. Each host namespace (AudioHost, PhysicsHost, WorldHost, WarehouseHost, the authoring hosts, and others), its member count, and the exact TypeScript declarations of each method.

Canonical ECS payload typing comes from the built-in component contracts (BuiltInComponentPayload, BuiltInComponentPatch, EngineComponentCatalog) exposed through ctx.entity.*Component<T extends BuiltInComponentType>(...). Project-defined components are weak, experimental project-local metadata, not production-grade typed ECS.

How nodes and SDK calls relate

A Script IR node is the canonical unit; the SDK path is its typed projection. For example, the host.physics.occupancy_query node corresponds to ctx.physics.occupancyQuery(...), and host.entity.patch_component corresponds to ctx.entity.patchComponent(...). The SDK Hosts table in the node catalog is the authoritative mapping between the two, including each node's determinism, metering, and authority requirements. Write nodes carry requiresAuthority, which is why scripts mutate state through authorized accessors rather than touching the Project Graph directly.

The shape below is illustrative of how a ctx call reads in a script body; the canonical signatures live in the generated SDK reference.

// On each tick, query who occupies the player's cell and react.
const occupants = ctx.physics.occupancyQuery(worldId, cellKey);
if (occupants.length > 1) {
  ctx.entity.patchComponent(ctx.entity.id, "component.timer", { paused: true });
}

Version pinning

Both generated files name their Tier-1 sources in the header and are kept in lockstep by gen-docs:check. The node catalog pins its shape with the kind counts and per-node contract flags; the SDK reference pins the ScriptContext and host-interface declarations. These trace back to packages/engine-version and the generated docs export manifest; see Versioning Policy.

Related

• How-To: Write GessaScript: author behavior via Script Semantic Patch.
• Explanation: Script IR and GessaScript: why Script IR is the canonical behavior contract.
• docs/spec/generated/script-semantic-patch.md and docs/spec/generated/script-effect-contracts.md: the semantic authoring and effect surfaces.

Status: stable orientation page; this page also anchors the SDK reference until a dedicated SDK page exists. The catalogs themselves are generated; trust the generated files over any prose here.