猹件开发组

Appearance

On this page

Blockbench .bbmodel 模型 ​

ChaEngineMod 可以直接读取 Blockbench 保存的 .bbmodel 工程文件，不必先导出为 .geo.json。服务端配置仍然只填写现有的 model、texture 和动画字段；本地路径通过 .bbmodel 扩展名识别，HTTP/HTTPS 网络地址也支持按响应内容识别。

同一模型直接读取 .bbmodel 或读取它导出的 .geo.json，前后方向、关节与通用动作应保持一致。旧版曾额外翻转 BBModel 的前后方向；更新后如果曾手动反转模型或添加旋转补偿，请恢复原始文件与对应配置，再检查效果。

最小配置 ​

yaml
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/ 下：

text
resourcepacks/ChaEngine/model/crystal/
├─ crystal.bbmodel
└─ crystal.png

配置的 texture 优先：填写时使用指定的外部 PNG 覆盖整个模型，保留原来的单贴图行为；省略、留空或填写 texture: "" 时，客户端按每个面的纹理引用自动读取工程中的多张 PNG，并在内存中合成图集、换算 UV。一个模型的不同部件、甚至同一个 Cube 的不同面，都可以使用不同贴图，无需手动合并。方块、实体、时装与三维物品均支持这一规则，已有外部 PNG 配置无需修改。

仅使用内嵌贴图时，可以复制以下方块配置，只需要放置对应的 .bbmodel 文件：

yaml
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，也可以是 HTTP/HTTPS PNG 直链。远程工程中的相对图片引用则以模型最终下载地址所在目录解析。模型实际引用的任一图片缺失、损坏或无权访问时，本次加载失败并跳过自定义模型渲染；不会拿第一张图片替代，也不会自动寻找同名 PNG。内嵌贴图和生成的图集只在客户端内存中使用，不会解密导出到磁盘。

方块配置可以额外设置 brightness 为 0 到 15 的固定亮度；省略、填写 -1 或填写其他无效值时跟随世界光照。该设置只影响自定义方块模型的方块渲染。

网络直链 ​

model 可以直接填写 HTTP/HTTPS 下载地址，包括没有 .bbmodel 扩展名、带查询参数的接口。接口必须返回 BBModel JSON 原始内容。以下完整方块配置使用工程内嵌纹理和 idle 动画；替换 model 地址后放入 plugins/ChaEngine/block/remote.yml：

yaml
remote_crystal:
  display: "网络水晶"                                  # 载体物品名称
  model: "https://assets.example.com/download.php?token=your-token" # 返回 BBModel 的直链
  texture: ""                                         # 使用工程自身的内嵌或引用纹理
  animation: ""                                       # 动画来自同一 BBModel 工程
  item-texture: ""                                    # 物品也显示三维模型
  default-animation: "idle"                           # 必须是工程中存在的动画名称
  scale: 1.0                                         # 模型缩放
  position: [0, 0, 0]                                 # 位置偏移
  rotation: [0, 0, 0]                                 # 旋转角度
  collision: [1, 1, 1]                                # 碰撞体积
  brightness: 15                                     # 可选固定亮度

首次使用时客户端后台下载，完成后显示模型、纹理和动画。配置的 texture 也可改为独立 PNG 的 HTTP/HTTPS 直链，此时仍覆盖整个模型。URL 查询参数原样保留；相对外部贴图不会自动继承模型 URL 的 token，应为需要独立授权的图片填写可直接访问的完整地址，或把 PNG 内嵌保存到工程。

下载缓存只在内存中保留，失败重试、资源大小限制、刷新方式和排障见网络资源规则。需要同时更新服务端插件与客户端 Mod；旧客户端不能读取网络地址。

支持内容 ​

模型尺寸按 16 像素等于 1 方块 换算。例如高 32 像素的模型在 scale: 1.0 时高 2 个方块，游戏内与 动作工作室使用相同尺寸。若旧版中 BBModel 异常巨大，请更新客户端并完整重启；工作室滚轮只改变观察比例，不会改写模型尺寸或骨骼关键帧。

  • Cube：读取 from、to、inflate，保留部件绕自身 origin 的旋转，以及六个面的 UV 朝向、镜像和 0/90/180/270 度旋转。支持零厚度元素，有面积的平面正常显示，退化成线或点的面自动忽略。
  • Mesh：读取顶点、三角形或多边形面，保留部件原点与旋转；多边形按稳定顺序拆分。
  • 多贴图：按 Cube 和 Mesh 各面的纹理引用显示静态 PNG，禁用的面不参与渲染。
  • Group/Bone：保留 outliner 的父子顺序、原点和初始旋转。嵌套部件跟随父骨骼，未放入骨骼的顶层元素保持独立。
  • 数值动画：读取 position、rotation、scale 通道，保留动画名称、长度和 once、loop、hold 循环语义。支持 Blockbench 保存的数字字符串，例如 "0"、"-360" 和 "1.25"，效果与直接填写数字一致；不接受 NaN、Infinity 等非有限值。
  • 线性、阶梯和曲线关键帧：曲线在客户端按 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 像素；超限时请缩小原图。本地资源路径必须是相对路径，不能包含盘符、根路径、空段、. 或 ..；网络资源使用完整 HTTP/HTTPS 地址。自动图集更新失败时不会继续显示过期纹理，无法加载则回到原版渲染。

动画配置 ​

动画写在 .bbmodel 工程中时，不需要另外填写 animation 文件：

yaml
animated_crystal:
  model: "crystal/animated.bbmodel"
  texture: "crystal/crystal.png"
  default-animation: "walk"

方块和物品仍按 default-animation 选择默认名称；实体和时装仍按状态或服务端操作选择动画名称。名称必须与工程中的动画名称一致，服务端不会替客户端改名。

常见问题 ​

模型文件存在但没有显示：本地路径确认 model 以 .bbmodel 结尾；网络地址确认响应为 BBModel JSON，允许无扩展名。JSON 应为 UTF-8，且所有 outliner 引用都指向存在的元素。

贴图缺失：填写了 texture 时，检查路径是否相对于 resourcepacks/ChaEngine/model/；留空时，确认每个面引用的 PNG 都已内嵌或放在正确的相对路径。加密资源请检查 ChaAssets 授权状态。

所有部件都套用了同一张图：检查是否仍填写了 texture。要使用工程自身的多贴图分配，必须省略或清空该字段，并确认 Blockbench 中各面选择了正确的纹理。

空纹理配置被跳过：同时更新服务端插件与客户端 Mod，并重新加载配置；仅更新客户端不能解除旧服务端的配置校验。

只有部分几何显示：检查是否使用了未支持的自定义元素、灯光或辅助节点。只有退化成线或点的面会被忽略，同一元素上的其他有效面仍正常显示；四边形的前三个顶点共线但整个面仍有面积时，也可以保留。

部件旋转错位、竖直装饰变成水平面，或侧面贴图倒置：旧版客户端的 BBModel 导入存在部件旋转和 UV 朝向错误。更新客户端并完整重启后再查看原始模型，无需旋转原文件中的部件来补偿。先暂停动画核对初始姿态，再播放模型自带动画；若使用通用人形动作，还需单独检查骨骼映射。工作室预览与游戏内模型使用相同的导入规则。

动画名称找不到：确认动画轨道是 position、rotation 或 scale 数值关键帧；表达式和事件轨道需要先烘焙，且 default-animation 要写工程中的完整名称。

文件存在，却提示 x must be numeric：旧版客户端可能把 Blockbench 保存的数字字符串误判为错误。更新客户端并完整重启后，普通数字字符串可直接读取，无需手动修改模型；若提示中包含 query、math 等表达式，则仍须先在 Blockbench 中烘焙为数值关键帧。错误日志会指出对应关键帧和坐标轴。

文件存在，却提示 BBModel face has zero area：旧版客户端会因零厚度元素的退化侧面拒绝整个模型。更新客户端并完整重启后，会保留有效平面并忽略零面积面，不必删除这些元素、增加厚度或重新导出模型。若工作室提示“模型资源未就绪”，需查看 logs/latest.log 中的具体错误；这条提示也可能由文件缺失或贴图无法读取引起。

相关说明：资源目录、模型动画、方块模型、物品模型、实体模型、装备模型。