跳到主要内容

FreeMinecraftModels 资源包输出

FreeMinecraftModels 将生成的资源包写入 output。

默认输出路径​

插件在启动时和执行 /fmm reload 时重建此文件夹：

plugins/FreeMinecraftModels/output/FreeMinecraftModels

随后将该文件夹打包为：

plugins/FreeMinecraftModels/output/FreeMinecraftModels.zip

该 zip 路径正是 ResourcePackManager 与 FreeMinecraftModels 集成时所期望的路径。

生成过程会删除 output 中除最近一次发布的 FreeMinecraftModels.zip 以外的所有内容，然后重新构建。请将模型源文件及其他文件保存在此目录之外。如果 FMM 无法清空该文件夹，生成会以 Failed to prepare output folder 失败，FMM 也无法完成初始化。

生成的内容​

生成过程会复制插件附带的资源包元数据、图标和图集，然后添加已加载的模型与纹理：

  • pack.mcmeta
  • pack.png
  • assets/minecraft/atlases/blocks.json
  • assets/freeminecraftmodels/... 模型与材质输出

附带资源缺失，或 FMM 无法创建某个文件夹，都会导致生成失败。写入单个模型的文件失败时会记录日志并继续生成，因此除了检查输出外，还要检查控制台。创建 ZIP 前，FMM 会为自己的实体纹理（包括粒子纹理）添加明确的图集条目，并替换自己基于实体目录的图集来源。其他图集来源保持不变。图集读取或写入失败会导致生成失败。

FreeMinecraftModels 在以下路径生成物品模型定义文件：

assets/freeminecraftmodels/items

代码仍保留了面向 1.21.4 之前服务器的皮革马铠模型覆盖路径，但插件声明了 api-version: 1.21.4，因此能够加载插件的服务器都不会执行该分支。

显示模型输出（1.21.4+）​

当模型旁边有有效的同名 .json 显示模型文件时（参见模型制作说明），FMM 会处理其 textures 映射并写入：

assets/freeminecraftmodels/models/display/{modelId}.json

它还会在以下位置生成对应的物品定义：

assets/freeminecraftmodels/items/display/{modelId}.json

带命名空间的纹理值保持不变。其他值按数字纹理索引解析；无法解析时使用一个可用的已提取纹理。格式错误的显示 JSON 会产生警告，且不会注册。运行时注册表让 FMM 能将处理后的显示模型用于物品在手中和背包里的外观。

粒子贴图​

对于模型使用的每个粒子效果，FMM 都会写入该效果的纹理，并为每张贴图写入一个平面物品模型：

assets/freeminecraftmodels/textures/entity/fmm_particles/{modelId}/{effect}.png
assets/freeminecraftmodels/models/particle/{modelId}/{effect}/{index}.json
assets/freeminecraftmodels/items/particle/{modelId}/{effect}/{index}.json

只有 Java 版玩家会看到这些贴图。基岩版玩家会从下文的基岩版资源包中获得原生粒子形式的效果。

ResourcePackManager 附属文件​

FMM 会写入一些小型 JSON 文件，供 ResourcePackManager 在将资源包转换为基岩版时读取。它们对 Java 客户端没有任何影响。

文件写入条件用途
assets/freeminecraftmodels/rspm_item_bases/display/{modelId}.json模型带有显示模型，且其同名 .yml 设置了服务器可识别的 material。带有皮革染色后缀（例如 LEATHER_CHESTPLATE:ff8800）时不会写入该文件指明自定义物品所基于的原版物品（例如 minecraft:blaze_rod），使基岩版在正确的基础物品上显示模型，而不是根据文件名猜测
assets/freeminecraftmodels/rspm_item_particles/display/{modelId}.json模型带有显示模型，且有一个包含粒子关键帧的动画列出 ResourcePackManager 要添加到物品基岩版 attachable 中的效果、定位器和循环粒子时间轴
assets/freeminecraftmodels/rspm_item_java_only/particle/{modelId}/{effect}.json模型使用了粒子效果告知 ResourcePackManager 不要把该效果的贴图物品转换为基岩版自定义物品

当 particleEffectsEnabled 为 false 时，FMM 会跳过 rspm_item_particles 文件和基岩版粒子文件。Java 版粒子贴图及其 rspm_item_java_only 文件仍会写入。

基岩版自定义实体资源包​

除了 Java 资源包资源，FreeMinecraftModels 还会尝试为每个带纹理的已加载模型导出基岩版自定义实体资源包，位置在：

plugins/FreeMinecraftModels/output/FreeMinecraftModels/assets/freeminecraftmodels/rspm_bedrock_pack

每个模型都会贡献它的贴图、几何体、渲染控制器、动画、动画控制器以及实体定义，全部位于 freeminecraftmodels: 命名空间下（freeminecraftmodels:<model_id>）。带有粒子效果的模型还会贡献 particles/<model_id>_<effect>.json（标识符为 fmm:<model_id>_<effect>），在 FMM 找到效果纹理时，还会贡献 textures/entity/fmm_particles/<model_id>/<effect>.png。参见粒子。

制作模型时值得注意的几点：

  • 没有贴图的模型会被跳过，控制台会输出 Skipping Bedrock custom entity export for <id>: model has no textures.

  • Java 导入器仍接受这种无纹理的定义；明确跳过的只是它在基岩版自定义实体资源包中的条目。

  • Bedrock 几何排除骑乘点骨骼 (m_)、自动生成的名称骨骼 (fmm_nametag_bone_*) 和 hitbox。作者创建的 tag_ 锚点仍保留在几何中，通常不含方块。

  • 没有任何动画的模型仍会导出一个 idle 动画槽

  • 除非模型的动画超过 672 个，否则模型的几何体会挂在自动生成的 freeminecraftmodels_lean 骨骼上。该骨骼向基岩版玩家展示行进朝向和以身体为中心。带有 MoLang 关键帧的动画通道会按作者所写原样写出，因此由基岩版客户端求值

  • 基岩版实体运行时碰撞箱的宽度和高度取自模型的 hitbox 骨骼；没有该骨骼时使用 1.0 x 2.0。

空 hitbox 组的尺寸为零，不会使用上述备用值。b_ 前缀会隐藏 Java 渲染，但不会从基岩版几何中排除对应骨骼。基岩版动画导出不会烘焙 FMM 在运行时计算的 IK 解；参见动画。导出错误会写入日志，并可能留下不完整的资源包文件。

基岩版运行时后端需要名为 floodgate、Geyser-Spigot 或 Geyser 的已启用插件，此项检查不区分大小写。逐玩家检测另行检查 Floodgate 或 Geyser-Spigot；仅满足后端启用条件，并不能证明玩家检测或资源包分发正常。在纯 Java 服务器上，FMM 仍导出资源包文件，但不会创建或执行该后端。

弓与弩条件式物品输出​

当 FMM 检测到一套完整的、已加载且已注册显示 JSON 的弓或弩状态模型时（参见模型制作说明），会以模型的基础 ID 生成一个物品定义。该定义在客户端切换状态。配置的物品必须使用对应的 BOW 或 CROSSBOW 材质。

弓的输出​

对于弓，生成的物品定义使用 using_item 上的 minecraft:condition，并在 use_duration（缩放 0.05）上使用 minecraft:range_dispatch：

条件使用的模型
未使用物品_idle
正在使用，回退（刚开始）_draw_start
正在使用，阈值 0.65_draw_half
正在使用，阈值 0.9_draw_full

弩的输出​

对于弩，生成的物品定义在 charge_type 上使用 minecraft:select。当装填完成（箭矢或烟花火箭）时显示 _charged 模型。未装填时的回退使用 crossbow/pull 上的 minecraft:range_dispatch：

条件使用的模型
未使用、未装填_idle
正在使用，回退（刚开始）_draw_start
正在使用，阈值 0.58_draw_half
正在使用，阈值 1.0_draw_full
已装填（箭矢或烟花火箭）_charged

输出位置​

生成的条件式物品定义会与其他物品定义一同写入：

assets/freeminecraftmodels/items/display/{baseModelId}.json

基础 ID 成为公开的显示物品。各状态的独立物品定义会从输出和运行时注册表中移除，但其显示几何会保留，因为条件式定义仍引用它们。

Minecraft 26.1+ 兼容性修复​

资源包生成器在所有受支持的版本上应用以下修复，包括 Minecraft 26.1 及更新版本：

  • UV 裁剪： 面的 UV 在缩放到 Minecraft 的 16x16 UV 空间前，会被限制在纹理的 UV 范围内（0–textureWidth / 0–textureHeight）。此范围优先使用纹理 UV 元数据，否则使用图像尺寸或模型的备用分辨率。限制负值或过大的坐标可能使受影响的面丢失纹理细节。
  • 跳过空骨骼与仅作锚点的骨骼： 没有立方体的骨骼不会写出几何 JSON，因此为它写物品模型定义会留下一个悬空引用。1.21.x 会默默容忍这种情况；26.1+ 则会把每一个都记录为 Missing block model: freeminecraftmodels:...。生成器现在会同时跳过这类骨骼的几何文件和物品定义。这也涵盖了 hitbox 骨骼（仅用于碰撞）、tag_name 位置锚点、FMM 自动生成的 fmm_nametag_bone_* 变体，以及纯粹的包装/锚点骨骼。

这些修复会自动应用，无需任何配置。

备注

tag_ 名牌锚点不需要立方体。不含立方体的锚点不会生成几何，但仅凭该前缀并不会隐藏所有含立方体的自制骨骼。名称恰好为 tag_name 的骨骼会受到特殊处理。参见名牌锚点。

确定性输出​

FMM 为各骨骼的物品定义和模型的 display 块使用保持插入顺序的映射，以减少不必要的输出变化。ZIP 写入器也会固定条目的时间戳。

这并不保证 ZIP 字节完全相同：ZIP 写入器按文件系统顺序遍历目录，没有对条目排序。模型、纹理、显示 JSON、配置、生成器或服务器版本的变化也可能合理地改变资源包。

如果资源包哈希意外变化，除了检查生成输入，还应比较压缩包条目的内容和顺序。仅凭重复下载不能确定原因。

重载行为​

执行 /fmm reload 时，FMM 先导入内容并准备候选物品、附魔和配方目录，同时保留当前运行时。如果准备失败，则拒绝重载并保留当前目录。准备成功后，它会：

  • 清理活动模型、装饰物、伪装、脚本运行时、监听器状态和脚本冷却记录，然后重建它们
  • 重新加载配置和配方
  • 重建 output/FreeMinecraftModels 文件夹
  • 重新生成 output/FreeMinecraftModels.zip
  • 若 ResourcePackManager 已启用，则执行 resourcepackmanager reload
  • 安排在 40 tick 后于主线程触发 FmmReloadedEvent，让依赖插件重新建立模型连接

FMM 会先把压缩包写入 output/FreeMinecraftModels.zip.pending，然后再将其移动覆盖 FreeMinecraftModels.zip。如果写入或移动失败，生成会失败，之前的 ZIP 保持不变。完整的 ZIP 并不代表已送达客户端，因此还要验证 ResourcePackManager 分发及客户端接受情况。完整重载与导入内容刷新之间的区别，参见配置。