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. Los métodos de abajo conservan su comportamiento: omisión de protecciones al generar rayos, especificaciones ampliadas de partículas y seguimiento de bloques temporales. Los demás métodos compartidos siguen disponibles, incluidos get_entity(uuid), block_is_passable(x, y, z), location_is_protected(location), spawn_dust(...) y raycast(...). Consulta sus argumentos y comportamiento con chunks descargados en la referencia de la API compartida; esas garantías no se aplican automáticamente a una sustitución de EliteMobs.

Las funciones de botín de FreeMinecraftModels no están disponibles aquí

FreeMinecraftModels añade drop_elitemobs_procedural_loot, drop_elitemobs_random_loot, drop_elitemobs_custom_loot y start_elitemobs_transport a context.world solo en sus propios scripts de props. Cada plugin lleva una copia independiente de la biblioteca de scripting compartida, por lo que estas funciones no aparecen en los poderes de jefe ni en los scripts de NPC de EliteMobs, aunque FreeMinecraftModels esté instalado. Los poderes de jefe usan generate_player_loot y drop_bonus_coins en su lugar.

---

context.world

La tabla de mundo permite generar entidades, reproducir efectos, modificar bloques y cambiar el mundo. Estos métodos admiten dos puntos (world:method()) o un punto sin pasar explícitamente el argumento self.

Las sustituciones de jefe descritas abajo convierten tablas con x, y, z, yaw/pitch opcionales y el nombre de un mundo cargado en world. Las coordenadas ausentes valen 0; omitir el mundo usa el mundo actual del jefe, pero un nombre explícito desconocido impide la conversión. También aceptan una tabla anidada current_location. Una ubicación nil o que no sea una tabla usa la ubicación del jefe. Los métodos compartidos conservan su contrato de ubicación y el mundo capturado al crear la tabla.

Cerrar la instancia Lua no deshace automáticamente los cambios del mundo ni elimina las entidades generadas. Se detienen los monitores del script, pero los temporizadores independientes de eliminación, regeneración de explosiones, rayos potenciados y proyectiles de oro tienen sus propios ciclos de vida. Las sustituciones de bloques y generación no aplican automáticamente location_is_protected ni las comprobaciones compartidas de chunks cargados; comprueba las condiciones pertinentes antes de modificar el mundo.

---

world:spawn_particle_at_location(location, particleSpec)

Genera partículas en una ubicación. El segundo argumento acepta un nombre o una tabla de especificación. Un tercer argumento entero opcional indica la cantidad cuando falta amount; su valor predeterminado es 1. Los nombres se convierten a mayúsculas antes de buscarlos. Un nombre no válido o datos de partícula no admitidos producen una advertencia y ninguna partícula.

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 to_red, to_green, to_blue; las claves camelCase tienen prioridad. Ambos tipos de polvo usan un tamaño fijo de 1 y componentes RGB entre 0..255. Las demás partículas no reciben datos adicionales, por lo que esta función no admite todas las partículas que los requieren.

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)

Genera un rayo real que causa daño y activa la omisión de cancelaciones de aparición de rayos de EliteMobs. No es la función compartida de rayos solo visuales, ni garantiza que se ignoren todas las reglas de daño o protección de otros plugins.

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 vanilla directamente en el mundo de la ubicación. Un nombre desconocido devuelve nil; un tipo reconocido que no pueda generarse aún puede causar un error. No asigna automáticamente un tirador al proyectil ni registra la entidad como refuerzo élite.

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	Un valor positivo programa la eliminación tras estos ticks; un valor no positivo no añade temporizador
on_land	función	nil	function(land_location, entity_ref) al tocar suelo, dejar de ser válida o superar max_ticks; no es un evento de impacto ni prueba de aterrizaje
max_ticks	entero	6000	Máximo de ticks de seguimiento antes de forzar la función on_land
persistent	booleano	el valor predeterminado de Minecraft	false mantiene a la entidad fuera del guardado del chunk, de modo que un apagado o la descarga de un chunk a mitad del efecto no pueda dejarla en el mundo

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.

El monitor comprueba la entidad cada tick mientras el script está activo y se detiene con sus tareas. El temporizador positivo de duration es independiente y puede eliminarla después de cerrar el script. Los nombres desconocidos de effect se ignoran.

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_display_at_location(location, options)

Genera un display de objeto o de bloque: un elemento visual flotante sin hitbox, gravedad ni IA. Úsalo para piedras en órbita, atrezo lanzado y otros efectos que solo necesitan verse, en lugar de decorar un soporte de armadura. El display se centra en location y se orienta según su yaw.

Opción	Tipo	Valor predeterminado	Notas
item	cadena		Material que se muestra como objeto. Un objeto de bloque como "AMETHYST_BLOCK" se muestra como un bloque centrado
block	cadena		Bloque que se muestra como display de bloque, como material o como datos de bloque, por ejemplo "lantern[hanging=true]"
scale	número o tabla vectorial	1	Un número escala todos los ejes; {x, y, z} escala cada uno. Con 1, un bloque mide un bloque de ancho
duration	entero	0	Los valores positivos eliminan el display tras esta cantidad de ticks
teleport_duration	entero	0	Ticks que tarda el cliente en deslizarse hasta cada nueva ubicación, de 0 a 59. Usa 1 cuando teletransportes el display cada tick
billboard	cadena	FIXED	FIXED, VERTICAL, HORIZONTAL o CENTER
glowing	booleano	false	Resplandor con contorno
brightness	entero	luz del mundo	De 0 a 15, sustituye la luz en el display
bedrock_fallback	booleano	true	Consulta más abajo

Indica exactamente uno de item o block. Si falta item o block, si alguno es desconocido, si se dan ambos a la vez o si scale no es positivo, se devuelve nil y se registra una advertencia que nombra el poder. Un valor desconocido de billboard mantiene FIXED.

Los displays nunca se guardan con el chunk. Se eliminan cuando se agota duration, cuando llamas a remove() o cuando el poder se apaga, lo que ocurra primero.

Los clientes Bedrock no pueden renderizar entidades display. Los jugadores de Bedrock que están en el mundo cuando aparece el display ven en su lugar un soporte de armadura invisible con el mismo objeto, o con el objeto del bloque en el caso de un display de bloque, y el display se les oculta. El soporte sigue al display y se elimina con él. Los jugadores de Bedrock que entran en el mundo después no reciben soporte, y un bloque sin forma de objeto, como fire, no recibe soporte en absoluto. Desactívalo con bedrock_fallback = false en efectos que los jugadores de Bedrock no necesiten ver.

El envoltorio devuelto tiene uuid y entity_type y estos métodos:

Método	Notas
is_valid(), is_alive()	Si el display sigue existiendo
get_location()	Ubicación actual
teleport_to_location(location)	Mueve el display y su soporte de Bedrock
remove()	Elimina el display y su soporte de Bedrock
set_scale(scale)	Los mismos valores que la opción scale
set_item(material)	Solo displays de objeto; devuelve false en los demás
set_block(block)	Solo displays de bloque; devuelve false en los demás
set_glowing(enabled)	Resplandor con contorno
set_brightness(level)	De 0 a 15, o nil para volver a usar la luz del mundo
set_teleport_duration(ticks)	Igual que la opción teleport_duration

Ejemplo

-- Three amethyst stones circle the target for three seconds.
return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil or not context.cooldowns:check_local("orbit", 200) then return end
    local target = context.player
    local stones = {}
    for i = 1, 3 do
      stones[i] = context.world:spawn_display_at_location(target:get_location(), {
        item = "AMETHYST_BLOCK", scale = 0.3, duration = 60, teleport_duration = 1
      })
    end
    local elapsed = 0
    local task
    task = context.scheduler:run_every(1, function(context)
      elapsed = elapsed + 1
      if elapsed >= 60 then
        context.scheduler:cancel_task(task)
        return
      end
      local center = target:get_location()
      for i = 1, 3 do
        local angle = elapsed * 0.2 + i * (2 * math.pi / 3)
        if stones[i] ~= nil and stones[i]:is_valid() then
          stones[i]:teleport_to_location(em.create_location(
            center.x + math.cos(angle) * 1.5, center.y + 1.2, center.z + math.sin(angle) * 1.5, center.world, 0, 0))
        end
      end
    end)
  end
}

---

world:spawn_falling_block_at_location(location, material, options)

Genera un bloque en caída usando un material de bloque. Con on_land, EliteMobs intercepta su evento de cambio de bloque, cancela la colocación y llama una vez a function(land_location, entity_ref). Sin esa función, puede colocarse normalmente. No admite duration, max_ticks ni una llamada por invalidez o tiempo agotado.

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 referencia de entidad no viva o nil si no se resuelve la ubicación o el material. Un material reconocido que no sea un bloque puede fallar al crear sus datos de bloque.

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 de la configuración del jefe generado	Sustituye su nivel. Si se omite, se aplican su configuración y reglas de nivel dinámico; no hereda el nivel del jefe que lo genera.
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. Al omitir la ubicación o el nivel, usa los del jefe que lo genera. No registra el resultado como refuerzo. Omite el tercer argumento para usar su valor predeterminado; pasar explícitamente nil en él no es válido.

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

Genera silenciosamente un refuerzo, registra a su invocador y hereda el combate normalizado si el jefe personalizado invocador lo usa. Su configuración y reglas de nivel dinámico determinan el nivel; duration es un temporizador de escape, no un nivel.

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
duration	entero	0	Temporizador de escape en ticks; 0 no añade temporizador. No cambia el nivel del refuerzo.
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 un fuego artificial real sin suprimir automáticamente su daño. Incluye al menos un color válido por efecto; construir un efecto sin colores puede fallar.

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	obligatorio por efecto	Lista no vacía de nombres de colores o tablas {red = 255, green = 0, blue = 0}
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 referencia de entidad no viva, o nil si no se resuelve la ubicación. :detonate() solicita la detonación. Los tipos y nombres de colores no distinguen mayúsculas; un tipo desconocido usa BALL_LARGE y un color desconocido usa blanco. Los componentes RGB deben estar entre 0..255.

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" },
        },
      },
    })

    if fw == nil then return end
    -- Detonate on the next tick for a visual burst
    context.scheduler:run_after(1, function()
      fw:detonate()
    end)
  end
}

---

world:spawn_splash_potion_at_location(location, spec)

Genera una poción arrojadiza real. Los efectos Bukkit desconocidos producen una advertencia y se omiten. No asigna un tirador ni aplica el filtro de efectos de instancia de los métodos directos de poción del jefe; se aplica el comportamiento normal de las pociones arrojadizas.

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	Sustituye un efecto anterior del mismo tipo en los metadatos de esta poción; no regula los efectos que ya tiene el jugador

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 registrado que restaura sus datos anteriores tras una duración positiva. Guarda datos de bloque, no el contenido de contenedores. El bloque original vuelve cuando termina el temporizador, cuando se descarga el chunk o el mundo, o cuando se apaga el plugin, pero solo mientras el bloque siga conteniendo el bloque temporal, así que no se sobrescribe una edición posterior. Colocar de nuevo sobre un bloque que sigue conteniendo un bloque temporal reinicia su temporizador y conserva el primer original guardado. Se omiten los bloques con entidades de bloque, como cofres y carteles, los chunks descargados y los bloques que mantiene otro propietario de bloques temporales. Romper un bloque registrado no suelta nada y termina el registro sin restaurarlo. Usa un material de bloque. Esta sustitución devuelve nil, incluso si requireAir o una omisión impiden colocar el bloque; no informa del éxito ni comprueba automáticamente las protecciones regionales.

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 restaurarlo; un valor cero o negativo coloca el bloque de forma permanente y sin registrarlo
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)

Coloca un bloque de forma permanente mediante el gestor de bloques temporales, sin temporizador de restauración y sin registrarlo, así que el cambio se mantiene después de apagar el plugin. Si el bloque contiene en ese momento un bloque temporal con temporizador, ese bloque deja de estar registrado y no se restaura. Los bloques que mantiene otro propietario de bloques temporales no se modifican. Usa place_temporary_block_at_location con una duración positiva para restaurar el original mediante un temporizador.

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 el nombre del material en mayúsculas o nil si no se resuelve la ubicación. A diferencia de la consulta compartida por coordenadas, accede al bloque directamente sin comprobar que el chunk esté cargado.

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 Y del bloque más alto según Bukkit en la posición X/Z, o nil si no se resuelve la ubicación. No comprueba si el chunk ya está cargado ni si es seguro teletransportarse al destino.

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 la resistencia a explosiones del material o 0 si no se resuelve la 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 el resultado de Block.isPassable() de Bukkit, o false si no se resuelve la ubicación. Consulta un solo bloque; no comprueba si una entidad completa cabe o puede navegar por él.

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 de la ubicación no es sólido y el bloque una unidad Y por debajo sí lo es. No comprueba el estado de contacto con el suelo, la caja de colisión ni el espacio sobre la cabeza de una entidad.

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)

Cambia la hora de todo el mundo. Puedes indicar una ubicación para seleccionar el mundo. La hora anterior no se restaura al cerrar el script.

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)

Cambia el clima en el mundo del jefe o de la ubicación opcional. Los nombres no distinguen mayúsculas; los desconocidos solo generan una advertencia. RAIN/CLEAR cambian el temporizador del clima; THUNDER cambia el de los truenos. Afecta a todo el mundo y no restaura el estado anterior al cerrar el script.

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)

Elimina bloques reales y crea escombros de bloques en caída mediante la regeneración de explosiones de EliteMobs. Los escombros tienen daño a entidades activado; no es un efecto inocuo de partículas. Requiere doExplosionRegen; comprueba la bandera de regeneración de WorldGuard cuando se proporciona una ubicación de origen. Omite aire, fuego, líquidos y bloques temporales registrados, y puede incluir bloques vecinos dependientes. La restauración comienza tras 1200 ticks y procesa un bloque registrado por tick. Mantén todas las ubicaciones en el mundo del jefe. Devuelve nil y cerrar el script no deshace la operación.

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 inmediatamente un comando de consola como el servidor y devuelve nil, sin exponer si tuvo éxito. No sustituye automáticamente marcadores de jugador o jefe.

Los comandos vanilla informan de su resultado y, con el valor predeterminado broadcast-console-to-ops=true, el servidor muestra cada resultado a todos los operadores conectados. Los comandos que se ejecutan a menudo, como data merge entity, kill o damage, inundan su chat. Usa en su lugar los métodos nativos: spawn_display_at_location para los elementos visuales, los métodos de soporte de armadura para los soportes, entity:remove() para eliminar lo que haya generado un script y entity:deal_custom_damage(amount) para infligir un daño exacto desde el jefe.

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)

Inicia una tarea Bukkit independiente en la ubicación capturada. Emite SOUL_FIRE_FLAME durante 60 iteraciones; después genera un rayo real con la omisión de cancelación de aparición y una bola de fuego hacia abajo con potencia explosiva 5, identificada como ender_dragon_empowered_lightning.yml. Es un ataque que causa daño. Cerrar o pausar el script no cancela esta tarea, que tampoco consulta la opción de efectos de advertencia.

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)

Crea una pepita de oro visual mediante paquetes para jugadores cercanos; los jugadores y las tolvas no pueden recogerla. Crearla no inicia su movimiento ni su daño. Pásala una vez a run_fake_gold_nugget_damage como parte de un grupo, o elimínala explícitamente.

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, o nil si no se resuelve la ubicación o el vector, con 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)

    local nugget = context.world:spawn_fake_gold_nugget_at_location(
      context.boss:get_location(),
      { x = dir.x, y = dir.y, z = dir.z }
    )
    if nugget ~= nil then
      context.world:run_fake_gold_nugget_damage({ nugget })
    end
  end
}

---

world:run_fake_gold_nugget_damage(projectiles)

Inicia una tarea Bukkit independiente que mueve y comprueba el grupo cada tick. Llámala una sola vez por grupo: cada llamada crea otra tarea. Busca entidades vivas en una caja de semitamaño 0.5 en la nueva posición, omite al jefe de origen y a jugadores bloqueando, y solicita daño personalizado de 1 mediante la política de daño del jefe. Una colisión puede eliminar el proyectil aunque se rechace el daño. Tocar suelo o alcanzar 100 ticks también lo elimina. Comprueba posiciones muestreadas, no todo el trayecto mediante un rayo; cerrar o pausar Lua no cancela la tarea.

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)
    -- Keep this batch separate from later combat entries.
    local 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 }
      )
      if nugget ~= nil then table.insert(projectiles, nugget) end
    end

    -- Start the batch once; the helper runs its own per-tick task.
    context.world:run_fake_gold_nugget_damage(projectiles)
    -- Remove any surviving projectiles after 3 seconds.
    context.scheduler:run_after(60, function()
      for _, projectile in ipairs(projectiles) do
        projectile:remove()
      end
    end)
  end
}

---

world:generate_player_loot(times)

Ejecuta el generador normal de botín times veces; los valores no positivos no hacen nada. Requiere eliteLoot, que no se haya activado la protección contra abusos, datos del jugador cargados y daño registrado de al menos el 10% de la salud máxima. Omite jugadores con bloqueo de recompensas de la instancia. Cada pasada puede incluir monedas y, con botín aleatorio activado, botín aleatorio/especial y pergaminos según la configuración y las reglas de grupo. No repite todos los drops personalizados definidos ni garantiza un objeto por tirada. Las llamadas repetidas generan más intentos de recompensa; no hay límite de una llamada por 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 jugadores cuyo daño registrado supera el 10% de la salud máxima del jefe. Omite NPC y jugadores sin datos de EliteMobs cargados. La cantidad usa el nivel de recompensa ajustado del jugador multiplicado por multiplier.

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

Las funciones vectoriales admiten punto o dos puntos. Aceptan campos x, y, z, índices numéricos 1..3 o una tabla anidada direction. Los componentes ausentes valen 0. Devuelven tablas nuevas sin modificar la entrada.

Método	Devuelve	Notas
vectors.get_vector_between_locations(loc1, loc2[, options])	tabla vectorial	Desplazamiento loc2 - loc1, sin normalizar por defecto
vectors.normalize_vector(vec)	tabla vectorial	Vector unitario para entradas no nulas; el vector cero sigue siendo cero
vectors.rotate_vector(vec, pitch, yaw)	tabla vectorial	Rota primero alrededor del eje X del mundo y luego del Y, en grados

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

Las opciones se aplican en orden: normalizar el desplazamiento no nulo, multiplicar y sumar el desplazamiento en los ejes del mundo. Las ubicaciones no resueltas o de mundos distintos devuelven cero antes de aplicar opciones. Dos ubicaciones válidas coincidentes aún pueden recibir offset.

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, 330, 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 la configuración de poderes. La función lee el valor actual al llamarla; no suprime partículas ni otros efectos automáticamente. El script debe decidir si muestra una advertencia según el resultado.

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 del hook actual. Los campos dependen del evento subyacente; comprueba los opcionales antes de usarlos. Los modificadores numéricos de daño requieren punto (event.set_damage_amount(value)); transfer_damage admite punto o dos puntos. Esta tabla de eventos de jefe no expone los miembros compartidos cancel, uncancel o is_cancelled.

Campo o método	Cuándo está disponible	Notas
event.damage_amount	Hooks de daño	Daño capturado al resolver por primera vez la tabla diferida del evento
event.get_damage_amount()	Hooks de daño	Lee la cantidad actual después de los cambios
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	Atacante original de Bukkit: el propio proyectil en impactos de proyectil, no su tirador
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	Daño de jugador a jefe, on_death, eventos de zona	Jefe dañado, entidad muerta o entidad que cruza la zona; si se daña un refuerzo, es el refuerzo
event.is_damage_transfer	Daño de jugador a jefe, incluido el reenviado por refuerzos	Indica si el golpe procede de una transferencia
event:transfer_damage(target, amount)	Daño de jugador a jefe, incluido el reenviado por refuerzos	Envía un golpe independiente a otro élite válido; consulta el contrato de transferencia de daño

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. No se actualiza automáticamente después de llamar a set_damage_amount() o multiply_damage_amount().
• El contexto nuevo que recibe una función programada tiene event = nil. Capturar el contexto anterior no permite modificar válidamente un evento ya terminado; modifica los eventos dentro de su hook.
• Los modificadores cambian el evento pendiente, no la salud ya perdida. Otros listeners pueden modificar o cancelar el golpe. Una transferencia aceptada envía un golpe adicional; no reduce ni cancela automáticamente el original.

---

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