> 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/overview/migrate-to-4-0-0-beta-27.md).

# 迁移到 4.0.0-beta.27

将现有 Unreal 项目从之前的插件测试版更新过来，涵盖所有已移除的引脚、已弃用的枚举以及需要刷新的 Blueprint 节点。

将项目从 `4.0.0-beta.21` 到 <code class="expression">space.vars.unreal\_plugin\_version</code> 只需对涉及 Convai 的 Blueprints 进行一次遍历。三项更改会破坏现有图表：两个 Blueprint 节点丢失了引脚，一个枚举被移除，目标解析节点的引脚被重命名。在此版本范围内，其他内容都无需编辑。仅调用 `Invoke Speech`、发送文本并播放口型同步的项目可以无需修改地编译通过。

### 开始之前

* 先分支或备份项目。一旦资源重新保存，重新安装旧插件也无法撤销 Blueprint 引脚的移除。
* 确认引擎版本。该插件支持 Unreal Engine <code class="expression">space.vars.unreal\_min\_version</code> 通过 <code class="expression">space.vars.unreal\_max\_version</code>.
* 一步升级。中间没有可停留的过渡版本，位于 `4.0.0-beta.21` 和 <code class="expression">space.vars.unreal\_plugin\_version</code>.

{% hint style="warning" %}
在保存任何内容之前，先编译所有 Convai Blueprint。带有已移除引脚的图表仍然可以打开，但该节点会携带一个孤立引脚，直到刷新为止；在这种状态下保存会保留损坏的连接。
{% endhint %}

### 改动了什么

其中两项更改源于同一设计决定：原本按每次调用设置的行为，现在改为从聊天机器人的自身配置中读取，因此移除了按调用设置的引脚。第三项则用更丰富的模型替换了一个双值移动枚举——一个对象引用加上可选的、由设计师编写的目标位置——这使得旧枚举及其配套标志变得多余。

### 破坏性更改

| 旧                                                                                                         | 新                                             | 处理方式                                                                            |
| --------------------------------------------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------- |
| generate-actions 输入位于 `Invoke Speech` 和 `Invoke Narrative Design Trigger` （参数 `InGenerateActions`)        | —                                             | 删除连线。动作生成现在遵循 `启用操作` 在聊天机器人组件上。                                                 |
| replicate-on-network 输入位于 `Invoke Speech` 和 `Invoke Narrative Design Trigger` （参数 `InReplicateOnNetwork`) | —                                             | 删除连线。复制现在遵循聊天机器人组件自身的配置。                                                        |
| `EConvaiMoveTarget` (`将 Actor 作为目标`, `将组件作为目标`)                                                           | `EConvaiObjectReference` (`整个 Actor`, `特定组件`) | 重建任何变量、转换或 `按枚举切换` 节点以适配新枚举。Details 面板字段现在标记为 **对象为**.                          |
| `bStepOntoBounds` 位于 `FConvaiObjectEntry`                                                                 | —                                             | 删除该检查。 `整个 Actor` 已经会在对象边界处停止。                                                  |
| `MoveTargetMode` 位于 `FConvaiObjectEntry`                                                                  | `对象引用`                                        | 重命名该字段访问。                                                                       |
| `输出模式` 输出位于 `解析目标位置`                                                                                      | `使用目标位置`                                      | 删除分支。将 `目标 Actor` 和 `目的地` 接入一个单一的 `AI Move To`; `目标 Actor` 是 `null` 仅在目标是固定位置时。 |
| `输出目标 Actor` 输出位于 `解析目标位置`                                                                                | `对象 Actor`                                    | 已重命名，也不再是要接入的引脚 `AI Move To`。请使用 `目标 Actor` 用于移动。                               |
| `输出目标位置` 输出位于 `解析目标位置`                                                                                    | `目的地`                                         | 已重命名。                                                                           |
| `bForceRefresh` 输入位于 `解析目标位置`                                                                             | —                                             | 删除连线。该节点会自行重新验证其解析后的组件。                                                         |

`Invoke Speech` 还增加了一个 `传递` 输入（`正常发送` 或 `等待对话空闲`）现在只会将其消息播报一次，而不会将其保留在对话上下文中。这两项都不是破坏性更改，但它们都会改变读者在升级后看到的内容。

### 迁移项目

{% stepper %}
{% step %}

#### 安装新插件

替换插件文件夹并重启编辑器。参见 [安装 Convai 插件](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/install-the-convai-plugin.md).
{% endstep %}

{% step %}

#### 刷新丢失引脚的节点

打开每个调用了……的 Blueprint `Invoke Speech` 或 `Invoke Narrative Design Trigger`。右键单击每个节点并选择 **刷新节点**，然后删除连接到那两个已移除布尔输入的连线， `InGenerateActions` 和 `InReplicateOnNetwork`.
{% endstep %}

{% step %}

#### 替换已移除的枚举

在项目中搜索 `EConvaiMoveTarget`, `MoveTargetMode`，以及 `bStepOntoBounds`。重建每个 `按枚举切换` 以适配 `EConvaiObjectReference`，重命名 `MoveTargetMode` 对……的访问 `对象引用`，并删除 `bStepOntoBounds` 检查本身。
{% endstep %}

{% step %}

#### 重新连线 Resolve Goal Location

刷新每个 `解析目标位置` 节点。移除旧的……上的分支 `输出模式` 输出，并将 `目标 Actor` 和 `目的地` 接入一个 `AI Move To` 节点。参见 [内置动作处理器](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/built-in-action-handlers.md) 以了解当前模式。
{% endstep %}

{% step %}

#### 编译并重新保存

先编译每个受影响的 Blueprint，然后保存。只有在干净编译后才重新保存。
{% endstep %}
{% endstepper %}

### 验证迁移

当每个 Convai Blueprint 都能无错误编译，且在整个项目中搜索 `EConvaiMoveTarget`, `MoveTargetMode`, `bStepOntoBounds`，以及 `输出模式` 没有返回结果，并且角色在播放模式下仍会走向已注册的对象时，迁移就完成了。

如果 Blueprint 在前四步之后仍然无法编译， `解析目标位置` 重新布线通常就是原因：仍然在已移除的……上分支的图表 `输出模式` 输出无法解析该引脚，而错误信息会指出节点而不是缺失的输出。

### 下一步

在这个版本范围内还新增了两项功能，升级后的项目可以立即采用：空间感知，它取代了已弃用的按对象邻近机制；以及取代手动连线的移动节点 `AI Move To` 图表。

{% content-ref url="/pages/10f005ecc29d44fa4ef4dd6d6ca9cf6c1c257d02" %}
[空间感知](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/spatial-awareness.md)
{% endcontent-ref %}

{% content-ref url="/pages/dfcf6fa365e3b6d4f5170cb925907a68cc032f42" %}
[角色移动](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-movement.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/overview/migrate-to-4-0-0-beta-27.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.