FreeMinecraftModels

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

The plugin provides:

• 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
• Blockbench particles — particle keyframes in a model's animations play on custom entities, props and held items, for Java and Bedrock players. See Particles
• admin content browser (/fmm admin) — an inventory menu for loaded models and successfully registered custom items, grouped by enabled package or folder
• player craftable items menu (/fmm) — shows registered prop crafting recipes with a spatial 3x3 grid and output; entries without registered recipes are absent
• 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 paper prop-placement items, configured per recipe via shopEnabled / shopPrice; valid shop entries can remain when crafting registration is disabled
• 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
• plugin updates without a restart - /fmm applypluginupdate or the nightbreak.applyPluginUpdatesWithoutRestart setting swaps in a downloaded plugin jar while the server runs. See Configuration
• filmic mode - /fmm filmic on|off or filmicMode sends each player every loaded model in their loaded chunks, even out of sight, for ReplayMod recordings. See Configuration

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 (8)

Prop scripts can respond to the following hooks:

Hook	Trigger
on_spawn	Prop is spawned into the world, or loads again with its chunk
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 for good (not on chunk unload or reload)
on_left_click	A player left-clicks the prop
on_right_click	A player right-clicks the prop
on_projectile_hit	A projectile hits the prop

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.
• Successful full initialization rebuilds the resource-pack output and schedules FmmReloadedEvent 40 ticks later so dependent plugins can reattach models. A reload rejected during candidate preparation retains the active runtime.
• ResourcePackManager can distribute the generated pack automatically. Check the generated output and actual client acceptance; a setup-complete flag or installed-package badge does not prove delivery.