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_monster	boolean	true for monster-type entities
entity.is_valid	boolean	Snapshot validity flag
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

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	70	Stay ticks
fadeOut	number	20	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	"RED"	BarColor value
style	string	"SOLID"	BarStyle value
duration	number	60	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	140	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
}

---

entity:remove_potion_effect(effect)

Removes an active potion effect from the entity.

Parameter	Type	Notes
effect	string	PotionEffectType name

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    -- Remove slowness when the player hits the boss
    context.player:remove_potion_effect("SLOWNESS")
    context.player:send_message("&aThe curse is lifted!")
  end
}

---

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:visual_fire(boolean)

Sets whether the entity visually appears on fire without taking fire damage.

Parameter	Type	Notes
enabled	boolean	true to show fire visual

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Boss appears on fire when combat starts
    context.boss:visual_fire(true)
    context.boss:send_message("&4The boss ignites with fury!")
  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
    -- Disable player gravity briefly and re-enable after 3 seconds
    context.player:set_gravity(false)
    context.player:send_message("&dYou begin to float!")
    context.scheduler:run_after(60, function()
      if context.player ~= nil and context.player:is_alive() then
        context.player: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		Bukkit Sound name
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_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
}

---

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
    context.player:set_custom_name("&c&lMarked Target")
    context.player:send_message("&cYou have been marked!")
    -- Reset after 5 seconds
    context.scheduler:run_after(100, function()
      if context.player ~= nil and context.player:is_alive() then
        context.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	40	Ticks before removal
requireAir	boolean	true	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
}

---

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, is_elite, current_location

Methods:

Method	Notes
is_valid()	Live validity check
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

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.

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

---

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:apply_potion_effect(effect, duration[, amplifier])

Applies a potion effect to the boss.

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_enter_combat = function(context)
    -- Boss gains speed when combat starts
    context.boss:apply_potion_effect("SPEED", 100, 1)
    context.boss:send_message("&cThe boss surges with speed!")
  end
}

---

boss:remove_potion_effect(effect)

Removes an active potion effect from the boss.

Parameter	Type	Notes
effect	string	PotionEffectType name

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    -- Remove speed buff when the boss takes damage
    context.boss:remove_potion_effect("SPEED")
    context.boss:send_message("&7The boss slows down!")
  end
}

---

boss:set_fire_ticks(ticks)

Sets the boss on fire.

Parameter	Type	Notes
ticks	number	Fire duration in ticks

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    context.boss:set_fire_ticks(100)
    context.boss:send_message("&4The boss ignites!")
  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:apply_push_vector(vector[, additive][, delay])

Applies a velocity push to the boss after a short delay.

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

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if not context.cooldowns:check_local("boss_jump", 100) then return end
    context.boss:apply_push_vector({ x = 0, y = 1.5, z = 0 })
    context.boss:send_message("&cThe boss leaps backward!")
  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		Bukkit Sound name
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: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][, follow][, timeout])

Uses pathfinding to walk the boss to a location.

Parameter	Type	Default	Notes
location	location table		Destination
speed	number	1.0	Movement speed multiplier
follow	boolean	false	Continuously follow the target
timeout	number	nil	Cancel navigation 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("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:set_invulnerable(enabled[, duration])

Toggles invulnerability on the boss.

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

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Boss is invulnerable for the first 3 seconds of combat
    context.boss:set_invulnerable(true, 60)
    context.boss:send_message("&6The boss is charging up!")
  end
}

---

boss:visual_fire(enabled)

Sets whether the boss visually appears on fire without taking fire damage.

Parameter	Type	Notes
enabled	boolean	true to show fire visual

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    context.boss:visual_fire(true)
    context.boss:send_message("&4The boss erupts in flames!")
  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:set_equipment(slot, material[, options])

Sets equipment on the boss.

Parameter	Type	Notes
slot	string	Equipment slot (e.g. "HAND", "HEAD")
material	string	Material name
options	table	Optional settings

Example

return {
  api_version = 1,
  on_spawn = function(context)
    context.boss:set_equipment("HAND", "DIAMOND_SWORD")
  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	number	Explosion power on impact
yield	number	Explosion yield (Fireball)
incendiary	boolean	Whether explosion is incendiary
gravity	boolean	Whether projectile has gravity
glowing	boolean	Glowing effect
invulnerable	boolean	Whether projectile is invulnerable
track	boolean	Whether to track the target
spawn_at_origin	boolean	Spawn at origin instead of offset
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[, duration])

Summons a reinforcement boss from a config file.

Parameter	Type	Notes
filename	string	Boss config filename
zoneOrLocation	location table or zone	Spawn location or zone definition
duration	number	Optional auto-despawn after ticks

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    context.boss:summon_reinforcement("my_minion.yml", context.boss:get_location(), 200)
    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
}

---

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

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

• World & Environment -- world interaction, spawning, blocks, sounds, and particles
• Zones & Targeting -- native Lua zones, zone watchers, and spatial queries
• Examples & Patterns -- complete working powers to study and adapt