027 版本更新手册 ​

TIPS ​

注意！本次更新变动极大，包括大量的材质改变以及大量的API改动，且改动不可兼容以前版本。

本更新手册只兼容022/023/024/025/026的项目升级到027，026之前的报错解决请参见文档：026编辑器新增严格编译功能下报错的解决方案 | 产品手册

操作手册共分为三个大部分： ​

• 更新升级程序自动处理大部分更新逻辑
• 部分无法自动处理的手动处理操作文档
• 运行测试，查看表现以及逻辑，进行更新微调

更新升级程序自动处理流程： ​

自动升级 ​

1. 双击项目选择升级，弹出版本升级提示界面
2. 点击版本升级提示界面的我知道了按钮（可以点击Release Note蓝字手动打开更新信息网页），弹出027升级重要提示
3. 在升级前，请认真阅读升级提示信息，阅读完成后，点击027升级重要提示界面的我知道了按钮，此时会自动弹出Release Note更新信息网页，此时项目已经开始升级了，根据项目规模及电脑配置的不同，升级时间将持续3-20分钟左右
4. 升级完成后将弹出AssetLog日志文件，该日志位于升级项目的根目录下，其中描述了升级的后续需要手动处理的信息，在完全升级完成前，请不要删除它
5. 升级完成项目后，会自动打开项目，如果项目文件夹存在非法字符（如 . , ` ~ = + !等，以及多数中文符号），会导致打开项目失败，解决办法就是在文件夹修改名字时去掉这些非法字符即可（特别注意：千万不要修改了文件夹名字，又在编辑器本地游戏那儿重命名项目名字，不要这么操作！）

1. 自动打开过程中有可能出现卡住的情况，重启编辑器再打开该项目就行。
2. 部分项目升级完成打开时，可能出现RollupError提示，这时候直接跳过修改API即可，修改完成后再次打开项目将不会再有类似提示：

RollupError: Unexpected token(Note that you need plugins to import files that are not JavaScript)

项目自动备份 ​

当选择升级，走升级流程后，我们的项目会自动备份到**\MetaWorldSaved\Saved\MetaWorld\Project\Backup**目录下，多次升级同名项目，还会在该目录下保存多份备份文件，后缀是选择升级的时间

特别注意 ​

1. 如若升级一个项目出现问题时，我们删除了当前游戏，然后将备份项目重新拷贝到项目路径下

   

2. 此时需要特别注意，在本地游戏这儿双击新拷贝的项目打开时，会出现没能执行自动升级而是直接打开了026的项目，这会导致项目出错

3. 因此当重新拷贝了备份项目到工程目录时，请一定要重启编辑器(关掉编辑器，重新运行编辑器的EXE)，这样才能保证在本地游戏里双击项目时会正确的走026升级027的自动流程

手动处理部分参考手册： ​

API替换 ​

• 双击脚本打开VSCode，逐步排查项目中报错的脚本。

  • VSCode打开项目中的ModifiedStaticAPI.ts全局替换部分
    1. 需要注意F2后等待一段时间，如下视频中一条移动的蓝色横线就是等待中
    2. 如果F2等待时间过久，可以先关闭VSCode，然后运行VSCode.exe重新打开继续替换
  • F2（或鼠标右键点击重命名符号）批量替换全局匹配项，注意两次替换过程都是通过F2进行，替换框打开后要按回车键来完成替换。
  • 部分没有做类型转换的代码可能会涉及到接口没有更新到并且编译时不会报错，运行时也没有在客户端1的日志里显示报错，代码也没执行下去，需要注意查看MW_Client.log和MW_Server.log，检查TypeError相关报错提醒

  

• 推荐优先删除项目里代码中的preloadAssets（只需要删除.ts文件中的preloadAssets）
• 这个部分较多情况是无法自动替换的API变动，可以参考完整的API变动列表文档来替换对应API的使用：027版本API变动列表 ，将报错的API在文档中搜索，应该都能找到对应的变动说明以及替代方案。书写代码时，可以悬停在接口上方或按F12跳转到相关代码的例子处，027多数接口都有了详细使用案例，极大地降低了接口学习使用难度
• API变动后的注意事项可以查看027API修改常见问题 ，里面有更新后在后续编写代码中需要注意的部分。
• 若没有搜索到可以及时在论坛反馈，发帖时可以在帖子标题前方添加“【027更新问题】”我们会优先查看处理。

资源更新 ​

要检查几个地方的问题：

场景表现，因为更新了部分资源、材质，会导致项目中某些地方出现资源没有了、材质表现不同等情况，需要进行更换材质或者更换物体，这个部分每个项目不同，所以寻找对应的替换材质和替换物体也不同，无法给出准确的参考意见，下边会给出一些示例供大家参考

不规范资源替换 ​

废弃材质替换 ​

• 除了材质变化以外，少部分项目可能还会有一些材质丢失的情况（材质废弃了），有明显丢失的可以自行找替换的材质。
• 若肉眼未发现丢失的，可以根据升级工具里的提示来对应查找

脚本资源替换 ​

1. 除了在编辑器中替换资源以外，编辑器自动更新还会帮我们找出在脚本中的疑似资源ID的位置并给出提示，例如：

这里面出现的是与资源ID相同的字符串，由于这些字符串有可能是代码中设定的数值，所以无法统一替换。大家需要根据提示位置找到对应的字符串手动替换，如果资源ID在表格中，需要将表格中的ID也做修改，例如上图中的资源ID25514：

将其修改为替换ID，修改后如图：

在替换ID时需要注意，若该ID资源原来存在于优先加载或是预加载，在替换时需要将该资源的替换资源也加入优先加载，例如提示资源名为25514：

找到位置后发现该资源通过spawn同步创建，而在此之前没有下载该资源，如图：

这表示该资源应该存在于优先加载，此时需要在脚本中替换ID后，将提示给出的替换资源拖入优先加载即可正常创建，如图：

2. 替换资源在资源库里不可见

   

可能出现代码替换资源推荐的资源无法在资源库中搜索到，但资源是存在的，正常在代码中替换即可，运行游戏查看效果是否正确

预制体无法通过guid查找 ​

预制体无法通过guid查找，因此涉及资源查找或代码写法都要注意，不要在预制体中使用

场景光照等表现调整 ​

027版本更新后，材质、场景光照以及天空盒部分产生了比较大的变动，这会导致部分工程会出现场景效果表现变化较大的情况，若改动完成后发现工程里的场景表现不佳，可以查看027场景环境调整说明 调整工程场景。

运行项目测试微调 ​

• 运行后如果出现了如下情况

  

  

  此时我们只需要修改场景中任意对象的进行调整（比如将某方块的x轴坐标+1），然后保存项目（Ctrl + S），再次运行项目，整个项目就会恢复正常

  

• 将上面操作都做完之后，运行项目测试看看

• 运行起来后，查看各个场景的物体材质情况和逻辑表现，处理细节微调问题，可能出现的问题，请参考文档：027API修改常见问题

• 若都没有问题后，删除根目录下的“027修改记录.txt”和"AssetLog.txt"文件

• 到此，027的升级就圆满结束了

最后 ​

升级过程中有任何意外情况、文档中没有提到的问题、现象和文档不一样等等，都可以去https://forum.ark.online/论坛反馈，发帖时帖子标题前方添加“【027更新问题】”我们会优先查看处理！