FreeMinecraftModels FAQ

If you have a question that isn't listed here, take a look at the sidebar to see if it has a page dedicated to it in the wiki!

Getting Started

How do I install and use FreeMinecraftModels?

Info

Installation:

Download FreeMinecraftModels.jar and place it in your plugins folder
Restart your server to generate plugin folders
Run /fmm initialize if you want the first-time setup flow
If you use official content packs, link Nightbreak with /nightbreaklogin <token>
Use /fmm setup or /fmm downloadall for official Nightbreak-managed content
For manual content, place .bbmodel files in ~/plugins/FreeMinecraftModels/imports/ and run /fmm reload
Find the generated resource pack in ~/plugins/FreeMinecraftModels/output/FreeMinecraftModels.zip

Distributing the Resource Pack:

Choose one of these methods:

Option A (Recommended): Install Resource Pack Manager for automatic distribution
Option B: Manually configure via server.properties or a hosting service

Spawning Models:

/fmm spawn static <id> - Spawn temporary decorative model
/fmm spawn dynamic <id> - Spawn model attached to entity
/fmm spawn prop <id> - Spawn persistent world model

Management:

/fmm - Open the craftable items menu (requires freeminecraftmodels.menu)
/fmm initialize - Open the first-time setup menu
/fmm setup - Open the content-management menu
/fmm downloadall - Download all accessible official content
/fmm updatecontent - Update outdated official content
/fmm reload - Reload plugin and convert new models
/fmm version - Show plugin version
/fmm stats - Display entity count statistics

Player Features:

/fmm disguise <modelID> - Transform your appearance into a custom model
/fmm undisguise - Remove player disguise and restore normal appearance
/fmm itemify <model> <material> - Create a placeable item that spawns the specified model
/fmm craftify <modelID> - Open an interactive recipe builder to create a crafting recipe for a prop
/fmm mount <modelID> - Spawn a rideable horse disguised as a custom model (experimental)

Debugging:

/fmm hitbox visualize [duration] - Visualize model hitboxes using particles (duration in ticks, default 100)

Administrative:

/fmm deleteall - Remove all currently loaded modeled entities (use with caution - no confirmation prompt)

Permissions:

freeminecraftmodels.* - Required for most commands (disguise, itemify, mount, hitbox visualize, spawn)
freeminecraftmodels.deleteall - Required for /fmm deleteall command
freeminecraftmodels.admin (default: OP) - Required for the admin menu (/fmm admin) and /fmm giveitem
freeminecraftmodels.menu (default: true) - Allows all players to open the craftable items browser via /fmm

Commands are OP-only by default unless noted otherwise. Grant these permissions to non-OP players if needed.

Model Features & Limits

What are the model size and rotation limits?

Info

Size Limits:

Maximum: 112x112x112 pixels (7x7x7 in-game blocks)
FreeMinecraftModels uses 4x internal scaling to achieve these sizes
Standard Minecraft resource packs are limited to smaller sizes

Cube Rotation Limits:

Allowed angles: 0°, ±22.5°, ±45° and multiples of 22.5° (as of v2.3.0)
Single-axis rotation only
Example: [22.5, 0, 0] works, but [22.5, 0, 45] only partially rotates
Other angles will not display correctly

Bone Rotation:

Bones support any rotation angle
Avoid default resting positions of 90°, -90°, 180°, -180° (may cause unexpected behavior)
Multi-axis rotation supported
Each bone creates a separate entity (performance consideration)

Performance Note:

Keep bone count as low as possible. Each bone spawns a separate entity in Minecraft, which can impact server performance at scale.

What animations are supported?

Info

FreeMinecraftModels supports these default state animations:

Standard Animations:

Walk
Idle
Death
Attack
Spawn

How It Works:

Create animations in BlockBench
Plugin reads animation keyframes from .bbmodel files
Animations trigger automatically based on entity state
Developers can trigger animations programmatically using playAnimation(animationName, false, false)

Special Case:

Evoker entities detect nearby Evoker Fangs to trigger attack animations automatically.

What are virtual bones and how do they work?

Info

Virtual bones are special bones with reserved names that add functionality to your models:

Hitbox Bones:

Name: hitbox
Creates interaction zones and collision boxes
Defines entity boundaries with matching x/z values

Name Tag Bones:

Prefix: tag_
Displays text above models
Used for entity naming

Head Rotation Bones:

Prefix: h_
Rotates based on player/entity head position
Tracks head movement automatically

Usage:

Create a bone in BlockBench with one of these special names, and the plugin automatically applies the corresponding functionality.

Troubleshooting FAQ

Instead of custom models, I only see horse armor.

Info

If, instead of custom models appearing in your game, you only see horse armor, the issue is most likely that you haven't merged the FMM resource pack properly with your preexisting resource pack.

MagmaGuy has developed a plugin called Resource Pack Manager (RSPM) that can automatically merge resource packs for you. You can download it from Spigot here.

Simply drop the RSPM .jar file into your plugins folder, and RSPM will handle everything. It will merge all the resource packs, auto-host them, and distribute them to players when they log into your server.

Why can't I see my model after adding the .bbmodel file?

Info

If your model isn't appearing, check these common issues:

1. Forgot to reload

Run /fmm reload after placing .bbmodel files in the imports folder. This converts models and generates the resource pack.

2. Resource pack not applied

Players must have the FMM resource pack active to see models.

Check ~/plugins/FreeMinecraftModels/output/FreeMinecraftModels.zip for the generated pack
Install Resource Pack Manager for automatic distribution
OR manually distribute via server.properties or a hosting service

3. Wrong file location

.bbmodel files for manual imports must go in: ~/plugins/FreeMinecraftModels/imports/

If you are using official content packs instead, use /fmm setup or /fmm downloadall rather than dropping files in manually.

4. Model has errors

Check console logs for error messages during /fmm reload. Common issues include unsupported rotations, oversized models, or texture problems.

5. Resource pack merge issue

If you see horse armor instead of models, resource packs weren't merged properly. Use Resource Pack Manager (RSPM) to handle merging automatically.

ViaVersion can lead to Resource Packs not displaying properly.

Info

ViaVersion can cause issues with resource packs, particularly when running a server on a version lower than 1.21.4. Minecraft introduced changes in how resource packs are handled starting from 1.21.4. If you are running a server on a version like 1.21.3 and using ViaVersion to allow 1.21.4 clients to connect, these clients may experience issues displaying certain resource pack contents, such as custom models from FMM (FreeMinecraftModels).

This happens because the resource pack system in Minecraft changed with the 1.21.4 update.

Note: This is a Minecraft and ViaVersion limitation, not specific to FreeMinecraftModels. ViaVersion's protocol translation may not fully support resource pack changes when running on server versions below 1.21.4.

To resolve this, consider updating your server to 1.21.4 or higher, as this will ensure better compatibility with modern resource pack features, including FMM custom models.

Why are my models causing lag or performance issues?

Info

Each bone in your BlockBench model creates a separate entity in Minecraft. Models with many bones can impact server performance.

Optimization Tips:

Minimize bone count in your models
Limit the number of spawned models
Consider using Static models instead of Dynamic models when animations aren't needed
Avoid spawning many high-bone-count models near each other

Technical Explanation:

FreeMinecraftModels renders each bone as a separate Minecraft entity. A model with 50 bones spawns 50 entities. At scale, this impacts performance.

Best Practices:

Design models with fewer bones
Test performance with realistic spawn counts
Monitor server TPS when adding new models

Advanced Features

Do I need Resource Pack Manager (RSPM)?

Info

Resource Pack Manager (RSPM) is optional but highly recommended.

What RSPM Does:

Automatically merges resource packs from multiple plugins
Hosts resource packs (no external hosting needed)
Distributes packs to players automatically on login
Eliminates manual resource pack configuration

Without RSPM:

You must manually:

Merge FMM resource pack with any existing server resource packs
Host the merged pack on an external service or via server.properties
Configure server to send pack to players
Update pack every time you add new models

Why Use RSPM:

Most "horse armor instead of models" issues are caused by improper resource pack merging. RSPM handles this automatically.

Download RSPM: https://www.spigotmc.org/resources/resource-pack-manager.118574/

Developed by MagmaGuy, the same author as FreeMinecraftModels.

Can I use FreeMinecraftModels in my own plugin?

Info

Yes, FreeMinecraftModels provides an API for developers.

Maven/Gradle Integration:

Repository: https://repo.magmaguy.com/releases

Artifact:

GroupId: com.magmaguy
ArtifactId: FreeMinecraftModels
Scope: provided (must be installed on server, do not shade)

Primary API Classes:

ModeledEntity (base class)
StaticEntity
DynamicEntity
PropEntity

Example Usage:

StaticEntity staticEntity = StaticEntity.create(id, location);
if (staticEntity == null) {
    Bukkit.getLogger().warning("Failed to create model");
    return;
}
staticEntity.setRightClickCallback(...);
staticEntity.remove();

Important:

Do not shade FreeMinecraftModels into your plugin. It must be installed separately on the server.

For detailed API documentation, see the official README.

How do I disguise a player as a custom model?

Info

The /fmm disguise command transforms a player's appearance into any custom model.

Command:

/fmm disguise <modelID>

How it works:

Makes the player invisible to other players
Overlays the custom model on the player's position
The model follows the player's movements
Perfect for roleplay servers or special events

Example:

/fmm disguise dragon

To remove the disguise:

/fmm undisguise

Requirements:

Permission: freeminecraftmodels.*
modelID must be a valid converted model in your models folder

Notes:

Player hitbox remains unchanged (same collision box)
Other players see the custom model instead of your player skin
The invisibility effect is permanent until you undisguise

How do I create placeable model items?

Info

The /fmm itemify command creates special items that players can use to place models in the world.

Command:

/fmm itemify <model> <material>

Parameters:

model - Any valid model ID from your models folder
material - Any Minecraft material (STICK, PAPER, DIAMOND, etc.)

Example:

/fmm itemify lamp_post STICK

What it creates:

A custom item with a formatted gold-decorated display name (e.g. "✦ Wolf ✦")
Descriptive lore explaining the item
The item is added directly to your inventory
Right-click to place the model as a prop

Use cases:

Give players items to decorate their builds
Create custom "spawn eggs" for furniture
Distribute models without giving build permissions
Setup kits for creative building

Requirements:

Permission: freeminecraftmodels.*
Player must be in-game (not console)

How do I debug model hitboxes?

Info

The /fmm hitbox visualize command visualizes model hitboxes using particles.

Command:

/fmm hitbox visualize [duration]

Parameters:

duration (optional) - How long to show hitboxes in ticks (default: 100, max: 1200)
20 ticks = 1 second

Examples:

/fmm hitbox visualize          # Show for 5 seconds
/fmm hitbox visualize 200      # Show for 10 seconds

How it works:

Searches for models within 10 blocks of you
Displays oriented bounding box (OBB) boundaries with particles
Shows both the model and its collision boundaries
Useful for verifying hitbox size and rotation

When to use:

Testing if hitboxes match visual models
Debugging interaction issues
Verifying hitbox rotations
Troubleshooting click detection

Requirements:

Permission: freeminecraftmodels.*

Note: Hitboxes in FMM rotate with the model, unlike standard Minecraft AABBs.

Can I create rideable custom models?

Info

Yes, use the /fmm mount command to create rideable custom models (experimental feature).

Command:

/fmm mount <modelID>

What it does:

Spawns a horse at your location
Disguises the horse as your custom model
Automatically tames the horse and adds a saddle
Makes you ride the horse immediately

Example:

/fmm mount dragon

Requirements:

Permission: freeminecraftmodels.*
Valid model ID

Important notes:

This feature is marked as experimental
Movement speed and behavior match a standard horse
The horse's hitbox remains unchanged
Works best with models designed for mounts

Use cases:

Custom mounts for roleplay servers
Special transportation for VIP players
Unique rideable creatures for adventure maps

What are mount point bones?

Info

Mount points let you define rideable positions directly on your model using specially named bones.

How to create mount points:

In Blockbench, name any bone with the prefix mount_ (e.g. mount_seat, mount_back). Each mount_ bone becomes a seat position on the model where a player or entity can be mounted.

How it works:

The mount position follows the bone's location, including animations
Multiple mount_ bones create multiple seats
Players/entities can be mounted onto these positions via the API or Lua scripts

Testing:

Use /fmm mount <modelID> to quickly test mount points on a model.

Use cases:

Multi-seat vehicles (boats, carriages)
Rideable creatures with specific seat positions
Shoulder-mounted pets or companions

Custom Items

What are custom items?

Info

Custom items are models that have a material: field set in their sibling YML config file, turning them into holdable, equippable items with Lua scripting support.

Key differences from prop placement items:

Custom items use the fmm_item_id PDC (PersistentDataContainer) key
Prop placement items (from /fmm itemify) use the model_id PDC key
Custom items support 22 item-specific Lua script hooks (equip, attack, consume, etc.)
Custom items can have enchantments, custom names, and lore defined in their YML config

How to create a custom item:

Create a .bbmodel model in Blockbench
Create a sibling YML file with the same base name (e.g. magic_sword.yml next to magic_sword.bbmodel)
Set the material: field in the YML to any valid Minecraft material (e.g. material: DIAMOND_SWORD)
Optionally set name:, lore:, and enchantments: fields
Optionally create a Lua script in plugins/FreeMinecraftModels/scripts/ and reference it via the scripts: field

Example YML:

isEnabled: true
material: DIAMOND_SWORD
name: "&6Flame Blade"
lore:
  - "&7A legendary weapon"
  - "&cBurns enemies on hit"
enchantments:
  - "FIRE_ASPECT,2"
scripts:
  - flame_blade.lua

How to get a custom item:

/fmm giveitem <id> (requires freeminecraftmodels.admin permission)
Through the admin menu (/fmm admin)

Menus

What menus does FMM provide?

Info

FreeMinecraftModels provides two in-game menus for browsing and managing content.

Player Menu — /fmm

Permission: freeminecraftmodels.menu (default: true, all players can use it)
Shows only items that have crafting recipes defined
Click an item to see a detail view with a spatial 3x3 crafting grid preview
Allows players to discover and learn how to craft custom items

Admin Menu — /fmm admin

Permission: freeminecraftmodels.admin (default: OP)
Full content browser showing:
- Installed packages
- Unpackaged model folders
- Root-level models
- Custom items (models with material: set)
Allows admins to give items, preview models, and manage content

Display Models

What are display models?

Info

Display models let custom items show a 3D model in the player's inventory and hand, instead of the default material appearance.

How to set up a display model:

In Blockbench, use File > Export > Java Block/Item to export a .json model file
Place the .json file next to the .bbmodel file with the same base name (e.g. magic_sword.json next to magic_sword.bbmodel)
Run /fmm reload

How it works:

On Minecraft 1.21.4+, the item will display with the custom 3D model when held or viewed in inventory
Bare texture references in the JSON are automatically rewritten to FMM namespace paths
If no .json file exists, the item falls back to the plain material appearance
Older server versions ignore display models silently

Requirements:

Server running Minecraft 1.21.4 or newer
A valid Blockbench "Java Block/Item" export (.json) placed alongside the model file

Getting Started

How do I install and use FreeMinecraftModels?​

Model Features & Limits

What are the model size and rotation limits?​

What animations are supported?​

What are virtual bones and how do they work?​

Troubleshooting FAQ

Instead of custom models, I only see horse armor.​

Why can't I see my model after adding the .bbmodel file?​

ViaVersion can lead to Resource Packs not displaying properly.​

Why are my models causing lag or performance issues?​

Advanced Features

Do I need Resource Pack Manager (RSPM)?​

Can I use FreeMinecraftModels in my own plugin?​

How do I disguise a player as a custom model?​

How do I create placeable model items?​

How do I debug model hitboxes?​

Can I create rideable custom models?​

What are mount point bones?​

Custom Items

What are custom items?​

Menus

What menus does FMM provide?​

Display Models

What are display models?​

How do I install and use FreeMinecraftModels?

What are the model size and rotation limits?

What animations are supported?

What are virtual bones and how do they work?

Instead of custom models, I only see horse armor.

Why can't I see my model after adding the .bbmodel file?

ViaVersion can lead to Resource Packs not displaying properly.

Why are my models causing lag or performance issues?

Do I need Resource Pack Manager (RSPM)?

Can I use FreeMinecraftModels in my own plugin?

How do I disguise a player as a custom model?

How do I create placeable model items?

How do I debug model hitboxes?

Can I create rideable custom models?

What are mount point bones?

What are custom items?

What menus does FMM provide?

What are display models?