> 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 的蓝图进行一次检查。三项变更会破坏现有图表：两个蓝图节点移除了引脚，一个枚举被移除，目标解析节点的引脚名称也已更改。此版本范围内的其他变更均无需修改。若项目只调用 `Invoke Speech`、发送文本并播放口型同步，则无需修改即可编译。

### 开始之前

* 先创建项目分支或备份。蓝图引脚被移除后，如果资产已重新保存，仅重新安装旧版插件也无法撤销这些更改。
* 确认引擎版本。该插件支持 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 与 `4.0.0-beta.21` 之间 <code class="expression">space.vars.unreal\_plugin\_version</code>.

{% hint style="warning" %}
在保存任何内容之前，先编译所有 Convai 蓝图。包含已移除引脚的图表仍可打开，但节点会保留一个孤立引脚，直到刷新节点为止；若在此状态下保存，损坏的连接也会被保存下来。
{% endhint %}

### 变更内容

其中两项变更源于同一项设计决策：过去每次调用时设置的行为，现在改为读取聊天机器人自身的配置，因此移除了相应的单次调用引脚。第三项变更则用更丰富的模型取代了只有两个值的移动枚举——该模型由对象引用和可选的设计师自定义目标位置组成，因此旧枚举及其配套标志都不再需要。

### 重大变更

| 旧版                                                                                                        | 新版                                                             | 处理方法                                                                                              |
| --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Invoke Speech 和 `Invoke Speech` 以及 `Invoke Narrative Design Trigger` （参数 `InGenerateActions`)             | —                                                              | 移除连线。动作生成现在由聊天机器人组件上的 `Enable Actions` 设置控制。                                                      |
| Invoke Speech 上的网络复制输入，以及 `Invoke Speech` 和 `Invoke Narrative Design Trigger` （参数 `InReplicateOnNetwork`) | —                                                              | 移除连线。复制行为遵循聊天机器人组件自身的配置。                                                                          |
| `EConvaiMoveTarget` (`Actor as goal`, `Component as goal`)                                                | `EConvaiObjectReference` (`Whole Actor`, `Specific Component`) | 根据新枚举重新创建所有变量、类型转换或 `Switch on Enum` 节点。Details 面板中的字段现在标记为 **对象类型**.                             |
| `bStepOntoBounds` （位于 `FConvaiObjectEntry`                                                                | —                                                              | ）删除该检查。 `Whole Actor` 已经会在对象边界处停止。                                                                |
| `MoveTargetMode` 开启 `FConvaiObjectEntry`                                                                  | `ObjectReference`                                              | 重命名字段访问。                                                                                          |
| `Out Mode` 输出开启 `Resolve Goal Location`                                                                   | `Uses Destination`                                             | 删除该分支。将 `Target Actor` 和 `Destination` 连接到同一个 `AI Move To`; `Target Actor` 是 `null` 当且仅当目标是固定位置时。 |
| `Out Goal Actor` 输出开启 `Resolve Goal Location`                                                             | `Object Actor`                                                 | 已重命名，不再是要连接到 `AI Move To`的引脚。请使用 `Target Actor` 进行移动。                                             |
| `Out Goal Location` 输出开启 `Resolve Goal Location`                                                          | `Destination`                                                  | 已重命名。                                                                                             |
| `bForceRefresh` Resolve Goal Location上的输入 `Resolve Goal Location`                                         | —                                                              | 移除这条连线。该节点会自行重新验证已解析的组件。                                                                          |

`Invoke Speech` 还新增了一个 `Delivery` 输入（`Send Normally` 或 `Wait Until Conversation Is Idle`），现在会将消息恰好播报一次，而不是将其留在对话上下文中。这两项都不是破坏性变更，但升级后读者观察到的行为都会有所不同。

### 迁移项目

{% stepper %}
{% step %}

#### 安装新插件

替换插件文件夹并重启编辑器。请参阅 [安装 Convai 插件](https://docs.convai.com/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`。针对 `Switch on Enum` 重新构建每个节点，使其使用 `EConvaiObjectReference`，将对 `MoveTargetMode` 的访问重命名为 `ObjectReference`，并直接删除 `bStepOntoBounds` 检查。
{% endstep %}

{% step %}

#### 重新连接 Resolve Goal Location

刷新每个 `Resolve Goal Location` 节点。移除基于旧的 `Out Mode` 输出的分支，并将 `Target Actor` 和 `Destination` 连接到同一个 `AI Move To` 节点。有关当前模式，请参阅 [内置操作处理程序](https://docs.convai.com/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`以及 `Out Mode` 均无搜索结果，并且角色在 Play 模式下仍能走向已注册的对象时，迁移即告完成。

如果完成前四个步骤后 Blueprint 仍无法编译， `Resolve Goal Location` 通常是重新连接线导致的：仍然分支到已移除的 `Out Mode` 输出无法解析该引脚，错误中指出的是节点，而不是缺失的输出。

### 后续步骤

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

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

{% content-ref url="/pages/dfcf6fa365e3b6d4f5170cb925907a68cc032f42" %}
[角色移动](https://docs.convai.com/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.
