版本兼容 ​

ChaEngine 由服务端插件 ChaEngine 与客户端 Mod ChaEngineMod 组成。六种受支持组合使用同一个 ChaEngine 服务端 Jar，客户端文件则必须与玩家实际使用的 Minecraft 版本和加载器一致。

客户端支持表 ​

当前仓库启用的客户端组合共有以下六种：

NeoForge 1.21.1 是功能实现与行为基准。其他模块使用相同的公开配置含义和通信语义；只有目标版本缺少对应游戏或加载器 API 时，内部实现才会采用兼容写法。

不要把 Forge 文件放入 NeoForge 客户端，也不要把相近小版本的 Mod 混用。表中未列出的组合不属于当前支持范围。

服务端选择 ​

服务端安装 ChaEngine 插件，并同时安装它的必需依赖 ChaCore。ChaAssets 是可选依赖，仅在需要读取 .chaassets 加密资源时安装。

同一个 ChaEngine 服务端 Jar 可以分别部署到表中的六组匹配环境，不需要按 Minecraft 版本下载不同的服务端插件，也不需要为每个客户端版本建立一份 YAML。这里的“共用”只表示插件文件相同，不提供跨版本连接；每台服务器仍应连接相同 Minecraft 版本的客户端。选择服务端核心时，应确认它能够加载 Bukkit 插件，并以实际启动日志中 ChaCore、ChaEngine 均成功启用为准。

ChaEngine 服务端 Jar 使用 Java 8 字节码，以便覆盖较宽的服务端范围。这不代表服务器进程都应使用 Java 8：实际启动服务器时，仍要使用当前 Minecraft 版本和服务端核心要求的 Java。

ChaAssets 服务端兼容 ​

ChaAssets 1.0.1 同样发布为 Java 8 字节码的通用服务端 Jar，可放入 Minecraft 1.16.5 以及当前较新的 Bukkit/Paper 服务端。六个客户端组合共用同一个 ChaAssets 服务端 Jar；服务器进程的 Java 版本仍以所选 Bukkit/Paper 核心要求为准。使用 1.16.5 客户端时，请安装匹配 Forge 的 ChaAssetsMod。.chaassets 的目录、协议、授权和失败关闭语义在这些版本间保持一致。

Java 环境 ​

Forge 1.16.5 的 ChaEngineMod 使用 Java 8 字节码，因此可在 Java 11 运行；但整合包中的其他旧 Mod 仍可能只兼容 Java 8。Java 版本不正确时，通常会在启动阶段出现无法加载类、字节码版本不受支持或加载器拒绝启动等错误。先按整合包整体要求修正 Java 环境，再排查模型配置。

六组环境如何验收 ​

如果服务器需要面向全部受支持组合，发布前应按支持表建立六组彼此隔离的测试环境，并在每组中实际启动服务端与对应客户端。客户端进入服务器后，等待能力准备和配置同步完成，再确认至少一个模型可以正常显示。

每组都应记录服务端核心、服务端与客户端 Java、ChaCore、ChaEngine 和 ChaEngineMod 的版本信息。测试失败时保留服务端和客户端日志，避免只凭其中一端的现象判断问题。

双端版本不一致时会发生什么 ​

客户端未安装 Mod、装错加载器或使用不受支持的游戏版本时，服务端仍可能正常启动，但该客户端无法完成 ChaEngine 能力准备，模型、粒子和按键不会按预期工作。

配置同步成功也不等于资源文件存在。客户端仍需拥有配置引用的模型、动画、纹理和粒子文件；缺失或损坏的资源会在客户端加载阶段失败。

更新前检查 ​

更新服务端插件或客户端 Mod 前，依次确认：

1. 备份 plugins/ChaEngine/ 下的现有配置。
2. 服务端只替换同一个 ChaEngine 插件文件；再核对每个客户端的 Minecraft 版本与加载器，重新选择对应模块。
3. 确认 Forge 1.16.5 使用 Java 8 或 Java 11、Forge 1.20.1 使用 Java 17、NeoForge 1.21.x 使用 Java 21。
4. 同时更新需要配套的 ChaCore；使用加密资源时也核对 ChaAssets 与 ChaAssetsMod。
5. 在测试环境完成一次进服、模型显示、动画、粒子和按键验证，再替换正式环境。

从旧资源布局或旧加密方式升级时，另请阅读版本迁移。