猹件开发组

Appearance

On this page

安装 ChaEngine 服务端插件 ​

安装前准备 ​

安装前请准备：

  • 一套能够加载 Bukkit 插件的服务端核心；
  • 与服务端环境匹配的 ChaCore，这是 ChaEngine 的必需依赖；
  • ChaEngine 服务端插件 ChaEngine-<version>.jar；
  • 可选的 ChaAssets。只有使用 .chaassets 加密资源时才需要它。

ChaEngine 的模型、粒子与按键效果需要客户端 ChaEngineMod 配合。只安装服务端插件不会让原版客户端获得这些能力。

六种受支持的客户端共用这一个服务端 Jar，不需要按 Minecraft 版本分别下载 ChaEngine 服务端插件。这里是把同一文件分别部署到匹配版本的测试服或正式服，不代表一个运行中的服务器可以让不同 Minecraft 版本跨版本连接。服务器进程使用的 Java 仍由服务端核心决定。

如果使用 ChaAssets 加密资源，请安装 ChaAssets-1.0.1-ob.jar（或对应构建产物）。它是可用于 1.16.5 及当前较新 Bukkit/Paper 的同一个通用服务端 Jar；1.16.5 客户端还需安装匹配 Forge 的 ChaAssetsMod。

安装步骤 ​

  1. 关闭服务端，不要在运行中替换插件文件。
  2. 把 ChaCore 与 ChaEngine-<version>.jar 放入服务端 plugins/。
  3. 如果准备使用加密资源，再把 ChaAssets 放入同一目录。
  4. 启动服务端，等待插件完成首次加载。
  5. 确认控制台没有依赖缺失、配置读取失败或 ChaEngine 启用失败的信息。

ChaEngine 会在 ChaCore 之后加载。ChaAssets 是软依赖，未安装时普通模型资源仍可使用。

首次启动会生成什么 ​

首次成功启动后，服务端目录如下：

text
plugins/ChaEngine/
├─ config.yml
├─ lang.yml
├─ block/
├─ item/
├─ entity/
├─ equip/
└─ key/
  • config.yml：系统配置；当前版本没有额外可调的系统项。
  • lang.yml：服务端提示文本。
  • block/：方块模型配置。
  • item/：不可放置的物品模型配置。
  • entity/：实体模型与匹配规则。
  • equip/：玩家时装配置。
  • key/：客户端按键配置。

每个功能目录可以放置多个 .yml 文件。建议一个文件只保存一类相关配置，并使用能说明用途的文件名。

如何确认服务端安装成功 ​

安装验收必须实际启动服务端与客户端，按以下顺序检查：

  1. 控制台显示 ChaCore 与 ChaEngine 均已启用。
  2. plugins/ChaEngine/ 及上述配置文件、子目录已经生成。
  3. 由管理员执行 /chaengine reload，并收到重载成功结果。
  4. 启动与 Minecraft 版本和加载器匹配的 ChaEngineMod 客户端并进入服务器，等待 ChaEngine 能力准备与配置同步完成。
  5. 完成一次模型物品获取或模型实体显示测试，确认客户端资源存在且模型显示正常。

第四、第五步同时验证了双端连接，不能用 Jar 能打开、单元测试通过或仅服务端启动成功代替。

更新插件 ​

  1. 备份整个 plugins/ChaEngine/。
  2. 关闭服务端。
  3. 同时核对 ChaCore 与 ChaEngine 的兼容版本；使用 ChaAssets 时也一并核对。
  4. 替换插件文件后启动测试服，观察配置加载日志。
  5. 如果服务器面向多种受支持客户端，使用同一个 ChaEngine 服务端 Jar，分别实际启动对应服务端测试环境与客户端，逐一完成进服、能力准备、配置同步和模型显示，再更新正式服。

不建议通过热替换插件文件完成跨版本更新。普通配置修改可以执行 /chaengine reload，但依赖或插件文件变化应完整重启。

常见安装问题 ​

现象优先检查
提示缺少依赖ChaCore 是否已安装并先于 ChaEngine 成功启用
插件目录没有生成插件文件是否放错目录，控制台是否存在 Java 或服务端核心不兼容错误
服务端正常但客户端没有模型客户端是否安装正确版本的 ChaEngineMod，资源是否已放到客户端目录
加密资源一直不可用双端 ChaAssets 组件是否齐全，客户端是否已获得当前服务器授权
修改 YAML 后无变化文件是否能正常解析，随后是否执行了 /chaengine reload

Unsupported API version 1.20 ​

如果 1.16.5 服务端日志出现 Unsupported API version 1.20，说明加载到了旧版 ChaAssets Jar。先关闭服务端，删除 plugins/ 中重复或旧的 ChaAssets 文件，再放入新的 ChaAssets-1.0.1-ob.jar（或最新构建产物），最后完整退出并重启服务端。不要手工编辑 Jar 内的 plugin.yml 或其他 YAML；API 版本由发布包固定。重启后确认日志不再出现该错误，再让匹配 Forge 的 1.16.5 ChaAssetsMod 进服验证加密资源。

完整重载命令：

text
/chaengine reload

继续阅读：安装 ChaEngineMod与ChaEngine 资源目录。