Motor de Scripting Lua de MagmaCore

MagmaCore proporciona un motor de scripting Lua compartido utilizado por múltiples plugins de Nightbreak. El motor gestiona sandboxing, programación, gestión de zonas, interacción con el mundo, tablas de entidades e interfaz de jugador -- todo con una API consistente entre plugins.

Actualmente, los siguientes plugins utilizan este motor:

EliteMobs -- Poderes Lua para jefes personalizados (hooks como on_boss_damaged_by_player, on_enter_combat, etc.)
FreeMinecraftModels -- Scripts Lua para props y objetos personalizados (hooks como on_right_click, on_left_click, on_equip, etc.)

Esta página documenta las características compartidas del motor. Para hooks, APIs y flujos de trabajo específicos de cada plugin, consulta las páginas de plugins enlazadas arriba.

Mini Introducción a Lua

Si eres completamente nuevo en Lua, aquí tienes la sintaxis mínima que necesitas para escribir scripts para cualquier plugin de Nightbreak.

Variables

Usa local para almacenar un valor:

local cooldown_key = "fire_burst"
local damage_multiplier = 1.5

local significa que la variable pertenece solo a este archivo o bloque.

Funciones

Las funciones son bloques reutilizables de lógica:

local function warn_player(player)
  player:send_message("&cMove!")
end

Después, puedes llamarla:

warn_player(some_player)

Comprobaciones `if`

Usa if cuando algo solo debería ocurrir a veces:

if context.player == nil then
  return
end

Eso significa "si no hay jugador para este hook, detente aquí".

`nil`

nil significa "sin valor". Es la versión de Lua de "aquí no hay nada".

A menudo verificarás nil con:

if context.event ~= nil then
  -- do something with the event
end

~= significa "no es igual a".

Tablas

Lua usa tablas para varios propósitos:

Listas
Objetos con claves nombradas
La definición de script retornada al final

Ejemplo de una tabla con claves nombradas:

local particle = {
  particle = "FLAME",
  amount = 1,
  speed = 0.05
}

Retornando la definición del script

Al final de cada archivo de script, retornas una tabla:

return {
  api_version = 1,

  on_spawn = function(context)
  end
}

Esa tabla retornada es el archivo de script.

Comentarios

Usa -- para escribir una nota para humanos:

-- This cooldown stops the attack from firing every hit
context.cooldowns:set_local(60, "fire_burst")

Sandbox de Lua

Todos los scripts Lua se ejecutan dentro de un entorno LuaJ con sandbox. Varios globales que podrían acceder al sistema de archivos o al runtime de Java son eliminados. Las reglas del sandbox son idénticas en todos los plugins que usan MagmaCore.

Globales Eliminados

Los siguientes globales estándar de Lua están establecidos como nil y no pueden usarse:

Eliminado	Razón
`debug`	Expone el estado interno de la VM
`dofile`	Acceso al sistema de archivos
`io`	Acceso al sistema de archivos
`load`	Carga arbitraria de código
`loadfile`	Acceso al sistema de archivos
`luajava`	Acceso directo a clases Java
`module`	Sistema de módulos (no necesario)
`os`	Acceso al sistema operativo
`package`	Sistema de módulos (no necesario)
`require`	Sistema de módulos / acceso al sistema de archivos

Biblioteca Estándar Disponible

Todo lo demás de la biblioteca estándar de Lua funciona normalmente:

Categoría	Funciones
Math	`math.abs`, `math.ceil`, `math.floor`, `math.max`, `math.min`, `math.random`, `math.sin`, `math.cos`, `math.sqrt`, `math.pi`, y todas las demás funciones `math.*`
String	`string.byte`, `string.char`, `string.find`, `string.format`, `string.gsub`, `string.len`, `string.lower`, `string.match`, `string.rep`, `string.sub`, `string.upper`, y todas las demás funciones `string.*`
Table	`table.insert`, `table.remove`, `table.sort`, `table.concat`, y todas las demás funciones `table.*`
Iteradores	`pairs`, `ipairs`, `next`
Tipo	`type`, `tostring`, `tonumber`, `select`, `unpack`
Manejo de errores	`pcall`, `xpcall`, `error`, `assert`
Otros	`print`, `rawget`, `rawset`, `rawequal`, `rawlen`, `setmetatable`, `getmetatable`

La librería os no está disponible

La librería os está completamente eliminada del sandbox. Si necesitas información de tiempo, usa context.world:get_time() para el tiempo del mundo o almacena marcas de tiempo en context.state usando contadores de ticks con on_tick / on_game_tick.

tip

print escribe en la consola del servidor, pero es preferible usar context.log:info(msg) para la salida. Los mensajes de log van precedidos del nombre del archivo de script, facilitando rastrear qué script produjo el mensaje.

Contrato del Archivo

Cada script Lua debe hacer return de una tabla. Esa tabla es intencionalmente estricta.

Campos de Nivel Superior Requeridos y Opcionales

Campo	Requerido	Tipo	Notas
`api_version`	Sí	Number	Actualmente debe ser `1`
`priority`	No	Number	Prioridad de ejecución. Los valores más bajos se ejecutan primero. Por defecto es `0`
claves de hook soportadas	No	Function	Debe usar uno de los nombres de hook exactos soportados por el plugin

Reglas de Validación

El archivo debe retornar una tabla.
api_version es requerido y actualmente debe ser 1.
priority debe ser numérico si está presente.
Cada clave extra de nivel superior debe ser un nombre de hook soportado.
Cada clave de hook debe apuntar a una función.
Las claves de nivel superior desconocidas son rechazadas.

Las funciones auxiliares y constantes locales deben vivir encima del return final, no dentro de la tabla retornada a menos que sean hooks reales.

local ANIMATION_NAME = "idle"

local function do_something(context)
  context.log:info("Doing something!")
end

return {
  api_version = 1,
  priority = 0,

  on_spawn = function(context)
    do_something(context)
  end
}

Sintaxis de Métodos: `:` vs `.`

En Lua, object:method(arg) es una abreviación de object.method(object, arg). La API de MagmaCore acepta ambas formas, así que cualquiera funciona:

context.log:info("hello")
context.log.info("hello")  -- same thing

Toda la documentación usa : consistentemente.

Presupuesto de Ejecución

Cada invocación de hook y cada invocación de callback se cronometra. Si una sola llamada tarda más de 50 milisegundos, el script se deshabilita con una advertencia en consola:

[Lua] my_script.lua took 73ms in 'on_game_tick' (limit: 50ms) -- script disabled to prevent lag.

Para mantenerte dentro del presupuesto:

Evita bucles sin límite dentro de hooks.
Mantén los manejadores on_game_tick / on_tick ligeros -- se ejecutan cada tick.
Usa context.scheduler:run_repeating(...) para distribuir el trabajo entre ticks.
Mueve el trabajo costoso detrás de un cooldown basado en estado o un intervalo razonable.

`context.state`

Una tabla Lua simple que persiste durante toda la vida de la instancia del script. Úsala para almacenar flags, contadores, IDs de tareas, estados de alternancia y cualquier dato que necesites compartir entre hooks.

on_spawn = function(context)
  context.state.is_open = false
  context.state.click_count = 0
  context.state.task_id = nil
end,

on_right_click = function(context)
  context.state.click_count = (context.state.click_count or 0) + 1
end

info

Solo context.state persiste entre llamadas de hook. Todas las demás tablas de contexto (context.prop, context.world, context.event, etc.) se reconstruyen cada vez. context.state no se reconstruye -- sobrevive desde el momento en que se crea la instancia del script hasta que se destruye.

`context.log`

Métodos de logging en consola. Los mensajes van precedidos del nombre del archivo de script en la consola del servidor.

Método	Notas
`log:info(message)`	Mensaje informativo
`log:warn(message)`	Mensaje de advertencia
`log:error(message)`	Mensaje de nivel advertencia (registrado a nivel WARN, igual que `log:warn`)
`log:debug(message)`	Mensaje de depuración (aparece como nivel info con un prefijo de depuración)

context.log:info("Script loaded!")
context.log:warn("Something unexpected happened")
context.log:error("Critical failure in zone setup")
context.log:debug("State value: " .. tostring(context.state.counter))

`context.cooldowns`

La tabla cooldowns gestiona cooldowns basados en tiempo para tus scripts. Hay dos ámbitos:

Cooldowns locales son por instancia de script e identificados por una clave string. Si no se proporciona clave, el nombre del archivo del script se usa como clave por defecto.
Cooldowns globales se comparten entre todos los scripts del mismo propietario de entidad (por ejemplo, todos los scripts del mismo prop, o todos los poderes Lua del mismo jefe).

`cooldowns:check_local(key?, duration)`

El método más común. Verifica si el cooldown está listo, y si es así, lo inicia y retorna true. Si no está listo, retorna false. Es un check-and-set atómico — sin condiciones de carrera.

Parámetro	Tipo	Notas
`key`	string (opcional)	Identificador del cooldown. Por defecto es el nombre del archivo del script.
`duration`	int	Duración del cooldown en ticks (20 = 1 segundo)

on_right_click = function(context)
  -- Only allow this action once every 3 seconds
  if not context.cooldowns:check_local("interact", 60) then
    return
  end
  -- ... do the action
end

`cooldowns:local_ready(key?)`

Retorna true si el cooldown local ha expirado (o nunca fue establecido), false si aún está activo.

`cooldowns:local_remaining(key?)`

Retorna el número de ticks restantes en el cooldown local, o 0 si está listo.

`cooldowns:set_local(duration, key?)`

Establece un cooldown local sin verificar si ya hay uno activo. Usa esto para reinicios incondicionales de cooldown.

Parámetro	Tipo	Notas
`duration`	int	Duración en ticks. Pasa 0 o negativo para limpiar.
`key`	string (opcional)	Identificador del cooldown. Por defecto es el nombre del archivo del script.

`cooldowns:global_ready()`

Retorna true si el cooldown global (compartido entre todos los scripts de la misma entidad) ha expirado.

`cooldowns:set_global(duration)`

Establece el cooldown global.

Parámetro	Tipo	Notas
`duration`	int	Duración en ticks

Cooldowns globales de EliteMobs

En los scripts de poderes de EliteMobs, global_ready() y set_global() usan el sistema de cooldown de poderes incorporado del jefe, que es compartido entre todos los poderes Lua del mismo jefe. Los cooldowns locales en EliteMobs también se comparten entre todos los poderes de la misma entidad jefe (identificados por tu string elegido).

`context.scheduler`

El scheduler te permite ejecutar tareas con retraso y repetitivas. Todas las tareas pertenecen a la instancia del script y se cancelan automáticamente cuando la instancia del script se destruye (por ejemplo, cuando un prop se elimina o un jefe muere).

`scheduler:run_later(ticks, callback)`

Ejecuta un callback una vez después de un retraso. Retorna un ID numérico de tarea.

Parámetro	Tipo	Notas
`ticks`	int	Retraso en ticks del servidor (20 ticks = 1 segundo)
`callback`	function	Se llama con un `context` fresco cuando el retraso expira

context.scheduler:run_later(40, function(delayed_context)
  delayed_context.log:info("2 seconds have passed!")
end)

`scheduler:run_repeating(delay, interval, callback)`

Ejecuta un callback repetidamente a un intervalo fijo. Retorna un ID numérico de tarea.

Parámetro	Tipo	Notas
`delay`	int	Retraso inicial en ticks antes de la primera ejecución
`interval`	int	Ticks entre cada ejecución subsiguiente
`callback`	function	Se llama con un `context` fresco en cada intervalo

context.state.particle_task = context.scheduler:run_repeating(0, 20, function(tick_context)
  tick_context.log:info("Another second passed!")
end)

`scheduler:cancel(taskId)`

Cancela una tarea programada por su ID.

Parámetro	Tipo	Notas
`taskId`	int	El ID de tarea retornado por `run_later` o `run_repeating`

Cancela siempre las tareas repetitivas

Si inicias una tarea repetitiva, siempre cancélala en tu hook de limpieza (on_destroy para props, on_exit_combat / on_death para jefes, on_unequip para objetos). Olvidar cancelar deja una tarea en segundo plano ejecutándose hasta que la instancia del script se destruya, lo que desperdicia rendimiento y puede causar errores.

Los callbacks reciben contexto fresco

Los callbacks programados reciben un contexto fresco como su parámetro. Siempre usa el argumento de contexto propio del callback, no el context externo del hook que creó el callback. El contexto externo puede contener referencias obsoletas.

`context.world`

La tabla world proporciona métodos para consultar e interactuar con el mundo de Minecraft. Se construye a partir del mundo actual de la entidad.

Extensiones específicas de plugin

EliteMobs extiende context.world con métodos adicionales para generar jefes, refuerzos, bloques cayendo, fuegos artificiales, pociones splash y bloques temporales. Consulta Mundo y Entorno de EliteMobs para la API extendida completa. Los métodos documentados aquí están disponibles en todos los plugins.

`world.name`

Un campo string que contiene el nombre del mundo.

`world:get_block_at(x, y, z)`

Retorna el nombre del material del bloque en las coordenadas dadas como un string en minúsculas (por ejemplo, "stone", "air").

Parámetro	Tipo	Notas
`x`	int	Coordenada X del bloque
`y`	int	Coordenada Y del bloque
`z`	int	Coordenada Z del bloque

`world:set_block_at(x, y, z, material)`

Establece el bloque en las coordenadas dadas. Se ejecuta en el hilo principal.

Parámetro	Tipo	Notas
`x`	int	Coordenada X del bloque
`y`	int	Coordenada Y del bloque
`z`	int	Coordenada Z del bloque
`material`	string	Nombre de Material de Bukkit, en minúsculas (por ejemplo, `"stone"`, `"air"`, `"oak_planks"`)

Retorna true si el bloque fue establecido exitosamente, false en caso contrario.

`world:spawn_particle(particle, x, y, z, count, dx, dy, dz, speed)`

Genera partículas en una ubicación.

Parámetro	Tipo	Predeterminado	Notas
`particle`	string	requerido	Nombre del enum Particle de Bukkit, MAYÚSCULAS (por ejemplo, `"FLAME"`, `"DUST"`)
`x`	number	requerido	Coordenada X
`y`	number	requerido	Coordenada Y
`z`	number	requerido	Coordenada Z
`count`	int	`1`	Número de partículas
`dx`	number	`0`	Dispersión/desplazamiento en X
`dy`	number	`0`	Dispersión/desplazamiento en Y
`dz`	number	`0`	Dispersión/desplazamiento en Z
`speed`	number	`0`	Velocidad de las partículas

Partículas que requieren datos

Algunos tipos de partículas requieren datos de bloque u objeto que no son soportados por esta API simple. BLOCK_CRACK, FALLING_DUST, BLOCK_DUST y ITEM_CRACK fallarán o no producirán efecto visible. Usa alternativas que no requieran datos: CLOUD, SMOKE, CAMPFIRE_COSY_SMOKE, SNOWFLAKE, FLAME, DUST, etc.

`world:play_sound(sound, x, y, z, volume, pitch)`

Reproduce un sonido en una ubicación.

Parámetro	Tipo	Predeterminado	Notas
`sound`	string	requerido	Nombre del enum Sound de Bukkit, MAYÚSCULAS (por ejemplo, `"ENTITY_EXPERIENCE_ORB_PICKUP"`)
`x`	number	requerido	Coordenada X
`y`	number	requerido	Coordenada Y
`z`	number	requerido	Coordenada Z
`volume`	number	`1.0`	Volumen
`pitch`	number	`1.0`	Tono

`world:strike_lightning(x, y, z)`

Invoca un rayo en una ubicación (visual y con daño).

Parámetro	Tipo	Notas
`x`	number	Coordenada X
`y`	number	Coordenada Y
`z`	number	Coordenada Z

`world:get_time()`

Retorna el tiempo actual del mundo en ticks.

`world:set_time(ticks)`

Establece el tiempo del mundo.

Parámetro	Tipo	Notas
`ticks`	int	Tiempo del mundo (0 = amanecer, 6000 = mediodía, 13000 = noche, 18000 = medianoche)

`world:get_nearby_entities(x, y, z, radius)`

Retorna un array de tablas wrapper de entidades para todas las entidades dentro de un cubo delimitador centrado en las coordenadas dadas.

Parámetro	Tipo	Notas
`x`	number	Centro X
`y`	number	Centro Y
`z`	number	Centro Z
`radius`	number	Radio de búsqueda (usado como semi-extensión en los tres ejes)

precaución

Esto retorna TODAS las entidades en rango, incluyendo entidades no vivas (armor stands, objetos tirados, etc.). Siempre verifica con if entity.damage then antes de llamar métodos de entidades vivas.

`world:get_nearby_players(x, y, z, radius)`

Retorna un array de tablas wrapper de jugadores para todos los jugadores dentro de un cubo delimitador centrado en las coordenadas dadas.

Parámetro	Tipo	Notas
`x`	number	Centro X
`y`	number	Centro Y
`z`	number	Centro Z
`radius`	number	Radio de búsqueda

`world:spawn_entity(entity_type, x, y, z)`

Genera una entidad vanilla de Minecraft en la ubicación dada.

Parámetro	Tipo	Notas
`entity_type`	string	Nombre de tipo de entidad de Bukkit, en minúsculas (por ejemplo, `"zombie"`, `"skeleton"`, `"pig"`)
`x`	number	Coordenada X
`y`	number	Coordenada Y
`z`	number	Coordenada Z

Retorna una tabla de entidad para la entidad generada (con métodos de entidad viva si aplica), o nil si el tipo de entidad es inválido.

`world:get_highest_block_y(x, z)`

Retorna la coordenada Y del bloque no-aire más alto en la posición X/Z dada.

Parámetro	Tipo	Notas
`x`	int	Coordenada X del bloque
`z`	int	Coordenada Z del bloque

`world:raycast(from_x, from_y, from_z, dir_x, dir_y, dir_z, [max_distance])`

Lanza un rayo desde un punto en una dirección y retorna información sobre lo que impacta.

Parámetro	Tipo	Predeterminado	Notas
`from_x`	number	requerido	Origen X
`from_y`	number	requerido	Origen Y
`from_z`	number	requerido	Origen Z
`dir_x`	number	requerido	Componente X de dirección
`dir_y`	number	requerido	Componente Y de dirección
`dir_z`	number	requerido	Componente Z de dirección
`max_distance`	number	`50`	Distancia máxima del rayo

Retorna una tabla con los siguientes campos:

Campo	Tipo	Notas
`hit_entity`	tabla de entidad o nil	La primera entidad impactada por el rayo, o `nil` si ninguna
`hit_location`	tabla de ubicación o nil	El punto exacto donde el rayo impactó algo
`hit_block`	tabla o nil	`{x, y, z, material}` del bloque impactado, o `nil` si no se impactó ningún bloque

`world:spawn_firework(x, y, z, colors, [type], [power])`

Genera un cohete de fuegos artificiales en la ubicación dada.

Parámetro	Tipo	Predeterminado	Notas
`x`	number	requerido	Coordenada X
`y`	number	requerido	Coordenada Y
`z`	number	requerido	Coordenada Z
`colors`	table	requerido	Array de strings de colores, por ejemplo `{"RED", "BLUE", "WHITE"}`
`type`	string	`"BALL"`	Forma del fuego artificial: `"BALL"`, `"BALL_LARGE"`, `"STAR"`, `"BURST"`, `"CREEPER"`
`power`	int	`1`	Potencia de vuelo, 0-127

-- Example: red and gold firework burst
context.world:spawn_firework(loc.x, loc.y, loc.z, {"RED", "GOLD"}, "BURST", 2)

`world:place_temporary_block(x, y, z, material, [ticks], [require_air])`

Coloca un bloque que automáticamente vuelve a su estado original después de un retraso.

Parámetro	Tipo	Predeterminado	Notas
`x`	int	requerido	Coordenada X del bloque
`y`	int	requerido	Coordenada Y del bloque
`z`	int	requerido	Coordenada Z del bloque
`material`	string	requerido	Nombre de Material de Bukkit (por ejemplo, `"stone"`, `"ice"`)
`ticks`	int	`0`	Duración en ticks antes de que el bloque se revierta. 0 significa permanente.
`require_air`	boolean	`false`	Si es `true`, solo coloca el bloque si el objetivo es aire

Retorna true si el bloque fue colocado, false si el material era inválido o el requisito de aire no se cumplió.

`world:drop_item(x, y, z, material, [amount])`

Suelta una entidad de objeto en la ubicación dada con dispersión natural.

Parámetro	Tipo	Predeterminado	Notas
`x`	number	requerido	Coordenada X
`y`	number	requerido	Coordenada Y
`z`	number	requerido	Coordenada Z
`material`	string	requerido	Nombre de Material de Bukkit
`amount`	int	`1`	Tamaño del stack

Retorna una tabla de entidad para el objeto soltado, o nil si el material era inválido.

`context.zones`

La tabla zones te permite crear zonas espaciales y vigilarlas para eventos de entrada/salida de jugadores. Las zonas están vinculadas a la instancia del script y se limpian automáticamente cuando la instancia del script se destruye.

`zones:create_sphere(x, y, z, radius)`

Crea una zona esférica centrada en las coordenadas dadas. Retorna un manejador numérico de zona.

Parámetro	Tipo	Notas
`x`	number	Centro X
`y`	number	Centro Y
`z`	number	Centro Z
`radius`	number	Radio de la esfera

`zones:create_cylinder(x, y, z, radius, height)`

Crea una zona cilíndrica. Retorna un manejador numérico de zona.

Parámetro	Tipo	Notas
`x`	number	Centro X
`y`	number	Centro Y (base)
`z`	number	Centro Z
`radius`	number	Radio del cilindro
`height`	number	Altura del cilindro

`zones:create_cuboid(x, y, z, xSize, ySize, zSize)`

Crea una zona cuboide. Retorna un manejador numérico de zona.

Parámetro	Tipo	Notas
`x`	number	Centro X
`y`	number	Centro Y
`z`	number	Centro Z
`xSize`	number	Semi-extensión en X
`ySize`	number	Semi-extensión en Y
`zSize`	number	Semi-extensión en Z

`zones:watch(handle, onEnterCallback, onLeaveCallback)`

Comienza a vigilar una zona para eventos de entrada/salida de jugadores. Cuando un jugador entra o sale de la zona, se dispara el callback correspondiente (y, si están definidos, los hooks on_zone_enter / on_zone_leave).

Parámetro	Tipo	Notas
`handle`	int	Manejador de zona de una llamada `create_*`
`onEnterCallback`	function o nil	Se llama cuando un jugador entra en la zona
`onLeaveCallback`	function o nil	Se llama cuando un jugador sale de la zona

Retorna true si la vigilancia se configuró exitosamente, nil si el manejador de zona era inválido.

info

Las vigilancias de zona se verifican cada tick del servidor contra todos los jugadores en el mismo mundo. Mantén un número razonable de zonas para evitar sobrecarga de rendimiento.

`zones:unwatch(handle)`

Deja de vigilar una zona y limpia sus recursos.

Parámetro	Tipo	Notas
`handle`	int	Manejador de zona que dejar de vigilar

Ejemplo: Zona de activación por proximidad

return {
  api_version = 1,

  on_spawn = function(context)
    local loc = context.prop.current_location  -- or context.boss:get_location()
    if loc == nil then return end

    local handle = context.zones:create_sphere(loc.x, loc.y, loc.z, 5)

    context.zones:watch(
      handle,
      function(player)
        context.log:info("Player entered zone!")
      end,
      function(player)
        context.log:info("Player left zone!")
      end
    )

    context.state.zone_handle = handle
  end,

  on_destroy = function(context)
    if context.state.zone_handle then
      context.zones:unwatch(context.state.zone_handle)
    end
  end
}

`context.event`

La tabla event está presente cuando el hook actual fue activado por un evento del juego (por ejemplo, on_right_click, on_zone_enter). No está presente durante on_tick o callbacks programados.

Campo / Método	Tipo	Notas
`is_cancelled`	boolean	Si el evento ha sido cancelado
`cancel()`	method	Cancela el evento (previene el comportamiento predeterminado)
`uncancel()`	method	Des-cancela un evento previamente cancelado
`player`	entity table	El jugador involucrado en el evento, si hay alguno

on_right_click = function(context)
  if context.event then
    context.event:cancel()  -- prevent the default right-click interaction
  end
end

Tabla de eventos de EliteMobs

Los scripts de poderes de EliteMobs tienen una tabla de eventos más detallada con cantidades de daño, causas de daño, referencias al atacante y métodos de modificación de daño. Consulta Referencia de API Lua para los campos completos de eventos de EliteMobs.

Espacio de Nombres `em`

La tabla em está disponible en tiempo de carga del archivo (antes de que se ejecute cualquier hook). Proporciona constructores auxiliares para crear tablas de ubicación, tablas de vectores y definiciones de zonas usadas en toda la API.

Función	Propósito
`em.create_location(x, y, z [, world, yaw, pitch])`	Crea una tabla de ubicación con nombre de mundo, yaw y pitch opcionales. La tabla retornada también tiene un método `.add(dx, dy, dz)` que desplaza la ubicación in-place y retorna sí misma para encadenamiento.
`em.create_vector(x, y, z)`	Crea una tabla de vector
`em.zone.create_sphere_zone(radius)`	Crea una definición de zona esférica
`em.zone.create_dome_zone(radius)`	Crea una definición de zona de cúpula
`em.zone.create_cylinder_zone(radius, height)`	Crea una definición de zona cilíndrica
`em.zone.create_cuboid_zone(x, y, z)`	Crea una definición de zona cuboide
`em.zone.create_cone_zone(length, radius)`	Crea una definición de zona cónica
`em.zone.create_static_ray_zone(length, thickness)`	Crea una definición de zona de rayo estático
`em.zone.create_rotating_ray_zone(length, point_radius, animation_duration)`	Crea una definición de zona de rayo rotatorio
`em.zone.create_translating_ray_zone(length, point_radius, animation_duration)`	Crea una definición de zona de rayo traslativo

Los constructores de zonas retornan tablas encadenables con :set_center(loc) (o :set_origin(loc) / :set_destination(loc) dependiendo del tipo de zona):

-- At file scope: create a reusable zone shape
local blast_zone = em.zone.create_sphere_zone(5)

return {
  api_version = 1,

  on_spawn = function(context)
    -- Anchor the zone at call time
    blast_zone:set_center(context.boss:get_location())
    local entities = context.zones:get_entities_in_zone(blast_zone)
    -- ...
  end
}

info

El espacio de nombres em es particularmente útil en EliteMobs donde las definiciones de zona se usan con context.zones:get_entities_in_zone() y context.script. En FreeMinecraftModels, los métodos context.zones:create_sphere(...) / create_cylinder(...) / create_cuboid(...) se usan más comúnmente para zonas simples basadas en vigilancia.

Tablas de Entidades

Las tablas de entidades son retornadas por consultas al mundo, datos de eventos y callbacks de zonas. Proporcionan un conjunto de campos y métodos por capas dependiendo del tipo de entidad.

Campos Base de Entidad

Campo	Tipo	Notas
`uuid`	string	El UUID de la entidad
`entity_type`	string	El tipo de entidad (por ejemplo, `"player"`, `"zombie"`, `"skeleton"`, `"villager"`)
`is_valid`	boolean	Si la referencia de entidad sigue siendo válida
`is_dead`	boolean	Si la entidad está muerta
`is_player`	boolean	Si la entidad es un jugador
`is_hostile`	boolean	Si la entidad es un mob hostil (zombie, skeleton, etc.)
`is_passive`	boolean	Si la entidad es un mob pasivo (vaca, cerdo, gallina, etc.)
`current_location`	tabla de ubicación	La posición actual de la entidad (`x`, `y`, `z`, `world`, `yaw`, `pitch`)
`world`	string	El nombre del mundo en el que está la entidad

Métodos Base de Entidad

Método	Retorna	Notas
`teleport(location_table)`	void	Teletransporta la entidad. La tabla de ubicación debe tener campos `x`, `y`, `z`, `world`; `yaw` y `pitch` son opcionales.
`remove()`	void	Elimina la entidad del mundo. Solo actúa si la entidad aún es válida.
`set_silent(flag)`	void	Suprime o reactiva los sonidos de la entidad.
`set_invulnerable(flag)`	void	Hace a la entidad invulnerable o vulnerable al daño.
`set_gravity(flag)`	void	Habilita o deshabilita la gravedad para la entidad.
`set_glowing(flag)`	void	Alterna el efecto de contorno brillante en la entidad.

Campos de Entidad Viva

Las entidades vivas (jugadores, mobs, etc.) tienen todos los campos base de entidad más:

Campo	Tipo	Notas
`health`	number	Salud actual
`maximum_health`	number	Salud máxima
`name`	string	Nombre para mostrar
`is_alive`	boolean	Si la entidad está viva

Métodos de Entidad Viva

Método	Retorna	Notas
`damage(amount)`	void	Inflige la cantidad dada de daño a la entidad
`push(x, y, z)`	void	Aplica un impulso de velocidad
`set_facing(x, y, z)`	void	Establece la dirección a la que mira la entidad
`add_potion_effect(effect, duration, amplifier)`	void	Agrega un efecto de poción. `effect` es un string (por ejemplo, `"speed"`, `"slowness"`, `"regeneration"`). `duration` es en ticks. `amplifier` es el nivel del efecto menos 1 (0 = nivel I).
`remove_potion_effect(effect)`	void	Elimina un efecto de poción por nombre

precaución

No todas las entidades retornadas por get_nearby_entities() son entidades vivas. Puedes usar entity.is_player, entity.is_hostile o entity.is_passive para filtrar por categoría, o verificar if entity.damage then antes de llamar métodos de entidades vivas como damage(), push() o add_potion_effect().

Campos de Integración de Plugins

Las tablas de entidades incluyen automáticamente campos para detectar e interactuar con entidades gestionadas por otros plugins de Nightbreak. Estos campos solo se llenan cuando el plugin relevante está instalado -- de lo contrario, por defecto son false / nil sin sobrecarga.

Campos de EliteMobs

Disponibles cuando EliteMobs está instalado.

Campo	Tipo	Notas
`is_elite`	boolean	Si la entidad es un elite de EliteMobs
`is_custom_boss`	boolean	Si la entidad es un jefe personalizado de EliteMobs (también disponible dentro de la subtabla `elite`)
`is_significant_boss`	boolean	Si la entidad es un jefe personalizado con un multiplicador de salud mayor a 1 (es decir, un encuentro diseñado, no un elite de relleno)
`elite`	tabla o nil	Subtabla de información de elite (ver abajo). `nil` si la entidad no es un elite.

La subtabla elite contiene:

Campo	Tipo	Notas
`elite.level`	int	El nivel del elite
`elite.name`	string	El nombre para mostrar del elite
`elite.health`	number	Salud actual
`elite.max_health`	number	Salud máxima
`elite.is_custom_boss`	boolean	Si es un jefe personalizado (en oposición a un elite natural)
`elite.health_multiplier`	number	Multiplicador de salud definido en configuración
`elite.damage_multiplier`	number	Multiplicador de daño definido en configuración
`elite:remove()`	void	Elimina el elite a través del pipeline de eliminación apropiado de EliteMobs (limpia rastreo, botín, etc.)

Ejemplo: Dañar elites de forma diferente

local entities = context.world:get_nearby_entities(x, y, z, 5)
for _, entity in ipairs(entities) do
    if entity.is_elite then
        -- Deal double damage to elites
        entity:damage(20)
        context.log:info("Hit elite: " .. entity.elite.name .. " (level " .. entity.elite.level .. ")")
    elseif entity.is_hostile then
        entity:damage(10)
    end
end

Campos de FreeMinecraftModels

Disponibles cuando FreeMinecraftModels está instalado.

Campo	Tipo	Notas
`is_modeled`	boolean	Si la entidad tiene un modelo FMM adjunto (DynamicEntity o PropEntity)
`is_prop`	boolean	Si la entidad es un prop de FMM (entidad decorativa estática)
`model`	tabla o nil	Subtabla de información del modelo (ver abajo). `nil` si la entidad no tiene modelo.

La subtabla model contiene:

Campo	Tipo	Notas
`model.model_id`	string	El ID del blueprint del modelo (por ejemplo, `"torch_01"`)
`model:play_animation(name, [blend], [loop])`	boolean	Reproduce una animación nombrada. `blend` por defecto es `false`, `loop` por defecto es `false`. Retorna `true` si la animación fue encontrada.
`model:stop_animations()`	void	Detiene todas las animaciones actualmente en reproducción en el modelo.
`model:remove()`	void	Elimina la entidad modelada a través del pipeline de eliminación apropiado de FMM.

Puente vs valores predeterminados de Prop

El puente del modelo (disponible en cualquier entidad) establece por defecto blend y loop en false. La tabla prop play_animation establece ambos por defecto en true porque los props típicamente quieren animaciones mezcladas y en bucle.

Ejemplo: Filtrar entidades por tipo

local entities = context.world:get_nearby_entities(x, y, z, 10)
for _, entity in ipairs(entities) do
    if entity.is_prop then
        -- Skip props
    elseif entity.is_player then
        entity:damage(5)
    elseif entity.entity_type == "villager" then
        -- Don't hurt villagers
    elseif entity.is_elite then
        entity:damage(20)
    elseif entity.is_hostile then
        entity:damage(10)
    end
end

Campos Específicos de Jugador

Las entidades jugador tienen todos los campos de entidad y entidad viva más:

Campo	Tipo	Notas
`game_mode`	string	El modo de juego del jugador (`"creative"`, `"survival"`, `"adventure"`, `"spectator"`)

Métodos Específicos de Jugador

Método	Retorna	Notas
`send_message(msg)`	void	Envía un mensaje de chat al jugador. Soporta códigos de color `&`.
`get_held_item()`	tabla o nil	Retorna `{type, amount, display_name}` para el objeto en la mano principal del jugador, o `nil` si está vacía
`consume_held_item(amount?)`	void	Consume objetos de la mano principal del jugador. `amount` por defecto es `1`
`has_item(material, amount?)`	boolean	Retorna `true` si el jugador tiene al menos `amount` (por defecto `1`) del material dado en cualquier parte de su inventario
`get_target_entity([range])`	tabla de entidad o nil	Retorna la entidad que el jugador está mirando vía raycast, o `nil` si ninguna. Rango por defecto es 50.
`get_eye_location()`	tabla de ubicación	Retorna una tabla de ubicación a la altura de los ojos del jugador
`get_look_direction()`	tabla	Retorna un vector de dirección `{x, y, z}` de hacia dónde mira el jugador
`send_block_change(x, y, z, material, [ticks])`	void	Envía un bloque falso visible solo para este jugador. Si se proporciona `ticks`, el bloque falso se reinicia automáticamente después de esa duración.
`reset_block(x, y, z)`	void	Reinicia un bloque falso al bloque real para este jugador
`sleep(x, y, z)`	void	Hace que el jugador entre en animación de dormir en cama en las coordenadas dadas. El bloque se restaura automáticamente cuando el jugador deja de dormir.
`wake_up()`	void	Despierta a un jugador dormido.

Métodos de UI de Jugador

Estos métodos están disponibles en cualquier tabla de entidad de jugador y proporcionan formas de mostrar información al jugador a través de los elementos de UI integrados de Minecraft.

`player:show_boss_bar(text, [color], progress, [ticks])`

Muestra una barra de jefe al jugador.

Parámetro	Tipo	Predeterminado	Notas
`text`	string	requerido	El texto a mostrar. Soporta códigos de color `&`.
`color`	string	`"WHITE"`	Color de la barra. Uno de: `"RED"`, `"BLUE"`, `"GREEN"`, `"YELLOW"`, `"PURPLE"`, `"PINK"`, `"WHITE"`
`progress`	number	requerido	Cantidad de relleno de `0.0` (vacío) a `1.0` (lleno)
`ticks`	int	nil	Retraso opcional de auto-ocultación en ticks. Si se omite, la barra permanece hasta que se oculta manualmente.

`player:hide_boss_bar()`

Elimina la barra de jefe de la pantalla del jugador. No toma parámetros.

`player:show_action_bar(text, [ticks])`

Muestra texto en el área de la barra de acción (encima de la barra de acceso rápido).

Parámetro	Tipo	Predeterminado	Notas
`text`	string	requerido	El texto a mostrar. Soporta códigos de color `&`.
`ticks`	int	nil	Duración opcional en ticks. Si se proporciona, el mensaje se reenvía cada 40 ticks para mantenerlo visible durante toda la duración.

`player:show_title(title, [subtitle], fade_in, stay, fade_out)`

Muestra una pantalla de título al jugador.

Parámetro	Tipo	Predeterminado	Notas
`title`	string	requerido	Texto del título principal. Soporta códigos de color `&`.
`subtitle`	string	`""`	Texto del subtítulo debajo del título principal. Opcional.
`fade_in`	int	requerido	Duración de aparición gradual en ticks
`stay`	int	requerido	Cuánto tiempo permanece el título en pantalla en ticks
`fade_out`	int	requerido	Duración de desaparición gradual en ticks

Siguientes Pasos

Para hooks, APIs y flujos de trabajo específicos de cada plugin:

EliteMobs: Primeros Pasos | Hooks y Ciclo de Vida | Jefes y Entidades | Mundo y Entorno | Zonas y Targeting
FreeMinecraftModels: Primeros Pasos | API de Props y Objetos | Ejemplos

Mini Introducción a Lua
Sandbox de Lua
- Globales Eliminados
- Biblioteca Estándar Disponible
Contrato del Archivo
- Campos de Nivel Superior Requeridos y Opcionales
- Reglas de Validación
Sintaxis de Métodos: : vs .
Presupuesto de Ejecución
context.state
context.log
context.cooldowns
context.scheduler
context.world
context.zones
context.event
Espacio de Nombres em
Tablas de Entidades
Métodos de UI de Jugador
Siguientes Pasos

Mini Introducción a Lua​

Variables​

Funciones​

Comprobaciones if​

nil​

Tablas​

Retornando la definición del script​

Comentarios​

Sandbox de Lua​

Globales Eliminados​

Biblioteca Estándar Disponible​

Contrato del Archivo​

Campos de Nivel Superior Requeridos y Opcionales​

Reglas de Validación​

Sintaxis de Métodos: : vs .​

Presupuesto de Ejecución​

context.state​

context.log​

context.cooldowns​

cooldowns:check_local(key?, duration)​

cooldowns:local_ready(key?)​

cooldowns:local_remaining(key?)​

cooldowns:set_local(duration, key?)​

cooldowns:global_ready()​

cooldowns:set_global(duration)​

context.scheduler​

scheduler:run_later(ticks, callback)​

scheduler:run_repeating(delay, interval, callback)​

scheduler:cancel(taskId)​

context.world​

world.name​

world:get_block_at(x, y, z)​

world:set_block_at(x, y, z, material)​

world:spawn_particle(particle, x, y, z, count, dx, dy, dz, speed)​

world:play_sound(sound, x, y, z, volume, pitch)​

world:strike_lightning(x, y, z)​

world:get_time()​

world:set_time(ticks)​

world:get_nearby_entities(x, y, z, radius)​

world:get_nearby_players(x, y, z, radius)​

world:spawn_entity(entity_type, x, y, z)​

world:get_highest_block_y(x, z)​

world:raycast(from_x, from_y, from_z, dir_x, dir_y, dir_z, [max_distance])​

world:spawn_firework(x, y, z, colors, [type], [power])​

world:place_temporary_block(x, y, z, material, [ticks], [require_air])​

world:drop_item(x, y, z, material, [amount])​

context.zones​

zones:create_sphere(x, y, z, radius)​

zones:create_cylinder(x, y, z, radius, height)​

zones:create_cuboid(x, y, z, xSize, ySize, zSize)​

zones:watch(handle, onEnterCallback, onLeaveCallback)​

zones:unwatch(handle)​

Ejemplo: Zona de activación por proximidad​

context.event​

Espacio de Nombres em​

Tablas de Entidades​

Campos Base de Entidad​

Métodos Base de Entidad​

Campos de Entidad Viva​

Métodos de Entidad Viva​

Campos de Integración de Plugins​

Campos de EliteMobs​

Campos de FreeMinecraftModels​

Campos Específicos de Jugador​

Métodos Específicos de Jugador​

Métodos de UI de Jugador​

player:show_boss_bar(text, [color], progress, [ticks])​

player:hide_boss_bar()​

player:show_action_bar(text, [ticks])​

player:show_title(title, [subtitle], fade_in, stay, fade_out)​

Siguientes Pasos​

Mini Introducción a Lua

Variables

Funciones

Comprobaciones `if`

`nil`

Tablas

Retornando la definición del script

Comentarios

Sandbox de Lua

Globales Eliminados

Biblioteca Estándar Disponible

Contrato del Archivo

Campos de Nivel Superior Requeridos y Opcionales

Reglas de Validación

Sintaxis de Métodos: `:` vs `.`

Presupuesto de Ejecución

`context.state`

`context.log`

`context.cooldowns`

`cooldowns:check_local(key?, duration)`

`cooldowns:local_ready(key?)`

`cooldowns:local_remaining(key?)`

`cooldowns:set_local(duration, key?)`

`cooldowns:global_ready()`

`cooldowns:set_global(duration)`

`context.scheduler`

`scheduler:run_later(ticks, callback)`

`scheduler:run_repeating(delay, interval, callback)`

`scheduler:cancel(taskId)`

`context.world`

`world.name`

`world:get_block_at(x, y, z)`

`world:set_block_at(x, y, z, material)`

`world:spawn_particle(particle, x, y, z, count, dx, dy, dz, speed)`

`world:play_sound(sound, x, y, z, volume, pitch)`

`world:strike_lightning(x, y, z)`

`world:get_time()`

`world:set_time(ticks)`

`world:get_nearby_entities(x, y, z, radius)`

`world:get_nearby_players(x, y, z, radius)`

`world:spawn_entity(entity_type, x, y, z)`

`world:get_highest_block_y(x, z)`

`world:raycast(from_x, from_y, from_z, dir_x, dir_y, dir_z, [max_distance])`

`world:spawn_firework(x, y, z, colors, [type], [power])`

`world:place_temporary_block(x, y, z, material, [ticks], [require_air])`

`world:drop_item(x, y, z, material, [amount])`

`context.zones`

`zones:create_sphere(x, y, z, radius)`

`zones:create_cylinder(x, y, z, radius, height)`

`zones:create_cuboid(x, y, z, xSize, ySize, zSize)`

`zones:watch(handle, onEnterCallback, onLeaveCallback)`

`zones:unwatch(handle)`

Ejemplo: Zona de activación por proximidad

`context.event`

Espacio de Nombres `em`

Tablas de Entidades

Campos Base de Entidad

Métodos Base de Entidad

Campos de Entidad Viva

Métodos de Entidad Viva

Campos de Integración de Plugins

Campos de EliteMobs

Campos de FreeMinecraftModels

Campos Específicos de Jugador

Métodos Específicos de Jugador

Métodos de UI de Jugador

`player:show_boss_bar(text, [color], progress, [ticks])`

`player:hide_boss_bar()`

`player:show_action_bar(text, [ticks])`

`player:show_title(title, [subtitle], fade_in, stay, fade_out)`

Siguientes Pasos