跳到主要内容

安装与资源包

运行环境​

项目要求
服务端Paper / Purpur 1.20 – 26.x
Java1.20 – 1.21 使用 Java 21；26.x 使用 Java 25
必需前置packetevents
可选联动MythicMobs（技能）、Citizens（NPC）、CloudCosmetics（模型时装）
不支持原生 Spigot、Folia、Fabric、Forge
兼容性说明

插件以 Java 17 字节码编译，分别用 Paper 1.20 与 26.3 的 API 检查过一次。1.21.4 起使用 item_model，1.21.3 以下自动改用 CustomModelData，不需要手动切换。

获取​

购买后在 资源中心 打开 CloudModel 云模型 下载最新版（CloudModel-<版本>-简体授权版.jar），授权码在 会员中心 的「我的授权」。

全新安装​

  1. 把 CloudModel-<版本>-简体授权版.jar 与 packetevents 放进 plugins/。
  2. 启动一次，生成 plugins/CloudModel/ 后，打开 token.yml 把授权码填到 key:，再启动。首次启动会自动绑定本机。
  3. 控制台出现 授权验证通过 与 CloudModel 授权已生效，模型开始显示 即成功。生成的文件：
plugins/CloudModel/
├── token.yml             # 授权码
├── config.yml            # 主配置（逐项中文注释）
├── blueprints/           # 模型放这里，可以分子文件夹
├── npcs.yml              # Citizens NPC 的模型记录（使用 /cm npc 后出现）
├── resource_pack/        # 生成的资源包文件夹
└── resource_pack.zip     # 生成的资源包压缩档
  1. 把 .bbmodel 放进 blueprints/，执行 /cm reload。模型 ID 就是文件名（小写）。
  2. 把生成的资源包发给玩家（见下方「合并资源包」）。
  3. 游戏内 /cm spawn <模型> 在脚下生成一个展示模型，确认显示正常。
授权说明
  • 授权码绑定机器，换服务器前请先在会员中心自助解绑。
  • 授权验证在后台进行，不会拖慢开服；授权服务器暂时连不上时最多可以离线运行 72 小时，连不上时每 60 秒自动重试，连上立即生效，不需要重启。
  • 没有有效授权时插件照常载入（模型与资源包照常读取、生成），但模型不显示、/cm 指令锁定，不影响服务器其他部分。
直接用 ModelEngine 的模型

不用复制文件，在 config.yml 填：

blueprints:
  extra-folders: ["ModelEngine/blueprints"]

路径相对于 plugins/。Blockbench 的「压缩存档」（<lz> 开头的 .bbmodel）也能直接读取。

合并资源包​

/cm reload 在后台线程读取模型并生成资源包，不会卡服；没有改动的文件不会被重写。

你的资源包方案做法
直接发给玩家使用 plugins/CloudModel/resource_pack.zip
CraftEngineresource-pack.copy-to 填 plugins/CraftEngine/resources/cloudmodel/resourcepack，或在 CraftEngine 的 merge-external-folders 加入 CloudModel/resource_pack。1.4.1 起资源包有变动时云模型会自动执行 /ce reload all（开服、/cm reload 后），不用手动重载
ItemsAdderresource-pack.copy-to 填 plugins/ItemsAdder/contents/cloudmodel/resourcepack，之后执行 /iazip
其他把 resource_pack/assets/ 合并进你的资源包
resource-pack:
  namespace: cloudmodel
  zip: true
  copy-to:
    - "plugins/CraftEngine/resources/cloudmodel/resourcepack"
1.21.3 以下的服务端

旧版本用 CustomModelData 显示模型，会覆写基底物品 leather_horse_armor 的 overrides。若和其他插件冲突，可在 render.base-item 换一个物品（必须能染色，受伤泛红才有效果），或调整 resource-pack.custom-model-data-start。

资源包太大时​

默认全部无损：PNG 重新压缩（索引色、最佳滤波）、相同贴图合并，结果会缓存，第二次起几乎不花时间。 高解析度手绘贴图很大时，可以打开有损压缩：

resource-pack:
  texture:
    max-size: 512     # 任一边超过就等比缩小（UV 是相对坐标，模型不用改）
    max-colors: 256   # 量化成 256 色

实测一件三张 1254 – 1983 像素手绘贴图的时装：无损 7509 KB → 512 + 256 色 后 786 KB。

从 ModelEngine 换过来​

  1. 停服，放入 CloudModel 与 packetevents。
  2. 移除 ModelEngine（想并行测试可以先保留，见 MythicMobs 技能）。
  3. 按上面的方法读取 ModelEngine 的模型文件夹、合并资源包。
  4. 启动服务端，MythicMobs 怪物文件不用修改。

安装后验证​

  • 控制台列出读取到的模型数量，没有红字。
  • /cm list 能看到模型；/cm info <模型> 显示骨骼与动画。
  • /cm selftest 全部通过。
  • /cm stats 显示「物品模式」：1.21.4 起为 item_model，以下为 custom_model_data。
最后于 更新