Workflow Runtime

Runtime Generation

Use runtime generation when a scene needs to execute a graph during play mode. ProceduralGraphExecutor is the high-level component for producing live Unity objects; the lower-level API returns graph output for your own systems.

Quick Start

Typical runtime workflow

Assign ProceduralGraph Reference the authored graph on the component.

Configure Parameters + mode Apply overrides and choose automatic, sync, or async execution.

Generate Execute the graph Call GenerateSync or await GenerateAsync.

Publish Live scene result The configured instancing strategy consumes the main output.

Manual generation from a component

Disable Generate On Enable when you want gameplay code to decide exactly when the graph executes. That gives you a clean setup phase for parameter overrides before the first generation.

using System.Threading.Tasks;
using CuriousTrove.OctoShaper;
using UnityEngine;

public sealed class RuntimeExecutorDriver : MonoBehaviour
{
    [SerializeField] private ProceduralGraphExecutor executor;

    private void Start()
    {
        executor.GenerateOnEnable = false;
        executor.ExecuteAsAsync = false;

        executor.SetParameterOverride("Count", 12);
        executor.SetParameterOverride("Radius", 4.5f);

        executor.GenerateSync();
    }

    public void RegenerateNow()
    {
        executor.SetParameterOverride("Count", 24);
        executor.GenerateSync();
    }

    public async Task RegenerateAsync()
    {
        executor.ExecuteAsAsync = true;
        executor.SetParameterOverride("Count", 32);
        await executor.GenerateAsync();
    }
}

GenerateSync() is the explicit immediate path.
GenerateAsync() is the explicit awaited path.
See Runtime Parameters for the complete override API and Sync vs Async for execution tradeoffs.

Direct graph execution without a component

Use the bootstrap API when you need the main output without the component's scene-instancing behavior.

using System;
using System.Threading.Tasks;
using CuriousTrove.OctoShaper;
using CuriousTrove.OctoShaper.Core.Data;
using UnityEngine;

public sealed class RuntimeGenerationExample : MonoBehaviour
{
    [SerializeField] private ProceduralGraph graph;

    public async Task<ElementSet> GenerateAsync(Guid countParameterId, int count)
    {
        using var context = OctoShaperRuntime.CreateExecutionContext(graph);
        var executor = OctoShaperRuntime.CreateExecutor(graph);
        var configuration = new ProceduralConfiguration();

        configuration.SetParameterOverride(countParameterId, count);

        await executor.ExecuteAsync(
            context,
            configuration);

        var output = (ElementSet)context.GetSlotValue(graph.MainOutputSlotId);
        return (ElementSet)output.Clone();
    }
}

The context is disposed when the method exits. The returned clone belongs to the caller and should also be disposed when it is no longer needed.

Choosing the right runtime surface

Live objects

ProceduralGraphExecutor

Use the component when a scene needs generated instances and regeneration.

Raw output

Direct bootstrap

Create the context and executor yourself when another system will consume the result.

Imported asset

Procedural prefab

Use import-time generation when the result should live in the project rather than regenerate in play mode.

Before running a graph in play mode

Regenerate graph code after changing the authored graph.
Confirm the main output is the data type your chosen consumer expects.
Remove dependencies on editor-only state from graphs intended for runtime use.