猹件开发组

Appearance

On this page

ChaEngine 资源目录 ​

资源根目录 ​

所有直接文件都从客户端当前游戏目录的 resourcepacks/ChaEngine/ 读取。一个同时包含模型、OBJ 和基岩版粒子的完整示例为：

text
resourcepacks/ChaEngine/
├─ model/
│  ├─ demo/
│  │  ├─ demo.geo.json
│  │  ├─ demo.animation.json
│  │  └─ demo.png
│  ├─ crystal/
│  │  ├─ crystal.bbmodel
│  │  └─ crystal.png
│  ├─ items/
│  │  └─ demo_icon.png
│  ├─ item-background/
│  │  └─ epic.png
│  └─ statue/
│     ├─ statue.obj
│     ├─ statue.mtl
│     └─ statue.png
├─ particles/
│  ├─ chaengine.index.json
│  └─ effects/
│     └─ portal.json
├─ textures/
│  └─ particle/
│     └─ portal.png
└─ protected-models.chaassets

文件夹名称和层级都是路径的一部分。不要额外再套一层同名目录。

模型、动画与贴图 ​

服务端模型配置中的 model、animation 和 texture 可以填写客户端 model/ 目录下的相对路径，也可以填写完整的 HTTP/HTTPS 地址。本地文件示例：

yaml
model: "demo/demo.geo.json"               # 实际文件：model/demo/demo.geo.json
animation: "demo/demo.animation.json"     # 实际文件：model/demo/demo.animation.json
texture: "demo/demo.png"                  # 实际文件：model/demo/demo.png

动画不是必填项；没有动画文件时不要填写不存在的路径。模型引用的文件名、扩展名和大小写必须与客户端文件一致。

玩家的标准十部位模型会自动使用内置动作，不需要动作工程文件。动作工作室以服务器动画库为准，统一存放在 plugins/ChaEngine/actions/。其中 humanoid.chaaction.json 保存分类、骨架形式、分组、映射与判定规则，animations/ 存放可与 Blockbench 互通的标准动画文件。

工作室导入直接提交服务器，“保存到服务器”会写入并同步生效，无需搬运客户端工程或生成发布包。备份时整体保存上述目录。首次转换会保留旧动画；工作室保存后新增文件通过导入进入库，避免删除后被旧文件重新加载。动画名称、分组和调用方法见通用人形动作。模型和纹理仍按原路径提供。旧 humanoid.json 首次读取时备份并迁移，已有新工程时优先读取新工程。

物品贴图 ​

item-texture 同样支持 model/ 下的相对路径或 HTTP/HTTPS 地址：

yaml
item-texture: "items/demo_icon.png"        # 实际文件：model/items/demo_icon.png

物品模型配置填写该字段后，会在背包、手持、掉落物和展示框等物品场景使用这张贴图生成带厚度的平面物品；省略时才直接渲染 model 指定的三维模型。方块载体物品仍沿用方块模型的物品渲染链路。

物品背景贴图 ​

物品背景配置的 texture 也相对于 model/：

yaml
texture: "item-background/epic.png"       # 实际文件：model/item-background/epic.png

背景只用于背包、箱子等物品槽，不会替代物品自身的模型或 item-texture。完整匹配与优先级规则见物品背景。

HTTP/HTTPS 网络资源 ​

方块、物品、实体和时装配置中的 model、texture、animation，以及支持物品贴图的配置中的 item-texture，均可填写完整的 http:// 或 https:// 地址。地址必须直接返回模型 JSON、OBJ、PNG 或动画 JSON 内容，不能返回网盘分享页、登录页面或下载按钮页面。每个字段独立选择来源，可以混用网络地址与本地相对路径。

下面是完整的方块配置，保存到 plugins/ChaEngine/block/remote.yml。将示例域名与文件替换为自己的直链；对应文件不需要另放到客户端资源目录。

yaml
remote_crystal:
  display: "网络水晶"                                      # 获取到的载体物品名称
  model: "https://assets.example.com/crystal/crystal.geo.json" # 模型直链
  texture: "https://assets.example.com/crystal/crystal.png"    # PNG 贴图直链
  animation: "https://assets.example.com/crystal/idle.animation.json" # 可选动画直链
  item-texture: "https://assets.example.com/crystal/icon.png"  # 可选载体物品贴图
  default-animation: "idle"                                 # 动画文件中的名称
  scale: 1.0                                                # 统一缩放
  position: [0, 0, 0]                                      # 位置偏移
  rotation: [0, 0, 0]                                      # 旋转角度
  collision: [1, 1, 1]                                     # 碰撞体积
  brightness: 15                                          # 可选固定亮度

地址中的查询参数会保留，因此支持 download.php?token=... 一类直链。模型地址没有扩展名时，客户端会根据返回内容识别已支持的模型格式；返回 BBModel 工程时仍可使用内嵌纹理和动画，完整配置见 BBModel 网络直链。网络地址不会扩大各版本原有的模型格式和渲染能力范围。

下载由玩家客户端后台执行。首次显示需要等待模型与必要贴图下载完成；动画单独下载时，模型可能先静态显示，随后开始播放。相同地址共用下载结果，下载失败后按需间隔 30 秒重试。资源只缓存在内存，不写入本地文件；重新同步模型配置、资源重载或断线后会清理缓存并在下次使用时重新下载。修改同一 URL 的内容后，请重新同步配置或重新进服；若需要立即区分新旧资源，也可以更新 URL 中的版本参数。

单个 HTTP 响应最大 32 MiB，同时最多下载两个资源，最多跟随五次 HTTP/HTTPS 跳转；连接超时 5 秒，读取超时 10 秒，总下载时长约 30 秒。内存下载缓存最多保留 128 MiB，较久未使用的资源可能再次下载。各模型解析器仍保留自身大小限制，例如 BBModel 工程本体最大 16 MiB。

远程 BBModel 或已受支持的 Java JSON 模型内部引用相对贴图时，以模型最终下载地址所在目录解析；内嵌 PNG 不需要额外请求。Java JSON 的 PNG 帧动画仍读取同地址路径后附加 .mcmeta 的文件，查询参数保留；没有该文件时使用静态贴图。配置字段中的普通相对路径仍相对于客户端 model/，不会因为 model 改为网络地址就自动变成网络路径。

仅支持 HTTP/HTTPS，不接受 file:、ftp: 或配置字段中的 data:。BBModel 工程本身原有的内嵌 PNG 不受影响。URL 资源独立从网络获取；ChaAssets 的加密与授权规则继续作用于本地相对路径。物品背景、粒子索引和粒子贴图不属于此处的模型 URL 字段范围。

链接能在浏览器打开但游戏没有显示：检查是否需要登录 Cookie、验证码或浏览器专用请求头，是否返回了网页，或链接中的 token 已过期。游戏从玩家网络访问直链，不借用浏览器登录状态；HTTPS 需要有效证书。检查客户端日志中的 Remote model resource 提示，并确认服务端插件与客户端 Mod 均已更新到支持网络地址的构建。

OBJ 与 MTL ​

OBJ 文件也放在 model/ 下。配置的 model 以 .obj 结尾时，客户端按 OBJ 模型读取；OBJ 中引用的 MTL 与贴图必须使用安全的相对路径，并与实际文件保持一致。

text
model/statue/statue.obj
model/statue/statue.mtl
model/statue/statue.png

OBJ 支持范围和限制见OBJ 模型。

Blockbench .bbmodel ​

保存的 Blockbench 工程可以直接放在 model/ 下，配置的 model 以 .bbmodel 结尾即可：

yaml
model: "crystal/crystal.bbmodel"
texture: "crystal/crystal.png"

工程中的 Cube、Mesh、骨骼层级、面 UV 和数值动画会由客户端读取；曲线动画按 20 Hz 归一化。支持的内容、大小限制和失败回退见Blockbench .bbmodel 模型。

粒子资源 ​

粒子程序直接组合客户端已有的原版粒子，不需要额外 JSON。基岩版粒子需要以下资源：

text
resourcepacks/ChaEngine/
├─ particles/
│  ├─ chaengine.index.json
│  └─ effects/<效果定义>.json
└─ textures/<粒子贴图>.png

chaengine.index.json 把粒子 ID 映射到以资源根为基准的定义路径，例如 particles/effects/portal.json。粒子定义中的纹理路径以资源根为基准，例如 textures/particle/portal，省略扩展名时读取 .png。

普通文件与 ChaAssets ​

ChaAssetsMod 是可选资源读取器：

  • 未安装时，忽略 .chaassets，只读取上述直接文件。
  • 安装后，先查询虚拟根 ChaEngine 中的加密资源。
  • 模型配置的 demo/demo.geo.json 会自动查询包内 model/demo/demo.geo.json。
  • 同一路径同时存在时，加密资源优先。
  • 加密包未声明路径或资源底座不可用时，允许回退直接文件。
  • 路径已声明但未授权，或加密包损坏时，立即失败，不回退同路径直接文件。

解密后的资源只用于内存中的加载与渲染，不会写回明文文件。完整工作流见ChaAssets 资源加密。

路径规则 ​

本地相对资源路径必须满足以下规则；模型配置的 HTTP/HTTPS 地址遵循上面的网络资源规则：

  • 使用相对路径，不写盘符或文件系统根目录；
  • 使用 /，不使用 \；
  • 不含空路径段、. 或 ..；
  • 文件扩展名与实际格式一致；
  • 大小写与实际文件完全一致，避免在不同系统间表现不一致。

路径无效时客户端拒绝读取，不会尝试猜测、拼接到其他目录或访问 ChaEngine 资源根之外的文件。

更新资源后的检查 ​

更新直接文件或 .chaassets 后：

  1. 确认服务端 YAML 中的相对路径或网络地址仍然有效。
  2. 检查所有客户端都取得了同一代资源。
  3. 使用加密资源时，确认包与当前服务器授权仍然匹配。
  4. 重新进入服务器或执行资源更新流程，让客户端切换到新的资源代次。
  5. 依次验证模型、动画、贴图和粒子。

资源代次变化或授权撤销时，客户端会清理已解码的模型、动画、纹理与粒子缓存；旧的异步加载结果即使稍后完成，也不会重新激活过期资源。