跳到主要内容

FreeMinecraftModels 模型制作说明

本页记录了当前在 FreeMinecraftModels 代码库中可以确认的模型制作细节。内容刻意保持保守：重点放在导入与运行时契约上，而不是涵盖所有 Blockbench 工作流偏好。

源格式​

FreeMinecraftModels 当前接受：

  • 用于可编辑源导入的 .bbmodel 文件
  • 用于精简后运行时模型数据的 .fmmodel 文件

标准导入流程是：

  1. 将模型放入 plugins/FreeMinecraftModels/imports
  2. 运行 /fmm reload
  3. 让 FreeMinecraftModels 将模型导入当前激活的模型集合，并重新生成资源包输出

文件夹角色​

plugins/FreeMinecraftModels/imports
plugins/FreeMinecraftModels/models
plugins/FreeMinecraftModels/models_disabled
  • imports 是手动模型导入和官方内容包下载在处理前进入的入口目录
  • models 包含当前已安装并启用的模型内容
  • models_disabled 包含已经下载或安装、但当前被禁用的包内容

模型 ID​

  • 运行时模型 ID 来自文件名本身，不包含 .bbmodel 或 .fmmodel 扩展名
  • 请使用稳定且唯一的文件名，因为命令和 API 调用解析的就是这个 ID
  • Blockbench 动画引用依赖名称，因此模型内部如果存在重复或不清晰的命名，比起清晰明确的命名更容易引发问题

Blockbench 兼容性​

  • FreeMinecraftModels 会在导入时检测 Blockbench 文件版本
  • 当前导入器仍然保留了对 Blockbench v5 之前版本的兼容分支
  • 如果导入日志提示模型格式与 FreeMinecraftModels 不兼容，应首先把它视为模型格式问题，而不是 wiki 或命令问题

对运行时有意义的 bone 命名约定​

当前的转换器和 skeleton 管线识别以下一些命名约定：

  • hitbox
    • 保留给 hitbox 生成使用
    • 应该用于清晰定义模型 hitbox，而不是拿来当作可视 bone
  • tag_...
    • 会被视为与 nametag 相关的虚拟 bone
  • h_...
    • 会被视为头部 bone

这些不只是风格约定；它们会影响转换结果和运行时行为。

IK、null object 和 locator​

当前代码确认支持：

  • 将 Blockbench null object 用作 IK 控制器
  • IK 链 blueprint 和运行时 IK 求解
  • locator 解析

重要的实际约束：

  • IK 控制器查找依赖名称，因此控制器命名必须在模型结构和动画数据之间保持稳定

1.21.4+ 输出分流​

对于 Minecraft 1.21.4+，FreeMinecraftModels 会在以下目录生成 item model definition 文件：

plugins/FreeMinecraftModels/output/FreeMinecraftModels/assets/freeminecraftmodels/items

较旧版本仍然使用旧式 item model 路径。如果你在制作过程中检查生成输出，请确认自己查看的是与你服务器版本对应的输出形式。

Bedrock 和渲染路径说明​

  • Bedrock 支持依赖 sendCustomModelsToBedrockClients 以及周围的 Floodgate/Geyser/resource-pack 路径
  • 支持版本上的 Java 客户端在启用 useDisplayEntitiesWhenPossible 时可以使用 display entity 渲染
  • 不要假设某个模型在 Java 客户端上显示正常，就一定适用于你的 Bedrock 路径

实用制作建议​

  • 保持文件名稳定，因为它们会成为运行时 ID
  • 保持控制器和动画命名清晰，因为 Blockbench 的动画查找依赖名称
  • 有意识地使用保留的 virtual bone 名称
  • 在 /fmm reload 之后验证导入输出，而不是只在 Blockbench 中检查
  • 检查目标 Minecraft 版本线上的生成包内容，特别是 1.21.4+

不在本页范围内​

本页不尝试保证：

  • 精确的 Blockbench UI 操作步骤
  • 艺术工作流偏好
  • 旧本地 README 材料中提到的每一个历史 .bbmodel 细节

这些内容变化速度比上面已验证的运行时契约更快。