FreeMinecraftModels Configuration

This page covers the current config.yml and shop_config.yml settings that materially affect setup, rendering, player interaction, and the optional furniture shop.

File Locations

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

shop_config.yml is generated on first run; the shop itself stays disabled until you opt in.

config.yml Settings

setupDone

• Default: false
• Controls whether the first-time setup guidance is considered complete
• Players with broad FreeMinecraftModels permissions are reminded to run /fmm initialize while this remains false
• The setup flow toggles this value for you; you do not need to hand-edit it during normal onboarding

useDisplayEntitiesWhenPossible

• Default: true
• Tells FreeMinecraftModels to prefer display-entity rendering when the server and client path support it
• The plugin still falls back to armor-stand displays when display entities are not available (older than 1.19.4 or Bedrock)
• Bedrock clients are a special case, so do not assume this forces the same rendering path for every player

maxModelViewDistance

• Default: 60
• Limits how far modeled entities are sent to viewers
• 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
• Runtime diagnostic logging for the Bedrock display pipeline is not a config key — it is flipped at runtime via /fmm debug bedrock on|off so it never accidentally stays on in production. See Commands

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	Price written into recipe files that do not set their own shopPrice on next load
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. Recipes with shopEnabled: false are still craftable but never listed for purchase
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 + self/others disguise 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 bedrock, /fmm setup, /fmm initialize, /fmm downloadall, /fmm updatecontent) check the wildcard freeminecraftmodels.* instead
freeminecraftmodels.disguise.self	op	Allows /fmm disguise / /fmm undisguise on the sender
freeminecraftmodels.disguise.others	op	Allows targeted disguise/undisguise plus /fmm disguiselist
freeminecraftmodels.menu	true	Access to /fmm craftable items menu
freeminecraftmodels.shop	true	Access to /fmm shop

Enforced by commands (not registered in plugin.yml)

Permission	Default	Description
freeminecraftmodels.deleteall	op	Access to /fmm deleteall (checked by the command handler at runtime)

Model YML Configuration

Each .bbmodel file can have a companion .yml file (same name, same directory) that controls model-specific settings. The unified YML format supports the following fields:

isEnabled: true
voxelize: true
solidify: true
scripts:
  - my_script.lua
material: DIAMOND_SWORD
name: "&bFrost Blade"
lore:
  - "&7A sword forged in ice"
  - "&7Deals frost damage"
enchantments:
  - SHARPNESS,3
  - UNBREAKING,2

Field	Type	Description
isEnabled	boolean	Whether the model is loaded (default: true)
scripts	list of strings	Lua script filenames to attach from plugins/FreeMinecraftModels/scripts/. Include .lua for clarity; config entries without .lua are accepted and resolved to .lua files.
voxelize	boolean	When true, the prop snaps to 90-degree rotation increments and aligns to the block grid when placed. The footprint is calculated from the model's hitbox dimensions (rounded to whole blocks). Placement checks that all blocks in the footprint are non-solid.
solidify	boolean	When true (requires voxelize: true), packet-only barrier blocks are placed in every block of the prop's footprint, giving it client-side collision. These barriers are invisible and exist only in packets — they are not placed in the world. Barriers are automatically removed when the prop is picked up or destroyed.
material	string	A Bukkit material name (e.g. DIAMOND_SWORD, PAPER). When set, the model becomes a custom item that players can hold and equip
name	string	Display name for the custom item (supports & color codes)
lore	list of strings	Lore lines for the custom item (supports & color codes)
enchantments	list of strings	Enchantments in ENCHANTMENT_NAME,LEVEL format (e.g. SHARPNESS,3)

When material is set, the model is registered as a custom item. Players can receive it via /fmm giveitem, craft it if a recipe is configured, and it gains access to all 22 Lua item hooks.

Props run every script listed under scripts: as independent instances. Custom items currently use only the first valid script in the list; additional entries after the first are ignored for item runtime binding.

Operational Notes

• /fmm reload re-imports content and regenerates the output pack, so configuration changes that affect rendering behavior are easiest to validate after a reload. A FmmReloadedEvent is dispatched on each reload so dependent plugins can re-bind their model attachments.
• 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, and Vault are declared as softdepend in plugin.yml — none of them are required to start the plugin, but they unlock specific features when present (protection-aware Lua predicates and the furniture shop).

When To Change These Values

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

• Use /fmm initialize, /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, or Bedrock behavior
• 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.
• The shop silently disables itself if Vault or an economy provider is missing. Use /fmm version and check the console on startup if /fmm shop is unexpectedly missing.