Scene metadata scripting API

Reference for ConvaiMetadataRegistry and ConvaiSceneMetadataCollector, including static events, manual trigger patterns, and debug utilities.

The Scene Metadata scripting surface has two parts. ConvaiMetadataRegistry is the static central registry — use it to query registration state and listen for changes. ConvaiSceneMetadataCollector is the runtime orchestrator — use it to trigger collection, check readiness, and audit all registered objects.

ConvaiMetadataRegistry

ConvaiMetadataRegistry is a static class. Access all members directly by class name — no instance or component reference needed.

Properties

Member	Type	Description
Count	int	Total number of registered ConvaiObjectMetadata instances, including invalid and disabled ones.

Methods

Method	Returns	Description
GetAllMetadata()	ConvaiObjectMetadata[]	Returns all registered instances, including those with empty names, disabled Include In Metadata, or null references.
GetValidMetadata()	ConvaiObjectMetadata[]	Returns only instances that are non-null, have Include In Metadata enabled, and pass name validation (IsValid == true). This is the exact set included in the next send.
GetSceneMetadataList()	List<SceneMetadata>	Converts all valid metadata to the serializable transport format. This is the payload sent to Convai.
GetStatistics()	Dictionary<string, object>	Returns a breakdown with keys: TotalRegistered, ValidMetadata, InvalidMetadata, NullReferences, ValidNames, InvalidReasons. Use for debugging.
CleanupNullReferences()	int	Removes destroyed-but-not-unregistered entries. Returns the count removed. Call this if objects are destroyed outside normal Unity lifecycle events.
Clear()	void	Clears all registered entries. Intended for testing and scene teardown. Do not call in production.

Static events

Event	Signature	Fires when
OnMetadataRegistered	Action<ConvaiObjectMetadata>	A ConvaiObjectMetadata component enables and registers itself.
OnMetadataUnregistered	Action<ConvaiObjectMetadata>	A ConvaiObjectMetadata component disables or is destroyed and unregisters itself.

void OnEnable()
{
    ConvaiMetadataRegistry.OnMetadataRegistered += HandleObjectRegistered;
    ConvaiMetadataRegistry.OnMetadataUnregistered += HandleObjectUnregistered;
}

void OnDisable()
{
    ConvaiMetadataRegistry.OnMetadataRegistered -= HandleObjectRegistered;
    ConvaiMetadataRegistry.OnMetadataUnregistered -= HandleObjectUnregistered;
}

private void HandleObjectRegistered(ConvaiObjectMetadata metadata)
{
    Debug.Log($"Registered: {metadata.ObjectName} ({ConvaiMetadataRegistry.Count} total)");
}

private void HandleObjectUnregistered(ConvaiObjectMetadata metadata)
{
    Debug.Log($"Unregistered: {metadata.ObjectName}");
}

ConvaiSceneMetadataCollector

Access via a component reference. ConvaiManager injects dependencies at startup — no manual setup required.

private ConvaiSceneMetadataCollector _collector;

void Awake()
{
    _collector = FindObjectOfType<ConvaiSceneMetadataCollector>();
}

Public methods

Method	Returns	Description
IsReadyToSendMetadata()	bool	Returns true when dependencies are injected and the room session is in Connected state. Always check this before calling CollectAndSendSceneMetadata() manually.
CollectAndSendSceneMetadata()	void	Reads all valid metadata from ConvaiMetadataRegistry, assembles the payload, and sends it to Convai via the RTVI update-scene-metadata message. Returns early and logs a warning or error to the Console if the room is not connected or dependencies are not injected.
GetMetadataCount()	int	Returns the count of valid, includable objects without triggering a send. Use for UI display or pre-send validation.
GetCurrentMetadata()	List<SceneMetadata>	Returns the current payload list without triggering a send. Use to inspect what would be sent on the next call.
ValidateAllMetadata()	void	Logs validation issues for all registered objects to the Console. Use this during development to catch missing names, length overflows, or disabled objects.

Common patterns

Manual trigger on scenario load:

IEnumerator LoadScenario(ScenarioData data)
{
    yield return StartCoroutine(SpawnScenarioProps(data));

    // Wait until room is ready
    yield return new WaitUntil(() => _collector.IsReadyToSendMetadata());
    _collector.CollectAndSendSceneMetadata();
}

Runtime object exclusion and re-send:

// Remove a locked door from AI context when it opens
void OnDoorUnlocked(ConvaiObjectMetadata doorMetadata)
{
    doorMetadata.IncludeInMetadata = false;
    if (_collector.IsReadyToSendMetadata())
        _collector.CollectAndSendSceneMetadata();
}

Pre-send audit:

void LogPreSendAudit()
{
    _collector.ValidateAllMetadata(); // prints all issues to Console
    Debug.Log($"Will send {_collector.GetMetadataCount()} objects");

    var preview = _collector.GetCurrentMetadata();
    foreach (var item in preview)
        Debug.Log($"  - {item.Name}: {item.Description}");
}

Debug statistics:

var stats = ConvaiMetadataRegistry.GetStatistics();
foreach (var kv in stats)
    Debug.Log($"{kv.Key}: {kv.Value}");

Next steps

Scene metadata usage examplesTroubleshoot scene metadata