猹件开发组

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/ 目录。例如：

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

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

物品贴图 ​

item-texture 同样相对于 model/：

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。完整匹配与优先级规则见物品背景。

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 资源加密。

路径规则 ​

所有资源路径都必须满足：

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

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

更新资源后的检查 ​

更新直接文件或 .chaassets 后：

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

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