build-gtk

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 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.

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, stylesheet)] for placement, icon, default title and USS.

3. Validation. Override OnGraphChanged(GraphLogger logger) and report with logger.LogError, LogWarning or Log, passing the offending node or port as context so the marker appears on it. Never mutate the graph in this callback; put the fix in a GraphLogAction attached to the message, a menu item, or the importer.

4. Structure, as requested. Context and block nodes, subgraphs, blackboard variables, type casting through IsConnectionAllowed, a toolbar element, or a context menu. Details in graph-api.md.

5. Output. A ScriptedImporter registered on the same extension compiles the graph into a plain runtime asset. The shape is always the same:

   var graph = GraphDatabase.LoadGraphForImporter<MyGraph>(ctx.assetPath);   // never LoadGraph here
   if (graph == null) return;                                                 // bad path or type: log and stop
   var start = graph.GetNodes().OfType<StartNode>().FirstOrDefault();
   if (start == null) return;                                                 // OnGraphChanged already reported it
   var next = start.GetOutputPortByName("Next").FirstConnectedPort?.GetNode(); // null when unconnected
   var titlePort = next.GetInputPortByName("Title");
   titlePort.TryGetValue<string>(out var title);                              // the value typed on the node
   if (titlePort.IsConnected) { /* resolve titlePort.FirstConnectedPort.GetNode() upstream instead */ }
   ctx.AddObjectToAsset("Runtime", runtime); ctx.SetMainObject(runtime);

   The runtime asset and its assembly must not reference Unity.GraphToolkit.Editor; keep Hash128 IDs as Hash128. Debug views and code-built graphs are in runtime-and-visualization.md.

6. Verify as described below.

Workflow B: build a state machine tool (Unity 6.7 and newer)

Read references/state-machine-api.md now; there is no manual walkthrough for this API yet, so that file and the Script Reference are the only accurate sources for its member names.

1. State machine class. [StateMachine(AssetExtension)] [Serializable] class MySM : StateMachine plus a menu item calling StateMachineDatabase.PromptInProjectBrowserToCreateNewAsset<MySM>().
2. States. [Serializable] class Patrol : State. States have no ports; the state machine owns the transitions. Options declared in OnDefineOptions appear only in the Graph Inspector.
3. Conditions. [Serializable] [Condition("Health")] class HealthCondition : Condition<float> with protected override bool DisplayComparisonDropdown => true when a comparison operator is wanted. Derive from Condition directly for a valueless trigger. Group (And/Or) and variable conditions are built in; do not reimplement them.
4. Optional. Custom self transitions (SelfTransition + [Transition(...)]), custom UI through StateView<T> and ConditionView<T>, and [StateMachineMenu] / [ConditionMenu] entries.
5. Validation. Override OnStateMachineChanged(StateMachineLogger logger). Same rules as OnGraphChanged.
6. Output. A ScriptedImporter loads with StateMachineDatabase.LoadStateMachineForImporter<MySM>, then walks GetStates(), each state's GetOutgoingTransitions(), each transition's GetRules(), and each rule's RootCondition tree. That tree always contains the built-in kinds as well as the user's classes, so the compiler must handle IGroupCondition (recurse, honour Operation) and IVariableCondition (Variable.Name, Comparison, Value) before matching custom Condition<T> types.

Editing a graph from code

When a menu item, generator or tool builds or edits an asset, bracket the mutations: LoadGraph/CreateGraph → UndoBeginRecordGraph("Action") → AddNode, Connect, port.TrySetValue, CreateVariable → GraphDatabase.SaveGraph(graph) → UndoEndRecordGraph(). The state machine equivalents are UndoBeginRecordStateMachine, Connect(fromState, toState), SaveStateMachine and UndoEndRecordStateMachine. Mutating inside OnEnable, OnDisable, OnGraphChanged or OnStateMachineChanged throws InvalidOperationException.

Decisions

Constraints

• Use member names exactly as the references spell them: properties are PascalCase (FirstConnectedPort, IsConnected), attributes take positional constructor arguments, and IDs are Hash128. When a member is not listed in the references, look it up at the URL pattern below rather than guessing its name or casing, because a guessed member fails to compile and the user cannot tell a typo from a missing feature.
• Link to the Script Reference or manual instead of restating them, so the answer stays correct when the docs change.
• Keep runtime assemblies free of Unity.GraphToolkit.Editor, and put visualization code inside a runtime assembly under #if UNITY_EDITOR, because the module is Editor-only and any reference to it breaks the player build.
• Keep the user's existing tool structure and do not restyle or reorganize nodes that were not mentioned, because node and port names are lookup keys that importers and saved assets depend on.
• Do not use Graph Toolkit internals or private types as a workaround, because they are not accessible from user code and change without notice. If the public API cannot do something, say so and point at the community thread list below.

Verify

0. Read references/pitfalls.md and check the code against it before showing it to the user.
1. The project compiles with no errors. If the Unity CLI is available, use it to build or run the Editor headless; otherwise ask the user to focus the Editor and report the Console.
2. Create an asset from the new menu item, double-click it, add every node or state type from the Add menu, connect them, save, close and reopen. The Console must show no errors or warnings.
3. With an importer, select the asset and confirm the produced runtime object is the main asset in the Inspector. 3b. When you wrote runtime code (an executor, a debug view), add Debug.Log lines that prove the behaviour, such as the state entered or the node executed, enter Play mode, and read them. Remove or guard them once the behaviour is confirmed.
4. Re-read references/pitfalls.md and fix anything it flags.
5. If a step fails or the Console reports an error, go back and reread the reference file and the Topic map page for that step before retrying; the fix is usually a member name or a version gate you missed.

Final report

Give the user a short checklist: the files you created or changed and where they go, how to create and open the first asset, what the importer produces, and which Editor version the code targets. List what is left for them to decide or do next, such as more node types, the runtime executor, or the debug view, and any Console error you could not verify because no Editor was available.

Topic map

Prefer WebFetch over WebSearch; it is faster and lands on the exact page. Only fetch what you need. Replace <VERSION> before fetching:

• docs.unity.com/en-us/engine/<VERSION> and docs.unity3d.com/<VERSION>/Documentation: the project's Editor version from ProjectSettings/ProjectVersion.txt, for example 6000.6 or 6000.7.
• docs.unity3d.com/Packages/com.unity.graphtoolkit-samples@<VERSION>: the samples package version shown in the Package Manager, for example 0.6.

Pages, all under https://docs.unity.com/en-us/engine/<VERSION>/, served as markdown when the .md suffix is kept:

• Manual index: manual/extending-the-editor/gtk-index.md
• Implementing a graph tool: manual/extending-the-editor/gtk-index/implementing-a-graph-tool.md, with child pages implement-a-graph-tool.md, implement-nodes.md, implement-node-options.md, implement-context-nodes.md, implement-block-nodes.md, type-cast-ports.md, add-custom-toolbar-actions.md, add-subgraph-support.md, graph-processing.md under that folder
• Graph window and panels: manual/extending-the-editor/gtk-index/landing-graph-interface.md, with graph-window.md, blackboard.md, graph-inspector.md, minimap.md under it
• Script Reference: script-reference/unity/graphtoolkit/editor/<type>.md and .../<type>/<member>.md, all lowercase, generic arity dropped (condition.md for Condition<T>). Example: script-reference/unity/graphtoolkit/editor/graph/ongraphchanged.md. State machine types exist from 6000.7. The older form https://docs.unity3d.com/<VERSION>/Documentation/ScriptReference/Unity.GraphToolkit.Editor.<Type>.html also resolves, as HTML.
• Samples: https://docs.unity3d.com/Packages/com.unity.graphtoolkit-samples@<VERSION>/manual/index.html. Install com.unity.graphtoolkit-samples by name in the Package Manager, then import Texture Maker (importer), Visual Novel Director (custom runtime and debug view) or Dungeon Graph Generator (building a graph from code).
• Community: https://discussions.unity.com/tag/graph-toolkit