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

# 场景元数据快速入门

添加一个 `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 Object`。选择要将其添加到的组件 `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 %}

#### 进入播放模式并询问角色

按下 **Play**。走近 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 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/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/scene-metadata/scene-metadata-quick-start.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.