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. Run /fmm setup for the first-time setup / content-management menu
4. If you use official content packs, link Nightbreak with /nightbreaklogin <token>
5. Use /fmm setup or /fmm downloadall for official Nightbreak-managed content
6. For loose manual models, place lowercase .bbmodel files directly in ~/plugins/FreeMinecraftModels/imports/ and run /fmm reload. Models with companion files need the active model folder or a packaged import; see Model authoring notes
7. 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 setup - Open the content-management / first-time setup menu
• /fmm recommendedplugins - Browse companion plugins that pair well with FMM
• /fmm downloadall - Download the latest plugin update, then accessible missing or outdated content; the jar takes effect after a restart or /fmm applypluginupdate
• /fmm downloadallcontent - Download accessible missing or outdated content without the plugin jar
• /fmm updatecontent - Update outdated official content
• /fmm downloadpluginupdate - Download the latest plugin jar update only
• /fmm applypluginupdate - Apply a downloaded plugin update without restarting the server
• /fmm forcereinstallcontent <package|all> - Re-download selected content regardless of version; use its slug directly if a package is completely missing
• /fmm reload - Reload plugin and convert new models
• /fmm version - Show plugin version
• /fmm stats - Display entity count statistics
• /nightbreaklogin <token> / /nightbreaklogout - Shared MagmaCore top-level commands for storing and clearing the Nightbreak account token (permission: nightbreak.login)
• /freeminecraftmodelschangelog [dismiss|disable] - Read unread FMM release notes in-game (admins only; also offered as a clickable prompt on join)

Player Features:

• /fmm disguise <modelID> [player] - Transform your appearance (or a target player's) into a custom model
• /fmm undisguise [player] - Remove a player's disguise
• /fmm disguiselist - List all currently disguised players
• /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 shop - Open the optional Vault-backed furniture shop (only when enabled in shop_config.yml)
• /fmm mount <modelID> - Spawn a rideable horse disguised as a custom model (experimental)

Debugging:

• /fmm hitbox visualize [duration] - Visualize nearby model hitboxes using particles for a number of ticks (default 100, nonpositive values use 100, maximum 1200)
• /fmm location - Report registered protection / dungeon providers and test them at your current location
• /fmm debug bedrock [on|off] - Set the verbose [FMM-BedrockDebug] log stream, or report its state when no state is given. It survives /fmm reload and starts off on a fresh server start
• /fmm debug props [on|off] - Enable stacked-prop diagnostics during startup, entity-load and pre-spawn checks, or report their state. It survives /fmm reload; a fresh server start resets it
• /fmm packetdebug [ticks] - Sample modeled-entity packet load for the given number of model-clock ticks (default 1, range 1–200; invalid input falls back to 1) and report packets/tick, per-viewer fan-out, the heaviest viewers and a packet-type breakdown
• /fmm filmic [on|off] - Temporarily send every loaded model to every player who has its chunk loaded, for ReplayMod recordings. Not recommended outside of recording. See filmic mode

Administrative:

• /fmm deleteall [radius] - Remove all loaded modeled entities and props (use with caution - no confirmation prompt). An optional player-only [radius] limits removal to that many blocks

Permissions:

• freeminecraftmodels.* (default: OP) - Wildcard that grants freeminecraftmodels.admin, freeminecraftmodels.deleteall, freeminecraftmodels.disguise.self, freeminecraftmodels.disguise.others, and freeminecraftmodels.bypassregionprotection. Also the literal permission required by /fmm reload, /fmm stats, /fmm spawn, /fmm itemify, /fmm craftify, /fmm mount, /fmm hitbox visualize, /fmm debug, /fmm packetdebug, /fmm filmic, /fmm location, /fmm setup, /fmm initialize, /fmm recommendedplugins, /fmm downloadall, /fmm downloadallcontent, /fmm updatecontent, /fmm downloadpluginupdate, /fmm applypluginupdate, and /fmm forcereinstallcontent
• freeminecraftmodels.admin (default: OP) - /fmm admin (the admin content browser) and /fmm giveitem
• freeminecraftmodels.disguise.self (default: OP) - Lets a player disguise/undisguise only themselves
• Targeted disguise and undisguise commands require both freeminecraftmodels.disguise.self and freeminecraftmodels.disguise.others. disguiselist requires only .others.
• freeminecraftmodels.deleteall (default: OP) - Required for /fmm deleteall (child of the wildcard)
• freeminecraftmodels.bypassregionprotection (default: OP) - Bypass FMM's region-protection check. It does not override every other plugin's event handling or the physical free-space check
• freeminecraftmodels.menu (default: true) - Lets all players open the craftable items browser via /fmm
• freeminecraftmodels.shop (default: true) - Lets all players open /fmm shop (still gated on the shop being enabled)
• nightbreak.login (default: OP) - Registered by MagmaCore, not plugin.yml. Required by /nightbreaklogin and /nightbreaklogout

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:

• Size is checked per bone across its cubes, rather than across the entire model
• The converter multiplies cube coordinates by 0.4 and recenters each bone. Its warning threshold is 192 in those scaled coordinates; this is not a verified 192-model-pixel or 12-block rendering limit
• The warning does not reject or resize the bone. If geometry fails, shrink the cubes, move them closer, or split them across bones and inspect the generated model on the target client
• Whole models can span multiple bones; absence of a size warning does not prove the generated resource-pack geometry is valid

Cube Rotation Limits:

• Minecraft 1.21.6 and newer: the converter accepts arbitrary remainders within ±45° after decomposing an angle into a base transform (0°, ±90°, ±180°, baked into the geometry). Keep authored angles in the usual −180° to 180° range and inspect the result; accepted decomposition is not a rendering check
• Minecraft 1.21.4 / 1.21.5: the remainder has to land on a value Minecraft accepts natively (−45°, −22.5°, 0°, 22.5°, 45°), so allowed angles are 0°, ±22.5°, ±45°, ±67.5°, ±90°, ±112.5°, ±135°, ±157.5°, ±180° — every multiple of 22.5°
• Single-axis cube rotation only, on all versions. The loop scans Z to X and overwrites its choice, so the first nonzero axis in X/Y/Z order wins
• Example: [22.5, 0, 45] keeps the X rotation and loses the Z rotation
• An angle FMM cannot decompose is logged as Could not decompose rotation angle ... for model name <model> and applied raw, which usually looks wrong

Bone Rotation:

• Bones support any rotation angle
• Multi-axis rotation supported
• Visible bones add per-viewer rendering and packet work; structural and metadata bones are not all displayed

Performance Note:

Keep visible bone count and viewer count low where practical. Java renders visible bones through packet entities, while the Bedrock model backend has a different representation. Bone count is not a count of ordinary Bukkit entities.

What animations are supported?

Info

FreeMinecraftModels binds five animation names to automatic runtime states:

State Animations:

• spawn — plays once when the model is created, then falls through to idle
• idle — loops until the backing entity has nonzero X or Z velocity
• walk — loops during horizontal movement; returns to idle when grounded with zero X and Z velocity
• attack — plays once, then returns to idle
• death — plays once on removal via removeWithDeathAnimation()

Any other animation name in the model is a custom animation: it never fires on its own, but it can be played by name from the API or from Lua.

About jump

JUMP exists in the AnimationStateType enum and the walk state does request it when the entity leaves the ground, but no jump state is registered in the animation manager, so that automatic transition currently does nothing. An animation literally named jump still works when you trigger it yourself — it just runs through the custom-animation path like any other name.

How It Works:

• Create animations in BlockBench using the lowercase names above so FMM auto-binds them to the matching state
• Plugin reads animation keyframes from .bbmodel files at import time and bakes them into per-tick frames
• State animations trigger automatically based on entity state
• Developers can trigger any animation programmatically using playAnimation(animationName, blend, loop) on a ModeledEntity, or context.prop:play_animation(name, blend, loop) from Lua

Player disguises are different:

A model used with /fmm disguise selects five names — attack, jump, sneak, walk, idle — in that priority order before the shared playback engine runs. sneak and jump have automatic disguise triggers; regular models can still play them explicitly as custom animations. One-shots pause all new selections for 20 ticks. A disguise model without idle logs a warning and can remain on the last frame when no other action is active. See Player Disguises.

See Animations for loop modes, interpolation types, keyframe timing, and IK.

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 (exact name, case-insensitive)
• Creates interaction zones and collision boxes
• Its cube defines width, depth and height; X and Z need not match. It does not change the player's hitbox for a disguise
• Must be a top-level bone in the outliner — a hitbox bone nested inside another group is treated as an ordinary bone
• Should contain exactly one cube. Extra cubes log has more than one value defining a hitbox! Only the first cube will be used; an empty group logs has a hitbox bone but no hitbox cube! and leaves zero dimensions. Cube position and rotation do not offset the hitbox
• Never animated, never rendered, and excluded from the Bedrock geometry export

Name Tag Bones:

• Prefix: tag_
• Displays text above models
• Used for entity naming
• Optional authored anchor. Without one, the nameplate uses a fallback above the hitbox. See Why does my model have no name?
• The bone needs no cubes; it is just a positional anchor for the text display, usually placed above the head

Head Rotation Bones:

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

Hidden / Structural Bones:

• Prefix: b_
• Hidden by Java's bone renderer; the Bedrock geometry exporter does not filter b_ bones
• Use these for structural, organizational or metadata-only bones that should still take part in the skeleton hierarchy without producing geometry

Mount Point Bones:

• Prefix: m_
• Each m_ bone becomes a rideable seat position on the model, managed by MountPointManager
• The seat follows the bone through animations
• Multiple m_ bones create multiple seats
• Excluded from the Bedrock geometry export
• See What are mount point bones? below

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

Horse armor in place of a model means the expected custom appearance is not being applied. Check that FMM generated the model, that the current pack includes it, and that the client downloaded and accepted that pack. A merge conflict is one possible cause, not the only one.

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.

RSPM can merge, host and distribute the generated pack. Follow its setup guide, verify the enabled pack sources and reachable hosting address, then reconnect a client and confirm the model appears.

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. Check the console: rejected candidate validation preserves the current runtime, so the command alone does not prove the new content was applied.

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

Loose .bbmodel imports go directly in ~/plugins/FreeMinecraftModels/imports/. That route retains the source and can reconvert it on later reloads. It does not import loose companion YAML or recurse into arbitrary folders. Models with companions can instead live in models/, or arrive in a correctly packaged import.

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 the client has a pack but still shows the base material, check the generated definition and texture paths, the merged output, and the client's pack version. Resource Pack Manager can manage merging and delivery, but its installation alone does not prove either succeeded.

6. Model ID collision

Look for [FMM Models] Rejected normalized model ID collision in the console. Two or more of your model files normalize to the same ID and differ in content, so all of them were rejected. See Why was my model rejected for an ID collision? below.

Why was my model rejected for an ID collision?

Info

FreeMinecraftModels normalizes every model file name before using it as a runtime model ID and resource-pack filename: it lowercases the name, then replaces every character outside a-z, 0-9, ., _, and - with an underscore.

That means these all collapse to the same ID, my_table:

My Table.bbmodel
my table.bbmodel
my_table.bbmodel
MY_TABLE.bbmodel

Before conversion starts, FMM sweeps the models tree for these collisions. If all the colliding files are byte-for-byte identical, for example the same model shipped by two content packages, FMM loads one copy and skips the rest without a warning. Otherwise every colliding file is rejected, not just the extras, so you never end up with an unpredictable "whichever loaded last wins" result. The console prints:

[FMM Models] Rejected normalized model ID collision '<id>'. These files normalize to the same ID: <paths>. Rename the files so every normalized model ID is unique; no colliding model was loaded.

The fix: rename the files so their normalized IDs differ, then run /fmm reload. The warning lists the exact absolute paths involved.

Avoiding it: use unique lowercase filenames with underscores (stone_table.bbmodel) across the model tree. Different folders do not make repeated base names unique, and another filename can still normalize to the same ID.

Rejected models are skipped everywhere — no Java pack output, and no Bedrock custom-entity bundle either.

Why does my model have no name?

The current runtime no longer requires a tag_ bone to display names. It uses the alphabetically first tag bone when present, otherwise a position above the model's hitbox.

Check that the owning plugin sets a nonempty display name and has not hidden the nameplate. For a misplaced name, inspect the hitbox or add a cube-free tag_name anchor in Blockbench. Multiple tag bones do not create repeated names. See nameplate authoring.

ViaVersion can lead to Resource Packs not displaying properly.

Info

Current FreeMinecraftModels requires a server on Minecraft 1.21.4 or newer. Allowing newer clients through a protocol translator does not make an older server a supported FMM installation.

When diagnosing a pack problem, first reproduce it with a client matching the supported server version. Confirm that the client downloaded the current pack and can render its item-model format, then compare the translated-client path. Record the server, client, and protocol-plugin versions instead of assuming every missing model is caused by ViaVersion.

Why are my models causing lag or performance issues?

Info

Models with many visible bones can add transformation, packet and client-rendering work. Viewer count also matters.

Optimization Tips:

• Minimize bone count in your models
• Limit the number of spawned models
• Use static models when no living backing entity is needed; static models can still animate
• Avoid spawning many high-bone-count models near each other

Technical Explanation:

Java rendering uses per-bone packet entities, excluding hidden and metadata-only display paths. The Bedrock backend can render a whole model through its custom-entity representation. A 50-bone model does not necessarily create 50 ordinary server entities or send 50 visible entities to every client.

Best Practices:

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

Measuring It:

Run /fmm packetdebug 20 in the affected area. It reports packet counts and per-viewer fan-out for the next 20 model-clock ticks, including the heaviest viewers and packet types. These counts help investigate traffic; they are not a CPU profile or proof that clients rendered the packets.

Built-in Packet Optimizations:

Three config.yml keys control the packet-side optimizations. All default to the optimized behavior — the alternate settings exist for debugging, not as tuning advice:

• skipUnchangedBoneUpdates (default true) — skips unchanged transform updates unless a bone was explicitly marked dirty, such as for a tint change. It does not eliminate all model processing or watcher traffic
• useDeltaMetadataPackets (default true) — the per-tick metadata packet carries only the changed transformation instead of re-serializing the whole item-display blob
• maxModelsForProximityOverride (default 25) — models within 10 blocks are normally always shown, skipping the line-of-sight raytrace to avoid pop-in. Once a world holds this many loaded models, that override switches off in that world so occlusion culling runs even up close. This is the key to look at for multi-floor NPC hubs where players were being made viewers of models on other floors

See Configuration for the full descriptions.

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
• Reduces manual pack-management work; source selection, hosting and client acceptance still need verification

Without RSPM:

You must manually:

• Merge FMM resource pack with any existing server resource packs
• Host the merged pack at a reachable download URL
• Configure server.properties or another pack sender to send that URL to players; server.properties itself is not a file host
• Update pack every time you add new models

Why Use RSPM:

RSPM provides one workflow for merging, hosting and sending packs. Check its output and a real client when investigating missing models.

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.

Commands:

/fmm disguise <modelID> [player]
/fmm undisguise [player]
/fmm disguiselist

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

Examples:

/fmm disguise dragon              # Disguise yourself
/fmm disguise dragon Steve         # Disguise another player
/fmm undisguise Steve              # Undisguise Steve
/fmm disguiselist                  # List everyone currently disguised

Requirements:

• Self-targeting: freeminecraftmodels.disguise.self (default: OP)
• Targeted disguise and undisguise commands require both freeminecraftmodels.disguise.self and freeminecraftmodels.disguise.others. disguiselist requires only .others.
• Console can run the targeted form as long as a player name is supplied
• modelID must exactly match a loaded model
• Third-party plugins can drive disguises via the public DisguiseAPI

Notes:

• Player hitbox remains unchanged (same collision box)
• Other players see the custom model instead of your player skin
• Disguising again while already disguised cleanly replaces the previous disguise
• FMM restores invisibility after relevant effect changes only when this disguise originally added the effect. A preexisting effect is not restored. See Player Disguises

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; leave room because overflow is not dropped
• Right-click from the main hand to place the prop, subject to FMM's placement checks. The item is consumed after a successful spawn outside creative mode

Use cases:

• Give players items to decorate their builds
• Create custom "spawn eggs" for furniture
• Distribute placement items while retaining the configured protection checks
• 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 is optional and defaults to 100 ticks. Nonpositive values use 100 ticks; the maximum is 1200
• 20 ticks = 1 second

Examples:

/fmm hitbox visualize 100      # 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

Projectile detection tests the segment between tracked positions to catch crossings of thin OBBs, with an overlap fallback when no previous position is available. Hits are ordered nearest-first. A normal projectile has one modeled-target hit; a Piercing arrow has pierce level + 1 distinct modeled-target hits. Cancelling the modeled hit prevents its callback/default damage but still spends the target budget. See the projectile API.

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
• Attempts to mount you one tick later: directly on the horse without mount points, or through a marker armor stand when the model has a mount point

Example:

/fmm mount dragon

Requirements:

• Permission: freeminecraftmodels.*
• Valid model ID

Important notes:

• This feature is marked as experimental
• Uses a tamed adult horse with movement-speed base 0.3 and jump-strength base 0.7
• 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 a bone with the case-sensitive prefix m_ (e.g. m_seat, m_back). Each creates a seat position managed for a player.

How it works:

• The mount position follows the bone's location, including animations
• Multiple m_ bones create multiple seats
• The seat manager accepts players through the API or Lua scripts, selecting the first free seat. Seats use temporary, zero-size Interaction entities and update while occupied

Testing:

For a prop seat, spawn or place the prop and right-click it, or call the Lua context.prop:mount(player) method. /fmm mount <modelID> creates an experimental horse-backed mount and is a different mounting path.

Use cases:

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

Custom Items

What are custom items?

Custom items are held items defined by a material: field in the model's sibling YAML. They carry fmm_item_id identity; prop placement items created by /fmm itemify instead carry model_id.

Create a model and same-named YAML, set material, and optionally add name, lore, and namespaced enchantments:

isEnabled: true
material: DIAMOND_SWORD
name: "&6Flame Blade"
enchantments:
  - "minecraft:fire_aspect,2"

Use /fmm giveitem <id> or /fmm admin with freeminecraftmodels.admin.

Do custom items still run Lua scripts?

No. The former equipped-item runtime and its 22 hooks are retired. A held-item definition with a nonempty scripts: list is skipped, as is an old unnamespaced enchantment entry such as FIRE_ASPECT,2. The file is not converted or rewritten. Prop Lua scripts are unchanged.

Use provider-owned enchantments for item effects and magic weapon definitions for wands and staves.

Menus

What menus does FMM provide?

Info

FreeMinecraftModels provides these two browsing menus, plus the separate setup, recipe-builder and optional shop menus.

Player Menu — /fmm

• Permission: freeminecraftmodels.menu (default: true, all players can use it)
• Shows only entries with successfully registered crafting recipes; registerCraftingRecipes: false removes them from this browser
• Click an item to see a detail view with a spatial 3x3 crafting grid preview
• Lets players inspect recipes for paper prop-placement items; this is separate from authored held items

Admin Menu — /fmm admin

• Permission: freeminecraftmodels.admin (default: OP)
• Full content browser showing:
  • Enabled packages with loaded content
  • Unpackaged model folders
  • Root-level models
  • Successfully registered custom items
• Package and folder entries open lists; individual entries give items. Use /fmm setup for package activation and downloads

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:

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

How it works:

• A registered display model can replace the held/inventory appearance once the client accepts the generated pack
• Bare texture references use the matching numeric texture-map key, falling back to an available extracted texture when the key is missing. The fallback is not guaranteed to be index zero; namespaced references are preserved
• If no .json file exists, the item falls back to the plain material appearance
• The current plugin requires Minecraft 1.21.4 or newer; legacy rendering branches do not make older servers supported

Requirements:

• Server running Minecraft 1.21.4 or newer
• A valid Blockbench "Java Block/Item" export (.json) placed alongside the model file; malformed JSON is not registered. Bow/crossbow state groups require all corresponding state models and display JSON files