Runtime API#

Summary

The Runtime API runs designer-authored logic and reads Visual Script state from C#. Use it to connect existing systems to Events, variables, saving, pooling, audio, and cached component lookups.

Available runtime systems#

Events — run Event components or host Instructions and Conditions on your own component.
Variables — read, write, subscribe to, and find variable containers.
Components — cache component lookups and add missing components.
Save and Load — call SaveLoadManager and observe its lifecycle.
Pooling — reuse game objects through PoolManager.
Audio — play, stop, inspect, and mix sounds.

Start with RunnerInstructions#

RunnerInstructions adds a designer-authored Instructions list to your component. This example runs the list when Finish is called:

using UnityEngine;
using VisualScript.Runtime;

public class MyComponent : MonoBehaviour
{
    [SerializeField] private RunnerInstructions m_OnComplete = new RunnerInstructions();

    private void Finish()
    {
        using Args args = Args.Get(this.gameObject, this.gameObject);
        this.m_OnComplete.Run(args).Fire(null, this);
    }
}

The m_OnComplete field exposes a configurable response to Finish. Designers can change that response without changing MyComponent.

RunnerConditions does the same for checks.

Lifecycle and caching boundaries#

These boundaries affect when you access managers and how long you keep runtime objects:

Boundary	Consequence
`Args` instances are pooled	Get one with `Args.Get`, dispose it, and never store the reference. See Args.
Singletons initialize on demand	The first manager access may cost more than later calls. Avoid first access in a hot path.
The application may be exiting	Check `AppManager.IsExiting` before teardown work to avoid quit-only errors.
Edit mode differs from Play mode	Repositories re-read, component lookups aren't cached, and breakpoints don't affect builds.

Where to go next#

Events and Runners — expose and execute designer-authored behavior.
Variables — read and write designer-authored state.
Args — manage Source, Target, parameters, and pooled context.
Extending Visual Script — add new types to editor dropdowns.