Lua-Scripting: Boss & Entitäten

Diese Seite behandelt alles über Boss- und Entity-Wrapper in EliteMobs Lua-Powers: context.boss, context.player, context.players, context.entities und die Entity-Wrapper-Tabellen, die sie zurückgeben. Wenn Sie neu bei Lua-Powers sind, beginnen Sie zuerst mit Erste Schritte.

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_sound_at_self(sound[, volume][, pitch])`

Alias for play_sound_at_entity. Plays a sound at the entity's location. Both names work identically.

`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
}

`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
}

`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_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

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.

vorsicht

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.

tipp

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

`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		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: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`	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

Entity Wrappers
Common Entity Fields
Common Entity Methods
Non-Living Entity Reference Wrappers
context.player
- Player-Only Fields
- Player-Only Methods
context.boss
- Boss Fields
- Boss Methods
context.players
context.entities
Next Steps

Entity Wrappers​

Common Entity Fields​

Common Entity Methods​

entity:is_alive()​

entity:get_location()​

entity:get_eye_location()​

entity:get_health() / entity:get_maximum_health()​

entity:get_velocity()​

entity:send_message(text)​

entity:show_action_bar(message)​

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

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

entity:teleport_to_location(location)​

entity:set_velocity_vector(vector)​

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

entity:face_direction_or_location(directionOrLocation)​

entity:set_fire_ticks(ticks)​

entity:add_visual_freeze_ticks([ticks])​

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

entity:remove_potion_effect(effect)​

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

entity:restore_health(amount)​

entity:set_invulnerable(enabled[, duration])​

entity:set_ai_enabled(enabled[, duration])​

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

entity:run_command(command)​

entity:visual_fire(boolean)​

entity:set_scale(scale[, duration])​

entity:set_gravity(enabled)​

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

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

entity:spawn_particle_at_self(particleOrSpec[, count])​

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

entity:play_model_animation(name)​

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

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

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

entity:get_height()​

entity:is_on_ground()​

entity:is_frozen()​

entity:set_awareness_enabled(aware[, duration])​

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

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

entity:remove_elite()​

entity:set_custom_name_visible(visible)​

Non-Living Entity Reference Wrappers​

context.player​

Player-Only Fields​

Player-Only Methods​

context.boss​

Boss Fields​

Boss Methods​

boss:is_alive()​

boss:get_location()​

boss:get_eye_location()​

boss:set_ai_enabled(enabled[, duration])​

boss:teleport_to_location(location)​

boss:set_velocity_vector(vector)​

boss:restore_health(amount)​

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

boss:spawn_particle_at_self(particleOrSpec[, count])​

boss:play_model_animation(name)​

boss:face_direction_or_location(vectorOrLocation)​

boss:navigate_to_location(location[, speed][, follow][, timeout])​

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

boss:send_message(message[, range])​

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

boss:summon_reinforcement(filename, zoneOrLocation[, duration])​

boss:despawn()​

boss:get_nearby_players(range)​

context.players​

context.entities​

Next Steps​

Entity Wrappers

Common Entity Fields

Common Entity Methods

`entity:is_alive()`

`entity:get_location()`

`entity:get_eye_location()`

`entity:get_health()` / `entity:get_maximum_health()`

`entity:get_velocity()`

`entity:send_message(text)`

`entity:show_action_bar(message)`

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

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

`entity:teleport_to_location(location)`

`entity:set_velocity_vector(vector)`

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

`entity:face_direction_or_location(directionOrLocation)`

`entity:set_fire_ticks(ticks)`

`entity:add_visual_freeze_ticks([ticks])`

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

`entity:remove_potion_effect(effect)`

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

`entity:restore_health(amount)`

`entity:set_invulnerable(enabled[, duration])`

`entity:set_ai_enabled(enabled[, duration])`

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

`entity:run_command(command)`

`entity:visual_fire(boolean)`

`entity:set_scale(scale[, duration])`

`entity:set_gravity(enabled)`

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

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

`entity:spawn_particle_at_self(particleOrSpec[, count])`

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

`entity:play_model_animation(name)`

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

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

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

`entity:get_height()`

`entity:is_on_ground()`

`entity:is_frozen()`

`entity:set_awareness_enabled(aware[, duration])`

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

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

`entity:remove_elite()`

`entity:set_custom_name_visible(visible)`

Non-Living Entity Reference Wrappers

`context.player`

Player-Only Fields

Player-Only Methods

`context.boss`

Boss Fields

Boss Methods

`boss:is_alive()`

`boss:get_location()`

`boss:get_eye_location()`

`boss:set_ai_enabled(enabled[, duration])`

`boss:teleport_to_location(location)`

`boss:set_velocity_vector(vector)`

`boss:restore_health(amount)`

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

`boss:spawn_particle_at_self(particleOrSpec[, count])`

`boss:play_model_animation(name)`

`boss:face_direction_or_location(vectorOrLocation)`

`boss:navigate_to_location(location[, speed][, follow][, timeout])`

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

`boss:send_message(message[, range])`

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

`boss:summon_reinforcement(filename, zoneOrLocation[, duration])`

`boss:despawn()`

`boss:get_nearby_players(range)`

`context.players`

`context.entities`

Next Steps