> 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 角色感知场景中的命名对象。完成后，你的角色会知道有哪些对象存在，并能在对话中引用它们——全部都在检查器中完成。

### 前提条件

开始前，请确认：

* [ ] 一个 `ConvaiCharacter` 在场景中，并在播放模式下响应语音

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

{% stepper %}
{% step %}

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

选择场景中任何你希望 AI 角色了解的 GameObject——一件设备、一个灭火器、一扇门、一个展品。在检查器中，单击 **添加组件**，然后浏览到 **Convai → World Object** 或搜索 `Convai Object Metadata`.

“ **对象名称** 字段会根据 GameObject 的名称自动填充。如果 GameObject 名称不够具描述性，请将其编辑为清晰、便于人类阅读的标签——例如，将 `Prop_FireExt_01` 移动到 `灭火器`.

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

{% hint style="warning" %}
**对象名称** 是必需的。将其留空则该对象会被排除在负载之外—— `已注册` 显示 `是`，但该对象不会传递到 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`。将其放在与……相同的 GameObject 上 `ConvaiManager` 是一个有用的组织约定。

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

将 **日志统计** 已启用——它会在每次收集时写入一条控制台条目，显示对象数量和耗时，这可确认一切正常。

`ConvaiSceneMetadataCollector` 在启动时会通过查找以下对象自动解析其依赖项 `ConvaiManager` 于场景中——无需手动连接。
{% endstep %}

{% step %}

#### 进入播放模式并验证

按下播放。当房间连接后，收集器会自动触发。检查控制台中类似以下的调试条目：

```
[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 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/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/scene-metadata/quick-start.md?ask=<question>&goal=<endgoal>
```

`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.