FreeMinecraftModels

FreeMinecraftModels 既是自定义模型运行时，也是面向开发者的 API。

插件提供以下功能：

• 首次设置流程，以及在设置标记为完成之前显示的登录提醒
• 基于 Nightbreak 的设置菜单，用于安装和更新官方模型包
• 在 plugins/FreeMinecraftModels/output/FreeMinecraftModels 生成资源包文件夹
• 在 plugins/FreeMinecraftModels/output/FreeMinecraftModels.zip 生成资源包 ZIP 文件
• 涵盖设置、内容更新、生成、伪装、道具和调试的命令
• 挂载点骨骼：名称以 m_ 开头的骨骼会在模型上创建座位，让玩家骑乘自定义实体
• 自定义显示模型 JSON：在 .bbmodel 旁放置对应的 .json 文件（Blockbench 显示物品导出），以替换游戏内的物品外观，需要 1.21.4 或更高版本
• 自定义物品和魔法武器：使用带命名空间的附魔的手持模型，以及作者定义的魔杖和法杖
• Blockbench 粒子：模型动画中的粒子关键帧会在自定义实体、道具和手持物品上播放，Java 版和基岩版玩家都能看到。参见粒子
• 管理员内容浏览器（/fmm admin）：按已启用的包或文件夹显示已加载模型和成功注册的自定义物品
• 玩家合成菜单（/fmm）：显示已注册的道具合成配方，包括 3x3 网格和产物；没有注册配方的条目不会显示
• 玩家伪装系统：/fmm disguise <model> [player]、/fmm undisguise [player]、/fmm disguiselist，并提供第三方插件可用的公共 DisguiseAPI
• 家具商店：可选的 Vault 商店 /fmm shop，出售用于放置道具的纸物品。通过各配方的 shopEnabled / shopPrice 配置；禁用配方注册后，有效的商店条目仍可保留
• 玩家 UI API：Lua 脚本可以向玩家显示 Boss 血条、动作栏和标题
• LocationAPI：第三方插件可注册地下城检测器和保护提供者，供 FMM 的 Lua 条件 em.location.is_in_dungeon / em.location.is_protected 及受保护区域的道具放置检查使用
• 游戏内更新记录：存在未读的 FreeMinecraftModels 版本说明时，管理员会在登录时收到提醒，并可通过 /freeminecraftmodelschangelog 查看
• 内容修复：/fmm forcereinstallcontent <package|all> 重新下载显示为最新的内容，用于恢复损坏或缺失的文件
• 免重启插件更新：/fmm applypluginupdate 或 nightbreak.applyPluginUpdatesWithoutRestart 设置可在服务器运行期间换入已下载的插件 jar。参见配置
• 电影模式：/fmm filmic on|off 或 filmicMode 会把每位玩家已加载区块中的所有已加载模型都发送给该玩家，即使不在视线内也一样，用于 ReplayMod 录制。参见配置

FreeMinecraftModels 声明 api-version: 1.21.4，因此 Minecraft 1.21.4 是最低支持的服务器版本。

从这里开始

• 安装设置

• 内容包

• 命令

• 配置

• 玩家伪装

• 家具商店

• 资源包输出

• 模型制作说明

• 动画

• API 与开发者指南

• 常见问题

• Lua：入门

• Lua：道具 API

• Lua：示例

• Lua：故障排查

Lua 脚本

FreeMinecraftModels 通过 MagmaCore 2.0 脚本引擎为道具提供 Lua 支持。脚本位于 plugins/FreeMinecraftModels/scripts/。

有效道具钩子（8 个）

道具脚本可响应以下钩子：

钩子	触发时机
on_spawn	道具生成到世界中，或随其区块重新加载
on_game_tick	道具存在期间的每个游戏刻
on_zone_enter	玩家进入脚本创建并监控的区域
on_zone_leave	玩家离开脚本创建并监控的区域
on_destroy	道具被永久移除（区块卸载或重载时不会触发）
on_left_click	玩家左键点击道具
on_right_click	玩家右键点击道具
on_projectile_hit	投射物击中道具

道具脚本收到 context.prop 表，包含 model_id、current_location 等字段以及 play_animation(name)、stop_animation() 等方法。

物品效果

装备物品的 Lua 脚本已停用。手持物品现在使用作者定义的附魔，魔杖和法杖使用魔法武器定义。不要向手持物品定义添加 scripts:。

当前说明

• 插件内置的 Nightbreak 官方托管包：Basic Furniture Pack、BetterStructures Prop Pack、EliteMobs Prop Pack、Craftenmine's Weapons Item Pack 和 Craftenmine Tools Item Pack。
• 完整初始化成功后会重新生成资源包，并安排在 40 刻后发送 FmmReloadedEvent，供依赖插件重新关联模型。如果重新加载在准备阶段被拒绝，则保留当前运行状态。
• ResourcePackManager 可以自动分发生成的资源包。请检查输出文件及客户端的实际接受情况；设置完成标记或已安装包标记不能证明资源包已送达。