Script Node Declarations

Canonical Script IR node declarations live in @game-platform/script-nodes and are consumed by runtime, codegen, generated SDK declarations, AI tooling, and frontend visual authoring.

This package is the single declaration source for script visual nodes. It has no server or runtime dependencies and is safe for frontend imports.

Declaration catalog hash: sha256:468b13a39fc8b6669aed3440b538a3da66303c349cd8843c300235cd63ee1a2f.

Script source and language views

• GessaScript is an INDENTATION language: not TypeScript, not JSON. No braces around blocks, no semicolons, no imports, no host, function or set keywords. A block opens with : and its body is indented 4 spaces.
• Line 1 is script <scriptKey>. Top level accepts only: var <name> = <literal> (mutable), const <name> = <literal>, event <key>(<params>) (declares a custom event; no body), [export] [pure] def <name>(<params>) [-> <type>]: (a function; call it ONLY as a statement name(args), never inside an expression), and handlers, which are a @on.... decorator on the line directly above a def.
• Handler heads: @on.start over def start():; @on.tick over def tick(deltaSeconds): (name the binding whatever you like); @on.action("<actionKey>") over def action_<key>():; @on.timer("<timerKey>") over def timer_<key>():; @on.event("<customEventKey>") over def event_<key>(<bindings>):; @on.init over def init():; @on.frame over def frame(t, dt):; @on.resize over def resize(w, h):. Every other engine event is @on.runtime("<Event>") where <Event> is one of: onCharacterRemoved, onCharacterSpawned, onMatchEnded, onNetworkMessage, onPanelAction, onPhaseEnter, onPhaseExit, onPlayerJoined, onPlayerLeft, onPurchaseFulfilled, onTriggerEnter, onTriggerExit, onWidgetPress. @on.event("k") is a CUSTOM event you declared, so @on.event("trigger_enter") is NOT the trigger; write @on.runtime("onTriggerEnter"). The name under a decorator is normalized on save, so write the derived one.
• Statements: let x = <expr> (a local, assigned ONCE; declare a var at the top of the script for mutable state); assignment x = <expr>, x += 1 (also -= *= /=); if <cond>: / elif <cond>: / else:; for item in <array> [limit n]:; while <cond> [limit n]:; match <expr>: with case <value>: arms and a case _: catch-all; return <expr>; break; continue; pass; dispatch <eventKey>.emit(<args>); and calls Namespace.function(args) or name(args) on their own line.
• Expressions: literals (numbers, strings, True, False, [arrays], { objects }), member access a.b, conditional expressions a if condition else b, and operators: or, and, not, == !=, < <= > >=, + -, * / %, ??, unary -. There are NO helper calls for arithmetic or comparison: add(a, b) and gt(a, 0) do not exist (GS_ELAB_UNKNOWN_HOST); write a + b and a > 0. There are also no classes, imports, lambdas, comprehensions, exceptions or async: the parser answers each of those with the form to use instead.
• Engine functions are called BARE by dotted path: the hosts listed below (e.g. Debug.log("x")) and the core operations array.length(...), array.mutate.<push|addUnique|insert|removeAt|removeValue|clear|set|unique|reverse>(...), bitwise.<and|or|xor|not|shl|shr|ushr>(...), entity.id(...), event.key(...), math.<min|max|abs|floor|ceil|round|clamp|sqrt|pow|sign|lerp|sin|cos|tan|asin|acos|atan|atan2|exp|ln|log10|log2|deg2rad|rad2deg|wrapAngle|smoothstep|imul32>(...), math.remap(...), object.<set|merge|keys|entries|has|delete>(...), quat.<make|multiply|slerp|fromEuler|toEuler|lookAt|rotateVector|inverse>(...), string.<concat|length|format|contains|split|upper|lower|replace|substring|trim|startsWith|endsWith|indexOf>(...), vec3.<add|sub|scale|dot|cross|length|normalize|distance|lerp|make|breakX|breakY|breakZ|reflect|moveTowards|project|angleBetween|clampLength>(...).

script script.relic.pickup
var collected = 0
const goal = 3
var armed = False
event scored(points: number)
def announce(points: number):
    Debug.log("scored", { value: points })
@on.start
def start():
    armed = True
@on.action("player.reset")
def action_player_reset():
    collected = 0
@on.runtime("onTriggerEnter")
def runtime_on_trigger_enter():
    collected += 1
    let remaining = math.max(0, goal - collected)
    if collected >= goal:
        scored.emit(collected)
    elif remaining == 1:
        Debug.log("one more")
    else:
        Debug.log("collected", { value: collected })
@on.event("scored")
def event_scored(points):
    announce(points)
@on.tick
def tick(dt):
    match collected:
        case 0:
            Debug.log("empty")
        case _:
            if Entity.hasTag("relic") and dt > 0:
                Debug.log("relic")

Counts

Categories

SDK Hosts

Atom Contract Cards

Every launch host atom has a contract card derived from SCRIPT_ATOM_REGISTRY. Compatibility-only aliases are intentionally excluded from this table and from new authoring.

All Nodes

Node Details

One section per node, keyed by node id, so a reference to a node id resolves to its own anchor. Each carries the node description and its first example.

core.arithmetic

Applies a numeric operator.

{ "op": "arithmetic", "operator": "add", "left": {}, "right": {} }

core.array.first

Reads the first typed item from an array.

{ "op": "array.first", "array": { "op": "get", "path": ["targets"], "valueType": "entity_array" }, "valueType": "entity" }

core.array.for_each

Iterates a typed array with a bounded execution budget.

{ "op": "array.forEach", "array": { "op": "get", "path": ["targets"], "valueType": "entity_array" }, "item": "target", "itemType": "entity", "maxIterations": 32, "body": [] }

core.array.get

Reads one typed item from an array by index.

{ "op": "array.get", "array": { "op": "get", "path": ["targets"], "valueType": "entity_array" }, "index": { "op": "value.literal", "value": 0 }, "valueType": "entity" }

core.array.length

Counts items in a typed array value.

{ "op": "array.length", "array": { "op": "value.array", "items": [] } }

core.array.mutate

Functional array update: push, addUnique, insert, removeAt, removeValue, clear, set, unique, reverse - returns a NEW array (no in-place mutation). Write it back to a component via Patch (ATOM-5).

{ "op": "array.mutate", "operator": "push", "array": {}, "value": {} }

core.array.query

Pure array reads: contains (by value), indexOf (by value; UE Find), last, join, slice, concat. No predicate, matching UE (ATOM-6).

{ "op": "array.query", "operator": "join", "array": {}, "separator": {} }

core.array.reduce

Fold an array down to a single accumulated value with a per-item expression over a bounded slice. The array-algebra ELIMINATE: the dual of the build ops (Make Array / Add). item binds the current element, accumulator binds the running total; both read via Get (ATOM-7).

{ "op": "array.reduce", "array": {}, "seed": {}, "item": "x", "accumulator": "acc", "accumulatorType": "number", "maxIterations": 16, "expr": {} }

core.array.transform

map / filter / sortBy / find / some / every over an array with a per-item expression and a bounded iteration budget. A forEach-shaped special form with a named item binding - NOT a lambda. map/filter/sortBy return an array; find returns the matching item; some/every return a boolean (ATOM-7).

{ "op": "array.transform", "operator": "map", "array": {}, "item": "x", "itemType": "number", "maxIterations": 16, "expr": {} }

core.bitwise

Integer bit-algebra: and, or, xor, not, shl, shr, ushr. Operands and result are numbers with exact JavaScript ToInt32 semantics (ushr is ToUint32); shift counts are masked to 5 bits. Pairs with Math.imul32 for integer hashing, noise, and u32 pixel packing (ATOM-1).

{ "op": "bitwise", "operator": "and", "a": {}, "b": {} }

core.boolean

Combines two boolean values.

{ "op": "boolean", "operator": "and", "left": {}, "right": {} }

core.bounded.for

Runs a for loop with a maximum iteration budget.

{ "op": "bounded.for", "iterator": "i", "from": {}, "to": {}, "maxIterations": 10, "body": [] }

core.bounded.while

Runs a while loop with a maximum iteration budget.

{ "op": "bounded.while", "test": {}, "maxIterations": 10, "body": [] }

core.comparison

Compares two values. eqi / nei check case-insensitive string equality / inequality (UE Equal (String) ignore-case).

{ "op": "comparison", "operator": "gte", "left": {}, "right": {} }

core.component.patch

Buffers an authoritative component patch.

{ "op": "component.patch", "componentType": "TransformComponent", "patch": { "position": { "x": 0, "y": 1, "z": 0 } } }

core.component.read

Reads a component from the owning entity or a specified entity.

{ "op": "component.read", "componentType": "TransformComponent", "fields": ["position"] }

core.entity.id

Reads an entity's ID. With no input, uses the entity running this script.

{ "op": "entity.id" }

core.event.key

Reads the semantic key from the current runtime event.

{ "op": "event.key" }

core.event.payload.get

Reads a typed value from the current event payload.

{ "op": "event.payload.get", "path": ["entityId"], "valueType": "string" }

core.expression.codebox

Author a value as a freeform GessaScript expression instead of wiring value nodes. The text is parsed to a real, type-checked expression tree (W2-C); its result type is the inner expression's type.

{ "op": "expression.codebox", "expression": { "op": "value.literal", "value": 1 } }

core.flow.break

Stops the enclosing loop immediately and continues after it.

break;

core.flow.continue

Skips the rest of this iteration and advances the enclosing loop to the next one.

continue;

core.flow.do_n

Runs its body the first N times it is reached, then blocks until reset. UE DoN (ATOM-12).

{ "op": "flow.doN", "stateKey": "burst", "n": { "op": "value.literal", "value": 3 }, "body": [] }

core.flow.do_once

Runs its body the first time it is reached, then blocks until reset. UE DoOnce (ATOM-12).

{ "op": "flow.doOnce", "stateKey": "intro", "body": [] }

core.flow.flip_flop

Alternates between the A and B branches on each reach (A first). UE FlipFlop (ATOM-12).

{ "op": "flow.flipFlop", "stateKey": "toggle", "a": [], "b": [] }

core.flow.gate

Open/closed pass-through. enter runs the body only while open; open/close/toggle set the latch. UE Gate (ATOM-12).

{ "op": "flow.gate", "stateKey": "spawnGate", "action": "enter", "body": [] }

core.flow.multi_gate

Routes to one of N branches: cycle in order, seeded-random, or once-each. UE MultiGate (ATOM-12). Random uses the seeded RNG.

{ "op": "flow.multiGate", "stateKey": "spread", "mode": "cycle", "branches": [] }

core.flow.return

Stops the current event handler (or function) immediately; nothing after it runs.

return;

core.flow.timer.after

Schedules a latent continuation: after seconds (measured in ticks) the resumeEvent handler is re-entered. UE Delay (ATOM-13).

{ "op": "flow.timer.after", "seconds": { "op": "value.literal", "value": 2 }, "resumeEvent": "onDelayComplete" }

core.flow.timer.cancel

Cancels a pending latent timer by key before it fires; the schedule<->cancel dual of Timer After (ATOM-13).

cancel timer "reload";

core.get

Reads a bound variable or context path, preserving optional type evidence for a path whose declared type is unknown.

{ "op": "get", "path": ["ctx", "delta"] }

core.host.call

Calls a declared runtime host function.

{ "op": "host.call", "host": { "namespace": "Debug", "name": "log" }, "args": [] }

core.if

Runs one of two statement branches.

{ "op": "if", "test": { "op": "value.literal", "value": true }, "then": [], "else": [] }

core.let

Binds an expression to a local constant.

{ "op": "let", "name": "score", "value": { "op": "value.literal", "value": 0 } }

core.map

String-keyed map container: make, add, remove, contains, get, keys, values, length, merge. Functional (no in-place mutation); deterministic insertion-order iteration (ATOM-15).

{ "op": "map", "operator": "add", "map": {}, "key": {}, "value": {} }

core.math

Numeric library: min, max, abs, floor, ceil, round, clamp, sqrt, pow, sign, lerp, sin, cos, tan, asin, acos, atan, atan2, exp, ln, log10, log2, deg2rad, rad2deg, wrapAngle, smoothstep, imul32. The operator enum is the whole float/int library in one node (ATOM-1); imul32 is the 32-bit modular multiply (Math.imul) that pairs with the Bitwise node for integer hashing.

{ "op": "math", "operator": "abs", "a": {} }

core.math.remap

Re-scale a value from an input range [inMin, inMax] onto an output range [outMin, outMax], linearly. The five-operand gameplay staple (health bars, aim assist) that does not fit Math's a/b/c ternary shape, so it is its own op. Not clamped - pair with Clamp to bound it.

{ "op": "math.remap", "value": {}, "inMin": {}, "inMax": {}, "outMin": {}, "outMax": {} }

core.not

Negates a boolean value.

{ "op": "not", "value": { "op": "value.literal", "value": false } }

core.object

Functional record update + enumeration: set (one field) / merge (two objects) / delete (drop a field) return a NEW object; keys / entries / has read the record (dynamic-key enumeration; ATOM-8).

{ "op": "object", "operator": "merge", "target": {}, "source": {} }

core.quat

Quaternion rotation: make, multiply, slerp, fromEuler, toEuler, lookAt, rotateVector, inverse. Promotes the runtime Quaternion helpers; makes TransformComponent rotation ergonomic (ATOM-4).

{ "op": "quat", "operator": "fromEuler", "euler": {} }

core.record.get

Reads a typed field from an object, component, warehouse record, query result, or event payload object.

{ "op": "record.get", "record": { "op": "get", "path": ["progress"], "valueType": "data_record" }, "path": ["score"], "valueType": "number" }

core.select

Pure data multiplexer: returns ifTrue when condition is true, else ifFalse. UE Select - no exec branch (ATOM-9).

{ "op": "select", "condition": {}, "ifTrue": {}, "ifFalse": {}, "valueType": "number" }

core.sequence

Runs child statements in order.

{ "op": "sequence", "body": [] }

core.set

Assigns a value to a variable or path.

{ "op": "set", "path": ["state"], "value": { "op": "value.literal", "value": 1 } }

core.string

String operations: concat, length, format, contains, split, upper, lower, replace, substring, trim, startsWith, endsWith, indexOf. The operator enum composes dynamic HUD text and keys (ATOM-2).

{ "op": "string", "operator": "concat", "a": {}, "b": {} }

core.switch

Multi-way branch on an int / enum / string value: runs the matching case body, else the default. UE Switch (ATOM-9).

{ "op": "switch", "on": {}, "cases": [], "default": [] }

core.value.array

Creates an array from item expressions.

{ "op": "value.array", "items": [] }

core.value.assert