API Runtime

Runtime Parameters

Runtime overrides let gameplay change exposed graph parameters without editing the graph asset. Use ProceduralGraphExecutor for component-driven generation or ProceduralConfiguration with the direct execution API.

Quick Start

Basic parameter override

Set overrides before generating. They remain on the executor's configuration until removed or cleared, and never change the defaults stored in the graph asset.

using CuriousTrove.OctoShaper;
using UnityEngine;

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

    public void ApplyGameplayState(int count, float width)
    {
        executor.SetParameterOverride("Count", count);
        executor.SetParameterOverride("Width", width);
        executor.GenerateSync();
    }

    public void ResetToDefaults()
    {
        executor.ClearParameterOverrides();
        executor.GenerateSync();
    }
}

Authored Graph default The value saved with the parameter.

Runtime Configuration override A name or Guid selects the parameter.

Execute Generate again The executor resolves the effective value.

Effective value Override wins Clearing it reveals the graph default again.

Executor-level parameter API

Gameplay code should normally use the helpers on ProceduralGraphExecutor.

Set an override

SetParameterOverride(string, object) throws when the name is missing.
TrySetParameterOverride(string, object) returns false instead.
SetParameterOverride(Guid, object) avoids name lookup when you already have the id.

Remove overrides

RemoveParameterOverride(string) and RemoveParameterOverride(Guid) restore one default.
ClearParameterOverrides() restores every graph default.
Call a generate method after changing overrides to publish a new result.

Working with ProceduralConfiguration directly

When using the low-level runtime API (without a ProceduralGraphExecutor component), create a ProceduralConfiguration and set overrides on it directly. Pass it to the executor's ExecuteAsync method.

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

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

    public async Task<ElementSet> GenerateWithParameters(Guid countParameterId, int count)
    {
        var configuration = new ProceduralConfiguration();

        // Set overrides before execution.
        configuration.SetParameterOverride(
            countParameterId,
            count);

        using var context = OctoShaperRuntime.CreateExecutionContext(graph);
        var executor = OctoShaperRuntime.CreateExecutor(graph);

        await executor.ExecuteAsync(
            context,
            configuration);

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

Two ownership details: a new configuration uses the parameter Guid because it does not yet have a graph reference for name lookup. The returned ElementSet is cloned before the context is disposed and becomes the caller's responsibility to dispose.

Configuration-level API

ProceduralConfiguration is the storage layer used by the executor and the direct API.

SetParameterOverride(Guid, object) and SetParameter<T>(Guid, T) set values by id.
Once the configuration is associated with a graph, SetParameter<T>(string, T) and TrySetParameter<T>(string, T) can resolve authored names.
GetParameter<T> and TryGetParameter<T> return the effective value: override first, graph default otherwise.
RemoveParameterOverride(Guid) removes one override; ClearOverrides() removes all of them.

Best practices

Prefer names at gameplay boundaries. Wrap them in constants instead of scattering string literals.
Use Guids in infrastructure. Cache ids when code already works directly with graph metadata.
Use the Try variant for optional controls. It makes graph-version differences an explicit branch instead of an exception.
Regenerate after changing values. Updating the configuration does not republish the existing output.