> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/plugins-and-integrations/convai-unity-sdk/features/scene-metadata/component-reference.md). # Scene metadata component reference Two components make up the Scene Metadata system. `ConvaiObjectMetadata` goes on each object the AI should know about. `ConvaiSceneMetadataCollector` goes on the `ConvaiManager` GameObject and handles collection and transmission. #### ConvaiObjectMetadata **Add Component path:** `Convai → World Object` `ConvaiObjectMetadata` is a `MonoBehaviour` that describes a single GameObject to Convai. When enabled, it registers itself with `ConvaiMetadataRegistry`. When disabled or destroyed, it unregisters automatically — no manual cleanup is needed. **Inspector fields** | Field | Type | Default | Constraint | Description | | ------------------------------- | ------------------------------------ | ------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Object Name** | `string` | *(GameObject name)* | Required. Max 50 characters. | The name Convai uses to identify and reference this object in conversation. Auto-filled from the GameObject's name when the component is first added. Edit to a clear, human-readable label. | | **Object Description** | `string` | `""` | Optional. Max 200 characters. | A factual, specific description — what the object is, where it is located, and any key attributes. The AI uses this text to ground its responses. | | **Include In Metadata** | `bool` | `true` | — | When unchecked, this object is excluded from the next metadata collection without removing or disabling the component. Use this to manage runtime inclusion. | | **Tracked Properties** | `List` | *(empty)* | Optional. | Per-entry runtime properties exposed to all connected characters as dynamic context state keys. See [Tracked properties](#tracked-properties) below. | | **Is Registered** *(read-only)* | `bool` | — | Read-only | Debug indicator. Shows `true` when the component is currently registered in `ConvaiMetadataRegistry`. Visible in Play Mode. | **Lifecycle** `ConvaiObjectMetadata` manages its own registration: | Event | Behavior | | ------------ | ------------------------------------------------------------------------------------------------ | | `OnEnable` | Registers with `ConvaiMetadataRegistry` | | `OnDisable` | Unregisters from `ConvaiMetadataRegistry` | | `OnDestroy` | Unregisters from `ConvaiMetadataRegistry` | | `OnValidate` | Auto-fills **Object Name** from `gameObject.name` if empty; logs validation errors in the Editor | GameObjects that are deactivated at runtime will not appear in the next metadata collection, even if **Include In Metadata** is still checked. Changing **Object Name**, **Object Description**, or **Include In Metadata** through the public `ObjectName`, `ObjectDescription`, or `IncludeInMetadata` properties marks the metadata dirty and re-syncs all connected characters immediately if a session is active — the change is not deferred to the next connection. **Validation rules** `ConvaiObjectMetadata.IsValid` returns `true` when **Object Name** is non-empty and non-whitespace. The 50-character limit is enforced only as an editor warning via `GetValidationErrors()` — objects with names over 50 characters still pass `IsValid` and are included in the payload. Objects with an empty **Object Name** fail `IsValid` and are excluded from `GetValidMetadata()` and from the payload sent to Convai. Objects with names over 50 characters are included in the payload but generate a validation warning in the Editor. {% hint style="warning" %} `OnValidate` logs a warning in the Editor when validation fails, but it does not prevent the component from being added. Check the Console after adding components to catch configuration errors before entering Play Mode. {% endhint %} **Tracked properties** Each entry in **Tracked Properties** is a `ConvaiTrackedContextProperty` — a serializable, per-entry definition that exposes one runtime value to every connected character as a dynamic context state key. | Field | Type | Default | Description | | ---------------------- | ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Property Name** | `string` | `""` | Required to enable this entry. Combined with **Object Name** to form the dynamic context state key. | | **Reaction** | `ConvaiRespondMode` | `Silent` | The reaction applied to characters when this property's value changes. See [`ConvaiRespondMode`](/api-docs/plugins-and-integrations/convai-unity-sdk/features/dynamic-context/relay-component-reference.md#convairespondmode). | | **Initial Value** | `string` | `""` | The value sent when the object registers, and the value used for entries that have no **Source Component** configured. | | **Source Component** | `Component` | `None` | Optional. The component to read the live value from on each poll. Leave unset for a fixed value. | | **Source Member Name** | `string` | `""` | Optional. The name of the property, field, or zero-argument method on **Source Component** to read. | The state key for each entry is built as `"{ObjectName}.{PropertyName}"` via `ConvaiObjectMetadata.BuildStateKey`. When both **Source Component** and **Source Member Name** are set, `ConvaiTrackedContextProperty` reads the value live on each poll through reflection, checking in order: a matching property, then a field, then a zero-argument method (including non-public members). When either field is unset, the entry stays fixed at **Initial Value** until changed by code. Polling and delivery to connected characters are handled automatically by an internal `ConvaiWorldObjectPollDriver` — there is no user-facing component to add. It is created on the `ConvaiManager` GameObject when the first `ConvaiObjectMetadata` component registers, evaluates tracked properties on all registered objects every `0.25` seconds, and is destroyed when the last `ConvaiObjectMetadata` component unregisters. #### ConvaiSceneMetadataCollector `ConvaiSceneMetadataCollector` is the orchestrator. It watches for room connection events, reads all valid metadata from `ConvaiMetadataRegistry`, and sends the payload to Convai. In the Inspector, click **Add Component** and search for `Convai Scene Metadata Collector`. Place it on any GameObject in the same scene as `ConvaiManager` — its required dependencies are resolved automatically at startup via `ConvaiManager.ActiveManager`. **Inspector fields** | Field | Type | Default | Description | | -------------------------------------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Collect On Start** | `bool` | `false` | When enabled, the collector automatically sends the full metadata payload the moment the room session reaches `SessionState.Connected`. Disable this if you need manual control over when metadata is sent. | | **Log Statistics** | `bool` | `true` | Writes a Console entry on each collection showing the object count, collection duration, and registry breakdown. Useful for verifying that all expected objects were captured. | | **Last Collected Count** *(read-only)* | `int` | — | Shows the number of objects included in the most recent collection. Visible in Play Mode. | | **Last Collection Time** *(read-only)* | `float` | — | Shows the duration in seconds of the most recent collection operation. Visible in Play Mode. | **Dependencies and injection** `ConvaiSceneMetadataCollector` requires two injected dependencies — `IEventHub` and `IConvaiRoomConnectionService` — provided by `ConvaiManager` automatically at startup. No manual wiring is needed. If the dependencies are not injected (for example, if `ConvaiManager` is missing from the scene), the collector logs an error and all collection calls become no-ops. {% hint style="danger" %} Do not add `ConvaiSceneMetadataCollector` to a scene without `ConvaiManager`. When `ConvaiManager` is missing, the component logs `"[ConvaiSceneMetadataCollector] Dependencies not injected. Add ConvaiManager to scene."` as an **error** in the Console and disables itself. {% endhint %} **Manual trigger** When **Collect On Start** is disabled, call `CollectAndSendSceneMetadata()` from a script to trigger collection at the moment your application needs it. The method is a no-op if the room is not connected — use `IsReadyToSendMetadata()` to check readiness first. ```csharp if (_collector.IsReadyToSendMetadata()) _collector.CollectAndSendSceneMetadata(); ``` For the full public method list, see [Scene metadata scripting API](/api-docs/plugins-and-integrations/convai-unity-sdk/features/scene-metadata/scripting-api-reference.md). #### Next steps {% content-ref url="/pages/aa4f25375b3961f18138e4a75710532316656e63" %} [Scene metadata scripting API](/api-docs/plugins-and-integrations/convai-unity-sdk/features/scene-metadata/scripting-api-reference.md) {% endcontent-ref %} {% content-ref url="/pages/c47675608acf86e70caf6c8b756d2be389006162" %} [Scene metadata usage examples](/api-docs/plugins-and-integrations/convai-unity-sdk/features/scene-metadata/usage-examples.md) {% endcontent-ref %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.convai.com/api-docs/plugins-and-integrations/convai-unity-sdk/features/scene-metadata/component-reference.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.