FreeMinecraftModels Configuration

Model YAML settings are prepared together during content reload. After editing a prop's YAML, reload successfully before creating a new prop. Give every model YAML a unique filename across the model folders. When two files share a filename (ignoring case), even in different subfolders, FMM loads the one whose absolute path sorts first and skips the others with a Duplicate content filename warning. A skipped copy whose values all match the loaded file is skipped without a warning.

This page covers the current config.yml and shop_config.yml settings that materially affect setup, rendering, player interaction, and the optional furniture shop. Pet settings in pets.yml are covered on Pets.

File Locations

plugins/FreeMinecraftModels/config.yml
plugins/FreeMinecraftModels/shop_config.yml
plugins/FreeMinecraftModels/pets.yml

shop_config.yml is generated on first run; the shop itself stays disabled until you opt in. pets.yml is generated on first run in COSMETIC mode, where wild pets appear only in night migrations. The Lua modules pets run live in plugins/FreeMinecraftModels/pet_behaviors/; see Pet Behavior Modules.

Minimum server version

plugin.yml declares api-version: 1.21.4, so Minecraft 1.21.4 is the minimum supported server version. Support for older lines was dropped; legacy render/output branches still exist in the code but are no longer reachable on a server that can load the plugin.

config.yml Settings

setupDone

• Default: false
• Controls whether the first-time setup guidance is considered complete
• Players with freeminecraftmodels.* receive a reminder about 10 seconds after each login while this remains false, if still online
• Opening /fmm setup saves true for the server and dismisses future reminders. Choosing a completion option in /fmm initialize also saves it; this flag does not prove a pack was installed or received by clients

nightbreak.autoDownloadPluginUpdates

• Default: false
• Shared MagmaCore setting (lives under the nightbreak: section of config.yml)
• When true, FreeMinecraftModels automatically downloads available plugin jar updates and content update files on startup
• Downloaded plugin and content updates are applied after the server restarts, unless nightbreak.applyPluginUpdatesWithoutRestart applies the plugin update sooner
• Automatic plugin downloads require a valid Nightbreak account token and an active supporter Patreon membership. Without both, leave this false and use the in-game update button instead
• The automatic content pass targets updates to installed packages and defers its reload. It is not the same as bulk-installing every accessible package with /fmm downloadall. Toggle it from /fmm setup or by hand

nightbreak.applyPluginUpdatesWithoutRestart

• Default: never
• Shared MagmaCore setting (lives under the nightbreak: section of config.yml). It decides when a downloaded plugin update is applied without a restart
• never: the update waits for the next restart. You can still apply it by hand with /fmm applypluginupdate
• when-empty: the update is applied the next time no players are online. FMM checks every 30 seconds
• immediately: the update is applied as soon as it finishes downloading
• Any other value counts as never
• Applying an update disables FreeMinecraftModels and every MagmaGuy plugin that depends on it, replaces the jar, then loads and enables them again. Bosses, arenas and dungeon instances in progress end when those plugins reload
• A plugin by another author that depends on FreeMinecraftModels blocks the swap; the update then waits for a restart. If the new jar fails to enable, the previous jar is loaded again and the update stays staged for the next restart. See Commands

useDisplayEntitiesWhenPossible

• Default: true
• Tells FreeMinecraftModels to prefer display-entity rendering when the server and client path support it
• Setting it to false selects armor-stand bone rendering for Java clients. The legacy pre-1.19.4 branch does not make older servers supported
• With Bedrock models enabled and an available native custom-entity bridge, Bedrock viewers use that presentation. Otherwise the bone-rendering path uses armor stands for Bedrock. This setting does not force one backend for every player

maxModelViewDistance

• Default: 60
• Sets the normal viewer-distance limit. In sparse worlds the under-10-block proximity override bypasses both this limit and the occlusion check, so values below 10 do not impose a strict cutoff there
• Lower values reduce packet and client rendering load in dense model-heavy areas
• Individual entities can override this at runtime via ModeledEntity.setViewDistanceOverride(int) — see the API guide

maxInteractionAndAttackDistance

• Default: 3
• Applies to static and dynamic modeled entities
• Used by the runtime interaction and hit detection checks

maxInteractionAndAttackDistanceForProps

• Default: 6
• Applies to prop entities
• This is separate from the static/dynamic entity interaction distance

sendCustomModelsToBedrockClientsV2

• Default: true
• Controls whether FreeMinecraftModels attempts to send custom models to Bedrock clients
• This key replaces the older sendCustomModelsToBedrockClients (which defaulted to false). The rename to V2 flips the default so Bedrock players see models by default; if you previously set the old key explicitly you can delete it and the new V2 key takes over
• If disabled, Bedrock players fall back to the underlying vanilla entity where that exists (and disguises will not render for them)
• If you enable it, make sure your Bedrock/Geyser/Floodgate resource-pack path is actually ready for those clients
• Bedrock diagnostic logging is not a config key. Toggle it with /fmm debug bedrock on|off and turn it off explicitly after collecting evidence. /fmm reload does not reset the flag; a fresh server start does. See Commands

skipUnchangedBoneUpdates

• Default: true
• When true, bone move/metadata updates are skipped if their tracked transforms have not changed beyond the comparison tolerance. Display bones track position, rotation and scale; armor-stand bones track position and rotation
• Still bones usually skip those updates, but explicit dirty changes such as tint force a resend
• Periodic full resync still runs to correct client drift; this option does not suppress every kind of model packet
• Set to false only to restore the old "always resend every bone every tick" behavior for debugging

useDeltaMetadataPackets

• Default: true
• When true, the per-tick metadata packet for display-entity model bones sends only the values that changed (the bone's transformation) instead of re-serializing the entire item-display blob (item model + custom model data) every tick
• Full state is still sent when a player first sees a model and on the periodic resync
• Set to false to restore the old full-snapshot-every-tick behavior for debugging or comparison

displayBonesRideTheirEntity

• Default: true
• When true, the display bones of a dynamic model ride its entity as passengers on Java clients. The client places every bone from the same smoothed position it uses for the entity and its riders, so mounts, riders and moving models stay together instead of trailing behind, and the bones send no position packets
• This applies to mounts such as /fmm mount and to models whose hidden entity is tracked through modelViewersTrackHiddenBodies. Bones ride only while every Java viewer's client tracks the entity. A viewer can see a model farther away than the server tracks its entity (models show up to maxModelViewDistance, default 60 blocks, while Spigot tracks monsters to 48 blocks by default), and plugins can hide the entity from a viewer. In those cases, and while the model dies, the bones go back to per-bone teleports
• Bedrock players are not affected
• Set to false to keep every model on per-bone teleports, as before

riddenBoneInterpolationTicks

• Default: 1
• How many ticks a Java client takes to glide a riding bone to its next animation pose. 0 snaps every tick. 1 glides over one tick, which also smooths rotations
• Only bones that ride their entity use it; see displayBonesRideTheirEntity
• /fmm boneglide <ticks> changes it until FMM reloads, without editing this file. See Commands

modelViewersTrackHiddenBodies

• Default: true
• When true, each Java player who can see a dynamic model whose entity is hidden also receives that entity as an invisible body with its equipment stripped. The model's bones can then ride it, as described under displayBonesRideTheirEntity
• Other players and Bedrock players keep the entity hidden as before
• Set to false to keep hidden entities untracked and their bones on per-bone teleports

idleWalkBlendTicks

• Default: 5
• Experimental. How many ticks a model takes to cross-fade between its idle and walk animations. Both animations keep playing during the fade
• 0 switches instantly, as older versions did
• Bedrock players get the same fade time. It is written into the generated Bedrock animation controllers, so they see a change after the resource pack regenerates
• See Animation blending

deathBlendTicks

• Default: 4
• Experimental. How many ticks a model takes to fade from the pose it holds into its death animation. 0 switches instantly, as older versions did
• Bedrock players get the same fade time once the resource pack regenerates

weightedTurning

• Default: true
• Experimental. When true, a dynamic model turns toward its mob's facing with inertia: it speeds up, turns at a capped speed, then slows down onto the new facing without overshooting. Bigger models turn more slowly
• Only the model turns this way. The mob itself still turns and walks exactly as before
• A model turns instantly while a player rides its mob directly or sits on one of its m_ seats
• Set to false to make models turn instantly with their mob, as older versions did
• See Turning inertia for how size changes the limits

turnSpeedCap

• Default: 30
• Experimental. Top turning speed, in degrees per tick, of a model one block in size
• The cap is divided by the square root of the model's size and never exceeds 90 degrees per tick

turnAcceleration

• Default: 6
• Experimental. How many degrees per tick a model one block in size gains or loses in turning speed each tick
• It is divided by the model's size, so bigger models speed up and slow down more slowly
• A value of 0 or less, like a turnSpeedCap of 0 or less, makes models turn instantly

maxModelsForProximityOverride

• Default: 25
• Pseudo load balancer for the close-range visibility override
• Normally a model less than 10 blocks from a player bypasses the distance and occlusion checks used to select viewers; other visibility rules still apply
• In a dense area (for example a multi-floor NPC hub) that override turns dozens of models the player cannot actually see — on other floors, behind walls — into viewers that send packets every tick
• When a world holds at least this many loaded models, the close-range override is disabled there. Viewers must pass the configured distance and visibility checks even up close. The visibility check samples the model center and hitbox corners; a missing hitbox passes it. Sparse worlds keep the override
• The decision is per world, not global, so a crowded hub world does not penalize quiet ones
• Raise it very high to effectively restore the always-override behavior; set it to 0 to always require line of sight
• /fmm packetdebug is the intended tool for measuring the effect — see Commands

filmicMode

warning

Not recommended outside of recording. Filmic mode sends far more packets to every player and makes the server animate every loaded model. Expect lag on busy servers.

• Default: false
• For recording trailers and videos with ReplayMod or a similar recording mod
• Normally a player only receives a model while it is within maxModelViewDistance and passes the line-of-sight check. Hidden models are removed from that client and stop animating. A replay only contains what the recording client received, so those models are missing or frozen when the replay camera looks at them
• When true, every player receives every loaded model in the chunks that player has loaded, and those models keep animating, even behind walls or past maxModelViewDistance. The loaded-chunk area is the world's view distance, capped by the client's render distance, plus one chunk. Models in unloaded chunks still don't show
• To turn it on only for a recording session, use /fmm filmic on|off instead of editing this file. See Commands

particleEffectsEnabled

• Default: true
• When false, no Blockbench particle effect plays on models, props or held items. Models load and animate as usual
• The change applies after /fmm reload or a restart. Java players see it once FMM reloads. Bedrock players see it once they receive the regenerated resource pack, because their effects ship inside the pack
• See Particles

maxParticlesPerEmitter

• Default: 100
• Upper limit of live particles for one particle effect on one model. A particle file's own max_particles applies when it is lower
• Each particle a Java player sees is a packet entity, so high values cost bandwidth

maxParticlesPerViewer

• Default: 400
• Upper limit of live particles one Java player is shown across all models
• Past it, new particles for that player are skipped until older ones expire. Bedrock players draw particles on their own client and are not counted

preventPropPlacementInProtectedRegions

• Default: true
• When true, FreeMinecraftModels asks MagmaCore's registered protection providers whether this specific player may build in the cell the prop would occupy, and refuses the placement if the answer is no
• Players with the freeminecraftmodels.bypassregionprotection permission (default: op) skip this FMM protection check. Space checks and other plugins' restrictions still apply
• Built-in player-aware providers cover WorldGuard and GriefPrevention. Other plugins can register providers. A denial or provider error refuses placement; MagmaCore also refuses locations covered by a protected location owner. With neither a denying provider nor protected ownership, it adds no restriction
• The refusal message is You don't have permission to place a model here!

The provider check asks whether this player may build, so claim membership can permit placement. Protected location ownership is a separate check without a player exemption. This is a query to registered integrations, not a simulated vanilla block-placement event, so it does not reproduce every plugin's placement rules.

Every placement gets a single-cell check; voxelized props get a second, volume-wide one:

Prop type	Cells checked
Normal (free-form) prop	The single cell adjacent to the clicked block face — the cell the prop will occupy
voxelize: true prop	That same adjacent cell first, then every cell in the prop's rotated footprint (width x height x depth) around the grid-aligned placement point. If any cell in that volume is off-limits, the whole placement is refused

The volume check exists because a voxelized prop can be several blocks wide, so testing only the clicked cell would let a player straddle a claim boundary and drop a large prop into someone else's build. It runs after the free-space check, so Not enough space to place this model! still takes priority when the footprint is physically obstructed.

The checked footprint rounds each hitbox dimension with Math.round, with a minimum of one block. The packet-barrier volume uses ceil(size - 0.4) instead and can differ; the placement check does not guarantee identical coverage of every client collision cell.

note

The bypass permission is checked before the provider query. Grant freeminecraftmodels.bypassregionprotection to exempt staff from FMM's protection checks while keeping this setting enabled for other players. It does not bypass free-space checks or another plugin's event cancellation.

registerCraftingRecipes

• Default: true
• Set to false and restart for a purchase-only economy. Valid enabled recipe entries remain in the shop catalog, but their Bukkit crafting recipes are removed
• The player /fmm craftable-items menu and recipe details require an actually registered recipe, so those disabled crafting entries are absent there
• isEnabled: false in an individual recipe removes it from the loaded recipe catalog, including the shop. shopEnabled: false only hides it from purchases

shop_config.yml

The optional Vault-backed furniture shop lives in its own config so it can be enabled or tuned independently of the main plugin behavior. The shop refuses to register if Vault or an economy provider is missing.

Top-level keys

Key	Default	Description
enabled	false	Master toggle for /fmm shop. The command only registers when this is true and Vault + an economy provider are both present
defaultPrice	100.0	Default used by recipes missing shopPrice; a nonpositive default falls back to 100.0. Saved per-recipe prices do not change when this default changes
menuTitle	&8FMM - Furniture Shop	Title shown at the top of the shop inventory (supports & color codes)
priceLoreFormat	&7Price: &e{price}	Lore line appended to each shop item showing its price. Placeholder: {price}
clickToBuyLoreFormat	&aClick to purchase	Lore line appended to each shop item prompting purchase

Message keys (messages.*)

All message strings support & color codes.

Key	Default	Placeholders
messages.purchaseSuccess	&aPurchased &f{item} &afor &e{price}&a. Balance: &e{balance}&a.	{item}, {price}, {balance}
messages.insufficientFunds	&cYou need &e{price} &cto buy &f{item}&c. Balance: &e{balance}&c.	{item}, {price}, {balance}
messages.shopDisabled	&cThe furniture shop is currently unavailable.	none
messages.itemNotForSale	&cThat item is not currently for sale.	{item}
messages.inventoryFull	&eYour inventory was full; &f{item} &ehas been dropped at your feet.	{item}

Per-recipe shop fields

Each recipe file in plugins/FreeMinecraftModels/recipes/<model_id>.yml gets two additional fields:

Field	Default	Description
shopEnabled	true	Whether this recipe is visible in /fmm shop. Setting it to false does not itself disable crafting; recipe enablement and registerCraftingRecipes still apply
shopPrice	defaultPrice from shop_config.yml	Vault currency cost for this specific item

The recipe builder (/fmm craftify) writes both fields on save so price tuning is just a text edit away.

Permissions

Registered in plugin.yml

Permission	Default	Description
freeminecraftmodels.*	op	Wildcard granting admin, deleteall, self/others disguise, region-protection bypass and pet admin permissions
freeminecraftmodels.admin	op	Access to /fmm admin (the admin content browser) and /fmm giveitem. Other admin/debug commands (/fmm location, /fmm spawn, /fmm mount, /fmm itemify, /fmm craftify, /fmm reload, /fmm stats, /fmm hitbox visualize, /fmm debug, /fmm packetdebug, /fmm filmic, /fmm boneglide, /fmm setup, /fmm initialize, /fmm recommendedplugins, /fmm downloadall, /fmm downloadallcontent, /fmm updatecontent, /fmm downloadpluginupdate, /fmm applypluginupdate, /fmm forcereinstallcontent) check the wildcard freeminecraftmodels.* instead
freeminecraftmodels.deleteall	op	Child of the wildcard; access to /fmm deleteall
freeminecraftmodels.disguise.self	op	Allows /fmm disguise / /fmm undisguise on the sender
freeminecraftmodels.disguise.others	op	Allows targeted disguise/undisguise plus /fmm disguiselist
freeminecraftmodels.bypassregionprotection	op	Bypass FMM's placement and interaction protection checks, including when preventPropPlacementInProtectedRegions is on; does not override other plugins' event cancellation or space requirements
freeminecraftmodels.menu	true	Access to /fmm craftable items menu
freeminecraftmodels.shop	true	Access to /fmm shop
freeminecraftmodels.pets	true	Access to /fmm pets
freeminecraftmodels.pets.admin	op	Child of the wildcard; access to /fmm petadmin and /fmm petmigrate
nightbreak.login	op	Registered by MagmaCore, not by plugin.yml. Required by the shared /nightbreaklogin and /nightbreaklogout commands
nightbreak.plugins	op	Registered by MagmaCore, not by plugin.yml. Required by the shared /nightbreak plugins command

The pet commands are described in Pets.

Model YML Configuration

A model's companion .yml file has the same base name and directory as its .bbmodel. Props and held items use different parts of this configuration.

Props

isEnabled: true
name: "&6Oak Table"
lore:
  - "&7Seats four"
voxelize: true
solidify: true
scripts:
  - my_prop.lua

Field	Description
isEnabled	Whether the definition is enabled; defaults to true
name	Display name of the prop's placement item. Supports color codes. Without it, the item is named after the model, as in ✦ Oak Table ✦
lore	Lore of the placement item. Supports color codes. Any lore key replaces the default lore (place and pick-up hints plus the model ID), and an empty list (lore: []) removes it
scripts	Independent prop Lua scripts from plugins/FreeMinecraftModels/scripts/
voxelize	Snap placement to the block grid and 90-degree rotation increments; check the whole rotated footprint for free space
solidify	With voxelization, send packet-only barrier blocks for client collision; these are not world blocks and are removed with the prop

The placement item's name and lore apply wherever FMM creates the item: /fmm itemify, crafted recipe output, shop purchases and items taken from the admin menus. Menu entries, such as the shop's listings and its purchase messages, still show the name formed from the model ID. Items already in inventories keep their old name and lore.

Held Items

isEnabled: true
material: DIAMOND_SWORD
name: "&bFrost Blade"
lore:
  - "&7A sword forged in ice"
enchantments:
  - "minecraft:sharpness,3"
  - "minecraft:unbreaking,2"

material selects a Bukkit item material and registers a held item instead of a prop. name and lore support color codes. Enchantments use lowercase namespaced IDs and positive integer levels. When an enchantment is an item set, the item's lore shows the set's pieces on the lore line that holds $itemSet, or after the lore when no line does. Receive registered items through /fmm giveitem <id> or the admin menu. The prop recipe/shop path creates paper placement items, not these authored held items.

To dye leather armor, add an RGB hex color after the material, without #, as in EliteMobs equipment: material: LEATHER_CHESTPLATE:ff8800. The suffix only works on materials whose name starts with LEATHER_, such as leather armor pieces and leather horse armor. A suffix on any other material, or a value that is not one to six hex digits, rejects the item catalog: /fmm reload keeps the current catalog and the console names the file. Items already in inventories keep their old color.

Upgrade compatibility

Equipped-item Lua scripts are retired. A held-item definition with a nonempty scripts: list, old unnamespaced enchantments such as SHARPNESS,3, or a material unavailable on this server is skipped with a diagnostic. FMM leaves the authored file unchanged. Remove the retired item script binding and author effects through enchantment definitions; prop scripts remain supported.

For wands and staves, add a magic weapon definition. Do not put weapon behavior in a prop script or the retired item hooks.

Operational Notes

• /fmm reload first imports and validates authored items, enchantments and prop recipes while the current catalog remains active. A validation failure rejects that reload; successful validation proceeds to full reinitialization, including config.yml, shop_config.yml, pets.yml, recipes, models, pet species, pet behavior modules and pack output. Concurrent initialization/reload requests are refused
• Successful full initialization schedules FmmReloadedEvent 40 ticks later for consumers to rebind attachments. The narrower importer-triggered content reload emits it on success. It rebuilds models, items, enchantments, prop scripts and recipes, but does not reread config.yml or shop_config.yml. Failure after that content path clears live registries disables FMM. A prop recipe failure is the exception. FMM logs Prop recipe catalog rejected and keeps the previous recipes active. A rejected validation is not a completed reload
• On a world unload, FMM removes prop runtime models while retaining their persistent backing stands. When those entities load again, it deduplicates and restores the props. This is separate from permanently picking up or destroying a prop.
• Fixed ZIP timestamps and ordered model maps reduce unnecessary pack changes, but filesystem traversal order can still change ZIP bytes and SHA1 with unchanged models. Identical output is not guaranteed. See Resource Pack Output.
• FreeMinecraftModels only generates the resource pack; it does not host it by itself.
• ResourcePackManager is still the recommended delivery path for Java clients and the safest documented path for mixed setups.
• WorldGuard, WorldEdit, GriefPrevention, Vault, floodgate, and Geyser-Spigot are declared as softdepend in plugin.yml. WorldGuard and GriefPrevention provide built-in protection queries; WorldEdit is not a separate protection provider. Vault plus an economy provider enables the shop. Bedrock client detection, its rendering bridge and pack delivery must all be available for the corresponding Bedrock presentation

When To Change These Values

Use this config for runtime behavior tuning, not content-package management.

• Use /fmm setup, /fmm downloadall, and /fmm updatecontent for official package lifecycle work
• Use the imports folder for manual .bbmodel or other local content import work
• Use config.yml when you need to adjust render mode, visibility distance, interaction distance, Bedrock behavior, region-protection enforcement, or automatic update downloads
• Use skipUnchangedBoneUpdates, useDeltaMetadataPackets, and maxModelsForProximityOverride for packet/bandwidth tuning in model-dense worlds. All three default to the optimized behavior; the false / very-high settings exist for debugging and A/B comparison, not as recommended production values
• Use filmicMode (or /fmm filmic on) only while recording videos, then turn it back off
• Use idleWalkBlendTicks, deathBlendTicks, weightedTurning, turnSpeedCap and turnAcceleration to tune how models animate and turn. Set the blend times to 0 and weightedTurning to false to get the instant switching and turning of older versions
• displayBonesRideTheirEntity and modelViewersTrackHiddenBodies are on by default. Setting them to false restores the older per-bone teleports, where moving models and mounts can trail behind their entity
• Lower maxParticlesPerEmitter and maxParticlesPerViewer, or set particleEffectsEnabled: false, if particle-heavy models cost too much bandwidth
• Use shop_config.yml (and the per-recipe shopEnabled/shopPrice fields) to tune the furniture shop without touching code

Known Caveats

• Bedrock behavior depends on both sendCustomModelsToBedrockClientsV2 and your broader Floodgate/Geyser/resource-pack setup, so keep claims conservative unless you have tested your exact stack.
• If the shop is enabled but Vault or an economy provider is missing, it remains unavailable and logs a specific startup warning. /fmm version only reports the plugin version; check those warnings when /fmm shop is missing.