Creating Boss Phases

Boss Phases let a Custom Boss change its configuration during an encounter.

How do Boss Phases work?

Boss Phases can be added to any Custom Boss in EliteMobs using the following config format:

phases:
- phase_2_boss.yml:0.X
- phase_3_boss.yml:0.Y

Note: The boss you originally spawn (which contains the phases: entry listing all other phases) is the phase 1 boss. The phase 1 boss file should NOT list itself in its own phases: entry.

Each entry is filename:healthFraction. The fraction must be at least 0 and below 1, such as 0.60 or 0.30, and the referenced boss file must be loaded and enabled. EliteMobs checks the list every time it creates the boss: an invalid entry stops that boss from spawning, and the console message names the entry.

Each phase references another boss file, allowing changes to powers, damage and health multipliers, entity type, disguise and equipment. Encounter state and the regional settings listed below remain shared.

EliteMobs replaces the boss's body with the next phase while retaining its encounter state. When a damage event would cross the next phase threshold, that event is cancelled and the next phase begins at its configured health percentage. Excess damage does not carry through the transition. The boss receives a 20-tick combat grace period afterward.

If the destination chunk cannot tick entities yet, EliteMobs loads it and waits up to 100 ticks (5 seconds) before replacing the body. Damage to the boss is cancelled while it waits. If the destination's world is not loaded, or the chunk does not become ready in time, the transition is refused: the boss keeps its current phase and the console logs a warning.

Example

Take this example phase boss:

File: phase_1_boss.yml

isEnabled: true
level: 50
healthMultiplier: 10
entityType: STRAY
powers:
- attack_gravity.lua
phases:
- phase_2_boss.yml:0.60
- phase_3_boss.yml:0.30

File: phase_2_boss.yml

isEnabled: true
level: 50
healthMultiplier: 10
entityType: SKELETON
powers:
- attack_gravity.lua
- arrow_fireworks.lua

File: phase_3_boss.yml

isEnabled: true
level: 50
healthMultiplier: 10
entityType: WITHER_SKELETON
powers:
- arrow_rain.lua

This constitutes a valid Phase Boss. If you spawn phase_1_boss.yml, it will spawn a Stray with the attributes listed above. After being damaged down to 60% of its health, it will immediately be replaced in the same location by the Custom Boss as formed in phase_2_boss.yml, since the configuration file states - phase_2_boss.yml:0.60 (phase_2_boss.yml is the file name for that custom boss, 0.60 is 60% health). Note that the phase 2 boss will spawn with 60% of its health, since that's when it changes to that phase. The boss will have the powers listed on the phase_2_boss.yml file. Once the phase 2 boss is damaged down to 30% of its health, it spawns the boss set for phase 3. Note that the powers for phase 3 are unrelated to the ones from before - you can completely change powers between phases, just like nearly all other attributes.

Advanced

Inherited mechanics

Here's a list of things that do not change from phase to phase:

• The first Phase Boss in the chain determines which phases the boss will go through, meaning that you shouldn't put a phases entry for the other bosses in the phase.

• Threat table / Damage table stays the same, meaning loot distribution and the advanced aggro system are unaffected by a phase change

• Switching phases uses the next phase's configured health percentage. If phase 2 starts at 50%, it receives 50% of its own maximum health, even if the triggering hit would have taken the previous phase below that threshold. Each phase can have a different maximum health.

Phases that all sit on the health cap are identical

Boss health is clamped at the server's settings.attribute.maxHealth.max (2048 by default). If several phases are configured with a high enough level and healthMultiplier to hit that ceiling, they all end up with exactly 2048 HP and your intended per-phase health differences disappear. The examples on this page (level: 50, healthMultiplier: 10) are in that territory — see healthMultiplier for the level at which each multiplier caps out.

• Eligible non-instanced phase bosses revert to phase 1 when the out-of-combat regeneration system calls fullHeal(). This requires regenerateCustomBossHealthOnCombatEnd; that event path excludes phantoms. Instanced bosses skip fullHeal(). Ordinary healing to maximum health does not itself trigger a phase reset.

• Regional phase bosses retain the leash radius and respawn cooldown established by phase 1, and respawn as phase 1 after that cooldown. A phase transition uses silent spawning and does not start a fresh escape timer; configure the encounter's timeout on phase 1.

• Phase 1 also owns normalizedCombat for the chain. A phase with level: -1 preserves an already resolved encounter level, including an instance's selected level; an explicit level in the new phase replaces it.

Phase-Specific Spawn Locations

By default, bosses remain at their current location when transitioning between phases. However, you can make a boss teleport to a specific location when entering a phase using the phaseSpawnLocation setting:

File: phase_2_boss.yml

isEnabled: true
level: 50
healthMultiplier: 10
entityType: SKELETON
powers:
- attack_gravity.lua
- arrow_fireworks.lua
phaseSpawnLocation: world_name,100,64,100,0,0

You can also teleport the boss while keeping it in the same world:

phaseSpawnLocation: same_as_boss,100,64,100,0,0

This is useful for creating dramatic phase transitions where the boss teleports to a different arena or location.

Warnings

Here's a list of mechanics that work in a way that may initially be counter-intuitive:

• Ordinary EliteMobs damage cannot skip a valid next phase with a one-shot: crossing its threshold cancels that hit and advances one phase. Loot comes from the configuration active when the boss actually dies. Configure the final phase's rewards. When a transition is refused, for example because phaseSpawnLocation names a world that is not loaded, the threshold-crossing hit is still cancelled, so ordinary damage cannot take the boss below that threshold until the problem is fixed.

• Each phase runs its spawning routine, including applicable onSpawnCommands. Phase transitions and full-health resets use silent spawning, so they suppress the ordinary spawn announcement. Regional respawns after the cooldown can announce again. A phase transition is not a death and does not run death commands.

• Regional phase bosses apply the outgoing phase's ON_REMOVE transitive blocks before advancing. The new phase then applies its spawn blocks. Actual death or the kill command clears the terminal phase's removal blocks. Ordinary chunk unloads and full-health resets do not count as defeats for that cleanup.

• Phase changes remove the outgoing phase's tracked mount, then the new phase creates its configured mount. A full-health reset likewise removes the current mount and uses the phase 1 mount configuration.

• Each phase reloads its powers. The custom_summon power's ONCE reinforcement state therefore resets when changing phases or resetting to phase 1; it is not a once-per-encounter limit.

Tips & tricks

• You can use the fact that equipment and entity types can be changed throughout combat to make the boss look more and more (or less and less) dangerous throughout the fight

• While possible, unless there is a specific design goal in mind, it is probably best that the powers the Phase Boss has don't change too drastically between phases, as players are more likely to enjoy a progression that feels natural throughout the fight.

• You can use onSpawn commands to run commands between phases

• Set song on each phase that should change the music. A different value replaces the track; the same value continues it. Omitting song on a later phase does not stop the previous track.

• Phases can be used to switch the boss from melee to ranged mode and vice-versa

• Phase Bosses were built to be tough bosses with lots of HP. They are usually best served as final boss encounter for dungeons or as big World Bosses.

• Reinforcements may remain alive between phases. cullReinforcements on the outgoing phase controls cleanup; a reset to phase 1 also requests reinforcement cleanup.

• Bosses can have any number of phases you want, but the more phases they have, the more health they will need to make each phase matter.

API Integration

For plugin developers: EliteMobs fires an ElitePhaseSwitchEvent when a boss transitions between phases. This event can be used to create custom behaviors or effects during phase transitions:

The event also fires for a reset to phase 1. It fires once the new phase's body has spawned, after its health percentage and the 20-tick combat grace period are applied. A transition that waits for its destination chunk fires the event only when the body appears.

@EventHandler
public void onPhaseSwitch(ElitePhaseSwitchEvent event) {
    CustomBossEntity boss = event.getCustomBossEntity();
    PhaseBossEntity phaseBoss = event.getPhaseBossEntity();
    // Your custom logic here
}