FreeMinecraftModels Configuration

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

File Location

plugins/FreeMinecraftModels/config.yml

Current Verified 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 when display entities are not available
• 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

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

sendCustomModelsToBedrockClients

• Default: false
• Controls whether FreeMinecraftModels attempts to send custom models to Bedrock clients
• If disabled, Bedrock players fall back to the underlying vanilla entity where that exists
• If you enable it, make sure your Bedrock/Geyser/Floodgate resource-pack path is actually ready for those clients

Permissions

Registered in plugin.yml

Permission	Default	Description
freeminecraftmodels.*	op	Grants access to all FreeMinecraftModels commands
freeminecraftmodels.admin	op	Grants access to admin commands such as /fmm admin and /fmm giveitem
freeminecraftmodels.menu	true	Grants access to the /fmm craftable items menu (available to all players by default)

Enforced by commands (not registered in plugin.yml)

Permission	Default	Description
freeminecraftmodels.deleteall	op	Grants 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/)
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.

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
• 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

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

Known Caveats

• The local repo has version metadata drift between plugin.yml and pom.xml, so this page intentionally documents behavior rather than pinning a hard public version string
• Bedrock behavior depends on both this config and your broader Floodgate/Geyser/resource-pack setup, so keep claims conservative unless you have tested your exact stack