FreeMinecraftModels 常见问题
如果您的问题未在此列出，请查看侧边栏，看看 wiki 中是否有专门的页面！
入门指南
如何安装和使用 FreeMinecraftModels？
详情
安装步骤：
- 下载 FreeMinecraftModels.jar 并将其放入您的 plugins 文件夹
- 重启服务器以生成插件文件夹
- 如果需要首次设置流程，运行
/fmm initialize - 如果使用官方内容包，请使用
/nightbreaklogin <token>链接 Nightbreak - 使用
/fmm setup或/fmm downloadall获取 Nightbreak 托管的官方内容 - 对于手动内容，将
.bbmodel文件放入~/plugins/FreeMinecraftModels/imports/并运行/fmm reload - 在
~/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- 显示设置/帮助摘要/fmm initialize- 打开首次设置菜单/fmm setup- 打开内容管理菜单/fmm downloadall- 下载所有可访问的官方内容/fmm updatecontent- 更新过期的官方内容/fmm reload- 重新加载插件并转换新模型/fmm version- 显示插件版本/fmm stats- 显示实体数量统计
玩家功能：
/fmm disguise <modelID>- 将您的外观变为自定义模型/fmm undisguise- 移除玩家伪装并恢复正常外观/fmm itemify <model> <material>- 创建一个可放置的物品，用于生成指定模型/fmm craftify <modelID>- 打开交互式配方构建器，为道具创建合成配方/fmm mount <modelID>- 生成一匹伪装为自定义模型的可骑乘马（实验性功能）
调试：
/fmm hitbox visualize [duration]- 使用粒子可视化模型碰撞箱（持续时间以刻为单位，默认 100）
管理操作：
/fmm deleteall- 移除所有当前加载的模型实体（谨慎使用——无确认提示）
权限：
freeminecraftmodels.*- 大多数命令需要此权限（disguise、itemify、mount、hitbox visualize、spawn）freeminecraftmodels.deleteall-/fmm deleteall命令需要此权限
命令默认仅 OP 可用。如需要，请将这些权限授予非 OP 玩家。
模型功能和限制
模型的尺寸和旋转限制是什么？
详情
尺寸限制：
- 最大：112x112x112 像素（游戏内 7x7x7 方块）
- FreeMinecraftModels 使用 4 倍内部缩放来实现这些尺寸
- 标准 Minecraft 资源包限制为更小的尺寸
方块旋转限制：
- 允许的角度：0°、±22.5°、±45° 以及 22.5° 的倍数（从 v2.3.0 起）
- 仅支持单轴旋转
- 示例：[22.5, 0, 0] 可以工作，但 [22.5, 0, 45] 只会部分旋转
- 其他角度将无法正确显示
骨骼旋转：
- 骨骼支持任意旋转角度
- 避免 90°、-90°、180°、-180° 的默认静止位置（可能导致意外行为）
- 支持多轴旋转
- 每个骨骼创建一个单独的实体（需考虑性能）
性能说明：
保持骨骼数量尽可能低。每个骨骼在 Minecraft 中生成一个单独的实体，大规模使用时可能影响服务器性能。
支持哪些动画？
详情
FreeMinecraftModels 支持以下默认状态动画：
标准动画：
- Walk（行走）
- Idle（待机）
- Death（死亡）
- Attack（攻击）
- Spawn（生成）
工作原理：
- 在 BlockBench 中创建动画
- 插件从 .bbmodel 文件中读取动画关键帧
- 动画根据实体状态自动触发
- 开发者可以使用
playAnimation(animationName, false, false)以编程方式触发动画
特殊情况：
唤魔者实体会检测附近的唤魔者尖牙以自动触发攻击动画。
什么是虚拟骨骼？它们如何工作？
详情
虚拟骨骼是具有保留名称的特殊骨骼，可为您的模型添加功能：
碰撞箱骨骼：
- 名称：
hitbox - 创建交互区域和碰撞箱
- 使用匹配的 x/z 值定义实体边界
名称标签骨骼：
- 前缀：
tag_ - 在模型上方显示文本
- 用于实体命名
头部旋转骨骼：
- 前缀：
h_ - 根据玩家/实体头部位置旋转
- 自动跟踪头部移动
使用方法：
在 BlockBench 中创建具有这些特殊名称之一的骨骼，插件会自动应用相应的功能。
故障排除
我看到的不是自定义模型，而是马铠。
详情
如果您在游戏中没有看到自定义模型，而是看到马铠，问题很可能是您没有将 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（FreeMinecraftModels）的自定义模型。
这是因为 Minecraft 的资源包系统在 1.21.4 更新中发生了变化。
注意： 这是 Minecraft 和 ViaVersion 的限制，并非 FreeMinecraftModels 特有的问题。当服务器版本低于 1.21.4 时，ViaVersion 的协议转换可能无法完全支持资源包变更。
要解决此问题，请考虑将服务器更新到 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
构件：
- GroupId：
com.magmaguy - ArtifactId：
FreeMinecraftModels - Scope：
provided（必须安装在服务器上，不要 shade）
主要 API 类：
ModeledEntity（基类）StaticEntityDynamicEntityPropEntity
使用示例：
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>
工作原理：
- 使玩家对其他玩家不可见
- 在玩家位置覆盖自定义模型
- 模型跟随玩家的移动
- 非常适合角色扮演服务器或特殊活动
示例：
/fmm disguise dragon
移除伪装：
/fmm undisguise
要求：
- 权限：
freeminecraftmodels.* - modelID 必须是模型文件夹中有效的已转换模型
注意事项：
- 玩家碰撞箱保持不变（相同的碰撞区域）
- 其他玩家看到的是自定义模型而不是您的玩家皮肤
- 隐身效果持续到取消伪装为止
如何创建可放置的模型物品？
详情
/fmm itemify 命令创建特殊物品，玩家可以使用它们在世界中放置模型。
命令：
/fmm itemify <model> <material>
参数：
model- 模型文件夹中任何有效的模型 IDmaterial- 任何 Minecraft 材料（STICK、PAPER、DIAMOND 等）
示例：
/fmm itemify lamp_post STICK
创建的内容：
- 一个带有金色装饰显示名称的自定义物品（例如 "✦ Wolf ✦"）
- 描述性的说明文字
- 物品直接添加到您的背包中
- 右键点击可将模型放置为道具
使用场景：
- 给玩家物品来装饰他们的建筑
- 创建自定义的家具"生成蛋"
- 无需给予建筑权限即可分发模型
- 创造性建设的套件
要求：
- 权限：
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 玩家的特殊交通工具
- 冒险地图的独特可骑乘生物