API Runtime

GameObject Callbacks

Implement IUnityInstanceSpawnReceiver on a prefab component when each spawned hierarchy needs to initialize itself. The callback includes its ElementSet row, hierarchy position, graph, owner, and instancing source.

Quick Start

Implementing a spawn receiver

Attach a MonoBehaviour that implements the interface to any GameObject in the prefab hierarchy. OctoShaper calls it automatically after spawning.

using CuriousTrove.OctoShaper.Instancing;
using UnityEngine;

public sealed class OnSpawnInitializer : MonoBehaviour, IUnityInstanceSpawnReceiver
{
    public void OnUnityInstanceSpawned(UnityInstanceSpawnContext context)
    {
        Debug.Log($"Spawned row {context.RowIndex} " +
                  $"(parent: {context.ParentRowIndex}, " +
                  $"sibling: {context.SiblingIndex}) " +
                  $"from source {context.Source}");
    }
}

UnityInstanceSpawnContext

The context struct carries all the information a spawned instance needs to initialize itself.

Identity fields

Instance — the spawned GameObject
Graph — the ProceduralGraph that produced this element
GraphId — the graph's unique identifier string
Owner — the object that triggered the spawn (e.g., the ProceduralGraphExecutor)
Source — UnityInstantiationSource enum indicating what triggered instantiation

Row and placement fields

RowIndex — the zero-based index of this element in the ElementSet
ParentRowIndex — the parent element's row index (or -1 for root rows)
SiblingIndex — the birth order among siblings under the same parent
SpawnKind — UnityInstanceSpawnKind enum: whether this is a new row, a hierarchy child, etc.
Prefab — the PrefabReference that produced this instance
PrimitiveType — the Unity PrimitiveType if a primitive was spawned
Scene — the scene the instance lives in

Receiver invocation rules

Instantiate Build hierarchy OctoShaper creates the row root and its children.

Prepare Apply placement Position, rotation, scale, and local hierarchy are ready.

Notify Call receivers Components under that spawned root receive the same context.

Finish Publish and parent Observers run, then root instances attach to the executor parent.

Receivers are found with GetComponentsInChildren<IUnityInstanceSpawnReceiver>(true) on each spawned root.
A receiver is only invoked when its transform belongs to the same spawned root hierarchy (not a nested sub-prefab instantiated separately).
Exceptions thrown inside OnUnityInstanceSpawned are caught and logged, so they do not break the instancing loop.

Toggling spawn callbacks

The GameObjectInstancingStrategy exposes a Notify Spawn Receivers toggle in the Unity inspector. When disabled, no IUnityInstanceSpawnReceiver callbacks are broadcast during instancing, which can save CPU time when spawned hierarchies do not need per-instance initialization.

Best practice: Turn this toggle off when your prefabs have no spawn receiver components. If you toggle it off and later add receivers to a prefab, remember to re-enable it.

Practical patterns

using CuriousTrove.OctoShaper.Instancing;
using UnityEngine;

public sealed class RowIndexLabel : MonoBehaviour, IUnityInstanceSpawnReceiver
{
    public void OnUnityInstanceSpawned(UnityInstanceSpawnContext context)
    {
        // Only apply to root-level elements, not hierarchy children.
        if (context.SpawnKind != UnityInstanceSpawnKind.Row)
        {
            return;
        }

        // Use the row index to pick a material variant.
        var renderer = GetComponent<MeshRenderer>();
        if (renderer != null && context.RowIndex % 2 == 0)
        {
            renderer.material.color = Color.cyan;
        }
    }
}

The SpawnKind field lets you distinguish root rows from hierarchy children. Combined with RowIndex and ParentRowIndex, you can implement parent-aware initialization logic entirely inside the spawned prefab, without any external manager scripts.