Visual Scripting
Visual scripting lets creators build gameplay behavior as a node graph, with readable TypeScript available alongside it. The canonical behavior contract is the Script IR: it is what the runtime executes, and both the node graph and the TypeScript source are projections generated from it. Editing either view edits the same underlying IR. See Explanation: Script IR and GessaScript for why behavior is modeled as one canonical IR with projections.
Core Concepts
- Exec wires define what runs and in what order.
- Data wires feed values into node inputs.
- Inline literal fields are used when an input is a simple value.
- Disconnected logic can stay on the canvas as parked content and does not run.
- Reroute nodes organize wires without changing behavior.
- Comment boxes and named groups document large graphs.
- Variables, functions, and custom events are typed script declarations.
Variables
Script variables are typed values shared by the script. Use Get Variable nodes to read a value and Set Variable nodes to update mutable variables. Values are backed by Runtime script state, so they persist across handler dispatches for the same room/entity/script.
Functions
Functions are reusable same-script subgraphs with typed inputs and outputs. Function calls appear as nodes in the main graph and compile to named TypeScript functions. Use the export toggle only for functions that external runtime clients should call through the SDK.
Custom Events
Custom events are typed named messages routed through the script event system. Scripts can dispatch custom events with payloads, and handlers can subscribe to them through the existing Runtime event surface.
TypeScript View
The TypeScript view shows the executing script:
- Parked graph content is not emitted as executable code.
- Variables use
ctx.script.variablesin generated TypeScript because runtime state lives outside the fresh QuickJS VM dispatch. - Exported functions appear in
defineScript({ functions }). - The full graph is preserved in the embedded
@gessa-irblock.
Switching back to visual scripting reconstructs the graph from that canonical IR block.