Skip to main content

Custom Models

EliteMobs supports Custom Models through Model Engine and FreeMineCraftModels.

Foreword

From an EliteMobs perspective, the Custom Model system is very simple, as the only thing admins have to do is add a line to an NPC or Custom Boss config file telling it which Custom Model to use. However, it is necessary to take the correct steps with Model Engine and Minecraft in order to get this system fully functional, and these aren't quite as easy to get into.

This guide will go into detail insofar as interfacing with Model Engine and Minecraft goes. It will not tell you how to use Blockbench to create custom bosses, nor will it go into detail about how Model Engine works. There are already plenty of guides on how to do that elsewhere, and if you want to learn more about those systems you are better served by looking directly at their documentation.

FreeMineCraft Models​

If you want to learn how you can use FMM to get your models working then you can check out this wiki page to learn more.

Model nameplates

Current FreeMinecraftModels uses an authored tag_ bone, such as tag_head, when available and falls back to a position above the model hitbox when no anchor exists. An anchor lets the model author choose the position; it is no longer required to display a name. FMM owns the complete nameplate, including the name and role lines on EliteMobs NPCs. Older FMM builds may still require an anchor.

Bedrock (Geyser) Support​

Whether Bedrock players (connecting through Geyser/Floodgate) can see custom models depends entirely on your model plugin (ModelEngine or FreeMinecraftModels) and your resource pack setup, not on EliteMobs. EliteMobs does detect Bedrock clients, but it uses that information for things like menu rendering and nametag positioning — it does not generate or serve a separate Bedrock-compatible model. Refer to your model plugin's documentation for Bedrock/Geyser model support.

LibsDisguises Integration​

EliteMobs also supports LibsDisguises as an alternative to custom models. An available configured model takes precedence over a disguise; when no usable model is selected, a configured disguise can be used. This integration synchronizes name visibility.

To use LibsDisguises instead of custom models, configure your boss/NPC disguise settings without specifying a customModel field.

Item Models and Magic Weapons (FMM)

Use fmmItemModel for FMM item presentation, with weaponType: WANDS or weaponType: STAVES for an authored magic weapon. EliteMobs keeps its name, lore, enchantments and level. FMM supplies the model and, for magic weapons, the attack definition.

The older scriptedItem bridge remains for authored-item identity and display. It no longer executes equipped-item Lua scripts, and FMM rejects item definitions containing a nonempty scripts list. Do not combine it with an authored magic weapon.

# Example EliteMobs custom item config
material: IRON_SWORD
name: "&cFlame Blade"
enchantments:
- "FIRE_ASPECT,2"
scalability: scalable
fmmItemModel: flame_blade

The referenced FMM item or model must exist. A missing presentation model can leave the vanilla material visible with a warning; an explicit weaponType that does not match an available authored weapon rejects item construction. See FMM magic weapons and custom item configuration.

Minimum requirements

EliteMobs, a compatible FreeMinecraftModels build or ModelEngine integration*, Blockbench**, and a Minecraft resource pack. The ModelEngine integration targets the R3 API: EliteMobs selects it only when ModelEngine is enabled and its version contains R3. A newer major version is not automatically compatible.

* This plugin may have further dependencies. Check the documentation on their end.
** Necessary for creating and editing Custom Models. Not necessary if you are just looking to install content without modifying it.

Plugin Priority

If both ModelEngine and FreeMinecraftModels are installed, EliteMobs will use FreeMinecraftModels by default. Only one custom model plugin will be active at a time.

Manually setting a Custom Model

Note: This guide assumes you already have a valid Custom Model. These come in Blockbench file formats (.bbmodel).

EliteMobs is able to use Custom Models for NPCs and Custom Bosses. The process to do this is the same for both, and is as follows:

Step 1. Setting the EliteMobs config​

Go to the configuration file of the Custom Boss or NPC you want to modify and add the following line:

customModel: modelname

Replace modelname with the name of your model. The name is the name of the Custom Model file you are using. As an example, the Test Boss' Custom Model file is showcase_boss.bbmodel. As such, the configuration option should be

customModel: showcase_boss

And that's it for EliteMobs! Now it gets a bit trickier.

Step 2. Generating the Model Engine data​

The following paths come from the archived ModelEngine import guide. Use instructions matching your installed ModelEngine build.

  1. Put your Custom Model Blockbench file (.bbmodel) into the directory (yourServer)/plugins/ModelEngine/blueprints .
  2. Run the model reload command for your ModelEngine version; the archived guide uses /meg reload models. Confirm that the model appears in ModelEngine's loaded registry and check its console errors.

Step 3. Distributing the Resource Pack​

This is possibly the trickiest part if you are looking to make your server manage the downloads. Try checking if the system works when you have the resource pack on your client before looking into distributing it automatically!

  1. Go to the directory (yourServer)/plugins/ModelEngine/resource pack and create a resource pack using that data or add the assets folder in there to your resource pack's assets
    1. For a new pack, place assets and a valid pack.mcmeta at the ZIP root. Use metadata compatible with your client version; do not copy the old format numbers from archived examples. More info.
    2. If you already have a resource pack, make sure you aren't accidentally overwriting existing models. More info.
  2. Distribute your resource pack to your players. Only players that have the resource pack will be able to see the Custom Models, and it will look very weird and broken to everyone else. If you intend to make heavy use of these, you may want to force the resource pack use.
    1. (Optional) To allow players to download a resource pack on login, you will need to host the file somewhere online and change the server.properties resource-pack= field to point to that address.*
    2. For automatic downloads, set resource-pack-sha1= to the SHA-1 of the final ZIP. Calculate it locally in PowerShell with (Get-FileHash -LiteralPath "pack.zip" -Algorithm SHA1).Hash.ToLowerInvariant() or on Linux with sha1sum pack.zip. Copy only the 40-character hash and update it whenever the ZIP changes.
    3. (Optional) To force players to use resource packs, use the option require-resource-pack=true in server.properties.*

If you modified server.properties you will need to restart!

* Note: There are a lot of guides online that can help you get this working if these instructions aren't helping you.

Merge resource packs​

You can merge packs manually or use ResourcePackManager for the Nightbreak pack workflow. An external tool such as merge.elmakers can combine ZIPs, but you must still resolve conflicting model IDs and verify the combined pack in the target client.

Step 4. Verify the model​

With the model registry loaded and the matching pack applied on the client, verify the model on an actual boss or NPC. These commands require a player sender and the corresponding permission:

  • Custom Boss: /em spawn boss filename.yml — elitemobs.place.admin, spawns at the location you are looking at.
  • NPC: /em place npc filename.yml — elitemobs.place.npc, saves a persistent placement where you stand.

/em remove toggles removal mode. Hit the target to remove it, then run the command again to leave that mode. Removing a placed NPC this way also removes its saved placement.

Creating and adapting Custom Models for EliteMobs

Use a model supported and successfully loaded by the selected provider. Provider compatibility and supported model features still apply.

However, when it comes to animations, the use of specific names for the animations is required to guarantee that the bosses can use the animations.

These animation names are the ones set on Blockbench in the animations tab. You can rename them at any time, meaning you can retrofit any existing models to work with EliteMobs.

Animations​

Use the following animation names for the automatic hooks provided by EliteMobs.

idle​

idle is the conventional idle animation name. EliteMobs starts a ModelEngine model in its default idle state; subsequent idle and movement animation selection belongs to the model provider.

walk​

walk is the conventional movement animation name. EliteMobs does not explicitly start a walk animation during attachment; movement animation selection belongs to ModelEngine/FMM.

attack​

There are three types of attack animations:

attack​

attack is the correct generic animation name for when a boss attacks.

attack_melee​

attack_melee overrides attack for a Custom Boss acting as the direct damager in a Bukkit entity-damage event. The animation is requested during event handling, not as a wind-up that delays the hit. Already-cancelled events are ignored; a later listener can still cancel the damage. Use a short animation rather than relying on it to schedule damage.

attack_ranged​

attack_ranged overrides attack when a projectile spawn event identifies a Custom Boss as its living shooter. It responds to the projectile spawn rather than delaying the shot until an animation completes. Projectiles without that shooter association do not trigger this automatic hook.

Animation Fallback System​

EliteMobs uses a fallback system for attack animations:

  • If attack_melee is not defined, falls back to attack
  • If attack_ranged is not defined, falls back to attack
  • FMM checks that attack exists before playing it; the ModelEngine adapter passes that fallback name to its animation handler

This allows you to create a single attack animation that works for all attack types, or create specialized animations for melee vs ranged attacks.

damaged​

warning

EliteMobs does not register an automatic damaged animation hook. A provider's damage tint or other hit feedback is separate from playing that named animation.

death​

On EliteMobDeathEvent, EliteMobs requests death on a Custom Boss's model when that animation exists. Removal and phase changes are not the same as a death event. Animation playback and model cleanup remain subject to the provider's lifecycle.

powers​

warning

There is no automatic matching between power names and model animation names.

You can already play an animation from a power today

There is no automatic name-matching yet, but both scripting systems can fire an animation by name explicitly:

  • EliteScript: the PLAY_ANIMATION action, with the animation name as its value. It resolves each target to a Custom Boss and plays the animation on that boss's model.
  • Lua: context.boss:play_model_animation("animation_name").

In both cases the animation is silently skipped if the model has no animation by that name, or if the boss has no custom model.

Importing Custom Models from dungeons

Step 1. Normal import​

Upon importing a dungeon packager zipped folder that contains Custom Models, the Custom Models get moved into whichever model plugin is installed:

  • FreeMinecraftModels installed — models go to (yourServer)/plugins/FreeMinecraftModels/models (or the legacy Models folder if it already exists), and .bbmodel files are converted to .fmmodel on the way in. EliteMobs then fires a model installation event so FMM rebuilds its model registry.
  • Only ModelEngine installed — models go to (yourServer)/plugins/ModelEngine/blueprints. The current shared importer does not automatically reload ModelEngine; rebuild its models/resource pack with the command appropriate to that version.
First boot after installing a DLC

After an import starts an FMM model rebuild, EliteMobs waits for FMM to reach its initialized state, for up to 300 seconds (five minutes). A failed/disabled FMM, timeout, or interrupted wait stops EliteMobs initialization before incomplete models and items are loaded. Check both plugins' console errors, resolve the rebuild problem, then restart; this is not a successful startup that merely skips a few modelled entities.

Step 2. Resource Pack​

EliteMobs exports its built-in pack to (yourServer)/plugins/EliteMobs/resource_pack/em_rsp_defaults on startup and records .rsp_checksum in the parent folder. It skips copying when the bundled checksum matches the saved checksum and em_rsp_defaults exists. A plugin version change alone does not force export, and matching checksums do not check every exported file for local edits or deletion. Replacement uses a staged directory swap; keep your own pack changes separate from this generated folder.

You will need to merge these resource pack files with any Model Engine resource pack files and distribute the combined resource pack to your players. Only players that have the resource pack will be able to see the Custom Models.

Troubleshooting

Common issues:

  1. Model not visible:

    • Verify the selected provider's registry contains the model; use the reload command for that provider and version
    • Check resource pack is installed on client
    • Ensure customModel matches the registered model ID, normally the model filename without its extension

  2. Animations not playing:

    • Verify animation names in Blockbench match documented names exactly
    • Check that animations are not set to loop if they should play once
    • Test individual animations using the selected provider's commands

  3. Both plugins installed:

    • EliteMobs will use FreeMinecraftModels if both are present
    • There is no per-model provider selector. To use ModelEngine instead, disable FreeMinecraftModels and run an R3 ModelEngine build

  4. Boss or NPC has no visible name (FMM):

    • Check name, the boss's alwaysShowName setting, and model loading first.
    • Current FMM uses a hitbox-top nameplate fallback without a tag_ anchor. Inspect the hitbox height or add an authored anchor if the name appears in the wrong place.
    • NPC models are reattached when FMM emits its reload-complete event. Check console warnings if a model disappears after an FMM reload.