> 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/how-scene-metadata-works.md).

# How scene metadata works

`ConvaiObjectMetadata`, `ConvaiMetadataRegistry`, and `ConvaiSceneMetadataCollector` form a three-part pipeline that collects object descriptions from your scene and delivers them to Convai when a session connects. Understanding this flow helps you configure the system correctly and debug it when objects are not reaching the character.

### Registration and delivery flow

Every `ConvaiObjectMetadata` component registers itself with `ConvaiMetadataRegistry` when enabled. When a room connects, `ConvaiSceneMetadataCollector` reads that registry, assembles a payload, and sends it to Convai as an `update-scene-metadata` RTVI message.

```mermaid
flowchart TD
    A[ConvaiObjectMetadata\nOnEnable] -->|registers| B[ConvaiMetadataRegistry\nstatic, O(1) lookup]
    B -->|GetSceneMetadataList| C[ConvaiSceneMetadataCollector]
    C -->|SessionState.Connected| D[RTVIUpdateSceneMetadata\nupdate-scene-metadata]
    D --> E([Convai])
```

Objects register and unregister themselves as they are enabled and disabled — no manual cleanup is needed. Convai receives the current state of all registered objects at connection time.

### Scene metadata vs. dynamic context

Both systems inject information into a character's context, but they serve different purposes:

|                       | Scene Metadata                                   | Dynamic Context                           |
| --------------------- | ------------------------------------------------ | ----------------------------------------- |
| **Who populates it**  | SDK auto-discovers objects                       | Developer manually injects state          |
| **What it describes** | Physical objects and entities in the scene       | Runtime state, events, player actions     |
| **When it's sent**    | Once, at room connection                         | Anytime, on demand                        |
| **Typical use**       | "There is a fire extinguisher on the south wall" | "The trainee just failed the valve check" |

Use both together for the most context-rich AI experience.

{% hint style="info" %}
Scene Metadata describes the static world — what exists. Dynamic Context describes the dynamic world — what is happening. They are complementary, not competing.
{% endhint %}

### Next steps

{% content-ref url="/pages/b21526ee9b2c1ed58e407fc454da6b3bd057905a" %}
[Scene metadata quick start](/api-docs/plugins-and-integrations/convai-unity-sdk/features/scene-metadata/quick-start.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:

```
GET https://docs.convai.com/api-docs/plugins-and-integrations/convai-unity-sdk/features/scene-metadata/how-scene-metadata-works.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.