FreeMinecraftModels 常见问题

如果你的问题没有列在这里，请查看侧边栏 是否已有专门页面！

入门

如何安装与使用 FreeMinecraftModels？

详情

安装：

1. 下载 FreeMinecraftModels.jar 并放入你的 plugins 文件夹
2. 重启服务器以生成插件文件夹
3. 运行 /fmm setup 打开内容管理 / 首次设置菜单
4. 如果你使用官方内容包，使用 /nightbreaklogin <token> 关联 Nightbreak
5. 使用 /fmm setup 或 /fmm downloadall 来管理 Nightbreak 官方内容
6. 对于手动内容，将 .bbmodel 文件放入 ~/plugins/FreeMinecraftModels/imports/ 然后运行 /fmm reload
7. 在 ~/plugins/FreeMinecraftModels/output/FreeMinecraftModels.zip 找到生成的资源包

分发资源包：

选择以下任一方式：

• 方案 A（推荐）：安装 Resource Pack Manager 进行自动分发
• 方案 B：通过 server.properties 或第三方托管服务手动配置

生成模型：

• /fmm spawn static <id> - 生成临时装饰性模型
• /fmm spawn dynamic <id> - 生成附着到实体的模型
• /fmm spawn prop <id> - 生成持久化世界模型

管理：

• /fmm - 打开可制作物品菜单（需要 freeminecraftmodels.menu）
• /fmm setup - 打开内容管理 / 首次设置菜单
• /fmm recommendedplugins - 浏览与 FMM 搭配良好的配套插件
• /fmm downloadall - 下载最新的插件更新以及所有可访问的官方内容
• /fmm downloadallcontent - 下载所有可访问的官方内容（仅内容）
• /fmm updatecontent - 更新已过期的官方内容
• /fmm downloadpluginupdate - 仅下载最新的插件 jar 更新
• /fmm reload - 重载插件并转换新模型
• /fmm version - 显示插件版本
• /fmm stats - 显示实体数量统计

玩家功能：

• /fmm disguise <modelID> [player] - 将你（或目标玩家）的外观变为自定义模型
• /fmm undisguise [player] - 移除某玩家的伪装
• /fmm disguiselist - 列出当前所有处于伪装中的玩家
• /fmm itemify <model> <material> - 创建一个可放置物品，使用时生成指定模型
• /fmm craftify <modelID> - 打开交互式配方编辑器为道具创建合成配方
• /fmm shop - 打开可选的、基于 Vault 的家具商店（仅在 shop_config.yml 中启用时可用）
• /fmm mount <modelID> - 生成一匹伪装成自定义模型的可乘骑马（实验性）

调试：

• /fmm hitbox visualize [duration] - 用粒子可视化模型碰撞箱（duration 以刻为单位，默认 100）
• /fmm location - 报告已注册的保护区/地下城提供者并在当前位置测试它们
• /fmm debug bedrock [on|off] - 切换用于诊断 Bedrock 显示管线的详细 [FMM-BedrockDebug] 日志流。不是配置项 —— 每次重启都会重置为 OFF

管理：

• /fmm deleteall [radius] - 移除所有已加载的模型化实体和道具（小心使用 - 无确认提示）。可选的 [radius]（仅玩家可用）将移除范围限定在若干方块以内

权限：

• freeminecraftmodels.*（默认：OP）- 通配符，授予 freeminecraftmodels.admin、freeminecraftmodels.deleteall、freeminecraftmodels.disguise.self 与 freeminecraftmodels.disguise.others。同时也是 /fmm reload、/fmm stats、/fmm spawn、/fmm itemify、/fmm craftify、/fmm mount、/fmm hitbox visualize、/fmm debug bedrock、/fmm location、/fmm setup、/fmm recommendedplugins、/fmm downloadall、/fmm downloadallcontent、/fmm updatecontent 与 /fmm downloadpluginupdate 字面意义上所要求的权限
• freeminecraftmodels.admin（默认：OP）- /fmm admin（管理员内容浏览器）与 /fmm giveitem
• freeminecraftmodels.disguise.self（默认：OP）- 允许玩家仅伪装/解除伪装自身
• freeminecraftmodels.disguise.others（默认：OP）- 允许针对目标的伪装/解除伪装以及 /fmm disguiselist
• freeminecraftmodels.deleteall（默认：OP）- 使用 /fmm deleteall 所需（通配符的子权限）
• freeminecraftmodels.bypassregionprotection（默认：OP）- 即使启用了 preventPropPlacementInProtectedRegions，仍可在 WorldGuard 保护区或 GriefPrevention 领地内放置道具并与之交互
• freeminecraftmodels.menu（默认：true）- 允许所有玩家通过 /fmm 打开可制作物品浏览器
• freeminecraftmodels.shop（默认：true）- 允许所有玩家打开 /fmm shop（仍受商店启用状态约束）

除非另有说明，命令默认仅限 OP 使用。如有需要可向非 OP 玩家授予这些权限。

模型功能与限制

模型大小和旋转有什么限制？

详情

大小限制：

• 单个骨骼的包围盒最大值：192x192x192 模型像素（游戏内 12x12x12 方块）—— 在同一个骨骼内的所有方块上一起测量
• FreeMinecraftModels 使用内部 4 倍缩放，并平移模型原点以适配 Minecraft 资源包 -16..+32 的范围
• 如果某个骨骼超过限制，FMM 会在控制台输出警告；这时可以缩小方块、把方块靠拢，或拆分到多个骨骼中
• 整个模型可以比此值更大 —— 限制只针对单个骨骼

方块（cube）旋转限制：

• 允许的角度：0°、±22.5°、±45° 及 22.5° 的倍数（自 v2.3.0 起）
• 仅支持单轴旋转
• 例如：[22.5, 0, 0] 可用，但 [22.5, 0, 45] 只会部分旋转
• 其他角度无法正确显示

骨骼（bone）旋转：

• 骨骼支持任意旋转角度
• 避免使用 90°、-90°、180°、-180° 作为默认静止姿态（可能引起异常行为）
• 支持多轴旋转
• 每个骨骼都会生成一个独立实体（性能考量）

性能提示：

请尽量减少骨骼数量。每个骨骼都会在 Minecraft 中生成一个独立实体，规模化时会影响服务器性能。

支持哪些动画？

详情

FreeMinecraftModels 支持以下默认状态动画（在 AnimationStateType 枚举中声明）：

标准动画：

• spawn
• idle
• walk
• jump
• attack
• death
• custom（由 API 或 Lua 触发的一次性动画的通用占位项）

工作原理：

• 在 BlockBench 中使用上述小写名称创建动画，FMM 会自动将其绑定到对应状态
• 插件从 .bbmodel 文件中读取动画关键帧
• 动画会根据实体状态自动触发
• 开发者可以在 ModeledEntity 上使用 playAnimation(animationName, blend, loop) 来编程式地触发动画，或在 Lua 中使用 context.prop:play_animation(name, blend, loop)

特殊情况：

唤魔者（Evoker）实体会检测附近的唤魔者尖牙以自动触发攻击动画。

什么是虚拟骨骼？它们如何工作？

详情

虚拟骨骼是具有保留名称的特殊骨骼，可为你的模型添加功能：

Hitbox 骨骼：

• 名称：hitbox
• 创建交互区域和碰撞箱
• 通过相同的 x/z 值定义实体边界

名牌骨骼：

• 前缀：tag_
• 在模型上方显示文字
• 用于实体命名

头部旋转骨骼：

• 前缀：h_
• 根据玩家/实体头部位置旋转
• 自动追踪头部移动

用法：

在 BlockBench 中用以上特殊名称创建骨骼，插件会自动应用相应功能。

故障排查 FAQ

我看到的不是自定义模型，而是马铠。

详情

如果游戏中显示的是马铠而不是自定义模型，最可能的原因是你没有正确地将 FMM 资源包与你已有的资源包合并。

MagmaGuy 开发了一个名为 Resource Pack Manager (RSPM) 的插件，可以为你自动合并资源包。可在 Spigot 这里 下载。

只需将 RSPM 的 .jar 放入 plugins 文件夹，RSPM 就会处理一切。它会合并所有资源包、自动托管，并在玩家登录时将其分发给他们。

添加 .bbmodel 文件后为什么看不到我的模型？

详情

如果你的模型未出现，请检查以下常见问题：

1. 忘记重载

将 .bbmodel 放入 imports 文件夹后请运行 /fmm reload。这会转换模型并生成资源包。

2. 资源包未应用

玩家必须启用了 FMM 资源包才能看到模型。

• 检查 ~/plugins/FreeMinecraftModels/output/FreeMinecraftModels.zip 是否生成
• 安装 Resource Pack Manager 进行自动分发
• 或通过 server.properties 或托管服务手动分发

3. 文件位置错误

手动导入的 .bbmodel 文件必须放在：~/plugins/FreeMinecraftModels/imports/

如果你使用的是官方内容包，请使用 /fmm setup 或 /fmm downloadall，而不是手动放置文件。

4. 模型有错误

请在 /fmm reload 期间检查控制台日志中的错误消息。常见问题包括不支持的旋转、过大的模型或材质问题。

5. 资源包合并问题

如果你看到马铠而不是模型，说明资源包没有正确合并。使用 Resource Pack Manager (RSPM) 来自动处理合并。

ViaVersion 可能导致资源包无法正常显示。

详情

ViaVersion 可能导致资源包问题，特别是在低于 1.21.4 的服务器版本上运行时。Minecraft 从 1.21.4 开始改变了资源包的处理方式。如果你的服务器运行的是如 1.21.3 之类的版本，并使用 ViaVersion 让 1.21.4 客户端连接，这些客户端在显示某些资源包内容（例如 FMM 的自定义模型）时可能会遇到问题。

这是因为 Minecraft 的资源包系统在 1.21.4 更新中发生了变化。

注意： 这是 Minecraft 和 ViaVersion 的限制，并非 FreeMinecraftModels 特有。ViaVersion 的协议转换在服务器版本低于 1.21.4 时可能无法完全支持资源包变更。

要解决此问题，建议将服务器升级到 1.21.4 或更高，从而确保对现代资源包功能（包括 FMM 自定义模型）有更好的兼容性。

为什么我的模型导致卡顿或性能问题？

详情

BlockBench 模型中的每个骨骼在 Minecraft 中都会生成一个独立的实体。骨骼很多的模型会影响服务器性能。

优化建议：

• 尽量减少模型中的骨骼数量
• 限制同时生成的模型数量
• 当不需要动画时考虑使用静态模型而不是动态模型
• 避免在彼此附近生成大量高骨骼数的模型

技术解释：

FreeMinecraftModels 将每个骨骼渲染为一个独立的 Minecraft 实体。一个有 50 个骨骼的模型会生成 50 个实体。规模化时会影响性能。

最佳实践：

• 设计骨骼更少的模型
• 用真实生成量进行性能测试
• 添加新模型时监控服务器 TPS

高级功能

我需要 Resource Pack Manager (RSPM) 吗？

详情

Resource Pack Manager (RSPM) 可选但强烈推荐。

RSPM 做什么：

• 自动合并来自多个插件的资源包
• 托管资源包（无需外部托管）
• 在玩家登录时自动分发包
• 免去手动配置资源包

没有 RSPM 时：

你必须手动：

• 将 FMM 资源包与任何现有服务器资源包合并
• 通过外部服务或 server.properties 托管合并后的包
• 配置服务器向玩家发送资源包
• 每次新增模型都更新资源包

为什么使用 RSPM：

大部分"显示马铠而不是模型"的问题都是由资源包合并不当导致的。RSPM 会自动处理。

下载 RSPM：https://www.spigotmc.org/resources/resource-pack-manager.118574/

由 MagmaGuy 开发，与 FreeMinecraftModels 同一作者。

我可以在自己的插件中使用 FreeMinecraftModels 吗？

详情

可以，FreeMinecraftModels 为开发者提供了 API。

Maven/Gradle 集成：

仓库：https://repo.magmaguy.com/releases

Artifact：

• GroupId：com.magmaguy
• ArtifactId：FreeMinecraftModels
• Scope：provided（必须安装在服务器上，不要 shade）

主要 API 类：

• ModeledEntity（基类）
• StaticEntity
• DynamicEntity
• PropEntity

示例用法：

StaticEntity staticEntity = StaticEntity.create(id, location);
if (staticEntity == null) {
    Bukkit.getLogger().warning("Failed to create model");
    return;
}
staticEntity.setRightClickCallback(...);
staticEntity.remove();

重要：

不要将 FreeMinecraftModels shade 进你的插件。它必须单独安装在服务器上。

详细的 API 文档请参阅 官方 README。

如何将玩家伪装为自定义模型？

详情

/fmm disguise 命令可以将玩家外观变换为任意自定义模型。

命令：

/fmm disguise <modelID> [player]
/fmm undisguise [player]
/fmm disguiselist

工作原理：

• 将玩家对其他玩家变为不可见
• 在玩家位置叠加自定义模型
• 模型跟随玩家的移动
• 非常适合角色扮演服务器或特殊事件

示例：

/fmm disguise dragon              # 伪装自己
/fmm disguise dragon Steve         # 伪装其他玩家
/fmm undisguise Steve              # 解除 Steve 的伪装
/fmm disguiselist                  # 列出当前所有伪装玩家

要求：

• 自身伪装：freeminecraftmodels.disguise.self（默认：OP）
• 针对他人及 /fmm disguiselist：freeminecraftmodels.disguise.others（默认：OP）
• 控制台可在提供玩家名时执行目标形式
• modelID 必须是 models 文件夹中已转换的有效模型
• 第三方插件可通过公共的 DisguiseAPI 驱动伪装

说明：

• 玩家碰撞箱不变（碰撞箱不变）
• 其他玩家会看到自定义模型而不是你的玩家皮肤
• 已伪装时再次伪装会干净地替换之前的伪装
• 不可见效果在喝牛奶或其他清除效果的交互后仍会持续，直到玩家被解除伪装

如何创建可放置的模型物品？

详情

/fmm itemify 命令创建特殊物品，让玩家可以在世界中放置模型。

命令：

/fmm itemify <model> <material>

参数：

• model - models 文件夹中任意有效模型 ID
• material - 任意 Minecraft 材质（STICK、PAPER、DIAMOND 等）

示例：

/fmm itemify lamp_post STICK

它创建什么：

• 带有金色装饰显示名称的自定义物品（例如 "✦ Wolf ✦"）
• 解释该物品的描述性 Lore
• 物品被直接添加到你的背包
• 右键即可将模型作为道具放置

使用场景：

• 给玩家发放装饰建筑的物品
• 为家具创建自定义"刷怪蛋"
• 在不给予建造权限的情况下分发模型
• 创造模式建造时的套装

要求：

• 权限：freeminecraftmodels.*
• 玩家必须在游戏内（不能是控制台）

如何调试模型碰撞箱？

详情

/fmm hitbox visualize 命令使用粒子可视化模型碰撞箱。

命令：

/fmm hitbox visualize [duration]

参数：

• duration（可选） - 显示碰撞箱的刻数（默认：100，最大：1200）
• 20 刻 = 1 秒

示例：

/fmm hitbox visualize          # 显示 5 秒
/fmm hitbox visualize 200      # 显示 10 秒

工作原理：

• 搜索距你 10 格内的模型
• 使用粒子显示定向包围盒（OBB）边界
• 同时显示模型与其碰撞边界
• 适用于验证碰撞箱大小与旋转

何时使用：

• 测试碰撞箱是否与视觉模型匹配
• 调试交互问题
• 验证碰撞箱旋转
• 排查点击检测问题

要求：

• 权限：freeminecraftmodels.*

注意： FMM 中的碰撞箱会随模型旋转，这与标准 Minecraft 的 AABB 不同。

我可以创建可乘骑的自定义模型吗？

详情

可以，使用 /fmm mount 命令创建可乘骑的自定义模型（实验性功能）。

命令：

/fmm mount <modelID>

它做什么：

• 在你的位置生成一匹马
• 将马伪装为你的自定义模型
• 自动驯服该马并装上马鞍
• 立即让你骑乘该马

示例：

/fmm mount dragon

要求：

• 权限：freeminecraftmodels.*
• 有效的模型 ID

重要说明：

• 此功能被标记为实验性
• 移动速度和行为与标准马一致
• 马的碰撞箱保持不变
• 最适合用为坐骑设计的模型

使用场景：

• 角色扮演服务器的自定义坐骑
• VIP 玩家的特殊交通工具
• 冒险地图中独特的可乘骑生物

什么是挂载点骨骼？

详情

挂载点让你可以使用特殊命名的骨骼，直接在模型上定义可乘骑的位置。

如何创建挂载点：

在 Blockbench 中，将任何骨骼命名为以 m_ 为前缀的名称（例如 m_seat、m_back）。每个 m_ 骨骼都会成为模型上的一个座位位置，玩家或实体可以挂载在此处。

工作原理：

• 挂载位置跟随骨骼的位置（包括动画期间）
• 多个 m_ 骨骼可创建多个座位
• 玩家/实体可通过 API 或 Lua 脚本挂载到这些位置

测试：

使用 /fmm mount <modelID> 快速测试模型上的挂载点。

使用场景：

• 多座位载具（船、马车）
• 带有特定座位的可乘骑生物
• 肩部宠物或伴侣

自定义物品

什么是自定义物品？

详情

自定义物品是指在配套 YML 配置文件中设置了 material: 字段的模型，从而成为可手持、可装备并支持 Lua 脚本的物品。

与道具放置物品的关键区别：

• 自定义物品使用 fmm_item_id PDC（PersistentDataContainer）键
• 道具放置物品（由 /fmm itemify 创建）使用 model_id PDC 键
• 自定义物品支持 22 个物品专属的 Lua 脚本钩子（装备、攻击、食用等）
• 自定义物品可在 YML 配置中定义附魔、自定义名称和 Lore

如何创建自定义物品：

1. 在 Blockbench 中创建 .bbmodel 模型
2. 创建同基名的同级 YML 文件（如 magic_sword.bbmodel 旁边的 magic_sword.yml）
3. 将 YML 中的 material: 字段设置为任意有效的 Minecraft 材质（如 material: DIAMOND_SWORD）
4. 可选地设置 name:、lore: 和 enchantments: 字段
5. 可选地在 plugins/FreeMinecraftModels/scripts/ 中创建 Lua 脚本，并通过 scripts: 字段引用

示例 YML：

isEnabled: true
material: DIAMOND_SWORD
name: "&6Flame Blade"
lore:
  - "&7A legendary weapon"
  - "&cBurns enemies on hit"
enchantments:
  - "FIRE_ASPECT,2"
scripts:
  - flame_blade.lua

如何获取自定义物品：

• /fmm giveitem <id>（需要 freeminecraftmodels.admin 权限）
• 通过管理员菜单（/fmm admin）

菜单

FMM 提供哪些菜单？

详情

FreeMinecraftModels 提供两个游戏内菜单，用于浏览和管理内容。

玩家菜单 —— /fmm

• 权限：freeminecraftmodels.menu（默认：true，所有玩家可用）
• 只显示已定义合成配方的物品
• 点击物品可查看带有 3×3 合成格预览的详情视图
• 让玩家发现并学习如何合成自定义物品

管理员菜单 —— /fmm admin

• 权限：freeminecraftmodels.admin（默认：OP）
• 完整内容浏览器，显示：
  • 已安装的包
  • 未打包的模型文件夹
  • 根级模型
  • 自定义物品（设置了 material: 的模型）
• 允许管理员给予物品、预览模型并管理内容

Display 模型

什么是 display 模型？

详情

Display 模型让自定义物品在玩家背包和手中显示 3D 模型，而不是默认的材质外观。

如何设置 display 模型：

1. 在 Blockbench 中，使用 File > Export > Java Block/Item 导出 .json 模型文件
2. 将 .json 文件放在与 .bbmodel 同目录、同基名的位置（如 magic_sword.bbmodel 旁边的 magic_sword.json）
3. 运行 /fmm reload

工作原理：

• 在 Minecraft 1.21.4+ 上，当物品被手持或在背包中查看时会显示自定义 3D 模型
• JSON 中的裸材质引用会被自动重写为 FMM 命名空间路径
• 若不存在 .json 文件，物品会回退到纯材质外观
• 旧服务器版本会静默忽略 display 模型

要求：

• 服务器运行 Minecraft 1.21.4 或更新版本
• 在模型文件旁边放置有效的 Blockbench "Java Block/Item" 导出（.json）