FreeMinecraftModels
FreeMinecraftModels 既是一个自定义模型运行时，也是一个面向开发者的 API。
当前插件不再仅仅是"imports 文件夹加 /fmm reload"的工作流程。当前代码库新增了：
- 首次设置流程，以及加入时的提醒，直到设置标记为完成为止
- 基于 Nightbreak 的设置菜单，用于安装和更新官方模型包
- 在
plugins/FreeMinecraftModels/output/FreeMinecraftModels生成资源包文件夹 - 在
plugins/FreeMinecraftModels/output/FreeMinecraftModels.zip生成压缩包工件 - 更广泛的命令支持，涵盖设置、内容更新、生成、伪装、道具与调试
- 挂载点骨骼 —— 名称以
m_开头的骨骼会在模型上创建可乘坐的座位点，让玩家骑乘自定义实体 - 自定义 display 模型 JSON —— 在
.bbmodel同目录下放置同名的.json文件（Blockbench display-item 导出）即可覆盖游戏内物品外观（需要 1.21.4+） - 自定义可脚本化物品 —— 在 YML 配置中设置
material:的模型将成为可手持的自定义物品，支持完整的 Lua 脚本和 22 个物品钩子 - 管理员内容浏览器（
/fmm admin）—— 供管理员浏览已安装包、文件夹、模型和自定义物品的物品栏菜单 - 玩家可制作物品菜单（
/fmm）—— 显示所有可合成物品及其配方的物品栏菜单；点击物品即可查看 3×3 合成格、箭头和产物 - 玩家伪装系统 ——
/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谓词
从这里开始
Lua 脚本
FreeMinecraftModels 同时为道具和自定义物品提供 Lua 脚本支持，由 MagmaCore 2.0 脚本引擎驱动。脚本存放在 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() 等方法。
物品钩子（22 个）
自定义物品脚本（针对在 YML 中设置了 material: 的模型）可以响应以下钩子：
| 钩子 | 触发时机 |
|---|---|
on_equip | 物品被装备（进入活动栏位） |
on_unequip | 物品被卸下（离开活动栏位） |
on_attack_entity | 玩家手持该物品攻击实体 |
on_kill_entity | 玩家手持该物品击杀实体 |
on_take_damage | 玩家在装备该物品时受到伤害 |
on_shield_block | 玩家使用盾牌格挡伤害 |
on_shoot_bow | 玩家射出弓 |
on_projectile_hit | 玩家射出的抛射物命中目标 |
on_projectile_launch | 玩家发射抛射物 |
on_right_click | 玩家手持物品时右键点击 |
on_left_click | 玩家手持物品时左键点击 |
on_shift_right_click | 手持物品时 Shift + 右键 |
on_shift_left_click | 手持物品时 Shift + 左键 |
on_interact_entity | 玩家手持物品右键点击实体 |
on_swap_hands | 物品在主副手之间切换 |
on_drop | 玩家丢弃物品 |
on_break_block | 玩家手持物品时破坏方块 |
on_consume | 物品被食用（食物/药水） |
on_item_damage | 物品受到耐久度损耗 |
on_fish | 玩家使用钓鱼竿 |
on_death | 玩家在装备该物品时死亡 |
on_game_tick | 物品被装备期间的每一服务器刻 |
物品脚本会收到一个 context.item 表，其中包含与所持物品和持有玩家相关的字段和方法。Lua 脚本还可以使用玩家 UI API 来显示 Boss 血条、动作栏和标题。
当前说明
- 当前内置在插件中的 Nightbreak 官方托管包：
Basic Furniture Pack、BetterStructures Prop Pack、EliteMobs Prop Pack、Craftenmine's Weapons Item Pack以及Craftenmine Tools Item Pack。 - FreeMinecraftModels 在启动时和执行
/fmm reload时会重建其资源包输出，并派发FmmReloadedEvent，以便依赖插件可以重新关联其模型引用。 - ResourcePackManager 仍是向客户端自动分发生成资源包的推荐方式。