Skip to main content

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:

  1. Download FreeMinecraftModels.jar and place it in your plugins folder
  2. Restart your server to generate plugin folders
  3. Place .bbmodel files in ~/plugins/FreeMinecraftModels/imports/
  4. Run /fmm reload to convert models and generate the resource pack
  5. Find the generated resource pack in ~/plugins/FreeMinecraftModels/outputs/

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 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 mount <modelID> - Spawn a rideable horse disguised as a custom model (experimental)

Debugging:

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

Administrative:

  • /fmm deleteall - Remove ALL modeled entities from your world (use with caution - no confirmation prompt)

Permissions:

  • freeminecraftmodels.* - Required for most commands (disguise, itemify, mount, hitbox debug, spawn)
  • freeminecraftmodels.deleteall - Required for /fmm deleteall command

Commands are OP-only by default. 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)

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/outputs/ 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 must be in: ~/plugins/FreeMinecraftModels/imports/ Not in subfolders, not in other directories.

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 gold-colored name: "Model Placer: [modelName]"
  • 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 debug command visualizes model hitboxes using particles.

Command:

/fmm hitbox debug [duration]

Parameters:

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

Examples:

/fmm hitbox debug          # Show for 5 seconds
/fmm hitbox debug 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