--- title: "Reference: Script Nodes" description: "Thin pointer to the generated Script IR node catalog and the generated Script SDK reference, how to read them and how nodes relate to SDK calls." engineVersion: v1.0.234 date: 2026-09-28 license: "(c) Gessa, proprietary. Cite with attribution to https://gessa.ai/docs/. Terms: https://gessa.ai/terms/." canonical: https://gessa.ai/docs/reference/script-nodes/ --- # 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`](../../../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`](../../../spec/generated/script-sdk.md): the generated Script SDK surface (`ScriptContext` and its host interfaces). {% generated-reference file="docs/spec/generated/script-node-catalog.md" label="Script IR node catalog" /%} {% generated-reference file="docs/spec/generated/script-sdk.md" label="Script SDK surface" /%} 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(...)`. 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. ```ts // 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 }); } ``` {% warning severity="caution" title="Author behavior semantically" %} Prefer the Script Semantic Patch flow (which lowers into the Script IR) over emitting raw IR. See [How-To: Write GessaScript](../how-to/write-gessascript.md) and the generated [`docs/spec/generated/script-semantic-patch.md`](../../../spec/generated/script-semantic-patch.md). {% /warning %} ## 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](../explanation/versioning-policy.md). ## Related - [How-To: Write GessaScript](../how-to/write-gessascript.md): author behavior via Script Semantic Patch. - [Explanation: Script IR and GessaScript](../explanation/script-ir-and-gessascript.md): why Script IR is the canonical behavior contract. - [`docs/spec/generated/script-semantic-patch.md`](../../../spec/generated/script-semantic-patch.md) and [`docs/spec/generated/script-effect-contracts.md`](../../../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.