> 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/unreal-engine/guides-v2-under-development/getting-started/simple-talking-cube.md).

# 简单对话立方体

一个从零开始的最小示例，帮助你熟悉插件的主要组件。

1. 创建一个新的第一人称项目。<br>

   <div align="left"><figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FCVbcZAV29NB53lTEPtdl%2Fimage.png?alt=media&amp;token=e7e0cb33-0714-438a-8e14-17bbf84f2aad" alt="" width="563"><figcaption></figcaption></figure></div>
2. 启用 Convai 插件，并将 API 密钥添加为 [此处所述](/api-docs/zh/cha-jian-yu-ji-cheng/unreal-engine/guides-v2-under-development/getting-started/download-and-setup.md#set-up-your-project).<br>
3. 创建一个新的 Actor 蓝图，我们将其用作 AI 角色。\
   \
   ![](https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FxNwl8SJhS9g5P2jSXwNa%2Fimage.png?alt=media\&token=8f4a3e7e-2082-4c1a-946a-a224b3c78093)![](https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FKjwP6gSuO8XISyAVg1ri%2Fimage.png?alt=media\&token=f98de758-a06f-4b77-8075-94cf40fc7961)
4. 打开创建的蓝图，然后在组件列表中搜索并添加 `Convai 聊天机器人` 组件。\
   \
   注意：如果你没有找到该组件，请确保你已按照 [安装指南](/api-docs/zh/cha-jian-yu-ji-cheng/unreal-engine/guides-v2-under-development/getting-started/download-and-setup.md#installing-the-plugin).<br>

   <div align="left"><figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FgtrqIMXD78fBvUMab1eA%2Fimage.png?alt=media&amp;token=f766e519-3e4d-444a-b974-b5a89f1c5fe9" alt="" width="563"><figcaption></figcaption></figure></div>
5. 选择已创建的组件，在详情面板中找到 Character ID 字段，并粘贴你的角色 ID；你可以通过创建一个新角色，或在 [Convai Playground](broken://pages/35a85ab8078743525dfb21372f6c08398990e426).<br>

   <div align="left"><figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FBRykO5zVayRaAkrhNAXw%2Fimage.png?alt=media&amp;token=bd146028-578e-4964-8f08-749b69f3c6be" alt="" width="563"><figcaption></figcaption></figure></div>
6. 添加一个盒体组件，这样你在场景中放置该蓝图时就能看到它。<br>

   <div align="left" data-full-width="false"><figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2Fl47ATzG7ieuDnfwycY0w%2Fimage.png?alt=media&amp;token=239a74c2-0e9f-4102-a31c-717ac0113f33" alt="" width="563"><figcaption></figcaption></figure></div>
7. 将该蓝图放置到场景中。<br>

   <div align="left"><figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FfTnAjwpHVHXnsNYdGvq9%2Fimage.png?alt=media&amp;token=fbacaa40-d99a-4330-a99e-03cd3891b593" alt="" width="563"><figcaption></figcaption></figure></div>
8. 打开玩家蓝图，默认位于 `First Person/Blueprints/BP_FirstPersonCharacter` ，适用于第一人称模板。<br>

   <div align="left"><figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2F5VRAF7ZM6AAr0va0DaQt%2Fimage.png?alt=media&amp;token=e16d55f9-246c-4ba2-bbf0-3d7c3a0474f9" alt="" width="563"><figcaption></figcaption></figure></div>
9. 搜索并添加 `Convai Player` 组件到组件列表中。<br>

   <div align="left"><figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2F6kcfdGwhKXCD01J8F075%2Fimage.png?alt=media&amp;token=e72091ee-c9c0-40f6-a47b-b04b1b0d46e2" alt="" width="563"><figcaption></figcaption></figure></div>
10. 添加以下蓝图示意图，以便玩家能够通过 V 键与 AI 角色交谈：

    1. 添加一个键盘按键事件，用作按住说话按钮（即本例中的 \`V\` 键）。
    2. 使用 `Convai 获取被注视的角色` 用于获取当前被玩家查看的角色的聊天机器人组件。
    3. 设置 `半径` 设置为一个合理的距离，或者如果你希望玩家可以在无限距离内与角色交谈，则设为零。
    4. 设置 `平面视图` 设为 true，则只考虑平面轴（X 和 Y），忽略高度轴（Z）。这样做是为了避免必须直接看向角色的枢轴点，而只需看向角色所在方向即可。
    5. 使用 `开始对话` 中的 `Convai Player` 组件的节点会与角色启动对话会话，请确保你已启用 `语音回复` 以便让角色进行语音回应。
    6. 在 `Released` 事件中，使用 `结束对话` 位于 `Convai Player` 组件上的节点，让 AI 角色知道我们已经结束对话，现在正在等待回应。<br>

    <div align="left"><figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FSpcY0b1HFnl0Rhz3Muju%2Fimage.png?alt=media&amp;token=affb94c6-5020-44d4-80b0-2579d27059cd" alt="" width="563"><figcaption></figcaption></figure></div>
11. 点击运行，靠近 AI 角色并按住 T 通过麦克风说话，然后在松开 T 键后角色应会作出回应。<br>

    <div align="left"><figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2F6GgLUbaY7DRt3ofe8wqP%2Fimage.png?alt=media&amp;token=75d7d9c5-f8f7-4201-a334-fdf41de8a86d" alt="" width="563"><figcaption></figcaption></figure></div>

{% hint style="info" %}
如果角色没有回应，请确保在操作系统设置中已将麦克风正确设置为默认麦克风。
{% endhint %}

## 发送文本而非语音

使用以下 `发送文本` 节点来代替，如果你想通过文本而不是语音与角色聊天。

注意，这里我们使用硬编码字符串作为输入传给角色，你需要创建所需的 UI，以从用户那里获取文本输入并将其发送给 AI 角色。

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FwiMmt4nQhztlGmVpn98r%2Fimage.png?alt=media&amp;token=255ccd56-2c6e-4194-a539-39f824ab32a5" alt=""><figcaption></figcaption></figure>


---

# 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/unreal-engine/guides-v2-under-development/getting-started/simple-talking-cube.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.
