版本迁移 ​

本页用于把旧版 ChaEngine 安装迁移到当前“服务端配置 + 客户端资源 + 可选 ChaAssets”结构。先在测试环境迁移，再替换正式服。

迁移后的职责 ​

ChaEngine 只维护模型、物品背景、动画、粒子、按键和相机能力。不要把页面配置或页面交互流程迁回 ChaEngine。

客户端版本 ​

为每个玩家重新选择准确模块：

• Forge 1.16.5：forge-1.16.5
• NeoForge 1.21.1：neoforge-1.21.1
• NeoForge 1.21.4：neoforge-1.21.4
• NeoForge 1.21.8：neoforge-1.21.8
• NeoForge 1.21.11：neoforge-1.21.11

不能把相近小版本混用。NeoForge 1.21.1 是行为基准；其余版本沿用相同配置语义，OBJ 的版本差异单独见OBJ 模型。

直接资源迁移 ​

1. 在客户端当前游戏目录创建 resourcepacks/ChaEngine/。
2. 把模型、动画和贴图整理到其 model/ 子目录。
3. 将服务端配置里的 model、animation、texture、item-texture 改为相对于 model/ 的路径。
4. 把基岩版粒子索引与效果定义放到 particles/，贴图放到 textures/。
5. 删除路径中的盘符、反斜杠、.、.. 和重复的资源根目录。

配置示例与完整树见ChaEngine 资源目录。

加密资源迁移 ​

旧的 ZIP 资源包、ZIP 密码和密码同步方式已经永久废弃，不能原样沿用。迁移时：

1. 从原始可信资源重新构建 .chaassets，不要从客户端缓存反向收集明文。
2. 使用虚拟根 ChaEngine，包内模型路径写为 model/<配置相对路径>。
3. 把 .chaassets 放到客户端 resourcepacks/ChaEngine/。
4. 在 ChaAssets 配置服务器身份、资源版本与授权。
5. 用未授权、已授权、资源损坏三类客户端分别验证失败关闭和缓存清理。

加密资源声明同一路径时优先于直接文件。只有未声明该路径或 ChaAssetsMod 不可用时才允许回退直接文件；拒绝授权或包损坏不能回退。

完整构建和授权流程见ChaAssets 资源加密。

页面能力迁移到 ChaUI ​

原先与页面或物品交互容器有关的配置和业务应迁移到 ChaUI：

1. 在 ChaUI 中重新建立页面与组件。
2. 将交互和物品处理逻辑改用 ChaUI 对应能力。
3. 若页面需要展示 ChaEngine 实体模型或时装，只调用可选的通用预览桥。
4. 调用前检测客户端能力；ChaEngineMod 缺失时让页面正常降级。
5. 页面关闭时清理预览上下文。

ChaEngine 文档不再提供页面构建教程。模型预览的接口边界见ChaUI 时装模型预览，页面本身请按 ChaUI 文档迁移。

配置核对 ​

迁移时逐类核对，不要直接复制无法解释的旧字段：

• 方块：载体材质、模型路径、动画和放置数据；
• 物品：材质、三维模型或 item-texture 二选一的渲染预期；
• 实体：匹配规则、强制模型优先级和动画名称；
• 时装：部位、模型、贴图与服务器重启后的业务恢复；
• 按键：唯一 ID、显示名、默认键、分类与按下/松开动作；
• 粒子：范围、唯一组 ID、TTL 和客户端预算。

上线前验证 ​

1. 服务端依赖和 ChaEngine 均成功启用。
2. 六个支持模块逐版本完成进服与能力握手。
3. 每类模型至少验证一个最小配置。
4. 验证实体特殊动画播放与停止、方块动画停止状态。
5. 验证粒子启动、更新、停止和断线清理。
6. 验证按键按下、松开、改键和重载同步。
7. 使用 ChaAssets 时验证授权、拒绝、损坏与资源更新。
8. 使用 ChaUI 预览时验证支持检测、页面关闭清理和无 ChaEngineMod 降级。
9. 验证物品背景优先级、相机预设、场景结束和异常恢复。

出现问题时按常见问题与排错的层级收集证据。