Scripting API#

Summary

Use the Scripting API to add Visual Script nodes and system integrations from C#, or run designer-authored logic from your own components. Custom types use the same editor discovery, serialization, and runtime contracts as built-in types.

C# and Unity knowledge are prerequisites

This section assumes you understand C# and Unity's component model. Read the Manual first if Event, Signal, or Variable is unfamiliar from a designer's perspective.

The extension model#

Most Visual Script extension points combine an abstract base class with a serialized list of implementations. Add a subclass and its attributes; the editor discovers the compiled type.

You want to add	Base class or interface
A new action	`Instruction`
A new check	`Condition`
A new way to start an Event	`Trigger`
A new source for a value	`TType<T>`
A new thing the save system remembers	`Memory`
A component or asset that saves itself	`ISaveLoad`
A new settings tab	`Repository` + `TAsset<T>`

You don't need to register the type. The editor discovers it by reflection after Unity compiles the new file.

Assemblies and namespaces#

Choose the assembly reference based on where your code runs:

Assembly	Contains
`VisualScript.Runtime.Core`	Everything that ships in a build.
`VisualScript.Editor.Core`	Inspectors, drawers, windows, and tooling.

Within those assemblies, the namespaces separate runtime systems from UI and editor code:

Namespace	Contains
`VisualScript.Runtime`	The bulk of the runtime API.
`VisualScript.Runtime.UI`	uGUI helpers.
`VisualScript.Runtime.UIToolkit`	Runtime UI Toolkit elements.
`VisualScript.Editor`	Editor-only types.
`VisualScript.Icons`	The icon set used by node images.

Runtime code needs an assembly definition that references VisualScript.Runtime.Core. Editor code needs one that references both assemblies.

Keep editor code out of the runtime assembly

Anything referencing UnityEditor must live in an editor assembly, or builds fail. When a runtime type needs editor-only behavior, guard it with #if UNITY_EDITOR.

Choose a path#

Conventions — apply the attributes, naming, and serialization patterns shared by every node.
Args — pass Source, Target, and parameters through execution.
Extending — create nodes, variable types, save integrations, and settings.
Runtime API — run Instructions and access variables, saving, pooling, audio, and components.

Write a minimal Instruction#

This complete Instruction logs a String Signal and returns synchronously:

using System;
using UnityEngine;
using VisualScript.Icons;
using VisualScript.Runtime;

[Title("Log Text")]
[Description("Prints text in the Console")]
[Category("Debug/Log Text")]

[Parameter("Text", "The text to print")]
[Keywords("Print", "Console", "Debug")]

[Image(typeof(IconSpeech), ColorTheme.Type.TextLight)]

[Serializable]
public class InstructionMyLogText : Instruction
{
    [SerializeField] private GetString m_Text = new GetString();

    protected override string GetTitle(GameObject source) => $"Log {this.m_Text}";

    protected override Awaitable Run(Args args)
    {
        Debug.Log(this.m_Text.Get(args));
        return Done;
    }
}

After Unity compiles the file, Log Text appears under Debug in the Instructions dropdown. Its keywords support search, and its parameter appears in the editor help window.

Where to go next#

Conventions — understand each attribute used by the example.
Custom Instructions — add Signals, asynchronous work, results, and cancellation.
Args — follow the context received by Run.
Events and Runners — expose designer-authored logic from a component.