猹件开发组Blockbench .bbmodel 模型
ChaEngineMod 可以直接读取 Blockbench 保存的 .bbmodel 工程文件，不必先导出为 .geo.json。服务端配置仍然只填写现有的 model、texture 和动画字段；客户端会根据 model 的扩展名选择 .bbmodel 解析路径。
最小配置
crystal:
display: "水晶"
model: "crystal/crystal.bbmodel"
texture: "crystal/crystal.png"
scale: 1.0
position: [0, 0, 0]
rotation: [0, 0, 0]
brightness: 15 # 可选固定亮度；0-15，省略时跟随世界光照文件放在每个客户端的 resourcepacks/ChaEngine/model/ 下：
resourcepacks/ChaEngine/model/crystal/
├─ crystal.bbmodel
└─ crystal.png配置的 texture 优先：填写时使用指定的外部 PNG 覆盖整个模型，保留原来的单贴图行为；省略、留空或填写 texture: "" 时，客户端按每个面的纹理引用自动读取工程中的多张 PNG，并在内存中合成图集、换算 UV。一个模型的不同部件、甚至同一个 Cube 的不同面，都可以使用不同贴图，无需手动合并。方块、实体、时装与三维物品均支持这一规则，已有外部 PNG 配置无需修改。
仅使用内嵌贴图时，可以复制以下方块配置，只需要放置对应的 .bbmodel 文件：
crystal:
display: "水晶"
model: "crystal/crystal.bbmodel"
texture: "" # 按模型各面的引用自动读取多张内嵌 PNG
scale: 1.0
position: [0, 0, 0]
rotation: [0, 0, 0]
brightness: 15例如模型的外壳使用一张 PNG、装饰使用另一张 PNG，只要在 Blockbench 中给各面选择正确纹理，并将两张图片内嵌保存到工程，使用上面的空纹理配置即可同时显示。不同图片尺寸、每张纹理的 UV 尺寸和透明像素均会保留，骨骼动画继续按原配置播放。
仅保存外部图片引用不等于已经内嵌图片。未内嵌时，工程中的图片引用必须是相对于 resourcepacks/ChaEngine/model/ 的安全相对路径，例如 crystal/detail.png，并放置对应文件。模型实际引用的任一图片缺失、损坏或无权访问时，本次加载失败并跳过自定义模型渲染；不会拿第一张图片替代，也不会自动寻找同名 PNG。内嵌贴图和生成的图集只在客户端内存中使用，不会解密导出到磁盘。
方块配置可以额外设置 brightness 为 0 到 15 的固定亮度；省略、填写 -1 或填写其他无效值时跟随世界光照。该设置只影响自定义方块模型的方块渲染。
支持内容
- Cube：读取
from、to、inflate、六个面和面 UV。 - Mesh：读取顶点、三角形或多边形面；多边形按稳定顺序拆分。
- 多贴图：按 Cube 和 Mesh 各面的纹理引用显示静态 PNG，禁用的面不参与渲染。
- Group/Bone：保留 outliner 的父子顺序、原点和初始旋转。
- 数值动画：读取 position、rotation、scale 通道，保留动画名称、长度和
once、loop、hold循环语义。 - 线性、阶梯和曲线关键帧：曲线在客户端按 20 Hz 采样后使用数值关键帧播放。
同一个 .bbmodel 可以用于方块、物品、实体、玩家时装和 ChaUI 的通用模型预览；这些入口继续使用各自原有的变换、匹配和生命周期规则。
不支持的工程内容
编辑器摄像机、灯光、辅助定位点、撤销历史和插件私有字段不会参与渲染。表达式驱动的 MoLang 或脚本动画、事件轨道和依赖外部编辑器插件的自定义元素不能直接转换为数值动画；请在 Blockbench 中烘焙为 position、rotation 或 scale 关键帧后再保存。多贴图目前支持静态 PNG，不播放贴图帧动画，也不读取每张材质独立的 PBR 参数。自动图集要求各面的 UV 位于对应纹理范围内；超出边界的重复平铺 UV 暂不支持，请先在 Blockbench 中调整。
安全限制
单个文件最大 16 MiB；工程最多 40,000 个元素、1,024 个骨骼、256 张纹理、500,000 个生成三角形和 100,000 个关键帧；所有内嵌 PNG 合计最大 32 MiB。自动图集引用的图片解码后合计不超过 16,777,216 像素，生成的图集（含边缘留白）也不超过这一像素数，单边最大 8192 像素；超限时请缩小原图。资源路径必须是相对路径，不能包含盘符、根路径、空段、. 或 ..。自动图集更新失败时不会继续显示过期纹理，无法加载则回到原版渲染。
动画配置
动画写在 .bbmodel 工程中时，不需要另外填写 animation 文件：
animated_crystal:
model: "crystal/animated.bbmodel"
texture: "crystal/crystal.png"
default-animation: "walk"方块和物品仍按 default-animation 选择默认名称；实体和时装仍按状态或服务端操作选择动画名称。名称必须与工程中的动画名称一致，服务端不会替客户端改名。
常见问题
模型文件存在但没有显示：确认 model 以 .bbmodel 结尾，JSON 为 UTF-8，且所有 outliner 引用都指向存在的元素。
贴图缺失：填写了 texture 时，检查路径是否相对于 resourcepacks/ChaEngine/model/；留空时，确认每个面引用的 PNG 都已内嵌或放在正确的相对路径。加密资源请检查 ChaAssets 授权状态。
所有部件都套用了同一张图：检查是否仍填写了 texture。要使用工程自身的多贴图分配，必须省略或清空该字段，并确认 Blockbench 中各面选择了正确的纹理。
空纹理配置被跳过：同时更新服务端插件与客户端 Mod，并重新加载配置；仅更新客户端不能解除旧服务端的配置校验。
只有部分几何显示：检查是否使用了未支持的自定义元素、灯光或辅助节点；Cube 和 Mesh 必须拥有至少三个非共线顶点。
动画名称找不到：确认动画轨道是 position、rotation 或 scale 数值关键帧；表达式和事件轨道需要先烘焙，且 default-animation 要写工程中的完整名称。