跳到主要内容

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 扩展名
  • 使用稳定、唯一的文件名，因为 ID 是命令和 API 调用解析的目标
  • Blockbench 动画引用基于名称，因此模型内重复或不清晰的命名比干净、明确的命名方案更容易造成问题

Blockbench 兼容性​

  • FreeMinecraftModels 在导入时检测 Blockbench 文件版本
  • 当前导入器仍包含 Blockbench v5 之前版本的兼容性分支
  • 如果导入日志显示模型格式与 FreeMinecraftModels 不兼容，请首先将其视为模型格式问题，而不是 wiki 或命令问题

运行时重要的骨骼约定​

当前转换器和骨架管线识别以下命名约定：

  • hitbox
    • 保留用于碰撞箱生成
    • 应该清晰地定义模型碰撞箱，而不是用作视觉骨骼
  • tag_...
    • 被视为与名称标签相关的虚拟骨骼
  • h_...
    • 被视为头部骨骼
  • b_...
    • 非显示骨骼（运行时隐藏）。用于不应在游戏中渲染的结构性或组织性骨骼。
  • m_... 或 mount_...
    • 骑乘点骨骼。带有此前缀的每个骨骼会在模型上创建一个可骑乘的座位位置。玩家或实体可以在运行时被挂载到这些位置上。多个骑乘骨骼会创建多个座位。由 MountPointManager 内部管理。

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

IK、空对象和定位器​

当前代码确认支持：

  • Blockbench 空对象作为 IK 控制器
  • IK 链蓝图和运行时 IK 求解
  • 定位器解析

重要的实际限制：

  • IK 控制器查找基于名称，因此控制器命名需要在模型结构和动画数据之间保持稳定

1.21.4+ 输出拆分​

对于 Minecraft 1.21.4+，FreeMinecraftModels 在以下位置生成物品模型定义文件：

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

旧版本仍使用旧版物品模型路径。如果您在创作时检查生成的输出，请确保查看的是与您服务器版本匹配的正确输出结构。

展示模型 JSON（1.21.4+）​

管理员可以在 .bbmodel 或 .fmmodel 文件旁边放置一个同名的 .json 文件（例如 table.bbmodel + table.json）。此 JSON 应从 Blockbench 导出为"Java Block/Item"模型，定义物品在手持或在物品栏中显示时的外观。

在导入时，FMM 会将此 JSON 复制到资源包输出中，并自动将其中的裸纹理引用重写为指向模型提取的纹理。如果不存在配套 JSON，该物品在游戏中将显示为普通纸张。

YML 中的自定义物品配置​

配套的 .yml 配置文件（与模型同名）现在支持可选的物品字段。如果设置了 material:，模型也可作为自定义可手持物品使用。完整的 YML 格式如下：

isEnabled: true
scripts:
  - my_script.lua
material: DIAMOND_SWORD      # 可选 — 设置后，模型同时成为自定义物品
name: '&b&lMy Custom Sword'  # 可选 — 显示名称
lore:                         # 可选
  - '&7A custom weapon'
enchantments:                 # 可选 — 格式: ENCHANTMENT_NAME,LEVEL
  - SHARPNESS,5
  - FIRE_ASPECT,2

当 material: 存在时，模型会与道具一起显示在管理员内容浏览器中，并可作为功能性物品给予玩家。

基岩版和渲染路径注意事项​

  • 基岩版支持取决于 sendCustomModelsToBedrockClients 以及周围的 Floodgate/Geyser/资源包路径
  • 受支持版本上的 Java 客户端可以在启用 useDisplayEntitiesWhenPossible 时使用展示实体渲染
  • 不要假设在 Java 客户端上显示正确的模型对您的基岩版路径自动安全

实用创作建议​

  • 保持文件名稳定，因为它们会成为运行时 ID
  • 保持控制器和动画命名明确，因为 Blockbench 动画查找是基于名称的
  • 有意识地使用保留的虚拟骨骼名称（hitbox、tag_、h_、b_、m_、mount_）
  • 在 /fmm reload 后验证导入的输出，而不仅仅是在 Blockbench 内部
  • 验证为目标 Minecraft 版本生成的包内容，尤其是 1.21.4+

弓和弩状态模型​

FMM 支持自定义弓和弩物品的自动拉弓动画状态。无需配置 -- 只需使用正确的后缀命名模型文件，FMM 在资源包生成期间会自动检测状态集。

命名约定​

后缀用途弓弩
_idle手持物品，未拉弓或未装填必需必需
_draw_start刚开始拉弓必需必需
_draw_half拉到一半必需必需
_draw_full完全拉满必需必需
_charged已装填的弩（箭或火箭）--必需

弓需要四个模型（除 _charged 外全部）。弩需要全部五个。

示例文件布局​

plugins/FreeMinecraftModels/imports/
  cool_bow_idle.bbmodel
  cool_bow_draw_start.bbmodel
  cool_bow_draw_half.bbmodel
  cool_bow_draw_full.bbmodel
  cool_bow.yml                  <-- 配置使用基础名称，不是 _idle

对于弩，您需要添加第五个文件 cool_bow_charged.bbmodel。

检测机制​

  • 检测在资源包生成时（启动时或 /fmm reload）自动进行。
  • 只有 _idle 模型在输出包中获得物品定义 JSON。拉弓和装填状态作为该定义中的条件条目引用。
  • 只有基础名称获得 YML 配置文件。对于上述示例，配置是 cool_bow.yml，而不是 cool_bow_idle.yml。

展示模型 JSON​

每个状态模型可以有自己的配套 .json 展示模型（例如 cool_bow_idle.json、cool_bow_draw_full.json）。FMM 会自动将它们接入生成的物品定义中。有关生成的确切 JSON 结构，请参阅资源包输出。

超出范围​

本页不尝试保证：

  • 确切的 Blockbench UI 步骤
  • 艺术工作流偏好
  • 旧版本地 README 材料中描述的每个遗留 .bbmodel 特性

这些细节的变化速度比上述已验证的运行时契约更快。