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 items and magic weapons - held models with namespaced enchantments, plus authored wands and staves
• 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 / em.location.is_protected predicates and the protected-region prop-placement check
• in-game changelogs — admins are nudged on join when there are unread FreeMinecraftModels release notes and can review them with /freeminecraftmodelschangelog
• content repair — /fmm forcereinstallcontent <package|all> re-downloads content that is nominally up to date, for when a pack's files are damaged or missing

FreeMinecraftModels declares api-version: 1.21.4, so Minecraft 1.21.4 is the minimum supported server version.

Start Here

• Setup

• Content packages

• Commands

• Configuration

• Player disguises

• Furniture shop

• Resource pack output

• Model authoring notes

• Animations

• API and developer guide

• FAQ

• Lua: Getting Started

• Lua: Prop API

• Lua: Examples

• Lua: Troubleshooting

Lua Scripting

FreeMinecraftModels includes Lua scripting support for props, 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 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 Effects

Equipped-item Lua scripts are retired. Held items now use authored enchantments, and wands/staves use magic weapon definitions. Do not add scripts: to a held-item definition.

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.