FreeMinecraftModels

FreeMinecraftModels is both a custom-model runtime and a developer-facing API.

The current plugin is no longer just an "imports folder plus /fmm reload" workflow. The current codebase adds:

• a first-time setup flow and join-time reminder until setup is marked complete
• a Nightbreak-backed setup menu for official model-pack installs and updates
• a generated resource-pack folder at plugins/FreeMinecraftModels/output/FreeMinecraftModels
• a zipped pack artifact at plugins/FreeMinecraftModels/output/FreeMinecraftModels.zip
• a broader command surface for setup, content updates, spawning, disguises, props, and debugging
• mount point bones — bones whose name starts with m_ create rideable seat points on a model, letting players ride custom entities
• custom display model JSON — place a sibling .json file (Blockbench display-item export) next to a .bbmodel to override the in-game item appearance (requires 1.21.4+)
• custom scriptable items — models whose YML config sets material: become holdable custom items with full Lua scripting support and 22 item hooks
• admin content browser (/fmm admin) — an inventory menu for admins to browse installed packs, folders, models, and custom items
• player craftable items menu (/fmm) — an inventory menu showing all craftable items with their recipes; clicking an item shows the spatial 3x3 grid with arrow and output
• player disguise system — /fmm disguise <model> [player], /fmm undisguise [player], /fmm disguiselist, with a public DisguiseAPI for third-party plugins
• furniture shop — optional Vault-backed /fmm shop for selling craftable props, configured per-recipe via shopEnabled / shopPrice
• player UI API — Lua scripts can display boss bars, action bars, and titles to players
• LocationAPI — third-party plugins can register dungeon detectors and protection providers that drive FMM's Lua em.location.is_in_dungeon and em.location.is_protected predicates

Start Here

• Setup

• Content packages

• Commands

• Configuration

• Player disguises

• Furniture shop

• Resource pack output

• Model authoring notes

• API and developer guide

• FAQ

• Lua: Getting Started

• Lua: Prop & Item API

• Lua: Examples

• Lua: Troubleshooting

Lua Scripting

FreeMinecraftModels includes Lua scripting support for both props and custom items, powered by the MagmaCore 2.0 scripting engine. Scripts live in plugins/FreeMinecraftModels/scripts/.

Active Prop Hooks (7)

Prop scripts can respond to the following hooks:

Hook	Trigger
on_spawn	Prop is spawned into the world
on_game_tick	Every game tick while the prop is alive
on_zone_enter	A player enters a script-created watched zone
on_zone_leave	A player leaves a script-created watched zone
on_destroy	Prop is removed from the world
on_left_click	A player left-clicks the prop
on_right_click	A player right-clicks the prop

The script validator currently accepts on_projectile_hit for prop scripts, but the runtime does not dispatch projectile hits to prop scripts yet. Use item on_projectile_hit for scripted-item projectile behavior, or the Bukkit ModeledEntityHitByProjectileEvent API from another plugin.

Prop scripts receive a context.prop table with fields like model_id and current_location, and methods like play_animation(name) and stop_animation().

Item Hooks (22)

Custom item scripts (for models with material: set in their YML) can respond to the following hooks:

Hook	Trigger
on_equip	Item is equipped (enters an active slot)
on_unequip	Item is unequipped (leaves an active slot)
on_attack_entity	Player attacks an entity while holding the item
on_kill_entity	Player kills an entity while holding the item
on_take_damage	Player takes damage while item is equipped
on_shield_block	Player blocks damage with a shield
on_shoot_bow	Player shoots a bow
on_projectile_hit	A projectile fired by the player hits something
on_projectile_launch	Player launches a projectile
on_right_click	Player right-clicks while holding the item
on_left_click	Player left-clicks while holding the item
on_shift_right_click	Shift + right-click while holding
on_shift_left_click	Shift + left-click while holding
on_interact_entity	Player right-clicks an entity while holding
on_swap_hands	Item is swapped between hands
on_drop	Player drops the item
on_break_block	Player breaks a block while holding the item
on_consume	Item is consumed (food/potion)
on_item_damage	Item takes durability damage
on_fish	Player uses a fishing rod
on_death	Player dies while item is equipped
on_game_tick	Every server tick while the item is equipped

Item scripts receive a context.item table with fields and methods relevant to the held item and the player holding it. Lua scripts can also use the player UI API to display boss bars, action bars, and titles.

Current Notes

• Official Nightbreak-managed packs baked into the plugin: Basic Furniture Pack, BetterStructures Prop Pack, EliteMobs Prop Pack, Craftenmine's Weapons Item Pack, and Craftenmine Tools Item Pack.
• FreeMinecraftModels rebuilds its resource-pack output during startup and on /fmm reload, and dispatches a FmmReloadedEvent so dependent plugins can re-attach their model references.
• ResourcePackManager is still the recommended way to distribute the generated pack automatically to clients.