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.

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:

Runtime object exclusion and re-send:

Pre-send audit:

Debug statistics:

Next steps

Scene metadata usage examplesTroubleshoot scene metadata

Last updated

Was this helpful?