Lua Scripting: World & Environment

This page covers every method available on context.world, context.vectors, context.settings, and context.event. These let your Lua powers interact with the Minecraft world -- spawning entities, playing effects, querying blocks, and more. If you are new to Lua powers, start with Getting Started first.

`context.world`

The world table provides methods for spawning entities, playing effects, modifying blocks, and changing world state. All methods are called with the colon syntax (world:method()).

`world:spawn_particle_at_location(location, particleSpec)`

Spawns particles at a location. The second argument can be a simple particle name string or a full particle spec table for advanced control.

Parameter	Type	Notes
`location`	location table	Where to spawn particles
`particleSpec`	string or table	Particle name or a particle spec table (see below)

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Simple particle by name
    context.world:spawn_particle_at_location(context.boss:get_location(), "FLAME")

    -- Full particle spec table with red dust
    context.world:spawn_particle_at_location(context.boss:get_location(), {
      particle = "DUST",
      amount = 10,
      x = 0.5,
      y = 0.5,
      z = 0.5,
      speed = 0.02,
      red = 255,
      green = 0,
      blue = 0,
    })
  end
}

Particle Spec Table Format

Key	Type	Default	Notes
`particle`	string	required	Particle name
`amount`	int	1	Number of particles
`x`, `y`, `z`	number	0	Spread/offset in each axis
`speed`	number	0	Particle speed
`red`, `green`, `blue`	int	255	RGB color for `DUST` and `DUST_COLOR_TRANSITION`
`toRed`, `toGreen`, `toBlue`	int	255	Transition target color for `DUST_COLOR_TRANSITION`

提示

For DUST_COLOR_TRANSITION, you can also use snake_case keys: to_red, to_green, to_blue.

`world:play_sound_at_location(location, sound, volume, pitch)`

Plays a sound at a location.

Parameter	Type	Default	Notes
`location`	location table		Where to play the sound
`sound`	string		Minecraft sound key (e.g. `"entity.blaze.shoot"`)
`volume`	number	`1.0`	Volume
`pitch`	number	`1.0`	Pitch

Example

return {
  api_version = 1,
  on_spawn = function(context)
    context.world:play_sound_at_location(
      context.boss:get_location(),
      "entity.wither.spawn",
      1.0,
      0.5
    )
  end
}

`world:strike_lightning_at_location(location)`

Strikes lightning at a location (visual and damaging).

Parameter	Type	Notes
`location`	location table	Where to strike

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("lightning", 100) then return end
    context.world:strike_lightning_at_location(context.player:get_location())
    context.player:send_message("&eA bolt of lightning strikes you!")
  end
}

`world:spawn_entity_at_location(entityType, location, options)`

Spawns a vanilla Minecraft entity.

Parameter	Type	Notes
`entityType`	string	Entity type name (e.g. `"FIREBALL"`, `"ARROW"`)
`location`	location table	Where to spawn
`options`	table (optional)	Spawn options (see below)

Entity Spawn Options

Key	Type	Default	Notes
`velocity`	vector table	`nil`	Initial velocity `{x, y, z}`
`effect`	string	`nil`	EntityEffect to play on spawn
`duration`	int	`0`	Auto-remove after this many ticks (0 = never)
`on_land`	function	`nil`	Callback when the entity lands on the ground
`max_ticks`	int	`6000`	Max ticks to monitor before forcing the `on_land` callback

Returns an entity wrapper table.

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_spawn", 100) then return end
    -- Spawn a fireball aimed at the player
    local boss_loc = context.boss:get_location()
    local dir = context.vectors.get_vector_between_locations(boss_loc, context.player:get_location())
    dir = context.vectors.normalize_vector(dir)

    context.world:spawn_entity_at_location("FIREBALL", boss_loc, {
      velocity = { x = dir.x * 2, y = dir.y * 2, z = dir.z * 2 },
      duration = 100,
    })
  end
}

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Spawn a primed TNT with a landing callback
    context.world:spawn_entity_at_location("TNT", context.boss:get_location(), {
      velocity = { x = 0, y = 1.5, z = 0 },
      on_land = function(land_location, entity_ref)
        context.world:spawn_particle_at_location(land_location, {
          particle = "EXPLOSION_EMITTER",
          amount = 1,
        })
      end,
    })
  end
}

`world:spawn_falling_block_at_location(location, material, options)`

Spawns a falling block entity.

Parameter	Type	Notes
`location`	location table	Where to spawn
`material`	string	Material name (e.g. `"STONE"`, `"MAGMA_BLOCK"`)
`options`	table (optional)	Spawn options (see below)

Falling Block Options

Key	Type	Default	Notes
`velocity`	vector table	`nil`	Initial velocity `{x, y, z}`
`drop_item`	boolean	`false`	Whether the block drops as an item
`hurt_entities`	boolean	`false`	Whether the block damages entities it lands on
`on_land`	function	`nil`	Callback `function(land_location, entity_ref)` when the block lands

Returns an entity reference table.

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Rain magma blocks from above
    local loc = context.boss:get_location()
    for i = 1, 5 do
      local offset_loc = {
        x = loc.x + math.random(-3, 3),
        y = loc.y + 10,
        z = loc.z + math.random(-3, 3),
        world = loc.world
      }
      context.world:spawn_falling_block_at_location(offset_loc, "MAGMA_BLOCK", {
        velocity = { x = 0, y = -0.5, z = 0 },
        hurt_entities = true,
        on_land = function(land_location, entity_ref)
          context.world:spawn_particle_at_location(land_location, { particle = "LAVA", amount = 8 })
        end,
      })
    end
  end
}

`world:spawn_custom_boss_at_location(filename, location, options)`

Spawns an EliteMobs custom boss from a config file.

Parameter	Type	Notes
`filename`	string	Boss config filename (e.g. `"my_boss.yml"`)
`location`	location table	Where to spawn
`options`	table (optional)	Spawn options (see below)

Custom Boss Spawn Options

Key	Type	Default	Notes
`level`	int	boss level	Override the spawned boss level
`silent`	boolean	`false`	Suppress spawn messages
`velocity`	vector table	`nil`	Initial velocity
`add_as_reinforcement`	boolean	`false`	Register as a reinforcement of the current boss

Returns an entity wrapper table, or nil if the boss could not be created.

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    local minion = context.world:spawn_custom_boss_at_location(
      "skeleton_minion.yml",
      context.boss:get_location(),
      { level = 10, add_as_reinforcement = true }
    )
    if minion ~= nil then
      context.boss:send_message("&cMinions, arise!")
    end
  end
}

`world:spawn_boss_at_location(filename, location, level)`

A simpler boss spawn method. Spawns a custom boss at a location with an optional level.

Parameter	Type	Default	Notes
`filename`	string		Boss config filename
`location`	location table	boss location	Where to spawn (optional, defaults to boss location)
`level`	int	boss level	Override spawn level (optional)

Returns an entity wrapper table, or nil.

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    context.world:spawn_boss_at_location("zombie_guard.yml", context.boss:get_location(), 5)
    context.boss:send_message("&cGuards, defend me!")
  end
}

`world:spawn_reinforcement_at_location(filename, location, inheritLevel, velocity)`

Spawns a reinforcement that is tracked by the EliteMobs reinforcement system.

Parameter	Type	Default	Notes
`filename`	string		Boss config filename
`location`	location table		Where to spawn
`inheritLevel`	int	`0`	Level inheritance mode (0 = default)
`velocity`	vector table	`nil`	Initial velocity (optional)

Returns an entity wrapper table, or nil.

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    context.world:spawn_reinforcement_at_location(
      "necro_skeleton.yml",
      context.boss:get_location(),
      0,
      { x = 0, y = 0.5, z = 0 }
    )
    context.boss:send_message("&5Rise, my servant!")
  end
}

`world:spawn_fireworks_at_location(location, spec)`

Spawns a firework entity with full control over effects.

Parameter	Type	Notes
`location`	location table	Where to spawn
`spec`	table	Firework specification (see below)

Firework Spec Table

Key	Type	Default	Notes
`power`	int	`1`	Flight power (height)
`velocity`	vector table	`nil`	Initial velocity
`shot_at_angle`	boolean	`true`	Whether the firework is shot at an angle (used when velocity is set)
`effects`	table of tables	`nil`	Array of firework effect specs. If omitted, the top-level spec is treated as a single effect.

Firework Effect Spec

Key	Type	Default	Notes
`type`	string	`"BALL_LARGE"`	`"BALL"`, `"BALL_LARGE"`, `"STAR"`, `"BURST"`, `"CREEPER"`
`flicker`	boolean	`true`	Twinkle effect
`trail`	boolean	`true`	Trail effect
`colors`	table	`nil`	Array of color names or `{red, green, blue}` tables
`fade_colors`	table	`nil`	Array of fade color names or `{red, green, blue}` tables

Color names: "WHITE", "SILVER", "GRAY", "BLACK", "RED", "MAROON", "YELLOW", "OLIVE", "LIME", "GREEN", "AQUA", "TEAL", "BLUE", "NAVY", "FUCHSIA", "PURPLE", "ORANGE"

Returns an entity reference table. You can call :detonate() on it to force immediate detonation.

Example

return {
  api_version = 1,
  on_spawn = function(context)
    local fw = context.world:spawn_fireworks_at_location(context.boss:get_location(), {
      power = 0,
      effects = {
        {
          type = "STAR",
          flicker = true,
          trail = true,
          colors = { "RED", "ORANGE", { red = 255, green = 200, blue = 0 } },
          fade_colors = { "YELLOW" },
        },
      },
    })

    -- Detonate immediately for a visual burst
    context.scheduler:run_after(1, function()
      fw:detonate()
    end)
  end
}

`world:spawn_splash_potion_at_location(location, spec)`

Spawns a thrown splash potion entity.

Parameter	Type	Notes
`location`	location table	Where to spawn
`spec`	table	Potion specification (see below)

Splash Potion Spec Table

Key	Type	Notes
`velocity`	vector table	Initial velocity for the thrown potion
`effects`	table of tables	Array of potion effect specs

Potion Effect Spec

Key	Type	Default	Notes
`type`	string	required	Potion effect type name (e.g. `"SLOWNESS"`, `"POISON"`)
`duration`	int	`0`	Duration in ticks
`amplifier`	int	`0`	Effect amplifier (0 = level I)
`overwrite`	boolean	`true`	Whether to overwrite existing effects of the same type

Returns an entity reference table, or nil.

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("potion_throw", 200) then return end

    local dir = context.vectors.get_vector_between_locations(
      context.boss:get_location(),
      context.player:get_location()
    )
    dir = context.vectors.normalize_vector(dir)

    context.world:spawn_splash_potion_at_location(context.boss:get_location(), {
      velocity = { x = dir.x * 1.5, y = 0.5, z = dir.z * 1.5 },
      effects = {
        { type = "SLOWNESS", duration = 100, amplifier = 1 },
        { type = "WEAKNESS", duration = 60, amplifier = 0 },
      },
    })
  end
}

`world:place_temporary_block_at_location(location, material, duration, requireAir)`

Places a temporary block that reverts automatically after a duration.

Parameter	Type	Default	Notes
`location`	location table		Where to place
`material`	string		Material name
`duration`	int	`0`	Ticks before the block reverts (0 = permanent)
`requireAir`	boolean	`false`	If `true`, only places if the block is currently air

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Create a temporary ice floor under the boss
    local loc = context.boss:get_location()
    for dx = -2, 2 do
      for dz = -2, 2 do
        context.world:place_temporary_block_at_location(
          { x = loc.x + dx, y = loc.y - 1, z = loc.z + dz, world = loc.world },
          "PACKED_ICE",
          100,
          false
        )
      end
    end
  end
}

`world:set_block_at_location(location, material, requireAir)`

Permanently sets a block. Use place_temporary_block_at_location if you want it to revert.

Parameter	Type	Default	Notes
`location`	location table		Where to place
`material`	string		Material name
`requireAir`	boolean	`false`	If `true`, only places if the block is currently air

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Place fire at the boss's location
    context.world:set_block_at_location(context.boss:get_location(), "FIRE", true)
  end
}

`world:get_block_type_at_location(location)`

Returns the material name of the block at a location as a string.

Parameter	Type	Notes
`location`	location table	Location to query

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    local block_type = context.world:get_block_type_at_location(context.boss:get_location())
    if block_type == "WATER" then
      context.boss:send_message("&bThe boss is empowered by water!")
      context.boss:apply_potion_effect("SPEED", 200, 1)
    end
  end
}

`world:get_highest_block_y_at_location(location)`

Returns the Y coordinate of the highest non-air block at the given X/Z position.

Parameter	Type	Notes
`location`	location table	Location to query (X and Z are used)

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("skyport", 200) then return end
    local loc = context.player:get_location()
    local ground_y = context.world:get_highest_block_y_at_location(loc)
    -- Teleport the player to the surface
    context.player:teleport_to_location({
      x = loc.x, y = ground_y + 1, z = loc.z, world = loc.world
    })
    context.player:send_message("&eYou are teleported to the surface!")
  end
}

`world:get_blast_resistance_at_location(location)`

Returns the blast resistance of the block at a location as a number.

Parameter	Type	Notes
`location`	location table	Location to query

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    local resistance = context.world:get_blast_resistance_at_location(context.boss:get_location())
    context.log:info("Blast resistance at boss: " .. resistance)
  end
}

`world:is_air_at_location(location)`

Returns true if the block at the location is air.

Parameter	Type	Notes
`location`	location table	Location to query

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    local loc = context.boss:get_location()
    local above = { x = loc.x, y = loc.y + 2, z = loc.z, world = loc.world }
    if context.world:is_air_at_location(above) then
      -- There is space above the boss, launch upward
      context.boss:set_velocity_vector({ x = 0, y = 1.5, z = 0 })
    end
  end
}

`world:is_passable_at_location(location)`

Returns true if the block at the location is passable (entities can walk through it).

Parameter	Type	Notes
`location`	location table	Location to query

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    if context.world:is_passable_at_location(context.boss:get_location()) then
      context.log:info("Boss is in a passable block")
    end
  end
}

`world:is_passthrough_at_location(location)`

Returns true if the block at the location is not solid (similar to passable, but based on solid check).

Parameter	Type	Notes
`location`	location table	Location to query

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    local loc = context.boss:get_location()
    local above = { x = loc.x, y = loc.y + 1, z = loc.z, world = loc.world }
    if context.world:is_passthrough_at_location(above) then
      context.log:info("Boss can move upward")
    end
  end
}

`world:is_on_floor_at_location(location)`

Returns true if the block at the location is non-solid AND the block below it is solid (i.e. the location is "standing on the floor").

Parameter	Type	Notes
`location`	location table	Location to query

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    if context.world:is_on_floor_at_location(context.boss:get_location()) then
      context.boss:send_message("&aThe boss slams the ground!")
      context.world:spawn_particle_at_location(context.boss:get_location(), {
        particle = "BLOCK",
        amount = 30,
      })
    end
  end
}

`world:is_standing_on_material(location, material)`

Returns true if the block directly below the location matches the given material.

Parameter	Type	Notes
`location`	location table	Location to query
`material`	string	Material name to check

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if context.world:is_standing_on_material(context.player:get_location(), "SOUL_SAND") then
      context.player:send_message("&8The soul sand saps your strength!")
      context.player:apply_potion_effect("SLOWNESS", 60, 2)
    end
  end
}

`world:set_world_time(time)` / `world:set_world_time(location, time)`

Sets the world time. You can optionally pass a location to specify which world.

Parameter	Type	Notes
`location`	location table (optional)	Which world to affect. Defaults to the boss world.
`time`	int	World time in ticks (0 = dawn, 6000 = noon, 13000 = night, 18000 = midnight)

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Set to midnight when combat starts
    context.world:set_world_time(18000)
    context.boss:send_message("&8Darkness falls...")
  end
}

`world:set_world_weather(weather, duration)` / `world:set_world_weather(location, weather, duration)`

Sets the weather in the boss world.

Parameter	Type	Default	Notes
`location`	location table (optional)	boss world	Which world to affect
`weather`	string		`"CLEAR"`, `"RAIN"` (or `"PRECIPITATION"`), `"THUNDER"`
`duration`	int	`6000`	Weather duration in ticks

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Start a thunderstorm for 200 ticks
    context.world:set_world_weather("THUNDER", 200)
    context.boss:send_message("&eA storm gathers!")
  end
}

`world:generate_fake_explosion(blockLocations, sourceLocation)`

Creates a fake explosion visual using the EliteMobs explosion regen system (blocks break and regenerate).

Parameter	Type	Notes
`blockLocations`	table of location tables	Array of block locations to "explode"
`sourceLocation`	location table (optional)	Explosion source for directional calculations

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    local loc = context.boss:get_location()
    local blocks = {}
    for dx = -1, 1 do
      for dz = -1, 1 do
        table.insert(blocks, { x = loc.x + dx, y = loc.y, z = loc.z + dz, world = loc.world })
      end
    end
    context.world:generate_fake_explosion(blocks, loc)
  end
}

`world:run_console_command(command)`

Executes a console command as the server.

Parameter	Type	Notes
`command`	string	The command to run (without the leading `/`)

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    context.world:run_console_command("say The boss has entered phase 2!")
  end
}

`world:run_empowered_lightning_task_at_location(location)`

Runs the empowered lightning visual task (used by Ender Dragon powers). This creates a more dramatic lightning strike with additional effects.

Parameter	Type	Notes
`location`	location table	Where to strike

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    context.world:run_empowered_lightning_task_at_location(context.boss:get_location())
    context.boss:send_message("&eFeel the power of the storm!")
  end
}

`world:spawn_fake_gold_nugget_at_location(location, velocity, hasGravity)`

Spawns a fake gold nugget projectile used by the bullet hell system.

Parameter	Type	Default	Notes
`location`	location table		Spawn location
`velocity`	vector table		Initial velocity
`hasGravity`	boolean	`false`	Whether the projectile has gravity

Returns a fake projectile table with methods: get_location(), set_gravity(bool), remove(), is_removed().

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("nugget", 60) then return end

    local dir = context.vectors.get_vector_between_locations(
      context.boss:get_location(),
      context.player:get_location()
    )
    dir = context.vectors.normalize_vector(dir)

    context.world:spawn_fake_gold_nugget_at_location(
      context.boss:get_location(),
      { x = dir.x, y = dir.y, z = dir.z }
    )
  end
}

`world:run_fake_gold_nugget_damage(projectiles)`

Processes damage for a table of fake gold nugget projectiles against nearby entities.

Parameter	Type	Notes
`projectiles`	table	Array of fake projectile tables from `spawn_fake_gold_nugget_at_location`

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Spawn some projectiles and store them
    context.state.active_projectiles = {}
    local loc = context.boss:get_location()
    for i = 1, 5 do
      local angle = (i / 5) * math.pi * 2
      local nugget = context.world:spawn_fake_gold_nugget_at_location(
        loc,
        { x = math.cos(angle) * 0.5, y = 0.3, z = math.sin(angle) * 0.5 }
      )
      table.insert(context.state.active_projectiles, nugget)
    end

    -- Process damage each tick for 3 seconds
    context.scheduler:run_every(1, function()
      context.world:run_fake_gold_nugget_damage(context.state.active_projectiles)
    end, 60)
  end
}

`world:generate_player_loot(times)`

Generates loot for players who damaged the boss.

Parameter	Type	Default	Notes
`times`	int	`1`	Number of loot rolls

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("bonus_loot") then
      context.boss:add_tag("bonus_loot")
      context.world:generate_player_loot(2)
      context.boss:send_message("&6Bonus loot drops!")
    end
  end
}

`world:drop_bonus_coins(multiplier)`

Drops bonus coins for all players who contributed to damaging the boss.

Parameter	Type	Default	Notes
`multiplier`	number	`2.0`	Coin amount multiplier

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.25 and not context.boss:has_tag("bonus_coins") then
      context.boss:add_tag("bonus_coins")
      context.world:drop_bonus_coins(3.0)
      context.boss:send_message("&6Gold spills everywhere!")
    end
  end
}

`context.vectors`

Vector math helpers. These are called as regular functions (dot syntax), not methods.

Method	Returns	Notes
`vectors.get_vector_between_locations(loc1, loc2[, options])`	vector table	Direction from `loc1` to `loc2`
`vectors.normalize_vector(vec)`	vector table	Returns a unit-length vector
`vectors.rotate_vector(vec, pitch, yaw)`	vector table	Rotates a vector by pitch and yaw degrees

All vector tables have fields x, y, z.

`vectors.get_vector_between_locations(loc1, loc2, options)`

Parameter	Type	Notes
`loc1`	location table	Start point
`loc2`	location table	End point
`options`	table (optional)	Post-processing options (see below)

Vector Options

Key	Type	Default	Notes
`normalize`	boolean	`false`	Normalize the resulting vector
`multiplier`	number	`1.0`	Scale the vector
`offset`	vector table	`nil`	Add an offset vector

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("dash", 100) then return end
    -- Compute a normalized direction from boss to player, scaled to speed 2
    local dir = context.vectors.get_vector_between_locations(
      context.boss:get_location(),
      context.player:get_location(),
      { normalize = true, multiplier = 2.0 }
    )
    -- Launch the boss toward the player
    context.boss:set_velocity_vector(dir)
  end
}

`vectors.normalize_vector(vec)`

Parameter	Type	Notes
`vec`	vector table	Input vector

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    local raw = context.vectors.get_vector_between_locations(
      context.boss:get_location(),
      context.player:get_location()
    )
    local unit = context.vectors.normalize_vector(raw)
    context.log:info("Direction: " .. unit.x .. ", " .. unit.y .. ", " .. unit.z)
  end
}

`vectors.rotate_vector(vec, pitch, yaw)`

Parameter	Type	Notes
`vec`	vector table	Input vector
`pitch`	number	Rotation around X axis in degrees
`yaw`	number	Rotation around Y axis in degrees

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("spread_shot", 100) then return end
    local forward = context.vectors.normalize_vector(
      context.vectors.get_vector_between_locations(
        context.boss:get_location(),
        context.player:get_location()
      )
    )
    -- Fire three fireballs in a spread pattern
    for _, yaw_offset in ipairs({ -30, 0, 30 }) do
      local dir = context.vectors.rotate_vector(forward, 0, yaw_offset)
      context.boss:summon_projectile(
        "FIREBALL",
        context.boss:get_eye_location(),
        {
          x = context.boss:get_location().x + dir.x * 10,
          y = context.boss:get_location().y + dir.y * 10,
          z = context.boss:get_location().z + dir.z * 10,
          world = context.boss:get_location().world
        },
        1.0
      )
    end
  end
}

提示

You can build a spread of directions by rotating a base vector in a loop:

local base = context.vectors.normalize_vector(
  context.vectors.get_vector_between_locations(boss_loc, target_loc)
)
for angle = 0, 360, 30 do
  local dir = context.vectors.rotate_vector(base, 0, angle)
  -- Use dir for spawning projectiles in a ring
end

`context.settings`

Read-only access to power-related configuration values.

Method	Returns	Notes
`settings.warning_visual_effects_enabled`	boolean	Whether warning visual effects are enabled in the mob combat settings

Example

return {
  api_version = 1,
  on_enter_combat = function(context)
    if context.settings.warning_visual_effects_enabled then
      context.world:spawn_particle_at_location(context.boss:get_location(), {
        particle = "DUST",
        amount = 20,
        red = 255, green = 0, blue = 0,
      })
    end
  end
}

`context.event`

Event data for the current hook. The available fields depend on which hook triggered the call.

Field or Method	When Available	Notes
`event.damage_amount`	Damage hooks	The current damage amount (snapshot at call time)
`event.damage_cause`	Damage hooks	Bukkit `DamageCause` enum name (e.g. `"ENTITY_ATTACK"`)
`event.cancel_event()`	Cancellable events	Cancels the event
`event.set_damage_amount(value)`	`EliteDamageEvent`-based hooks	Sets the damage directly
`event.multiply_damage_amount(multiplier)`	`EliteDamageEvent`-based hooks	Multiplies current damage
`event.damager`	Damage events with a damager entity	Entity reference wrapper for the damager
`event.projectile`	Damage events where damager is a projectile	Projectile entity reference wrapper
`event.spawn_reason`	`on_spawn`	Spawn reason enum name
`event.entity`	`on_death`, zone events	The relevant entity wrapper

Example: Halving incoming damage

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.event ~= nil then
      local dmg = context.event.damage_amount
      context.log:info("Boss took " .. dmg .. " damage, halving it")
      context.event:multiply_damage_amount(0.5)
    end
  end
}

Example: Cancelling damage from projectiles

Example

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.event ~= nil and context.event.damage_cause == "PROJECTILE" then
      context.event:cancel_event()
      if context.player ~= nil then
        context.player:send_message("&cThe boss deflects your projectile!")
      end
    end
  end
}

Example: Reading damage cause

Example

return {
  api_version = 1,
  on_player_damaged_by_boss = function(context)
    if context.event ~= nil then
      context.log:info("Damage cause: " .. (context.event.damage_cause or "unknown"))
    end
  end
}

备注

damage_amount is a snapshot. It does not auto-refresh after calling set_damage_amount() or multiply_damage_amount().
Inside scheduled callbacks, context.event is nil. Use event hooks for event modification.

Next Steps

Zones & Targeting -- zone queries, watchers, and entity targeting
Boss & Entities -- boss wrapper, entity methods, player methods
Examples -- full working Lua power examples

context.world
context.vectors
context.settings
context.event
Next Steps

context.world​

world:spawn_particle_at_location(location, particleSpec)​

Particle Spec Table Format​

world:play_sound_at_location(location, sound, volume, pitch)​

world:strike_lightning_at_location(location)​

world:spawn_entity_at_location(entityType, location, options)​

Entity Spawn Options​

world:spawn_falling_block_at_location(location, material, options)​

Falling Block Options​

world:spawn_custom_boss_at_location(filename, location, options)​

Custom Boss Spawn Options​

world:spawn_boss_at_location(filename, location, level)​

world:spawn_reinforcement_at_location(filename, location, inheritLevel, velocity)​

world:spawn_fireworks_at_location(location, spec)​

Firework Spec Table​

Firework Effect Spec​

world:spawn_splash_potion_at_location(location, spec)​

Splash Potion Spec Table​

Potion Effect Spec​

world:place_temporary_block_at_location(location, material, duration, requireAir)​

world:set_block_at_location(location, material, requireAir)​

world:get_block_type_at_location(location)​

world:get_highest_block_y_at_location(location)​

world:get_blast_resistance_at_location(location)​

world:is_air_at_location(location)​

world:is_passable_at_location(location)​

world:is_passthrough_at_location(location)​

world:is_on_floor_at_location(location)​

world:is_standing_on_material(location, material)​

world:set_world_time(time) / world:set_world_time(location, time)​

world:set_world_weather(weather, duration) / world:set_world_weather(location, weather, duration)​

world:generate_fake_explosion(blockLocations, sourceLocation)​

world:run_console_command(command)​

world:run_empowered_lightning_task_at_location(location)​

world:spawn_fake_gold_nugget_at_location(location, velocity, hasGravity)​

world:run_fake_gold_nugget_damage(projectiles)​

world:generate_player_loot(times)​

world:drop_bonus_coins(multiplier)​

context.vectors​

vectors.get_vector_between_locations(loc1, loc2, options)​

Vector Options​

vectors.normalize_vector(vec)​

vectors.rotate_vector(vec, pitch, yaw)​

context.settings​

context.event​

Example: Halving incoming damage​

Example: Cancelling damage from projectiles​

Example: Reading damage cause​

Next Steps​

`context.world`

`world:spawn_particle_at_location(location, particleSpec)`

Particle Spec Table Format

`world:play_sound_at_location(location, sound, volume, pitch)`

`world:strike_lightning_at_location(location)`

`world:spawn_entity_at_location(entityType, location, options)`

Entity Spawn Options

`world:spawn_falling_block_at_location(location, material, options)`

Falling Block Options

`world:spawn_custom_boss_at_location(filename, location, options)`

Custom Boss Spawn Options

`world:spawn_boss_at_location(filename, location, level)`

`world:spawn_reinforcement_at_location(filename, location, inheritLevel, velocity)`

`world:spawn_fireworks_at_location(location, spec)`

Firework Spec Table

Firework Effect Spec

`world:spawn_splash_potion_at_location(location, spec)`

Splash Potion Spec Table

Potion Effect Spec

`world:place_temporary_block_at_location(location, material, duration, requireAir)`

`world:set_block_at_location(location, material, requireAir)`

`world:get_block_type_at_location(location)`

`world:get_highest_block_y_at_location(location)`

`world:get_blast_resistance_at_location(location)`

`world:is_air_at_location(location)`

`world:is_passable_at_location(location)`

`world:is_passthrough_at_location(location)`

`world:is_on_floor_at_location(location)`

`world:is_standing_on_material(location, material)`

`world:set_world_time(time)` / `world:set_world_time(location, time)`

`world:set_world_weather(weather, duration)` / `world:set_world_weather(location, weather, duration)`

`world:generate_fake_explosion(blockLocations, sourceLocation)`

`world:run_console_command(command)`

`world:run_empowered_lightning_task_at_location(location)`

`world:spawn_fake_gold_nugget_at_location(location, velocity, hasGravity)`

`world:run_fake_gold_nugget_damage(projectiles)`

`world:generate_player_loot(times)`

`world:drop_bonus_coins(multiplier)`

`context.vectors`

`vectors.get_vector_between_locations(loc1, loc2, options)`

Vector Options

`vectors.normalize_vector(vec)`

`vectors.rotate_vector(vec, pitch, yaw)`

`context.settings`

`context.event`

Example: Halving incoming damage

Example: Cancelling damage from projectiles

Example: Reading damage cause

Next Steps