Skip to main content

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

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.

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

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.