/build-gtk

name: build-gtk
description: >-
  Builds node-based Editor tools with Unity Graph Toolkit (GTK) on Unity 6.6+: graphs, nodes, ports
  and validation, State Machine API tools on 6.7+, and runtime assets via a scripted importer. Use for
  custom graph, node or state machine editors, or migrating a GraphView tool. Not for Shader Graph, VFX
  Graph or Animator Controllers.
required_editor_version: ">=6000.6"

Unity Graph Toolkit (GTK)

Build Editor graph tools and state machine tools on Unity's Graph Toolkit module, using only its public API in the `Unity.GraphToolkit.Editor` namespace.

Important

• Create a restore point you can roll back to if your changes fail.
• Do only what's asked. Don't change unrelated assets or files. Avoid long explanations.
• Before you go forward with a workflow or diagnosis, open and read the reference file(s) named in

that workflow and the [Topic map](#topic-map) page(s) that cover the thing you intend to do. Name the file(s) you read in your response. This is because your training knowledge about Unity might be out of date, incorrect, or for the wrong Unity version, and Graph Toolkit changed between 6000.4, 6000.6 and 6000.7.

References

Read these as needed. Paths are relative to this skill's folder.

• `references/graph-api.md` — the Graph API surface: Graph, Node, port and option builders, context

and block nodes, subgraphs, variables, validation, toolbar and context menus. Read before writing any graph-tool code.

• `references/state-machine-api.md` — the State Machine API (Unity 6.7+): StateMachine, State,

Condition, transitions and rules, self transitions, custom views. Read whenever states, transitions or conditions are involved.

• `references/runtime-and-visualization.md` — compiling a graph or state machine into a runtime asset

with a ScriptedImporter, and showing live execution in the graph editor. Read when the user wants the authored data used in the game or debugged at runtime.

• `references/pitfalls.md` — the mistakes that survive compilation. Read before handing off, and

whenever the user reports a compile error, an empty Add menu, a missing node, or an exception.

Step 1: Check the Editor version and pick the API

Read `m_EditorVersion` in `ProjectSettings/ProjectVersion.txt` before writing code. Graph Toolkit is an Editor module, so there is no package to install. `com.unity.graphtoolkit` is a deprecated shim and must not be added to the manifest.

| Editor version | What is available | |---|---| | Older than 6000.4 | Only the retired experimental package (0.x). Its API differs from this skill. Recommend upgrading. | | 6000.4 to 6000.5 | Module present, but without port capacity, type casting, wire and node visualization, USS node styling, or element IDs. | | 6000.6 | The Graph API this skill documents. | | 6000.7 and newer | Everything above plus the State Machine API, `NodeView<T>` / `StateView<T>` / `ConditionView<T>` custom UI, `[GraphMenu]` / `[BlackboardMenu]` context menus, the `GraphLogger.GraphChanges` change delta, port type-following, and Blackboard type restriction. Members marked **6.7** in the references. |

If the user asks for a state machine tool on an Editor older than 6000.7, say plainly that the State Machine API is not available there. Do not emulate it with the Graph API unless asked.

Mental model

• Graph Toolkit is an authoring framework only. It draws and persists graphs; it never executes them.

The user writes the runtime data model and the code that runs it, usually fed by a ScriptedImporter.

• One asset type per `Graph` or `StateMachine` subclass, identified by the file extension passed to

`[Graph("ext")]` or `[StateMachine("ext")]`.

• Discovery is by reflection. Node, state and condition classes in the same assembly as the graph

class are listed automatically. Classes in other assemblies opt in with `[UseWithGraph]` or `[UseWithStateMachine]`. Abstract classes are never listed.

• Every authoring class is `[Serializable]` and lives in an Editor-only assembly, either an `Editor`

folder or an asmdef restricted to the Editor platform.

• Only the public API compiles for users. If a name from the left column appears in a draft, stop and

use the right column:

| Never write | Write instead | |---|---| | `GraphModel`, `GraphObject`, `GraphTool`, `Stencil`, `BaseGraphTool` | `Graph` and `GraphDatabase` | | `NodeModel`, `PortModel`, `WireModel` | `Node`, `IPort`, `Wire` | | `StateModel`, `TransitionModel`, `ConditionModel` | `State`, `ITransition`, `Condition<T>` | | `GraphViewEditorWindow`, `GraphElementsExtensionMethodsCache`, `ModelView` | the window is provided; `NodeView<T>` on 6000.7 for custom UI | | `UnityEditor.Experimental.GraphView`, `graphViewChanged`, `Port.Create` | no equivalent; model the tool as `Graph` and `Node` classes | | `com.unity.graphtoolkit` in the manifest | nothing; the module is built in |

Workflow A: build a graph tool

Read `references/graph-api.md` now, before writing code; member names and builder chains come from there, not from memory. Read `references/runtime-and-visualization.md` as well when step 5 applies.

1. **Graph class.** `[Graph(AssetExtension)] [Serializable] class MyGraph : Graph` with a `public const string AssetExtension`. Add a `[MenuItem("Assets/Create/...")]` static method that calls `GraphDatabase.PromptInProjectBrowserToCreateNewAsset<MyGraph>()`. Pass `GraphOptions.SupportsSubgraphs` in the attribute when subgraphs are wanted. 2. **Node classes.** `[Serializable] class MyNode : Node`. Override `OnDefinePorts` and end every port builder chain with `.Build()`. Override `OnDefineOptions` for inspector-editable settings, and read them inside `OnDefinePorts` with `GetNodeOptionByName(name).TryGetValue<T>(out var v)` when ports depend on them. Call `.Delayed()` on count-like options so ports are not rebuilt on every keystroke. Use `[Node("Category/Path", iconPath, title, styleshe