---
title: "Visual Scripting"
description: "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](../product/v1/ex"
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/creator/visual-scripting/
---
# 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](../product/v1/explanation/script-ir-and-gessascript.md)
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.variables` in 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-ir` block.

Switching back to visual scripting reconstructs the graph from that canonical
IR block.

## More Guides

- [Variables](./visual-scripting-variables.md)
- [Functions](./visual-scripting-functions.md)
- [Events](./visual-scripting-events.md)
- [Parking](./visual-scripting-parking.md)
- [Comments](./visual-scripting-comments.md)
- [Reroutes](./visual-scripting-reroutes.md)
- [Collaboration](./visual-scripting-collaboration.md)
- [SDK Access](./visual-scripting-sdk-access.md)