> 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/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/scene-metadata/quick-start.md).

# 场景元数据快速开始

为 Unity 场景添加对象感知能力，使 Convai 角色在连接后即可在对话中引用命名对象。

设置场景元数据，让 Convai 角色感知场景中的命名对象。最终，你的角色会知道有哪些对象存在，并且可以在对话中引用它们——完全通过 Inspector 完成。

### 前置条件

开始之前，请确认：

* [ ] 一个 `ConvaiCharacter` 已在场景中，并且在 Play 模式下能够响应语音

### 标记场景对象并收集它们

{% stepper %}
{% step %}

#### 向场景对象添加 ConvaiObjectMetadata

选择场景中任意一个 AI 角色应该了解的 GameObject——例如一件设备、一个灭火器、一扇门或一个展品。在 Inspector 中，点击 **添加组件**，然后浏览到 **Convai → World Object** 或搜索 `Convai Object Metadata`.

该 **中搜索“Convai World Object”** 字段会根据 GameObject 的名称自动填充。如果 GameObject 名称不够直观，请将其编辑为清晰、易读的人类可读标签——例如，将 `Prop_FireExt_01` 为 `灭火器`.

可选填写 **Object Description** ，用一到两句事实性描述：该对象是什么、位于何处以及任何关键属性。请保持在 200 个字符以内。

{% hint style="warning" %}
**中搜索“Convai World Object”** 是必填项。若留空，该对象将被排除在负载之外—— `是否已注册` 显示为 `true`，但该对象不会传送到 Convai。
{% endhint %}
{% endstep %}

{% step %}

#### 向其余对象添加 ConvaiObjectMetadata

添加 `ConvaiObjectMetadata` 到 AI 需要了解的每个其他对象上。你不需要把它添加到每个 GameObject——只需添加到与 AI 对话相关的对象即可。

每个组件都会自动向 `ConvaiMetadataRegistry` 在启用时自动完成。无需手动连接或调用注册。
{% endstep %}

{% step %}

#### 添加 ConvaiSceneMetadataCollector 并启用自动收集

即使没有此组件，已注册的对象也会在角色准备就绪后自动送达—— `ConvaiSceneMetadataCollector` 是可选的。现在添加它，以用于 **日志统计** 下一步使用的确认，以及稍后手动重新收集；请参阅 [场景元数据如何工作](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/scene-metadata/how-scene-metadata-works.md) 完整的传递流程。

在场景中的任意 GameObject 上，点击 **添加组件** 中搜索 `Convai Scene Metadata Collector`。将其放在与 `ConvaiManager` 相同的 GameObject 上，是一个有用的组织惯例。

在 Inspector 中启用 **启动时采集**。这会告诉收集器在房间会话连接时自动发送完整的元数据负载。

保持 **日志统计** 已启用——它会在每次收集时写入一条 Console 记录，显示对象数量和耗时，以确认一切正常。

`ConvaiSceneMetadataCollector` 在启动时通过查找 `ConvaiManager` 场景中的对象——无需手动连接。
{% endstep %}

{% step %}

#### 进入 Play 模式并验证

按下 Play。房间连接后，收集器会自动触发。请在 Console 中检查类似以下的调试记录：

```
[ConvaiSceneMetadataCollector] 在 0.0010 秒内收集了 4 个元数据对象。注册表统计：总计 4 个，4 个有效，0 个无效
```

这确认了负载已组装并发送到 Convai。通过提出一个需要场景感知的问题来测试角色——例如：“这层楼有什么设备可用？”或“你能描述一下出口附近有什么吗？”
{% endstep %}
{% endstepper %}

{% hint style="success" %}
角色会根据你输入的名称和描述作出回应。场景元数据正在正常工作。
{% endhint %}

### 下一步

{% content-ref url="/pages/b55fe13afe8f10f3ca27eec09be22c5bd975a884" %}
[场景元数据组件参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/scene-metadata/component-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/f6f3f3d88a3636afea1b0c8774162c2014fba780" %}
[排查场景元数据问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/scene-metadata/troubleshooting-and-diagnostics.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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/scene-metadata/quick-start.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.