Skip to main content

Creating EliteMobs Content

EliteMobs uses YAML for bosses, items, quests and other definitions, with Lua for powers, NPC scripts and native behaviors. Place each file in its content folder under plugins/EliteMobs/.

Content Types​

This overview covers eight main content types, plus the supporting definitions and scripts listed below:

  1. Custom Bosses - Create unique elite mobs with custom powers, equipment, and abilities
  2. Custom Items - Design custom weapons, armor, and items with enchantments
  3. Custom Quests - Build quest chains with objectives and rewards
  4. Custom Events - Set up timed or triggered boss events
  5. Custom NPCs - Add quest givers, shops, and interactive NPCs
  6. Treasure Chests - Place loot chests with custom rewards and mimic mechanics
  7. Arenas - Design wave-based combat challenges with boss encounters
  8. Wormholes - Create teleportation portals between locations

Each content type has its own configuration folder and field structure.

Quick Start​

For a YAML content definition:

  1. Create a YAML file with .yml extension
  2. Name it using lowercase_with_underscores.yml format
  3. Place it in the appropriate folder
  4. Configure the content using YAML fields
  5. Reload EliteMobs or restart server

File Locations​

Each content type is stored in its own folder:

  • Custom Bosses: ~/plugins/EliteMobs/custombosses/
  • Custom Items: ~/plugins/EliteMobs/customitems/
  • Custom Quests: ~/plugins/EliteMobs/customquests/
  • Custom Events: ~/plugins/EliteMobs/customevents/
  • Custom NPCs: ~/plugins/EliteMobs/npcs/
  • Treasure Chests: ~/plugins/EliteMobs/customtreasurechests/
  • Arenas: ~/plugins/EliteMobs/customarenas/
  • Wormholes: ~/plugins/EliteMobs/wormholes/

Supporting content has additional folders:

  • Powers: ~/plugins/EliteMobs/powers/
  • Custom Spawns: ~/plugins/EliteMobs/customspawns/
  • NPC Lua scripts: ~/plugins/EliteMobs/npc_scripts/
  • Native Lua behaviors: ~/plugins/EliteMobs/behaviors/
  • Transport routes: ~/plugins/EliteMobs/transport_routes/
  • Enchantment definitions and Lua: ~/plugins/EliteMobs/enchantments/
  • Dungeon packages: ~/plugins/EliteMobs/content_packages/
  • Instanced world templates: ~/plugins/EliteMobs/world_blueprints/

A package-level scripts/ folder belongs to FreeMinecraftModels. It is not the EliteMobs NPC or behavior script folder; see package folder routing.

Content Creation Tools​

The EliteMobs WebApp provides a visual interface for generating configuration files. Check its output against the current reference for each content type; newer fields and Lua scripts may require manual editing.

Manual YAML Configuration​

For advanced users, create YAML files manually for complete control over all available fields and options.

YAML File Format​

YAML content definitions follow these rules. Lua powers, NPC scripts and behaviors are separate .lua files:

  • Use spaces, not tabs, for indentation
  • Quote strings that start with color codes; single quotes are convenient for literal text
  • Lists use hyphen format or bracket format
  • isEnabled controls whether a YAML definition is enabled. Defaults depend on the content type and premade definition; set it explicitly in new files and check the relevant reference
  • File names should use lowercase_with_underscores.yml format

For detailed YAML syntax help, see the Configuration File Guide.

Content Type Overview​

Custom Bosses​

Custom bosses are elite mobs with enhanced abilities, custom equipment, and special powers. The boss system supports 60+ configuration fields including:

  • Entity type and level
  • Health and damage multipliers
  • Equipment (armor and weapons)
  • Elite powers and abilities
  • Loot tables and drops
  • Spawn/death messages and commands
  • Multi-phase mechanics
  • Custom models and disguises

Example Basic Boss:

isEnabled: true
entityType: ZOMBIE
name: '&e Test Boss'
level: dynamic
healthMultiplier: 2.0
damageMultiplier: 0.5
helmet: GOLDEN_HELMET
chestplate: IRON_CHESTPLATE
mainHand: GOLDEN_AXE
powers:
  - invulnerability_knockback.lua
spawnMessage: A test boss has been spawned!
deathMessage: A test boss has been slain by $players!

Custom Items​

Custom items allow you to create unique weapons, armor, and tools with custom enchantments and effects. The item system includes:

  • Material type
  • Display name and lore
  • Enchantments list
  • Potion effects
  • Custom model IDs
  • Drop weight and scaling
  • Level and soulbound settings

Example Basic Item:

isEnabled: true
material: DIAMOND_SWORD
name: '&4Legendary Blade'
lore:
  - '&7A powerful weapon'
  - '&7forged in dragon fire'
enchantments:
  - DAMAGE_ALL,5
  - FIRE_ASPECT,2
level: 10
soulbound: true

Custom Quests​

Custom quests create objectives for players with rewards upon completion. The quest system includes:

  • Quest objectives and types
  • Rewards (items, money, permissions)
  • Accept/complete dialog
  • NPC turn-in requirements
  • Quest lockout timers
  • Tracking and sounds

Custom Events​

Custom events trigger boss spawns based on time, chance, or other conditions. The event system includes:

  • Event type and boss list
  • Trigger chance and weight
  • Start/end messages and commands
  • Cooldown timers (local and global)
  • Minimum player count
  • Event duration

Custom NPCs​

Custom NPCs provide interactive characters for quests, shops, and arenas. The NPC system includes:

  • NPC name, role, and profession
  • Spawn locations
  • Dialog (greetings, dialog, farewell)
  • Interaction types
  • Quest and arena references
  • Custom models and disguises
  • NPC Lua hooks and patrol routes

Treasure Chests​

Treasure chests provide loot rewards with customizable restock timers and mimic mechanics. The chest system includes:

  • Chest type and orientation
  • Location coordinates
  • Loot table
  • Restock timers
  • Mimic chance and boss list
  • Single-player or per-player group drop styles

Arenas​

Arenas create wave-based combat challenges with boss encounters. The arena system includes:

  • Arena boundaries (corner1, corner2)
  • Wave count and delays
  • Boss list and spawn points
  • Rewards and player limits
  • Arena messages
  • Intermission waves

Wormholes​

Wormholes create teleportation portals between two locations. The wormhole system includes:

  • Two location endpoints
  • Display text for each location
  • Visual style and particle colors
  • Coin cost and permissions
  • Blind effect and size multiplier
  • Optional entity models at either endpoint

Common Patterns​

Referencing Content​

Content types reference each other using filenames:

  • Reference powers in bosses: power_name.lua (a legacy power_name.yml reference is automatically resolved to the .lua power of the same name)
  • Reference items in loot: filename: item_name.yml (see the Loot Tables format for chance, amount and more)
  • Reference bosses in events: boss_filename.yml
  • Reference quests in NPCs: quest_filename.yml

Reusing Definitions​

Custom boss, NPC and transport route files can start from another file of the same kind with extends: base_file.yml and override only the keys that differ. Placements and isEnabled are never inherited. See Reusing another boss file and Reusing another NPC file for the full rules.

Placeholders​

Placeholders are specific to the field that reads them, not global replacements for every message:

  • $players - Participating attackers' display names in boss death announcements
  • $distance - Distance to the tracked boss location in locationMessage
  • $eventBossLevel - Formatted level in boss names; preview text can show ? when the level is unknown

Color Codes​

Use Minecraft color codes in names and messages. Quote the complete string when it starts with a color code. Single quotes keep backslashes literal; YAML double-quoted strings are also valid.

Standard Minecraft color codes:

  • &0 - Black
  • &1 - Dark Blue
  • &2 - Dark Green
  • &3 - Dark Aqua
  • &4 - Dark Red
  • &5 - Dark Purple
  • &6 - Gold
  • &7 - Gray
  • &8 - Dark Gray
  • &9 - Blue
  • &a - Green
  • &b - Aqua
  • &c - Red
  • &d - Light Purple
  • &e - Yellow
  • &f - White

Formatting codes:

  • &l - Bold
  • &m - Strikethrough
  • &n - Underline
  • &o - Italic
  • &r - Reset

Elite Powers System​

EliteMobs ships 71 elite powers. 68 of them are Lua files (*.lua) and only bonus_coins.yml, custom_summon.yml and elite_script.yml are still YAML-backed. Powers are referenced by filename in boss configurations, and a legacy .yml reference automatically resolves to the .lua power of the same name. See Creating Powers.

Power categories​

The category a power belongs to is its powerType, which also decides whether natural elites can roll it.

Offensive: arrow_fireworks, arrow_rain, attack_arrow, attack_fire, attack_fireball, attack_freeze, attack_gravity, attack_lightning, attack_poison, attack_push, attack_vacuum, attack_wither, fireworks_barrage, lightning_bolts, taze

Defensive: invulnerability_arrow, invulnerability_fall_damage, invulnerability_fire, invulnerability_fireworks, invulnerability_knockback, shield_wall

Miscellaneous: attack_blinding, attack_confusing, attack_weakness, attack_web, bonus_loot, channel_healing, corpse, frost_walker, ground_pound, implosion, invisibility, moonwalk, movement_speed, taunt

Major powers (entity-type locked):

  • MAJOR_ZOMBIE: zombie_bloat, zombie_friends, zombie_necronomicon, zombie_parents
  • MAJOR_SKELETON: bullet_hell, skeleton_pillar, skeleton_tracking_arrow
  • MAJOR_BLAZE: firestorm, flame_pyre
  • MAJOR_ENDERMAN: plasma_blaster
  • MAJOR_GHAST: tracking_fireball

Unique (only applied when a boss asks for them by name): death_slice, flamethrower, frost_cone, gold_explosion, gold_shotgun, hyper_loot, meteor_shower, photon_ray, spirit_walk, summon_embers, summon_the_returned, thunderstorm, plus the ten Ender Dragon powers: ender_dragon_aimed_fireball, ender_dragon_arrow_bombardment, ender_dragon_disco_fireballs, ender_dragon_empowered_lightning, ender_dragon_ender_fireball_bombardment, ender_dragon_endermite_bombardment, ender_dragon_fireball_bombardment, ender_dragon_potion_bombardment, ender_dragon_shockwave, ender_dragon_tornado

Still YAML: bonus_coins.yml, custom_summon.yml (the reinforcement system), elite_script.yml

Powers are added to bosses using the powers list field:

powers:
  - invulnerability_knockback.lua
  - flame_pyre.lua
  - spirit_walk.lua

Advanced Features​

Multi-Phase Bosses​

Bosses can have multiple phases with separate configuration files. Use the phases field to reference phase boss files, and phaseSpawnLocation to set where phase transitions occur.

Elite Scripts​

Elite scripts provide advanced custom boss abilities with event-driven actions, conditions, and cooldowns. YAML EliteScript uses the eliteScript field in boss configurations. Lua powers are separate .lua files referenced from powers; see Creating Powers.

Custom Models​

Bosses and NPCs use customModel for entity models. Items use their own fields, including customModelV2, equipmentModelID and fmmItemModel; see Custom Items. Entity and item model setup are separate.

Boss Equipment​

Boss equipment fields accept Minecraft material names. They do not load custom item files or their EliteMobs stats:

helmet: DIAMOND_HELMET
chestplate: IRON_CHESTPLATE
leggings: LEATHER_LEGGINGS
boots: CHAINMAIL_BOOTS
mainHand: GOLDEN_AXE
offHand: SHIELD

Command Execution​

Bosses can execute commands at specific events:

  • onSpawnCommands - Execute when boss spawns
  • onDeathCommands - Execute when boss is defeated
  • onCombatEnterCommands - Execute when combat starts
  • onCombatLeaveCommands - Execute when combat ends

Boss Messages​

Customize boss announcements:

  • spawnMessage - Broadcast when boss spawns
  • deathMessage - Broadcast when boss is defeated (supports $players placeholder)
  • escapeMessage - Broadcast when boss escapes
  • locationMessage - Shows distance to boss (supports $distance placeholder)
  • deathMessages - Ordered lines sent on boss death when attackers are recorded; a nonempty list takes precedence over deathMessage. It is not a random selection

Use announcementPriority (0–3) to control announcement delivery, tracking and DiscordSRV forwarding. Death announcements at 0 go to recorded attackers, while positive priorities broadcast server-wide; 3 also forwards through the configured DiscordSRV integration. Spawn announcements and tracking use their own rules.

Regional Bosses​

Regional bosses use the isRegionalBoss field and can have leash radius, spawn restrictions, and block state changes:

  • leashRadius - Maximum distance from spawn point
  • onSpawnBlockStates - Block changes when boss spawns
  • onRemoveBlockStates - Block changes when the boss is defeated; ordinary unloads, despawns and resets do not apply the defeat state

Automatic class loot​

Use class loot for level-scaled rewards selected for the player's class. Its encounter ranks and difficulty budgets let you tune reward quality separately from boss health and damage. Custom item families can provide authored names, materials, lore and models.

Loot Configuration​

Control boss drops:

  • dropsEliteMobsLoot - Enables the normal generated-loot and coin path (default true); it is not a master switch for authored or class loot
  • dropsVanillaLoot - Enables vanilla drops (default true)
  • dropsRandomLoot - Enables random generated loot within the normal loot path (default true)
  • uniqueLootList - Authored loot entries, handled separately from those generated-loot switches
  • classLoot - Controls automatic class loot separately; its global settings and eligibility checks still apply

Example:

uniqueLootList:
  - filename=custom_sword.yml:chance=1.0
  - filename=rare_helmet.yml:chance=0.05:amount=1

The legacy shorthand custom_sword.yml:1 is still parsed, but the number after the colon is the drop chance (1 = 100%), not the quantity. Use amount= for quantity. See Loot Tables for the full set of options.

Premade Content​

EliteMobs ships premade configurations for most content types and writes them straight into the normal content folders on first boot - there is no separate /premade/ folder on disk. The generated files (bosses in custombosses/, items in customitems/, NPCs in npcs/, and so on) are ordinary YAML and serve as working examples for your own content.

Premade package definitions also ship with the plugin, while their dungeon worlds and additional content are downloaded and installed through /em setup. See the Dungeon Packager page.

Getting Help​