Scripting Lua: Mundo y entorno

Esta página explica los métodos disponibles en context.world, context.vectors, context.settings y context.event. Permiten que tus poderes Lua interactúen con el mundo de Minecraft: generar entidades, reproducir efectos, consultar bloques y más. Si estás empezando a crear poderes Lua, lee primero Primeros pasos.

Contexto de jefe de EliteMobs

Los poderes de jefe de EliteMobs reutilizan el entorno aislado Lua de MagmaCore. La tabla context.world del jefe parte de la tabla de mundo compartida de MagmaCore, por lo que las funciones genéricas de coordenadas, como get_block_at(...), set_block_at(...) y spawn_particle(...), siguen disponibles. Esta página se centra en las adiciones y sustituciones de EliteMobs para context.world, context.vectors, context.settings y context.event en poderes de jefe. Para la API genérica del mundo, consulta Motor de scripting Lua de MagmaCore.

Cuando existe un método con el mismo nombre en ambas tablas, prevalece la versión de EliteMobs: cada método *_at_location documentado abajo sustituye al compartido para mantener el comportamiento de EliteMobs en los scripts de jefe: rayos que omiten las protecciones, especificaciones ampliadas de partículas y seguimiento de bloques temporales.

Las funciones de botín solo aparecen con FreeMinecraftModels instalado

Cuando FreeMinecraftModels también está instalado en el servidor, registra tres métodos adicionales en la tabla de mundo compartida, que heredan los poderes de jefe: world:drop_elitemobs_procedural_loot(player, level[, location]), world:drop_elitemobs_random_loot(player, level[, location]) y world:drop_elitemobs_custom_loot(player, filename, level[, location]). Cada método acepta una tabla de jugador, una cadena UUID o el nombre del jugador; usa la ubicación del propio jugador si se omite location o no es válida, y devuelve un booleano. Devuelven false en lugar de lanzar un error si falta alguno de los dos plugins.

---

context.world

La tabla de mundo ofrece métodos para generar entidades, reproducir efectos, modificar bloques y cambiar el estado del mundo. Todos los métodos se llaman con dos puntos (world:method()).

---

world:spawn_particle_at_location(location, particleSpec)

Genera partículas en una ubicación. El segundo argumento puede ser una cadena con el nombre de la partícula o una tabla de especificación completa para un control avanzado.

Parámetro	Tipo	Notas
location	tabla de ubicación	Dónde generar las partículas
particleSpec	cadena o tabla	Nombre de partícula o tabla de especificación de partículas (véase abajo)

Ejemplo

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
}

Formato de la tabla de partículas

Clave	Tipo	Valor predeterminado	Notas
particle	cadena	obligatorio	Nombre de partícula
amount	entero	1	Número de partículas
x, y, z	número	0	Dispersión/desplazamiento en cada eje
speed	número	0	Velocidad de las partículas
red, green, blue	entero	255	Color RGB para DUST y DUST_COLOR_TRANSITION
toRed, toGreen, toBlue	entero	255	Color final de la transición para DUST_COLOR_TRANSITION

consejo

Para DUST_COLOR_TRANSITION, también puedes usar claves en snake_case: to_red, to_green, to_blue.

aviso

A diferencia de las configuraciones YAML de EliteScript, los nombres de partículas en Lua no admiten la conversión de nombres antiguos. Debes usar los nombres actuales de la API de Spigot (por ejemplo, FIREWORK en vez de FIREWORKS_SPARK, SMOKE en vez de SMOKE_NORMAL y DUST en vez de REDSTONE). Consulta la lista de partículas válidas para ver todos los nombres actuales y sus equivalentes antiguos.

---

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

Reproduce un sonido en una ubicación.

Parámetro	Tipo	Valor predeterminado	Notas
location	tabla de ubicación		Dónde reproducir el sonido
sound	cadena		Clave de sonido de Minecraft (p. ej., "entity.blaze.shoot") o nombre del enum Sound de Spigot. También admite claves de paquetes de recursos.
volume	número	1.0	Volumen
pitch	número	1.0	Tono

Ejemplo

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)

Hace caer un rayo en una ubicación, con efecto visual y daño.

Parámetro	Tipo	Notas
location	tabla de ubicación	Dónde hacer caer el rayo

Ejemplo

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)

Genera una entidad de Minecraft vanilla.

Parámetro	Tipo	Notas
entityType	cadena	Nombre del tipo de entidad (p. ej., "FIREBALL", "ARROW")
location	tabla de ubicación	Dónde generar la entidad
options	tabla (opcional)	Opciones de generación (véase abajo)

Opciones de generación de entidades

Clave	Tipo	Valor predeterminado	Notas
velocity	tabla vectorial	nil	Velocidad inicial {x, y, z}
effect	cadena	nil	EntityEffect que se reproduce al aparecer
duration	entero	0	Eliminar automáticamente tras este número de ticks (0 = nunca)
on_land	función	nil	Función de retorno cuando la entidad aterriza en el suelo
max_ticks	entero	6000	Máximo de ticks de seguimiento antes de forzar la función on_land

Devuelve una tabla que representa a la entidad. Las entidades no vivas (FIREBALL, ARROW, TNT, ...) devuelven una tabla de referencia de entidad no viva, donde is_valid() es un método. Los tipos de entidad viva (ZOMBIE, GIANT, ...) devuelven una tabla completa de entidad viva, donde is_valid es un campo booleano. Llamar a entity:is_valid() en una de ellas produce el error attempt to call a boolean value.

Ejemplo

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
}

Ejemplo

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)

Genera una entidad de bloque en caída.

Parámetro	Tipo	Notas
location	tabla de ubicación	Dónde generar la entidad
material	cadena	Nombre del material (p. ej., "STONE", "MAGMA_BLOCK")
options	tabla (opcional)	Opciones de generación (véase abajo)

Opciones de bloques en caída

Clave	Tipo	Valor predeterminado	Notas
velocity	tabla vectorial	nil	Velocidad inicial {x, y, z}
drop_item	booleano	false	Si el bloque se suelta como objeto
hurt_entities	booleano	false	Si el bloque daña a las entidades sobre las que cae
on_land	función	nil	Función function(land_location, entity_ref) que se ejecuta cuando el bloque aterriza

Devuelve una tabla de referencia de entidad.

Ejemplo

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)

Genera un jefe personalizado de EliteMobs a partir de un archivo de configuración.

Parámetro	Tipo	Notas
filename	cadena	Nombre del archivo de configuración del jefe (p. ej., "my_boss.yml")
location	tabla de ubicación	Dónde generar la entidad
options	tabla (opcional)	Opciones de generación (véase abajo)

Opciones de generación de jefes personalizados

Clave	Tipo	Valor predeterminado	Notas
level	entero	nivel del jefe	Sobrescribir el nivel del jefe generado
silent	booleano	false	Suprimir los mensajes de aparición
velocity	tabla vectorial	nil	Velocidad inicial
add_as_reinforcement	booleano	false	Registrar como refuerzo del jefe actual

Devuelve una tabla que representa al jefe, o nil si no se pudo crear.

Ejemplo

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)

Método simplificado para generar un jefe personalizado en una ubicación, con un nivel opcional.

Parámetro	Tipo	Valor predeterminado	Notas
filename	cadena		Nombre del archivo de configuración del jefe
location	tabla de ubicación	ubicación del jefe	Dónde generar la entidad (opcional; por defecto, la ubicación del jefe)
level	entero	nivel del jefe	Sobrescribir el nivel de aparición (opcional)

Devuelve una tabla que representa a la entidad, o nil.

Ejemplo

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, level, velocity)

Genera un refuerzo que se registra en el sistema de refuerzos de EliteMobs.

Parámetro	Tipo	Valor predeterminado	Notas
filename	cadena		Nombre del archivo de configuración del jefe
location	tabla de ubicación		Dónde generar la entidad
level	entero	0	Nivel del refuerzo. Con 0, la función de invocación resuelve el nivel según su comportamiento predeterminado.
velocity	tabla vectorial	nil	Velocidad inicial (opcional)

Devuelve una tabla que representa a la entidad, o nil.

Ejemplo

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)

Genera una entidad de fuego artificial con control completo de sus efectos.

Parámetro	Tipo	Notas
location	tabla de ubicación	Dónde generar la entidad
spec	tabla	Especificación del fuego artificial (véase abajo)

Tabla de especificación de fuegos artificiales

Clave	Tipo	Valor predeterminado	Notas
power	entero	1	Potencia de vuelo (altura)
velocity	tabla vectorial	nil	Velocidad inicial
shot_at_angle	booleano	true	Si el fuego artificial se dispara en ángulo (se usa cuando se define la velocidad)
effects	tabla de tablas	nil	Lista de especificaciones de efectos del fuego artificial. Si se omite, la especificación principal se trata como un único efecto.

Especificación de efectos de fuegos artificiales

Clave	Tipo	Valor predeterminado	Notas
type	cadena	"BALL_LARGE"	"BALL", "BALL_LARGE", "STAR", "BURST", "CREEPER"
flicker	booleano	true	Efecto de destello
trail	booleano	true	Efecto de estela
colors	tabla	nil	Lista de nombres de colores o tablas {red, green, blue}
fade_colors	tabla	nil	Lista de nombres de colores de desvanecimiento o tablas {red, green, blue}

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

Devuelve una tabla de referencia de entidad. Puedes llamar a :detonate() para forzar su detonación inmediata.

Ejemplo

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)

Genera una entidad de poción arrojadiza lanzada.

Parámetro	Tipo	Notas
location	tabla de ubicación	Dónde generar la entidad
spec	tabla	Especificación de la poción (véase abajo)

Tabla de especificación de pociones arrojadizas

Clave	Tipo	Notas
velocity	tabla vectorial	Velocidad inicial de la poción lanzada
effects	tabla de tablas	Lista de especificaciones de efectos de poción

Especificación de efectos de poción

Clave	Tipo	Valor predeterminado	Notas
type	cadena	obligatorio	Nombre del tipo de efecto de poción (p. ej., "SLOWNESS", "POISON")
duration	entero	0	Duración en ticks
amplifier	entero	0	Amplificador del efecto (0 = nivel I)
overwrite	booleano	true	Si se sobrescriben los efectos existentes del mismo tipo

Devuelve una tabla de referencia de entidad, o nil.

Ejemplo

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)

Coloca un bloque temporal que se restaura automáticamente al terminar la duración indicada.

Parámetro	Tipo	Valor predeterminado	Notas
location	tabla de ubicación		Dónde colocar el bloque
material	cadena		Nombre del material
duration	entero	0	Ticks hasta restaurar el bloque (0 = permanente)
requireAir	booleano	false	Si es true, solo coloca el bloque si actualmente hay aire

Ejemplo

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)

Cambia un bloque de forma permanente. Usa place_temporary_block_at_location si quieres restaurarlo después.

Parámetro	Tipo	Valor predeterminado	Notas
location	tabla de ubicación		Dónde colocar el bloque
material	cadena		Nombre del material
requireAir	booleano	false	Si es true, solo coloca el bloque si actualmente hay aire

Ejemplo

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)

Devuelve como cadena el nombre del material del bloque en una ubicación.

Parámetro	Tipo	Notas
location	tabla de ubicación	Ubicación que consultar

Ejemplo

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)

Devuelve la coordenada Y del bloque más alto que no sea aire en la posición X/Z indicada.

Parámetro	Tipo	Notas
location	tabla de ubicación	Ubicación que consultar (se usan X y Z)

Ejemplo

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)

Devuelve como número la resistencia a explosiones del bloque en una ubicación.

Parámetro	Tipo	Notas
location	tabla de ubicación	Ubicación que consultar

Ejemplo

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)

Devuelve true si el bloque en la ubicación es aire.

Parámetro	Tipo	Notas
location	tabla de ubicación	Ubicación que consultar

Ejemplo

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)

Devuelve true si el bloque en la ubicación es transitable: las entidades pueden atravesarlo.

Parámetro	Tipo	Notas
location	tabla de ubicación	Ubicación que consultar

Ejemplo

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)

Devuelve true si el bloque en la ubicación no es sólido. Es similar a la comprobación de transitabilidad, pero se basa en si el bloque es sólido.

Parámetro	Tipo	Notas
location	tabla de ubicación	Ubicación que consultar

Ejemplo

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)

Devuelve true si el bloque en la ubicación no es sólido Y el bloque justo debajo sí lo es; es decir, la ubicación está «sobre el suelo».

Parámetro	Tipo	Notas
location	tabla de ubicación	Ubicación que consultar

Ejemplo

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 = "CLOUD",
        amount = 30,
      })
    end
  end
}

---

world:is_standing_on_material(location, material)

Devuelve true si el bloque justo debajo de la ubicación coincide con el material indicado.

Parámetro	Tipo	Notas
location	tabla de ubicación	Ubicación que consultar
material	cadena	Nombre del material que comprobar

Ejemplo

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)

Establece la hora del mundo. Puedes pasar una ubicación opcional para indicar qué mundo modificar.

Parámetro	Tipo	Notas
location	tabla de ubicación (opcional)	Mundo que modificar. Por defecto, el mundo del jefe.
time	entero	Hora del mundo en ticks (0 = amanecer, 6000 = mediodía, 13000 = noche, 18000 = medianoche)

Ejemplo

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)

Establece el clima en el mundo del jefe.

Parámetro	Tipo	Valor predeterminado	Notas
location	tabla de ubicación (opcional)	mundo del jefe	Mundo que modificar
weather	cadena		"CLEAR", "RAIN" (o "PRECIPITATION"), "THUNDER"
duration	entero	6000	Duración del clima en ticks

Ejemplo

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)

Crea el efecto visual de una explosión falsa mediante el sistema de regeneración de explosiones de EliteMobs: los bloques se rompen y se regeneran.

Parámetro	Tipo	Notas
blockLocations	tabla de tablas de ubicación	Lista de ubicaciones de bloques que «explotarán»
sourceLocation	tabla de ubicación (opcional)	Origen de la explosión para calcular la dirección

Ejemplo

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)

Ejecuta un comando de consola como el servidor.

Parámetro	Tipo	Notas
command	cadena	Comando que ejecutar (sin la / inicial)

Ejemplo

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)

Ejecuta la tarea visual de rayo potenciado, usada por los poderes del Ender Dragon. Produce un rayo más espectacular con efectos adicionales.

Parámetro	Tipo	Notas
location	tabla de ubicación	Dónde hacer caer el rayo

Ejemplo

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)

Genera un proyectil de pepita de oro falsa usado por el sistema de lluvia de proyectiles.

Parámetro	Tipo	Valor predeterminado	Notas
location	tabla de ubicación		Ubicación de aparición
velocity	tabla vectorial		Velocidad inicial
hasGravity	booleano	false	Si el proyectil tiene gravedad

Devuelve una tabla de proyectil falso con los métodos get_location(), set_gravity(bool), remove() e is_removed().

Ejemplo

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)

Procesa el daño de una tabla de proyectiles de pepitas de oro falsas contra entidades cercanas.

Parámetro	Tipo	Notas
projectiles	tabla	Lista de tablas de proyectiles falsos obtenidas con spawn_fake_gold_nugget_at_location

Ejemplo

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
    local task_id
    task_id = context.scheduler:run_every(1, function(tick_context)
      tick_context.world:run_fake_gold_nugget_damage(tick_context.state.active_projectiles)
    end)
    context.scheduler:run_after(60, function(later_context)
      later_context.scheduler:cancel_task(task_id)
    end)
  end
}

---

world:generate_player_loot(times)

Genera botín para los jugadores que dañaron al jefe.

Parámetro	Tipo	Valor predeterminado	Notas
times	entero	1	Número de tiradas de botín

Ejemplo

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)

Suelta monedas adicionales para todos los jugadores que contribuyeron a dañar al jefe.

Parámetro	Tipo	Valor predeterminado	Notas
multiplier	número	2.0	Multiplicador de la cantidad de monedas

Ejemplo

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

Funciones auxiliares de cálculo vectorial. Se llaman como funciones normales, con un punto, y no como métodos.

Método	Devuelve	Notas
vectors.get_vector_between_locations(loc1, loc2[, options])	tabla vectorial	Dirección de loc1 a loc2
vectors.normalize_vector(vec)	tabla vectorial	Devuelve un vector de longitud unitaria
vectors.rotate_vector(vec, pitch, yaw)	tabla vectorial	Rota un vector los grados indicados de inclinación y orientación

Todas las tablas vectoriales tienen los campos x, y y z.

vectors.get_vector_between_locations(loc1, loc2, options)

Parámetro	Tipo	Notas
loc1	tabla de ubicación	Punto inicial
loc2	tabla de ubicación	Punto final
options	tabla (opcional)	Opciones de posprocesamiento (véase abajo)

Opciones de vectores

Clave	Tipo	Valor predeterminado	Notas
normalize	booleano	false	Normalizar el vector resultante
multiplier	número	1.0	Escalar el vector
offset	tabla vectorial	nil	Añadir un vector de desplazamiento

Ejemplo

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)

Parámetro	Tipo	Notas
vec	tabla vectorial	Vector de entrada

Ejemplo

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)

Parámetro	Tipo	Notas
vec	tabla vectorial	Vector de entrada
pitch	número	Rotación alrededor del eje X en grados
yaw	número	Rotación alrededor del eje Y en grados

Ejemplo

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
}

consejo

Puedes crear un abanico de direcciones rotando un vector base dentro de un bucle:

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

Acceso de solo lectura a los valores de configuración de los poderes.

Método	Devuelve	Notas
settings:warning_visual_effects_enabled()	booleano	Si los efectos visuales de advertencia están activados en la configuración de combate de los mobs

Ejemplo

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

Datos del evento para el hook actual. Los campos disponibles dependen del hook que activó la llamada.

Campo o método	Cuándo está disponible	Notas
event.damage_amount	Hooks de daño	Cantidad de daño actual (valor capturado al llamar al hook)
event.damage_cause	Hooks de daño	Nombre del enum DamageCause de Bukkit (p. ej., "ENTITY_ATTACK")
event.cancel_event()	Eventos cancelables	Cancela el evento
event.set_damage_amount(value)	Hooks basados en EliteDamageEvent	Establece el daño directamente
event.multiply_damage_amount(multiplier)	Hooks basados en EliteDamageEvent	Multiplica el daño actual
event.damager	Eventos de daño con una entidad atacante	Tabla de referencia de la entidad atacante
event.projectile	Eventos de daño en los que el atacante es un proyectil	Tabla de referencia de la entidad del proyectil
event.spawn_reason	on_spawn	Nombre del enum del motivo de aparición
event.entity	on_death, eventos de zona	Tabla que representa a la entidad correspondiente

Ejemplo: Reducir a la mitad el daño recibido

Ejemplo

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
}

Ejemplo: Cancelar el daño de proyectiles

Ejemplo

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
}

Ejemplo: Leer la causa del daño

Ejemplo

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
}

nota

• damage_amount es un valor capturado al llamar al hook. No se actualiza automáticamente después de llamar a set_damage_amount() o multiply_damage_amount().
• En las funciones programadas, context.event es nil. Usa hooks de evento para modificar eventos.

---

Siguientes pasos

• Primeros pasos | Scripts de NPC | Hooks y ciclo de vida | Jefes y entidades | Zonas y selección de objetivos | Ejemplos | Enums | Solución de problemas
• Referencia de la API | Motor de scripting