FreeMinecraftModels Model Authoring Notes

This page documents the current authoring details that are visible in the FreeMinecraftModels codebase. It is intentionally conservative: it focuses on the import/runtime contract, not on every Blockbench workflow preference.

Source Formats

FreeMinecraftModels currently accepts:

• .bbmodel files for editable source imports
• .fmmodel files for stripped runtime-ready model data

The normal import flow is:

1. place the model in plugins/FreeMinecraftModels/imports
2. run /fmm reload
3. let FreeMinecraftModels import the model into the active model set and rebuild the generated resource pack

Folder Roles

plugins/FreeMinecraftModels/imports
plugins/FreeMinecraftModels/models
plugins/FreeMinecraftModels/models_disabled

• imports is the intake folder for manual model imports and official package downloads before processing
• models contains active installed model content
• models_disabled contains downloaded or installed package content that is currently disabled

Model IDs

• Runtime model IDs come from the file name, without the .bbmodel or .fmmodel extension
• Use stable, unique file names because the ID is what commands and API calls resolve against
• Blockbench animation references are name-based, so duplicate or unclear naming inside the model is more likely to cause trouble than a clean, explicit naming scheme

Blockbench Compatibility

• FreeMinecraftModels detects the Blockbench file version during import
• The current importer still contains compatibility branches for versions older than Blockbench v5
• If import logs say the model format is not compatible with FreeMinecraftModels, treat that as a model-format issue first, not a wiki or command issue

Runtime-Significant Bone Conventions

The current converter and skeleton pipeline recognize a few naming conventions:

• hitbox
  • reserved for hitbox generation
  • should define the model hitbox cleanly instead of being used as a visual bone
• tag_...
  • treated as nametag-related virtual bones
• h_...
  • treated as head bones
• b_...
  • non-display bones (hidden at runtime). Use these for structural or organizational bones that should not render in-game.
• m_... or mount_...
  • mount-point bones. Each bone with this prefix creates a rideable seat position on the model. Players or entities can be mounted onto these positions at runtime. Multiple mount bones create multiple seats. Managed internally by MountPointManager.

These are not just style conventions; they affect conversion and runtime behavior.

IK, Null Objects, And Locators

Current code confirms support for:

• Blockbench null objects as IK controllers
• IK chain blueprints and runtime IK solving
• locator parsing

Important practical constraint:

• IK controller lookup is name-based, so controller naming needs to stay stable between the model structure and animation data

1.21.4+ Output Split

For Minecraft 1.21.4+, FreeMinecraftModels generates item-model definition files under:

plugins/FreeMinecraftModels/output/FreeMinecraftModels/assets/freeminecraftmodels/items

Older versions still use the legacy item-model pathing. If you are checking generated output while authoring, make sure you are looking at the right output shape for your server version.

Display Model JSON (1.21.4+)

Admins can place a sibling .json file next to a .bbmodel or .fmmodel file with the same base name (for example, table.bbmodel + table.json). This JSON should be exported from Blockbench as a "Java Block/Item" model and defines how the item looks when held in-hand or shown in inventory.

During import, FMM copies the JSON into the resource pack output and automatically rewrites any bare texture references inside it to point to the model's extracted textures. If no sibling JSON exists, the item displays as plain paper in-game.

Custom Item Config in YML

The sibling .yml config file (same base name as the model) now supports optional item fields. If material: is set, the model is also available as a custom holdable item. The full YML format is:

isEnabled: true
scripts:
  - my_script.lua
material: DIAMOND_SWORD      # optional — if set, model is also a custom item
name: '&b&lMy Custom Sword'  # optional — display name
lore:                         # optional
  - '&7A custom weapon'
enchantments:                 # optional — format: ENCHANTMENT_NAME,LEVEL
  - SHARPNESS,5
  - FIRE_ASPECT,2

When material: is present, the model appears in the admin content browser alongside props and can be given to players as a functional item.

Bedrock And Render-Path Notes

• Bedrock support depends on sendCustomModelsToBedrockClients and the surrounding Floodgate/Geyser/resource-pack path
• Java clients on supported versions can use display-entity rendering when useDisplayEntitiesWhenPossible is enabled
• Do not assume a model that looks correct on a Java client is automatically safe for your Bedrock path

Practical Authoring Advice

• keep file names stable because they become runtime IDs
• keep controller and animation naming explicit because Blockbench animation lookup is name-driven
• use the reserved virtual-bone names intentionally (hitbox, tag_, h_, b_, m_, mount_)
• validate imported output after /fmm reload, not just inside Blockbench
• verify the generated pack contents for your target Minecraft line, especially on 1.21.4+

Bow And Crossbow State Models

FMM supports automatic pull-animation states for custom bow and crossbow items. No configuration is needed -- just name your model files with the correct suffixes and FMM detects the state set automatically during resource pack generation.

Naming Convention

Suffix	Purpose	Bow	Crossbow
_idle	Item in hand, not drawing or charged	required	required
_draw_start	Just started pulling	required	required
_draw_half	Halfway drawn	required	required
_draw_full	Fully drawn	required	required
_charged	Loaded crossbow (arrow or rocket)	--	required

A bow needs four models (all except _charged). A crossbow needs all five.

Example File Layout

plugins/FreeMinecraftModels/imports/
  cool_bow_idle.bbmodel
  cool_bow_draw_start.bbmodel
  cool_bow_draw_half.bbmodel
  cool_bow_draw_full.bbmodel
  cool_bow.yml                  <-- config uses the base name, not _idle

For a crossbow you would add a fifth file, cool_bow_charged.bbmodel.

How Detection Works

• Detection happens automatically when the resource pack is generated (on startup or /fmm reload).
• Only the _idle model gets an item definition JSON in the output pack. The draw and charged states are referenced as conditional entries inside that definition.
• Only the base name gets a YML config file. For the example above, the config is cool_bow.yml, not cool_bow_idle.yml.

Display Model JSON

Each state model can have its own sibling .json display model (e.g. cool_bow_idle.json, cool_bow_draw_full.json). FMM wires them into the generated item definition automatically. See Resource Pack Output for the exact JSON structure that gets generated.

Out Of Scope

This page does not try to guarantee:

• exact Blockbench UI steps
• artistic workflow preferences
• every legacy .bbmodel quirk described in older local README material

Those details change faster than the verified runtime contract above.