Lua Scripting: Boss & Entities

This page covers everything about boss and entity wrappers in EliteMobs Lua powers: context.boss, context.player, context.players, context.entities, and the entity wrapper tables they return. If you are new to Lua powers, start with Getting Started first.

---

Entity Wrappers

When you access entities through the Lua API -- whether from context.boss, context.player, query results like context.players:nearby_players(), or event fields -- you always receive wrapper tables. These are not raw Bukkit objects. Each wrapper provides a set of fields (snapshot values captured at creation time) and methods (live calls that reach into the server).

Two rules to remember:

• Fields like health, current_location, and maximum_health are snapshots. They reflect the state at the moment the wrapper was created and do not auto-update.
• Methods like get_location(), get_health(), and is_alive() perform a live check every time you call them.

---

Common Entity Fields

Every living entity wrapper includes these fields.

Field	Type	Notes
entity.name	string	Display name
entity.uuid	string	UUID as text
entity.entity_type	string	Bukkit EntityType name (e.g. "ZOMBIE", "PLAYER")
entity.is_player	boolean	true for players
entity.is_elite	boolean	true if EliteMobs tracks it as an elite
entity.is_mount	boolean	true if this wrapper represents a boss mount
entity.is_monster	boolean	true for monster-type entities
entity.health	number	Current health (snapshot)
entity.maximum_health	number	Max health (snapshot)
entity.current_location	location table	Position at the time the wrapper was created
entity.is_valid	boolean	Whether the backing entity existed when the wrapper was created (snapshot)

is_valid is a field on living entities, not a method

On living-entity wrappers (including context.player and context.boss) is_valid is a plain boolean captured when the wrapper was built. Calling entity:is_valid() raises attempt to call a boolean value and disables the power.

• Read the snapshot with entity.is_valid (dot).
• For a live check, call entity:is_alive() instead -- it re-queries the server every time.

is_valid() is a real method on the lighter non-living reference wrappers returned by summon_projectile, spawn_falling_block_at_location and friends. Those are the wrappers you are most likely to store across ticks, which is where the live check matters.

To read elite-specific data such as the boss level, use the context.boss fields and methods described in the context.boss section below. To despawn an elite from a script, call the entity:remove_elite() method.

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    context.log:info("Boss level: " .. context.boss.level)
  end
}

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    local target = context.players:current_target()
    if target ~= nil then
      context.log:info("Target: " .. target.name .. " HP: " .. target.health)
    end
  end
}

---

Common Entity Methods

Every living entity wrapper supports these methods. Each method performs a live call to the server.

---

entity:is_alive()

Returns true if the entity is still valid and not dead.

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if context.player:is_alive() then
      context.player:send_message("&aYou're still standing!")
    end
  end
}

---

entity:get_location()

Returns the current live location as a location table.

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    local loc = context.player:get_location()
    context.world:play_sound_at_location(loc, "entity.experience_orb.pickup")
  end
}

---

entity:get_eye_location()

Returns the eye-level location as a location table.

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    local eye = context.player:get_eye_location()
    context.world:spawn_particle_at_location(eye, "FLAME")
  end
}

---

entity:get_health() / entity:get_maximum_health()

Returns the live current or maximum health.

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    local pct = context.player:get_health() / context.player:get_maximum_health()
    if pct < 0.25 then
      context.player:send_message("&cYou're running low!")
    end
  end
}

---

entity:get_velocity()

Returns the entity's current velocity as a vector table.

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    local vel = context.player:get_velocity()
    context.log:info("Player speed Y: " .. vel.y)
  end
}

---

entity:send_message(text)

Sends a chat message to the entity. Supports EliteMobs color formatting.

Parameter	Type	Notes
text	string	Message with color codes

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    context.player:send_message("&6[Boss] &fPrepare yourself!")
  end
}

---

entity:show_action_bar(message)

Sends an action bar message to the entity.

Parameter	Type	Notes
message	string	Action bar text with color codes

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    context.player:show_action_bar("&c&lDANGER ZONE")
  end
}

---

entity:show_title(title[, subtitle][, fadeIn][, stay][, fadeOut])

Sends a title and optional subtitle to the entity.

Parameter	Type	Default	Notes
title	string		Title text
subtitle	string	""	Subtitle text
fadeIn	number	10	Fade-in ticks
stay	number	40	Stay ticks
fadeOut	number	10	Fade-out ticks

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    local nearby = context.players:nearby_players(20)
    for _, p in ipairs(nearby) do
      p:show_title("&4PHASE 2", "&7The boss is enraged!", 10, 40, 10)
    end
  end
}

---

entity:show_boss_bar(title[, color][, style][, duration])

Shows a temporary boss bar to the entity.

Parameter	Type	Default	Notes
title	string		Bar title text
color	string	"WHITE"	BarColor value
style	string	"SOLID"	BarStyle value
duration	number	40	Duration in ticks

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    local nearby = context.players:nearby_players(20)
    for _, p in ipairs(nearby) do
      p:show_boss_bar("&cIncoming Attack!", "RED", "SOLID", 100)
    end
  end
}

---

entity:teleport_to_location(location)

Teleports the entity to a location.

Parameter	Type	Notes
location	location table	Destination

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if not context.cooldowns:check_local("teleport_pull", 200) then return end
    context.player:teleport_to_location(context.boss:get_location())
    context.player:send_message("&cThe boss pulls you in!")
  end
}

---

entity:set_velocity_vector(vector)

Sets the entity's velocity immediately.

Parameter	Type	Notes
vector	vector table	{ x, y, z } or { x = 0, y = 1, z = 0 }

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if not context.cooldowns:check_local("launch", 100) then return end
    context.player:set_velocity_vector({ x = 0, y = 1.5, z = 0 })
    context.player:send_message("&cYou are launched into the air!")
  end
}

---

entity:apply_push_vector(vector[, additive][, delay])

Applies a velocity push after a short delay (default 1 tick). Useful to override knockback.

Parameter	Type	Default	Notes
vector	vector table		Direction and strength
additive	boolean	false	Add to existing velocity instead of replacing
delay	number	1	Delay in ticks before applying

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if not context.cooldowns:check_local("push_up", 100) then return end
    context.player:apply_push_vector({ x = 0, y = 2.0, z = 0 })
    context.player:send_message("&cUpward blast!")
  end
}

---

entity:face_direction_or_location(directionOrLocation)

Makes the entity face toward a direction vector or a location.

Parameter	Type	Notes
directionOrLocation	vector or location table	Target to face

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    context.player:face_direction_or_location(context.boss:get_location())
    context.player:send_message("&cThe boss forces you to look at it!")
  end
}

---

entity:set_fire_ticks(ticks)

Sets the entity on fire for the given duration.

Parameter	Type	Notes
ticks	number	Fire duration in ticks (20 ticks = 1 second)

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if not context.cooldowns:check_local("ignite", 100) then return end
    context.player:set_fire_ticks(60)
    context.player:send_message("&cYou catch fire!")
  end
}

---

entity:add_visual_freeze_ticks([ticks])

Adds visual freeze ticks to the entity (the blue overlay effect).

Parameter	Type	Default	Notes
ticks	number	1	Freeze tick amount

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if not context.cooldowns:check_local("freeze", 200) then return end
    context.player:add_visual_freeze_ticks(100)
    context.player:send_message("&bYou feel a chilling frost!")
  end
}

---

entity:apply_potion_effect(effect, duration[, amplifier])

Applies a potion effect to the entity.

Parameter	Type	Default	Notes
effect	string		PotionEffectType name
duration	number		Duration in ticks
amplifier	number	0	Effect level (0 = level I)

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if not context.cooldowns:check_local("slow", 200) then return end
    context.player:apply_potion_effect("SLOWNESS", 60, 1)
    context.player:send_message("&7You feel sluggish...")
  end
}

---

caution

remove_potion_effect(effect) is not available in EliteMobs Lua powers. It exists only in Magmacore/FMM. Use apply_potion_effect with a duration of 0 as a workaround, or design your power without needing to remove effects.

---

entity:deal_damage(amount) / entity:deal_custom_damage(amount) / entity:deal_damage_from_boss(amount)

Deals damage to the entity. Three variants are available.

Method	Notes
deal_damage(amount)	Generic damage source
deal_custom_damage(amount)	Uses BossCustomAttackDamage from the boss
deal_damage_from_boss(amount)	Boss entity is set as the damager

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    local nearby = context.players:nearby_players(10)
    for _, p in ipairs(nearby) do
      p:deal_custom_damage(10)
      p:send_message("&cThe boss unleashes a shockwave!")
    end
  end
}

---

entity:restore_health(amount)

Heals the entity up to its maximum health.

Parameter	Type	Notes
amount	number	Amount to heal

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    -- Heal the player slightly when they hit the boss
    context.player:restore_health(5)
    context.player:send_message("&aYou drain life from the boss!")
  end
}

---

entity:set_invulnerable(enabled[, duration])

Toggles invulnerability on the entity. Optionally reverts after a duration.

Parameter	Type	Default	Notes
enabled	boolean		true to enable invulnerability
duration	number	nil	Auto-revert after this many ticks

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if not context.cooldowns:check_local("shield", 200) then return end
    context.player:set_invulnerable(true, 40)
    context.player:send_message("&6A brief shield protects you!")
  end
}

---

entity:set_ai_enabled(enabled[, duration])

Toggles AI on the entity. Optionally reverts after a duration.

Parameter	Type	Default	Notes
enabled	boolean		true to enable AI
duration	number	nil	Auto-revert after this many ticks

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Disable boss AI for 3 seconds at combat start
    context.boss:set_ai_enabled(false, 60)
    context.boss:send_message("&7The boss is stunned!")
  end
}

---

entity:add_tag(tag[, duration]) / entity:remove_tag(tag) / entity:has_tag(tag)

Manages tags on the entity. Tags are tracked by EliteMobs and persist for the entity's lifetime.

Method	Parameter	Notes
add_tag(tag[, duration])	string, optional number	Adds tag, optionally auto-removes after ticks
remove_tag(tag)	string	Removes the tag
has_tag(tag)	string	Returns true if the tag is present

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if not context.player:has_tag("marked") then
      context.player:add_tag("marked", 200)
      context.player:send_message("&cYou have been marked!")
    end
  end
}

---

entity:run_command(command)

Makes the entity run a command. For players this runs as the player; use command text without a leading /.

Parameter	Type	Notes
command	string	Command text without leading /

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if not context.cooldowns:check_local("curse_cmd", 200) then return end
    context.player:run_command("say I have been cursed!")
  end
}

---

entity:set_scale(scale[, duration])

Sets the entity's generic_scale attribute. Optionally reverts to 1.0 after a duration.

Parameter	Type	Default	Notes
scale	number		Scale multiplier
duration	number	nil	Auto-revert after this many ticks

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Boss grows to double size for 5 seconds
    context.boss:set_scale(2.0, 100)
    context.boss:send_message("&4The boss grows in size!")
  end
}

---

entity:set_gravity(enabled)

Toggles gravity on the entity.

Parameter	Type	Notes
enabled	boolean	true for normal gravity

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if not context.cooldowns:check_local("levitate", 200) then return end
    -- Change the boss's gravity; player state must not outlive this script.
    context.boss:set_gravity(false)
    context.scheduler:run_after(60, function(tick_context)
      if tick_context.boss.exists then
        tick_context.boss:set_gravity(true)
      end
    end)
  end
}

---

entity:play_sound_at_entity(sound[, volume][, pitch])

Plays a sound at the entity's location.

Parameter	Type	Default	Notes
sound	string		Minecraft sound key (for example, "entity.ender_dragon.growl") or a Spigot Sound enum name. Resource-pack keys work too.
volume	number	1.0	Volume
pitch	number	1.0	Pitch

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    context.player:play_sound_at_entity("entity.ender_dragon.growl", 1.0, 0.5)
  end
}

---

entity:play_sound_at_self(sound[, volume][, pitch])

Alias for play_sound_at_entity. Plays a sound at the entity's location.

---

entity:spawn_particle_at_self(particleOrSpec[, count])

Spawns particles at the entity's location.

Parameter	Type	Default	Notes
particleOrSpec	string or table		Particle name or spec table
count	number	1	Number of particles

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    context.player:spawn_particle_at_self("HEART", 5)
  end
}

---

entity:spawn_particles_at_location(location, particle[, count])

Spawns particles at a specific location.

Parameter	Type	Default	Notes
location	location table		Target location
particle	string		Particle type name
count	number	1	Number of particles

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    local loc = context.player:get_location()
    context.player:spawn_particles_at_location(loc, "FLAME", 10)
  end
}

---

entity:play_model_animation(name)

Plays a custom model animation if the entity has a custom model that supports it.

Parameter	Type	Notes
name	string	Animation name

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    context.boss:play_model_animation("attack_swing")
  end
}

---

Vehicle And Passenger Methods

Living entity wrappers also expose Bukkit vehicle/passenger helpers. These are useful for scripted mounts, temporary riding effects, and checking whether an entity is already attached to another entity.

Method	Returns	Notes
entity:is_inside_vehicle()	boolean	True if the entity is riding another entity.
entity:has_vehicle()	boolean	True if the entity currently has a vehicle.
entity:get_vehicle()	entity wrapper or nil	Returns the current vehicle wrapper.
entity:set_vehicle(vehicle)	boolean	Makes this entity ride vehicle.
entity:leave_vehicle()	boolean	Makes this entity leave its current vehicle.
entity:has_passengers()	boolean	True if this entity has passengers.
entity:get_passenger_count()	number	Number of passengers.
entity:get_passengers()	table	Array of passenger wrappers.
entity:add_passenger(passenger)	boolean	Adds a passenger to this entity.
entity:remove_passenger(passenger)	boolean	Removes a passenger from this entity.
entity:eject_passengers()	boolean	Ejects all passengers.

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if context.player:has_vehicle() then
      context.player:leave_vehicle()
    end
  end
}

---

entity:push_relative_to(source[, strength][, xOffset][, yOffset][, zOffset])

Pushes the entity away from a source location or entity wrapper.

Parameter	Type	Default	Notes
source	location or wrapper		Push origin
strength	number	1.0	Push strength multiplier
xOffset	number	0	Extra X offset
yOffset	number	0	Extra Y offset
zOffset	number	0	Extra Z offset

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if not context.cooldowns:check_local("knockback", 60) then return end
    context.player:push_relative_to(context.boss:get_location(), 2.0, 0, 0.5, 0)
    context.player:send_message("&cThe boss knocks you back!")
  end
}

---

entity:set_custom_name(name) / entity:reset_custom_name()

Sets or resets the entity's custom display name. Supports color codes.

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if not context.cooldowns:check_local("mark", 200) then return end
    local player = context.player
    player:set_custom_name("&c&lMarked Target")
    player:send_message("&cYou have been marked!")
    -- Reset after 5 seconds
    context.scheduler:run_after(100, function()
      if player:is_alive() then
        player:reset_custom_name()
      end
    end)
  end
}

---

entity:place_temporary_block(material[, duration][, requireAir])

Places a temporary block at the entity's current location.

Parameter	Type	Default	Notes
material	string		Block material name
duration	number	0	Ticks before removal
requireAir	boolean	false	Only place if the block is currently air

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if not context.cooldowns:check_local("ice_trap", 200) then return end
    context.player:place_temporary_block("ICE", 60, true)
    context.player:send_message("&bIce forms at your feet!")
  end
}

---

entity:get_height()

Returns the entity's height in blocks.

---

entity:is_on_ground()

Returns true if the entity is currently standing on solid ground.

---

entity.is_valid

On a living-entity wrapper this is a boolean field, not a method: it records whether the backing Bukkit entity existed at the moment the wrapper was created. Read it with a dot (entity.is_valid); calling it with a colon errors out.

Because it is a snapshot it goes stale, so it is not a substitute for a live check. Use entity:is_alive() when you need the current state, and is_valid() (the method) on non-living reference wrappers you stored across ticks.

---

entity:is_frozen()

Returns true if the entity (when tracked as a custom boss) has the frozen flag set.

---

entity:set_awareness_enabled(aware[, duration])

Toggles mob awareness. Only affects mob-type entities. Optionally reverts after a duration.

Parameter	Type	Default	Notes
aware	boolean		true to enable awareness
duration	number	nil	Auto-revert after this many ticks

---

entity:is_healing() / entity:set_healing(enabled)

Checks or toggles the healing state on an elite entity.

---

entity:overlaps_box_at_location(center[, halfX][, halfY][, halfZ])

Returns true if the entity's bounding box overlaps an axis-aligned box at the given location.

Parameter	Type	Default	Notes
center	location table		Center of the test box
halfX	number	0.5	Half-width on X axis
halfY	number	same as halfX	Half-height on Y axis
halfZ	number	same as halfX	Half-width on Z axis

---

entity:remove_elite()

Removes the elite entity from EliteMobs tracking. If the entity is an elite, this despawns it properly through EliteMobs.

---

entity:set_custom_name_visible(visible)

Sets whether the entity's custom name is always visible or only when looked at.

Parameter	Type	Notes
visible	boolean	true for always visible

---

entity:set_equipment(slot, material[, options])

Sets equipment on the entity.

Parameter	Type	Default	Notes
slot	string		Equipment slot: "HEAD", "CHEST", "LEGS", "FEET", "HAND", "OFF_HAND"
material	string		Material name (e.g. "DIAMOND_SWORD", "IRON_HELMET")
options	table	{}	Optional settings (see below)

Options table:

Key	Type	Default	Notes
enchantments	array of tables	nil	Each entry: { type = "SHARPNESS", level = 2 }
unbreakable	boolean	false	Whether the item is unbreakable

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Give the boss a glowing diamond sword
    context.boss:set_equipment("HAND", "DIAMOND_SWORD", {
      unbreakable = true,
      enchantments = {
        { type = "SHARPNESS", level = 5 }
      }
    })
  end
}

---

entity:is_ai_enabled()

A method that returns true if the entity currently has AI enabled.

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.boss:is_ai_enabled() then
      context.log:info("Boss AI is active")
    else
      context.log:info("Boss AI is disabled (stunned?)")
    end
  end
}

---

Non-Living Entity Reference Wrappers

When a spawned entity is not a LivingEntity -- for example a falling block, projectile, or fireball -- you receive a lighter reference wrapper. These are returned by methods like context.world:spawn_falling_block_at_location() or context.boss:summon_projectile().

Fields: name, uuid, entity_type, is_player (always false), is_elite (always false), is_mount (always false), current_location

Methods:

Method	Notes
is_valid()	Live validity check. Unlike living-entity wrappers, this really is a method here
get_location()	Current live location
get_velocity()	Current velocity vector
is_on_ground()	Whether on the ground
teleport_to_location(location)	Teleports the entity
set_velocity_vector(vector)	Sets velocity
set_direction_vector(vector)	Sets direction (Fireball only)
set_yield(value)	Sets explosion yield (Fireball only)
set_gravity(enabled)	Toggles gravity
detonate()	Detonates firework entities
remove()	Removes the entity from the world
unregister([reason])	Unregisters from the entity tracker

These wrappers also carry the full set of vehicle and passenger methods (is_inside_vehicle(), get_vehicle(), set_vehicle(v), add_passenger(p), eject_passengers(), ...), which is how a boss is put on a non-living mount.

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if not context.cooldowns:check_local("fireball", 100) then return end
    local fb = context.boss:summon_projectile("FIREBALL",
      context.boss:get_eye_location(),
      context.player:get_location(),
      1.5
    )
    -- fb is a non-living reference wrapper; remove it after 5 seconds if still alive
    context.scheduler:run_after(100, function()
      if fb:is_valid() then
        fb:remove()
      end
    end)
  end
}

---

context.player

Available in hooks where a player is directly involved (on_boss_damaged_by_player, on_player_damaged_by_boss, etc.). Player wrappers include every common entity field and method listed above, plus the extras below.

caution

context.player is nil in hooks that have no associated player, such as on_spawn, scheduled callbacks, and timer hooks. Always nil-guard before use.

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    context.player:send_message("&cHello!")
  end
}

Player-Only Fields

Field	Type	Notes
game_mode	string	Current game mode name (e.g. "SURVIVAL")

Player-Only Methods

Method	Notes
send_message(message)	Chat message with EliteMobs color formatting
show_action_bar(message)	Action bar text
show_title(title[, subtitle][, fadeIn][, stay][, fadeOut])	Title screen overlay
show_boss_bar(title[, color][, style][, duration])	Temporary boss bar
run_command(command)	Run a command as the player (no leading /)

Example

return {
  api_version = 1,
  on_player_damaged_by_boss = function(context)
    if context.player == nil then return end
    local hp_pct = context.player:get_health() / context.player:get_maximum_health()
    if hp_pct < 0.3 then
      context.player:show_title("&4LOW HEALTH", "&7Find cover!", 5, 30, 10)
      context.player:show_boss_bar("&cBoss Enrage Incoming", "RED", "SEGMENTED_6", 80)
    end
  end
}

---

context.boss

The boss wrapper for the elite mob that owns this Lua power. Always available in every hook.

tip

The boss wrapper inherits every common entity method listed above (e.g. push_relative_to, apply_push_vector, set_gravity, set_scale, set_invulnerable, spawn_particle_at_self, overlaps_box_at_location, etc.). The methods documented in this section are either boss-specific or have different behavior through the EliteEntity layer.

Boss Fields

Field	Type	Notes
boss.name	string	Display name
boss.uuid	string	Boss elite UUID
boss.entity_type	string	Bukkit EntityType name
boss.is_monster	boolean	true if the underlying entity is a Monster
boss.level	number	Elite level
boss.health	number	Current health (snapshot)
boss.maximum_health	number	Max health (snapshot)
boss.damager_count	number	Number of damagers (snapshot)
boss.is_in_combat	boolean	Combat state
boss.exists	boolean	Whether the elite still exists
boss.current_location	location table	Position at wrapper creation (snapshot)

Example

return {
  api_version = 1,
  on_spawn = function(context)
    context.log:info(context.boss.name .. " level " .. context.boss.level)
  end
}

Boss Methods

---

Patrol movement methods

Bosses with a configured patrol expose patrol_pause(), patrol_resume(), walk_to(x, y, z), hold(x, y, z), and teleport(x, y, z). The coordinates are offsets from the boss's authored spawn location and every method returns a boolean indicating whether the request was accepted. walk_to resumes the normal route on arrival; hold waits for patrol_resume(); long walks use the automatic route solver.

---

boss:is_alive()

Returns true if the boss entity is valid, not dead, and the elite still exists. Use this instead of the exists field for live checks.

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if not context.boss:is_alive() then return end
    context.boss:send_message("&cI still live!")
  end
}

---

boss:get_location()

Returns the boss's current live location as a location table.

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    local loc = context.boss:get_location()
    context.world:spawn_particle_at_location(loc, "FLAME")
  end
}

---

boss:get_eye_location()

Returns the boss's eye-level location.

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    local eye = context.boss:get_eye_location()
    context.world:spawn_particle_at_location(eye, "SMOKE")
  end
}

---

boss:set_ai_enabled(enabled[, duration])

Toggles AI on the boss. Optionally reverts after a duration.

Parameter	Type	Default	Notes
enabled	boolean		true to enable AI
duration	number	nil	Auto-revert after this many ticks

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if not context.cooldowns:check_local("stun", 200) then return end
    context.boss:set_ai_enabled(false, 60)
    context.boss:send_message("&7The boss is stunned for 3 seconds!")
  end
}

---

boss:teleport_to_location(location)

Teleports the boss to a location.

Parameter	Type	Notes
location	location table	Destination

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if not context.cooldowns:check_local("retreat", 300) then return end
    local spawn = context.entities:get_boss_spawn_location()
    context.boss:teleport_to_location(spawn)
    context.boss:send_message("&7The boss retreats to its lair!")
  end
}

---

boss:set_velocity_vector(vector)

Sets the boss's velocity immediately.

Parameter	Type	Notes
vector	vector table	{ x, y, z } or { x = 0, y = 1, z = 0 }

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Boss leaps into the air at combat start
    context.boss:set_velocity_vector({ x = 0, y = 2.0, z = 0 })
    context.boss:send_message("&cThe boss leaps!")
  end
}

---

boss:restore_health(amount)

Heals the boss up to its maximum health.

Parameter	Type	Notes
amount	number	Amount to heal

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if not context.cooldowns:check_local("heal", 200) then return end
    context.boss:restore_health(20)
    context.boss:send_message("&aThe boss regenerates!")
    context.boss:spawn_particle_at_self("HEART")
  end
}

---

boss:play_sound_at_self(sound[, volume][, pitch])

Plays a sound at the boss's location.

Parameter	Type	Default	Notes
sound	string		Minecraft sound key (for example, "entity.wither.spawn") or a Spigot Sound enum name. Resource-pack keys work too.
volume	number	1.0	Volume
pitch	number	1.0	Pitch

Example

return {
  api_version = 1,
  on_spawn = function(context)
    context.boss:play_sound_at_self("entity.wither.spawn", 1.0, 0.8)
  end
}

---

boss:spawn_particle_at_self(particleOrSpec[, count])

Spawns particles at the boss's location.

Parameter	Type	Default	Notes
particleOrSpec	string or table		Particle name or spec table
count	number	1	Number of particles

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    context.boss:spawn_particle_at_self("SMOKE", 20)
    context.boss:send_message("&8Smoke billows from the boss!")
  end
}

---

boss:play_model_animation(name)

Plays a custom model animation on the boss if available.

Parameter	Type	Notes
name	string	Animation name

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    context.boss:play_model_animation("slam")
  end
}

---

boss:has_mount() / boss:get_mount()

Checks or returns the entity this boss is currently riding. boss:get_mount() returns nil if the boss has no mount. When a mount is returned, its wrapper has is_mount = true.

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    local mount = context.boss:get_mount()
    if mount ~= nil then
      context.log:info("Boss is mounted on " .. mount.entity_type)
    end
  end
}

---

boss:set_mount(entity) / boss:clear_mount() / boss:dismount()

Mounts or dismounts the boss. boss:set_mount(entity) makes the boss ride the supplied entity wrapper and returns true if Bukkit accepted the passenger change. boss:clear_mount() and boss:dismount() both make the boss leave its current vehicle.

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if not context.cooldowns:check_local("mount_check", 100) then return end
    if context.boss:has_mount() then
      context.boss:dismount()
    end
  end
}

---

boss:face_direction_or_location(vectorOrLocation)

Makes the boss face a direction or location.

Parameter	Type	Notes
vectorOrLocation	vector or location table	Direction to face

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    context.boss:face_direction_or_location(context.player:get_location())
  end
}

---

boss:navigate_to_location(location[, speed][, forceTeleport][, timeout])

Uses pathfinding to walk the boss to a location. Only works on custom bosses.

Parameter	Type	Default	Notes
location	location table		Destination
speed	number	1.0	Movement speed multiplier
forceTeleport	boolean	false	Teleport the boss to the destination if timeout elapses before it arrives
timeout	number	0	Give-up time in ticks. 0 means the built-in default of 100 ticks (5 seconds)

Navigation also stops on its own when the boss gets within 1 block of the destination, stops existing, or leaves the destination's world. Starting a new navigation cancels any navigation already running on that boss.

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if not context.cooldowns:check_local("charge", 200) then return end
    context.boss:navigate_to_location(context.player:get_location(), 1.5)
    context.boss:send_message("&cThe boss charges at you!")
  end
}

---

boss:add_tag(tag[, duration]) / boss:remove_tag(tag) / boss:has_tag(tag)

Manages tags on the boss.

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    local pct = context.boss:get_health() / context.boss:get_maximum_health()
    if pct < 0.5 and not context.boss:has_tag("phase2") then
      context.boss:add_tag("phase2")
      context.boss:send_message("&4Entering Phase 2!")
    end
  end
}

---

boss:send_message(message[, range])

Sends a chat message to all nearby players.

Parameter	Type	Default	Notes
message	string		Message text with color codes
range	number	20	Radius in blocks

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    context.boss:send_message("&4You dare challenge me?!")
  end
}

---

boss:summon_projectile(entityType, origin, destination[, speed][, options])

Launches a projectile-like entity from the boss.

Parameter	Type	Default	Notes
entityType	string		Entity type (e.g. "FIREBALL", "ARROW")
origin	location table		Launch position
destination	location table		Target position
speed	number	1.0	Projectile speed
options	table	{}	See options below

Options table:

Key	Type	Notes
duration	number	Auto-remove after ticks
max_ticks	number	Max ticks to monitor for landing
custom_damage	number	Damage on impact
detonation_power	string	Explosion power on impact
yield	number	Explosion yield (Fireball)
persistent	boolean	Whether the projectile persists (default true)
effect	string	EntityEffect name to play on spawn
incendiary	boolean	Whether explosion is incendiary
gravity	boolean	Whether projectile has gravity
glowing	boolean	Glowing effect
invulnerable	boolean	Whether projectile is invulnerable
track	boolean	Defaults to true: registers the projectile with EliteMobs. Does not make it home toward a target.
spawn_at_origin	boolean	Defaults to false: normal projectiles launch from the boss. Set true to spawn at the supplied origin.
direction_only	boolean	Use direction only, ignore target
on_land	function	Callback (landing_location, spawned_entity)

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if not context.cooldowns:check_local("fireball", 100) then return end
    context.boss:summon_projectile(
      "FIREBALL",
      context.boss:get_eye_location(),
      context.player:get_location(),
      1.5,
      {
        custom_damage = 10,
        on_land = function(loc, entity)
          context.world:spawn_particle_at_location(loc, "EXPLOSION")
        end
      }
    )
  end
}

---

boss:summon_reinforcement(filename[, zoneOrLocation][, level])

Summons a reinforcement boss from a config file.

Parameter	Type	Notes
filename	string	Boss config filename
zoneOrLocation	location table or zone	Optional spawn location or zone definition. Defaults to the boss location.
level	number	Optional reinforcement level. Defaults to 0, which lets the summon helper inherit/resolve level normally.

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    context.boss:summon_reinforcement("my_minion.yml", context.boss:get_location(), 0)
    context.boss:send_message("&cMinions, come to my aid!")
  end
}

---

boss:despawn()

Removes the boss from the world.

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    local pct = context.boss:get_health() / context.boss:get_maximum_health()
    if pct < 0.1 then
      context.boss:send_message("&7The boss vanishes into thin air!")
      context.boss:despawn()
    end
  end
}

---

boss:get_nearby_players(range)

Returns an array of player wrappers within range of the boss.

Parameter	Type	Notes
range	number	Radius in blocks

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    local players = context.boss:get_nearby_players(30)
    for _, p in ipairs(players) do
      p:show_action_bar("&cThe boss sees you!")
    end
  end
}

---

boss:get_damager_count()

Returns the live number of players that have damaged this boss. Unlike the damager_count field, this performs a live check.

---

boss:get_target_player()

Returns the boss's current mob target as a player wrapper, or nil if the target is not a player or is unset.

---

Zone & Particle Methods

These methods combine zones with particle effects. They require a zone table as input.

---

boss:get_nearby_players_in_zone(zone)

Returns an array of player wrappers for all players currently inside the given zone.

Parameter	Type	Notes
zone	zone table	A zone shape definition

---

boss:spawn_particles_in_zone(zone, particle[, amount][, x][, y][, z][, speed][, coverage])

Fills the interior of a zone with particles. The arguments are positional -- there is no spec table here.

Parameter	Type	Default	Notes
zone	zone table		Zone shape to fill (native kind style, see Zones & Targeting)
particle	string		Particle type name
amount	number	1	Particles per sampled location
x, y, z	number	0	Spread, or direction when amount is 0
speed	number	0	Particle speed
coverage	number	1.0	Fraction of the zone's locations to use. Clamped to 0.01-1.0; at least one location is always used

---

boss:spawn_particles_in_zone_border(zone, particle[, amount][, x][, y][, z][, speed][, coverage])

Same as above, but samples the zone's border locations instead of its interior.

---

boss:get_particles_from_self_toward_zone(zone, particle[, speed])

Returns an array of particle spec tables aimed outward, from the boss toward each sampled zone location. It does not spawn anything -- pass the result to boss:spawn_particles_with_vector(...).

Parameter	Type	Default	Notes
zone	zone table		Target zone
particle	string		Particle type name
speed	number	0.1	Particle travel speed written into each spec

Each returned entry is { location = ..., particle = ..., amount = 0, x/y/z = <unit direction>, speed = ... }. The zone is sampled at a fixed 20% coverage.

---

boss:get_particles_toward_self(zone, particle, speed)

The same, with the direction reversed: each particle points from its zone location back toward the boss. Also returns the array rather than spawning it.

Parameter	Type	Default	Notes
zone	zone table		Source zone
particle	string		Particle type name
speed	number		Pass an explicit speed such as 0.1; omitting it currently reads the particle argument as a number and fails.

---

boss:spawn_particles_with_vector(particles)

Spawns an array of directional particles, each with its own position and velocity vector.

Parameter	Type	Notes
particles	array of tables	Each entry defines a particle with position and direction

---

Ender Dragon Methods

These methods only apply when the boss entity is an Ender Dragon.

---

boss:get_ender_dragon_phase()

Returns the current EnderDragon.Phase name as a string, or nil if the boss is not an Ender Dragon.

---

boss:set_ender_dragon_phase(phase)

Sets the Ender Dragon's phase.

Parameter	Type	Notes
phase	string	EnderDragon.Phase name (e.g. "CIRCLING", "CHARGE_PLAYER")

---

Special Power Support Methods

These methods support built-in EliteMobs power mechanics from Lua scripts.

---

boss:start_tracking_fireball_system(speed?)

Starts the tracking fireball AI system on the boss. The boss will periodically launch fireballs that track its target.

Parameter	Type	Default	Notes
speed	number	0.5	Fireball speed

---

boss:handle_spirit_walk_damage(cause)

Handles spirit walk behavior for the given damage cause. Spirit walk makes the boss immune to certain damage types and teleport behind the attacker.

Parameter	Type	Notes
cause	string	Bukkit DamageCause name (e.g. "ENTITY_ATTACK", "PROJECTILE")

---

boss:shield_wall_is_active()

Returns true if the boss currently has an active shield wall.

---

boss:initialize_shield_wall(charges?)

Activates a shield wall on the boss that can absorb incoming damage.

Parameter	Type	Default	Notes
charges	number	1	Number of hits the shield can absorb

---

boss:shield_wall_absorb_damage(player, damage)

Attempts to absorb damage with the shield wall. Returns true if the damage was absorbed, false if the shield is inactive or depleted.

Parameter	Type	Notes
player	player wrapper	The attacking player
damage	number	Damage amount to absorb

---

boss:deactivate_shield_wall()

Deactivates the boss's shield wall, removing any remaining charges.

---

boss:start_zombie_necronomicon(target, file)

Starts the zombie necronomicon power on a target, spawning undead reinforcements from a config file.

Parameter	Type	Notes
target	entity wrapper	Target entity for the necronomicon
file	string	Boss config filename for the summoned undead

---

context.players

Player query helpers centered around the boss. Use these to find players without needing a specific player from the event.

Method	Returns	Notes
players:current_target()	player wrapper or nil	The event player or boss mob target if it is a player
players:nearby_players(radius)	array of player wrappers	All players within radius of the boss
players:all_players_in_world()	array of player wrappers	All players in the boss's world

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    local nearby = context.players:nearby_players(20)
    for _, player in ipairs(nearby) do
      player:send_message("&cThe boss is enraged!")
      player:apply_potion_effect("GLOWING", 60, 0)
    end
  end
}

Example

return {
  api_version = 1,
  on_spawn = function(context)
    -- Warn everyone in the world
    local everyone = context.players:all_players_in_world()
    for _, p in ipairs(everyone) do
      p:show_title("&4WARNING", "&7A world boss has spawned!", 10, 60, 20)
    end
  end
}

---

context.entities

General entity query helpers centered around the boss.

Method	Returns	Notes
entities:get_nearby_entities(radius[, filter])	array of entity wrappers	Nearby entities around the boss
entities:get_entities_in_box(center, halfX, halfY, halfZ[, filter])	array of entity wrappers	Entities within an axis-aligned box
entities:get_all_entities([filter])	array of entity wrappers	All matching entities in the boss world
entities:get_direct_target_entity()	entity wrapper or nil	Direct target for the current event
entities:get_boss_spawn_location()	location table	The boss's original spawn location

Valid filters: living (default), player / players, elite / elites, mob / mobs, all / entities

all / entities is only honoured by get_nearby_entities, and it is the one filter that returns non-living entities (dropped items, projectiles, armour stands, ...) — those come back as lighter reference wrappers rather than full entity wrappers. On the other methods it falls through to living. The boss itself is excluded from every result.

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Damage all nearby elites
    local elites = context.entities:get_nearby_entities(10, "elites")
    for _, elite in ipairs(elites) do
      elite:deal_damage(5)
    end
  end
}

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Find players in a box area
    local center = context.boss:get_location()
    local players = context.entities:get_entities_in_box(center, 10, 5, 10, "players")
    for _, p in ipairs(players) do
      p:send_message("&eYou are in the danger zone!")
    end
  end
}

---

Next Steps

• Getting Started | Hooks & Lifecycle | World & Environment | Zones & Targeting | Examples | Enums | Troubleshooting
• API Reference | Scripting Engine