> 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` 为 space.vars.unreal\_plugin\_version 只需对触及 Convai 的蓝图进行一次遍历即可。三项变更会破坏现有图：两个蓝图节点丢失了引脚，一个枚举被移除，目标解析节点的引脚也被重命名。该范围内没有其他内容需要编辑。一个只调用 `调用语音`、发送文本并播放唇形同步的项目可以在不变更的情况下编译。
### 开始之前
* 请先创建分支或备份项目。蓝图引脚移除后，一旦资产被重新保存，就无法通过重新安装旧插件来撤销。
* 请确认引擎版本。该插件支持 Unreal Engine space.vars.unreal\_min\_version 到 space.vars.unreal\_max\_version.
* 可一次性升级。在 `4.0.0-beta.21` 和 space.vars.unreal\_plugin\_version.
{% hint style="warning" %}
与保存任何内容之前，先编译每个 Convai 蓝图。带有已移除引脚的图仍然可以打开，但该节点会保留一个孤立引脚，直到刷新为止；在该状态下保存会保留损坏的连接。
{% endhint %}
### 变更内容
其中两项变更源自同一个设计决策：以前按每次调用设置的行为，现在改为从聊天机器人的自身配置中读取，因此移除了按调用设置的引脚。第三项则用更丰富的模型替换了一个二值移动枚举——对象引用加上可选的设计师自定义目的地——这使得旧枚举及其配套标志变得多余。
### 破坏性变更
| 旧版 | 新版 | 处理方法 |
| ----------------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------ |
| ……上的 generate-actions 输入 `调用语音` 和 `调用叙事设计触发器` （参数 `InGenerateActions`) | — | 删除连线。动作生成现在遵循 `启用动作` 聊天机器人组件上的设置。 |
| ……上的 replicate-on-network 输入 `调用语音` 和 `调用叙事设计触发器` （参数 `InReplicateOnNetwork`) | — | 删除连线。复制行为遵循聊天机器人组件自身的配置。 |
| `EConvaiMoveTarget` (`Actor 作为目标`, `Component 作为目标`) | `EConvaiObjectReference` (`整个 Actor`, `特定组件`) | 将任何变量、Cast 或 `按枚举切换` 节点，使用新枚举进行重建。Details 面板中的字段现在标注为 **对象是**. |
| `bStepOntoBounds` on `FConvaiObjectEntry` | — | 删除该检查。 `整个 Actor` 已经会在对象边界处停下。 |
| `MoveTargetMode` on `FConvaiObjectEntry` | `ObjectReference` | 重命名该字段访问。 |
| `输出模式` ……上的输出 `解析目标位置` | `使用目标位置` | 删除该分支。将 `目标 Actor` 和 `目标` 连接到一个单一的 `AI Move To`; `目标 Actor` 为 `为空` 仅在目标是固定位置时。 |
| `输出目标 Actor` ……上的输出 `解析目标位置` | `对象 Actor` | 已重命名，不再是要连接到 `AI Move To`中 `目标 Actor` 用于移动的引脚。 |
| `输出目标位置` ……上的输出 `解析目标位置` | `目标` | 已重命名。 |
| `bForceRefresh` ……上的输入 `解析目标位置` | — | 删除连线。该节点会自行重新验证其已解析的组件。 |
`调用语音` 还新增了一个 `传递方式` 输入（`正常发送` 或 `等待对话空闲`）并且现在只会发言一次，而不会将其留在对话上下文中。二者都不是破坏性变更，但升级后读者看到的内容会因这两项变化而不同。
### 迁移项目
{% stepper %}
{% step %}
#### 安装新插件
替换插件文件夹并重启编辑器。请参见 [安装 Convai 插件](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/install-the-convai-plugin.md).
{% endstep %}
{% step %}
#### 刷新丢失引脚的节点
打开每个调用 `调用语音` 或 `调用叙事设计触发器`的蓝图。右键单击每个节点并选择 **刷新节点**，然后删除连接到这两个已移除布尔输入的连线， `InGenerateActions` 和 `InReplicateOnNetwork`.
{% endstep %}
{% step %}
#### 替换已移除的枚举
在项目中搜索 `EConvaiMoveTarget`, `MoveTargetMode`，以及 `bStepOntoBounds`。重建每个 `按枚举切换` 以适配 `EConvaiObjectReference`，将 `MoveTargetMode` 访问重命名为 `ObjectReference`，并删除 `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 %}
#### 编译并重新保存
编译每个受影响的蓝图，然后保存。仅在干净编译后重新保存。
{% endstep %}
{% endstepper %}
### 验证迁移
当每个 Convai 蓝图都能无错误编译，并且在整个项目中搜索 `EConvaiMoveTarget`, `MoveTargetMode`, `bStepOntoBounds`，以及 `输出模式` 没有任何结果，同时角色在 Play 模式下仍会走向已注册对象时，迁移才算完成。
如果蓝图在前四步后仍无法编译， `解析目标位置` 重新接线通常是原因：仍然基于已移除的 `输出模式` 输出进行分支的图无法解析该引脚，而错误信息指向的是节点而不是缺失的输出。
### 下一步
在此版本范围内新增了两个功能，升级后的项目可以立即采用：空间感知，它取代了已弃用的按对象近距离机制；以及取代手工连线的移动节点 `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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
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=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.