Scene metadata quick start
Add object awareness to a Unity scene so a Convai character can reference named objects in conversation from the moment it connects.
Set up Scene Metadata to give a Convai character awareness of named objects in your scene. By the end, your character knows what objects exist and can reference them in conversation — entirely from the Inspector.
Prerequisites
Before starting, verify:
Tag scene objects and collect them
Add ConvaiObjectMetadata to a scene object
Select any GameObject in your scene that the AI character should know about — a piece of equipment, a fire extinguisher, a door, an exhibit. In the Inspector, click Add Component, then browse to Convai → World Object or search for Convai Object Metadata.
The Object Name field auto-fills from the GameObject's name. Edit it to a clear, human-readable label if the GameObject name is not descriptive — for example, change Prop_FireExt_01 to Fire Extinguisher.
Optionally fill in Object Description with one to two factual sentences: what the object is, where it is located, and any key attributes. Keep it under 200 characters.
Object Name is required. Leave it empty and the object is excluded from the payload — Is Registered shows true, but the object does not reach Convai.
Add ConvaiObjectMetadata to remaining objects
Add ConvaiObjectMetadata to each additional object the AI should know about. You do not need to add it to every GameObject — only to objects relevant to AI conversations.
Each component registers itself with ConvaiMetadataRegistry automatically when enabled. No manual wiring or registration calls are needed.
Add ConvaiSceneMetadataCollector and enable auto-collection
Registered objects reach the character automatically as soon as it's ready, even without this component — ConvaiSceneMetadataCollector is optional. Add it now for the Log Statistics confirmation used in the next step, and for manual re-collection later; see How scene metadata works for the full delivery flow.
On any GameObject in your scene, click Add Component and search for Convai Scene Metadata Collector. Placing it on the same GameObject as ConvaiManager is a useful organizational convention.
In the Inspector, enable Collect On Start. This tells the collector to send the full metadata payload automatically when the room session connects.
Leave Log Statistics enabled — it writes a Console entry on each collection showing the object count and duration, which confirms everything is working.
ConvaiSceneMetadataCollector resolves its dependencies automatically at startup by finding ConvaiManager in the scene — no manual wiring required.
Enter Play Mode and verify
Press Play. When the room connects, the collector fires automatically. Check the Console for a debug entry similar to:
[ConvaiSceneMetadataCollector] Collected 4 metadata objects in 0.0010s. Registry stats: 4 total, 4 valid, 0 invalidThis confirms the payload was assembled and sent to Convai. Test the character by asking a question that requires scene awareness — for example: "What equipment is available on this floor?" or "Can you describe what's near the exit?"
The character responds with information that reflects the names and descriptions you entered. Scene Metadata is working.
Next steps
Scene metadata component referenceTroubleshoot scene metadataLast updated
Was this helpful?