> 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-unreal-engine-plugin/features/scene-metadata/scene-metadata-quick-start.md).

# 场景元数据快速开始

用 Convai Object Component 标记一个世界 Actor，分配其名称和描述，并确认 Convai 角色可以在对话中引用它。

添加一个 `UConvaiObjectComponent` 到一个世界 `Actor`，为其命名并描述，然后测试 Convai 角色是否可以在对话中将该对象用作场景上下文。

### 前提条件

* 已安装 Convai Unreal Engine 插件并配置好 API 密钥。
* 一个 `UConvaiChatbotComponent` 和一个 `UConvaiPlayerComponent` 在关卡中，具有有效的角色 ID 和可用麦克风。请参见 [添加你的第一个 Convai 角色](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/add-your-first-convai-character.md) 如果你尚未完成该设置。

### 公开一个 Actor 并验证识别

{% stepper %}
{% step %}

#### 选择目标 Actor

打开你的关卡并点击 `Actor` 你希望 Convai 角色了解的对象，例如门、箱子或拉杆。
{% endstep %}

{% step %}

#### 添加对象组件

在 **详情** 面板，点击 **添加组件** 并搜索 `UConvaiObjectComponent` 或 `Convai 对象`。选择要将该组件添加到的 `Actor`.
{% endstep %}

{% step %}

#### 设置对象名称和描述

在 **Convai 对象组件** 选中后，在其中设置对象标识字段 **详情** 面板：

* **`名称`** — 一个简短且唯一的标签，例如 `FrontDoor`.
* **`说明`** — 一句关于该对象的普通描述，例如 `主入口处的一扇大型木门。`

名称在关卡中必须唯一。请参见 [场景元数据组件参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/scene-metadata/scene-metadata-component-reference.md) 以了解重复项处理和完整字段列表的详细信息。
{% endstep %}

{% step %}

#### 进入播放模式并向角色提问

按 **播放**。走到 Convai 角色面前并提问： `“你知道关于这扇门什么？”` 或 `“描述你附近的物体。”` 角色应提及你设置的名称和描述。

如果角色没有提及该对象，请打开 **输出日志** 并按以下项筛选 `ConvaiSubsystemLog` 以查看注册警告，或 `ConvaiObjectComponentLog` 以查看组件警告。请参见 [场景元数据故障排查](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/scene-metadata/troubleshoot-scene-metadata.md) 以获取症状完整列表。
{% endstep %}

{% step %}

#### 添加一个跟踪属性（可选）

为了让角色了解实时游戏状态，请展开 **跟踪属性** 在“详细信息”面板中并点击 **+** 以添加一行。点击 **Bind** 旁边的 **属性路径** 并选择一个 `UPROPERTY` 来自 `Actor`。设置一个通俗易懂的 **`说明`** 并选择一个 **`ShouldRespond`** 值。

有关完整的跟踪属性工作流程，请参见 [场景元数据组件参考 — 跟踪属性](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/scene-metadata/scene-metadata-component-reference.md#tracked-properties).
{% endstep %}
{% endstepper %}

{% hint style="success" %}
配置正确时，角色会使用你设置的名称和描述来回答关于该对象的问题。
{% endhint %}

{% hint style="info" %}
有关该组件可用属性和函数的完整列表，请参见 [场景元数据组件参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/scene-metadata/scene-metadata-component-reference.md).
{% endhint %}

### 下一步

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

{% content-ref url="/pages/4a8ee50a93a78b9b86484cb79897f6d0d6bde187" %}
[运行时管理环境](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/scene-metadata/managing-the-environment-at-runtime.md)
{% endcontent-ref %}

{% content-ref url="/pages/35be910ed18e7f78411fd4d732770d70307e1434" %}
[排查场景元数据问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/scene-metadata/troubleshoot-scene-metadata.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-unreal-engine-plugin/features/scene-metadata/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.