# Scripting API

!!! note "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.

!!! info "C# and Unity knowledge are prerequisites"
    This section assumes you understand C# and Unity's component model. Read the [Manual](../manual/index.md) 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.

!!! warning "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

<div class="grid cards" markdown>

- **[Conventions](conventions.md)** — apply the attributes, naming, and serialization patterns shared by every node.
- **[Args](args.md)** — pass Source, Target, and parameters through execution.
- **[Extending](extending/index.md)** — create nodes, variable types, save integrations, and settings.
- **[Runtime API](runtime/index.md)** — run Instructions and access variables, saving, pooling, audio, and components.

</div>

## Write a minimal Instruction

This complete Instruction logs a String Signal and returns synchronously:

```cs
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](conventions.md)** — understand each attribute used by the example.
- **[Custom Instructions](extending/instructions.md)** — add Signals, asynchronous work, results, and cancellation.
- **[Args](args.md)** — follow the context received by `Run`.
- **[Events and Runners](runtime/events.md)** — expose designer-authored logic from a component.