Motor de Scripts Lua do MagmaCore

O MagmaCore fornece um motor de scripts Lua compartilhado, usado por vários plugins do Nightbreak. O motor cuida do sandbox, agendamento, gerenciamento de zonas, interação com o mundo, tabelas de entidades e UI do jogador -- tudo com uma API consistente entre os plugins.

Atualmente, os seguintes plugins usam este motor:

• EliteMobs -- Poderes em Lua para chefes personalizados (hooks como on_boss_damaged_by_player, on_enter_combat, etc.)
• FreeMinecraftModels -- Scripts Lua para props e itens personalizados (hooks como on_right_click, on_left_click, on_equip, etc.)

Esta página documenta os recursos compartilhados do motor. Para hooks, APIs e fluxos de trabalho específicos de cada plugin, veja as páginas dos plugins linkadas acima.

---

Mini-introdução ao Lua

Se você é completamente novo no Lua, aqui está a sintaxe mínima necessária para escrever scripts para qualquer plugin do Nightbreak.

Variáveis

Use local para armazenar um valor:

local cooldown_key = "fire_burst"
local damage_multiplier = 1.5

local significa que a variável pertence apenas a este arquivo ou bloco.

Funções

Funções são blocos de lógica reutilizáveis:

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

Depois, você pode chamá-la:

warn_player(some_player)

Verificações if

Use if quando algo só deve acontecer em certas condições:

if context.player == nil then
  return
end

Isso significa "se não houver um jogador para este hook, pare aqui".

nil

nil significa "sem valor". É a versão Lua de "não há nada aqui".

Você vai frequentemente verificar por nil com:

if context.event ~= nil then
  -- faça algo com o evento
end

~= significa "não é igual a".

Tabelas

O Lua usa tabelas para várias funções:

• Listas
• Objetos com chaves nomeadas
• A definição final do script que é retornada

Exemplo de uma tabela com chaves nomeadas:

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

Retornando a definição do script

No final de cada arquivo de script, você retorna uma tabela:

return {
  api_version = 1,

  on_spawn = function(context)
  end
}

Essa tabela retornada é o arquivo de script.

Comentários

Use -- para escrever uma nota para humanos:

-- Este cooldown impede que o ataque dispare a cada acerto
context.cooldowns:set_local(60, "fire_burst")

---

Sandbox Lua

Todos os scripts Lua rodam dentro de um ambiente LuaJ em sandbox. Várias globais que poderiam acessar o sistema de arquivos ou o runtime do Java são removidas. As regras do sandbox são idênticas em todos os plugins que usam o MagmaCore.

Globais Removidas

As seguintes globais padrão do Lua são definidas como nil e não podem ser usadas:

Removida	Motivo
debug	Expõe o estado interno da VM
dofile	Acesso ao sistema de arquivos
io	Acesso ao sistema de arquivos
load	Carregamento de código arbitrário
loadfile	Acesso ao sistema de arquivos
luajava	Acesso direto a classes Java
module	Sistema de módulos (não necessário)
os	Acesso ao sistema operacional
package	Sistema de módulos (não necessário)
require	Sistema de módulos / acesso ao sistema de arquivos

Biblioteca Padrão Disponível

Todo o restante da biblioteca padrão do Lua funciona normalmente:

Categoria	Funções
Math	math.abs, math.ceil, math.floor, math.max, math.min, math.random, math.sin, math.cos, math.sqrt, math.pi, e todas as outras funções math.*
String	string.byte, string.char, string.find, string.format, string.gsub, string.len, string.lower, string.match, string.rep, string.sub, string.upper, e todas as outras funções string.*
Table	table.insert, table.remove, table.sort, table.concat, e todas as outras funções table.*
Iteradores	pairs, ipairs, next
Tipo	type, tostring, tonumber, select, unpack
Tratamento de erros	pcall, xpcall, error, assert
Outros	print, rawget, rawset, rawequal, rawlen, setmetatable, getmetatable

A biblioteca os não está disponível

A biblioteca os foi completamente removida do sandbox. Se você precisar de informações de tempo, use context.world:get_time() para o tempo do mundo ou armazene timestamps em context.state usando contadores de ticks através do hook on_game_tick.

dica

print escreve no console do servidor, mas prefira context.log:info(msg) para saída. As mensagens de log recebem como prefixo o nome do arquivo do script, facilitando rastrear qual script produziu a mensagem.

---

Contrato de Arquivo

Todo script Lua deve return uma tabela. Essa tabela é intencionalmente rigorosa.

Campos de Topo Obrigatórios e Opcionais

Campo	Obrigatório	Tipo	Notas
api_version	Sim	Number	Atualmente deve ser 1
priority	Não	Number	Prioridade de execução. Valores menores rodam primeiro. Padrão 0
chaves de hook suportadas	Não	Function	Devem usar um dos nomes exatos de hook suportados pelo plugin

Regras de Validação

• O arquivo deve retornar uma tabela.
• api_version é obrigatório e atualmente deve ser 1.
• priority deve ser numérico, se presente.
• Cada chave extra de topo deve ser um nome de hook suportado.
• Cada chave de hook deve apontar para uma função.
• Chaves de topo desconhecidas são rejeitadas.

Funções auxiliares e constantes locais devem ficar acima do return final, não dentro da tabela retornada -- a não ser que sejam, de fato, hooks.

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
}

---

Hooks Compartilhados do Motor

Os hooks a seguir estão disponíveis em todos os plugins que usam o motor de scripts do MagmaCore. Plugins individuais adicionam seus próprios hooks por cima desses.

Hook	Quando dispara
on_spawn	Chamado uma vez quando a instância do script é criada (entidade nasce ou prop é colocado)
on_game_tick	Chamado a cada tick do servidor enquanto a entidade estiver viva/ativa
on_zone_enter	Chamado quando um jogador entra em uma zona observada
on_zone_leave	Chamado quando um jogador sai de uma zona observada

---

Sintaxe de Método: : vs .

No Lua, object:method(arg) é uma forma abreviada de object.method(object, arg). A API do MagmaCore aceita as duas formas, então ambas funcionam:

context.log:info("hello")
context.log.info("hello")  -- mesma coisa

Toda a documentação usa : de forma consistente.

---

Orçamento de Execução

Cada invocação de hook e cada invocação de callback é cronometrada. Se uma única chamada demorar mais de 50 milissegundos, o script é desabilitado com um aviso no console:

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

Para se manter dentro do orçamento:

• Evite loops sem limite dentro de hooks.
• Mantenha handlers de on_game_tick leves -- eles rodam a cada tick.
• Use context.scheduler:run_repeating(...) para distribuir o trabalho ao longo dos ticks.
• Mova trabalho caro para trás de um cooldown baseado em estado ou um intervalo razoável.

Erros em tempo de execução de scripts

Se um script Lua lançar um erro de runtime em qualquer hook ou callback agendado, a instância do script é desabilitada imediata e permanentemente para aquela entidade. Corrija o erro no seu arquivo de script -- o script vai reinicializar no próximo spawn da entidade.

---

context.state

Uma tabela Lua comum que persiste por toda a vida útil da instância do script. Use-a para armazenar flags, contadores, IDs de tarefas, estados de toggle e qualquer dado que você precise compartilhar 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

informação

Apenas context.state persiste entre chamadas de hook. Todas as outras tabelas de contexto (context.prop, context.world, context.event, etc.) são reconstruídas do zero a cada chamada. context.state não é reconstruída -- ela sobrevive desde o momento em que a instância do script é criada até ser destruída.

---

context.log

Métodos de log no console. As mensagens são prefixadas com o nome do arquivo do script no console do servidor.

Método	Notas
log:info(message)	Mensagem informativa
log:warn(message)	Mensagem de aviso
log:error(message)	Mensagem de nível de aviso (registrada em nível WARN, igual a log:warn)

Variante do EliteMobs

O context.log do EliteMobs registra debug em vez de error. Use log:debug(message) para saída de depuração (aparece como nível info com um prefixo de debug).

context.log:info("Script loaded!")
context.log:warn("Something unexpected happened")
context.log:error("Critical failure in zone setup")

---

context.cooldowns

A tabela cooldowns gerencia cooldowns baseados em tempo para seus scripts. Há dois escopos:

• Cooldowns locais são por instância de script e identificados por uma chave string. Se nenhuma chave for fornecida, o nome do arquivo do script é usado como chave padrão.
• Cooldowns globais são compartilhados entre todos os scripts da mesma entidade dona (ex.: todos os scripts no mesmo prop, ou todos os poderes Lua no mesmo chefe).

cooldowns:check_local(key?, duration)

O método mais comum. Verifica se o cooldown está pronto e, em caso afirmativo, inicia-o e retorna true. Se não estiver pronto, retorna false. Esta é uma verificação atômica de "checar e definir" — sem condições de corrida.

Parâmetro	Tipo	Notas
key	string (opcional)	Identificador do cooldown. Padrão é o nome do arquivo do script.
duration	int	Duração do cooldown em ticks (20 = 1 segundo)

on_right_click = function(context)
  -- Só permite essa ação uma vez a cada 3 segundos
  if not context.cooldowns:check_local("interact", 60) then
    return
  end
  -- ... execute a ação
end

cooldowns:local_ready(key?)

Retorna true se o cooldown local expirou (ou nunca foi definido), false se ainda estiver ativo.

cooldowns:local_remaining(key?)

Retorna o número de ticks restantes no cooldown local, ou 0 se já estiver pronto.

cooldowns:set_local(duration, key?)

Define um cooldown local sem verificar se já há um ativo. Use isso para resets incondicionais de cooldown.

Parâmetro	Tipo	Notas
duration	int	Duração em ticks. Passe 0 ou negativo para limpar.
key	string (opcional)	Identificador do cooldown. Padrão é o nome do arquivo do script.

cooldowns:global_ready()

Retorna true se o cooldown global (compartilhado entre todos os scripts da mesma entidade) expirou.

cooldowns:set_global(duration)

Define o cooldown global.

Parâmetro	Tipo	Notas
duration	int	Duração em ticks

Escopos do cooldown global

O "dono" de um cooldown global depende do tipo de script:

• Poderes Lua do EliteMobs — compartilhados por EliteEntity (um balde por chefe). global_ready() / set_global() usam o sistema embutido de cooldown de poderes do chefe; cooldowns locais também são compartilhados entre todos os poderes do mesmo chefe.
• Scripts de prop do FMM — compartilhados por PropEntity (um balde por prop colocado).
• Scripts de item do FMM — compartilhados por UUID de jogador (um balde por jogador). Cooldowns locais em itens são persistidos entre ciclos de equipar/desequipar, indexados por playerUUID → "itemId:scriptFile" → key, então um cooldown sobrevive a o jogador tirar o item da hotbar e voltar a colocá-lo.

---

context.scheduler

O scheduler permite executar tarefas atrasadas e repetidas. Todas as tarefas pertencem à instância do script e são canceladas automaticamente quando essa instância é destruída (ex.: quando um prop é removido ou um chefe morre).

scheduler:run_later(ticks, callback)

Executa um callback uma vez após um atraso. Retorna um ID numérico de tarefa.

Parâmetro	Tipo	Notas
ticks	int	Atraso em ticks de servidor (20 ticks = 1 segundo)
callback	function	Chamado com um context novo quando o atraso expira

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

scheduler:run_repeating(delay, interval, callback)

Executa um callback repetidamente em um intervalo fixo. Retorna um ID numérico de tarefa.

Parâmetro	Tipo	Notas
delay	int	Atraso inicial em ticks antes da primeira execução
interval	int	Ticks entre cada execução subsequente
callback	function	Chamado com um context novo a 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 uma tarefa agendada pelo seu ID.

Parâmetro	Tipo	Notas
taskId	int	O ID da tarefa retornado por run_later ou run_repeating

Sempre cancele tarefas repetidas

Se você iniciar uma tarefa repetida, sempre cancele-a no seu hook de limpeza (on_destroy para props, on_exit_combat / on_death para chefes, on_unequip para itens). Esquecer de cancelar deixa uma tarefa em segundo plano rodando até a instância do script ser destruída, o que desperdiça desempenho e pode causar erros.

Callbacks recebem um contexto novo

Callbacks agendados recebem um contexto novo como parâmetro. Sempre use o argumento de contexto do próprio callback, não o context externo do hook que criou o callback. O contexto externo pode conter referências obsoletas.

---

context.world

A tabela world fornece métodos para consultar e interagir com o mundo do Minecraft. Ela é construída a partir do mundo atual da entidade.

Extensões específicas de plugin

O EliteMobs estende context.world com métodos adicionais para spawnar chefes, reforços, blocos caindo, fogos de artifício, poções de splash e blocos temporários. Veja EliteMobs Mundo & Ambiente para a API estendida completa. Os métodos documentados aqui estão disponíveis em todos os plugins.

world.name

Um campo string contendo o nome do mundo.

---

world:get_block_at(x, y, z)

Retorna o nome do material do bloco nas coordenadas fornecidas como uma string em minúsculas (ex.: "stone", "air").

Parâmetro	Tipo	Notas
x	int	Coordenada X do bloco
y	int	Coordenada Y do bloco
z	int	Coordenada Z do bloco

---

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

Define o bloco nas coordenadas fornecidas. Roda na thread principal.

Parâmetro	Tipo	Notas
x	int	Coordenada X do bloco
y	int	Coordenada Y do bloco
z	int	Coordenada Z do bloco
material	string	Nome do Material do Bukkit, em minúsculas (ex.: "stone", "air", "oak_planks")

Retorna true se o bloco foi definido com sucesso, false caso contrário.

---

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

Spawna partículas em uma localização.

Parâmetro	Tipo	Padrão	Notas
particle	string	obrigatório	Nome do enum Particle do Bukkit, UPPER_CASE (ex.: "FLAME", "DUST")
x	number	obrigatório	Coordenada X
y	number	obrigatório	Coordenada Y
z	number	obrigatório	Coordenada Z
count	int	1	Número de partículas
dx	number	0	Espalhamento/offset em X
dy	number	0	Espalhamento/offset em Y
dz	number	0	Espalhamento/offset em Z
speed	number	0	Velocidade da partícula

Partículas que exigem dados

Alguns tipos de partícula exigem dados de bloco ou item que não são suportados por esta API simples. BLOCK_CRACK, FALLING_DUST, BLOCK_DUST e ITEM_CRACK falharão ou não produzirão efeito visível. Use alternativas sem dados: CLOUD, SMOKE, CAMPFIRE_COSY_SMOKE, SNOWFLAKE, FLAME, DUST, etc.

---

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

Toca um som em uma localização.

Parâmetro	Tipo	Padrão	Notas
sound	string	obrigatório	Nome do enum Sound do Bukkit, UPPER_CASE (ex.: "ENTITY_EXPERIENCE_ORB_PICKUP")
x	number	obrigatório	Coordenada X
y	number	obrigatório	Coordenada Y
z	number	obrigatório	Coordenada Z
volume	number	1.0	Volume
pitch	number	1.0	Pitch

---

world:strike_lightning(x, y, z)

Atinge um raio em uma localização (visual e com dano).

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

---

world:get_time()

Retorna o tempo atual do mundo em ticks.

---

world:set_time(ticks)

Define o tempo do mundo.

Parâmetro	Tipo	Notas
ticks	int	Tempo do mundo (0 = amanhecer, 6000 = meio-dia, 13000 = noite, 18000 = meia-noite)

---

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

Retorna um array de tabelas-wrapper de entidade para todas as entidades dentro de uma bounding box centrada nas coordenadas fornecidas.

Parâmetro	Tipo	Notas
x	number	X central
y	number	Y central
z	number	Z central
radius	number	Raio de busca (usado como meia-extensão nos três eixos)

cuidado

Isso retorna TODAS as entidades no alcance, incluindo entidades não-vivas (armor stands, itens dropados, etc.). Sempre proteja com if entity.damage then antes de chamar métodos de entidade viva.

---

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

Retorna um array de tabelas-wrapper de jogador para todos os jogadores dentro de uma bounding box centrada nas coordenadas fornecidas.

Parâmetro	Tipo	Notas
x	number	X central
y	number	Y central
z	number	Z central
radius	number	Raio de busca

---

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

Spawna uma entidade vanilla do Minecraft na localização fornecida.

Parâmetro	Tipo	Notas
entity_type	string	Nome do tipo de entidade do Bukkit, em minúsculas (ex.: "zombie", "skeleton", "pig")
x	number	Coordenada X
y	number	Coordenada Y
z	number	Coordenada Z

Retorna uma tabela de entidade para a entidade spawnada (com métodos de entidade viva, se aplicável), ou nil se o tipo de entidade for inválido.

---

world:get_highest_block_y(x, z)

Retorna a coordenada Y do bloco mais alto que não seja ar na posição X/Z fornecida.

Parâmetro	Tipo	Notas
x	int	Coordenada X do bloco
z	int	Coordenada Z do bloco

---

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

Lança um raio a partir de um ponto em uma direção e retorna informações sobre o que ele atinge.

Parâmetro	Tipo	Padrão	Notas
from_x	number	obrigatório	X de origem
from_y	number	obrigatório	Y de origem
from_z	number	obrigatório	Z de origem
dir_x	number	obrigatório	Componente X da direção
dir_y	number	obrigatório	Componente Y da direção
dir_z	number	obrigatório	Componente Z da direção
max_distance	number	50	Distância máxima do raio

Retorna uma tabela com os seguintes campos:

Campo	Tipo	Notas
hit_entity	tabela de entidade ou nil	A primeira entidade atingida pelo raio, ou nil se nenhuma
hit_location	tabela de localização ou nil	O ponto exato onde o raio atingiu algo
hit_block	tabela ou nil	{x, y, z, material} do bloco atingido, ou nil se nenhum bloco foi atingido

---

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

Spawna um foguete de fogos de artifício na localização fornecida.

Parâmetro	Tipo	Padrão	Notas
x	number	obrigatório	Coordenada X
y	number	obrigatório	Coordenada Y
z	number	obrigatório	Coordenada Z
colors	table	obrigatório	Array de strings de cor, ex.: {"RED", "BLUE", "WHITE"}
type	string	"BALL"	Formato do fogo: "BALL", "BALL_LARGE", "STAR", "BURST", "CREEPER"
power	int	1	Potência de voo, 0-127

-- Exemplo: explosão de fogos vermelhos e dourados
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 um bloco que reverte automaticamente para seu estado original após um atraso.

Parâmetro	Tipo	Padrão	Notas
x	int	obrigatório	Coordenada X do bloco
y	int	obrigatório	Coordenada Y do bloco
z	int	obrigatório	Coordenada Z do bloco
material	string	obrigatório	Nome do Material do Bukkit (ex.: "stone", "ice")
ticks	int	0	Duração em ticks antes de o bloco reverter. 0 significa permanente.
require_air	boolean	false	Se true, só coloca o bloco se o alvo for ar

Retorna true se o bloco foi colocado, false se o material era inválido ou se o requisito de ar não foi atendido.

---

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

Solta uma entidade de item na localização fornecida com dispersão natural.

Parâmetro	Tipo	Padrão	Notas
x	number	obrigatório	Coordenada X
y	number	obrigatório	Coordenada Y
z	number	obrigatório	Coordenada Z
material	string	obrigatório	Nome do Material do Bukkit
amount	int	1	Tamanho da pilha

Retorna uma tabela de entidade para o item dropado, ou nil se o material era inválido.

---

context.zones

A tabela zones permite criar zonas espaciais e observá-las em busca de eventos de entrada/saída de jogadores. Zonas são vinculadas à instância do script e limpas automaticamente quando a instância é destruída.

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

Cria uma zona esférica centrada nas coordenadas fornecidas. Retorna um handle numérico de zona.

Parâmetro	Tipo	Notas
x	number	X central
y	number	Y central
z	number	Z central
radius	number	Raio da esfera

---

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

Cria uma zona cilíndrica. Retorna um handle numérico de zona.

Parâmetro	Tipo	Notas
x	number	X central
y	number	Y central (base)
z	number	Z central
radius	number	Raio do cilindro
height	number	Altura do cilindro

---

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

Cria uma zona cuboide. Retorna um handle numérico de zona.

Parâmetro	Tipo	Notas
x	number	X central
y	number	Y central
z	number	Z central
xSize	number	Meia-extensão em X
ySize	number	Meia-extensão em Y
zSize	number	Meia-extensão em Z

---

zones:watch(handle, onEnterCallback, onLeaveCallback)

Começa a observar uma zona em busca de eventos de entrada/saída de jogadores. Os parâmetros de callback agem como sinais booleanos — passar um valor não-nil (ex.: uma função ou true) habilita o hook correspondente no script. Os próprios callbacks não são invocados diretamente. Em vez disso, a lógica de entrada/saída dispara pelos hooks on_zone_enter / on_zone_leave do script.

Parâmetro	Tipo	Notas
handle	int	Handle de zona retornado por uma chamada create_*
onEnterCallback	qualquer não-nil ou nil	Não-nil habilita o hook on_zone_enter para esta zona
onLeaveCallback	qualquer não-nil ou nil	Não-nil habilita o hook on_zone_leave para esta zona

Retorna true se a observação foi configurada com sucesso, nil se o handle da zona era inválido.

informação

As observações de zona são checadas a cada tick do servidor contra todos os jogadores no mesmo mundo. Mantenha o número de zonas razoável para evitar sobrecarga de desempenho.

---

zones:unwatch(handle)

Para de observar uma zona e libera seus recursos.

Parâmetro	Tipo	Notas
handle	int	Handle da zona a ser desobservada

---

Exemplo: Zona-gatilho por proximidade

return {
  api_version = 1,

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

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

    -- Passe valores não-nil para habilitar os hooks on_zone_enter e on_zone_leave.
    -- Esses são sinais booleanos, não callbacks — a lógica real vai nos hooks abaixo.
    context.zones:watch(handle, true, true)

    context.state.zone_handle = handle
  end,

  on_zone_enter = function(context)
    context.log:info("Player entered zone!")
  end,

  on_zone_leave = function(context)
    context.log:info("Player left zone!")
  end,

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

---

context.event

A tabela event está presente quando o hook atual foi disparado por um evento de jogo (ex.: on_right_click, on_zone_enter). Ela não está presente durante on_game_tick ou callbacks agendados.

Campo / Método	Tipo	Notas
is_cancelled	boolean	Se o evento foi cancelado
cancel()	método	Cancela o evento (impede o comportamento padrão)
uncancel()	método	Descancela um evento previamente cancelado
player	tabela de entidade	O jogador envolvido no evento, se houver

on_right_click = function(context)
  if context.event then
    context.event:cancel()  -- impede a interação padrão de clique direito
  end
end

Tabela de evento do EliteMobs

Os scripts de poder do EliteMobs têm uma tabela de evento mais detalhada com quantidades de dano, causas de dano, referências ao causador do dano e métodos de modificação de dano. Veja a Referência da API Lua para os campos completos de evento do EliteMobs.

---

Namespace Auxiliar em

A tabela em está disponível em tempo de carga do arquivo (antes de qualquer hook rodar). Ela fornece construtores auxiliares para criar tabelas de localização, tabelas de vetor e definições de zona usadas em toda a API.

Função	Propósito
em.create_location(x, y, z [, world, yaw, pitch])	Cria uma tabela de localização com nome de mundo, yaw e pitch opcionais. A tabela retornada também tem um método .add(dx, dy, dz) que desloca a localização no lugar e retorna a si mesma para encadeamento.
em.create_vector(x, y, z)	Cria uma tabela de vetor
em.zone.create_sphere_zone(radius)	Cria uma definição de zona esférica
em.zone.create_dome_zone(radius)	Cria uma definição de zona em domo
em.zone.create_cylinder_zone(radius, height)	Cria uma definição de zona cilíndrica
em.zone.create_cuboid_zone(x, y, z)	Cria uma definição de zona cuboide
em.zone.create_cone_zone(length, radius)	Cria uma definição de zona cônica
em.zone.create_static_ray_zone(length, thickness)	Cria uma definição de zona de raio estático
em.zone.create_rotating_ray_zone(length, point_radius, animation_duration)	Cria uma definição de zona de raio rotativo
em.zone.create_translating_ray_zone(length, point_radius, animation_duration)	Cria uma definição de zona de raio em translação
em.location.is_in_dungeon(loc)	Verifica se uma localização está dentro de alguma região de dungeon registrada
em.location.is_protected(loc)	Verifica se uma localização está dentro de alguma região protegida (WorldGuard, GriefPrevention, regiões EM, etc.)
em.location.owned_by(loc, namespace)	Verifica se um namespace de plugin específico possui a localização (ex.: "EliteMobs")
em.location.owners(loc)	Array de strings de namespace que possuem a localização
em.location.kinds_at(loc)	Array de tags de tipo na localização ("elitemobs", "world_package", "open_world_dungeon", categoria de tamanho de dungeon)
em.location.has_kind(loc, kind)	Verifica se a localização está marcada com o tipo fornecido

Os construtores de zona retornam tabelas encadeáveis com :set_center(loc) (ou :set_origin(loc) / :set_destination(loc) dependendo do tipo de zona):

-- No escopo do arquivo: crie uma forma de zona reutilizável
local blast_zone = em.zone.create_sphere_zone(5)

return {
  api_version = 1,

  on_spawn = function(context)
    -- Ancore a zona no momento da chamada
    blast_zone:set_center(context.boss:get_location())
    local entities = context.zones:get_entities_in_zone(blast_zone)
    -- ...
  end
}

informação

O namespace em é particularmente útil no EliteMobs, onde definições de zona são usadas com context.zones:get_entities_in_zone() e context.script. No FreeMinecraftModels, os métodos context.zones:create_sphere(...) / create_cylinder(...) / create_cuboid(...) são mais usados para zonas simples baseadas em observação (watch).

---

Tabelas de Entidade

Tabelas de entidade são retornadas por consultas ao mundo, dados de evento e callbacks de zona. Elas fornecem um conjunto em camadas de campos e métodos dependendo do tipo de entidade.

Campos Base da Entidade

Campo	Tipo	Notas
uuid	string	O UUID da entidade
entity_type	string	O tipo da entidade (ex.: "player", "zombie", "skeleton", "villager")
is_valid	boolean	Se a referência da entidade ainda é válida
is_dead	boolean	Se a entidade está morta
is_player	boolean	Se a entidade é um jogador
is_hostile	boolean	Se a entidade é um mob hostil (zumbi, esqueleto, etc.)
is_passive	boolean	Se a entidade é um mob passivo (vaca, porco, galinha, etc.)
current_location	tabela de localização	A posição atual da entidade (x, y, z, world, yaw, pitch)
world	string	O nome do mundo em que a entidade está

Métodos Base da Entidade

Método	Retorna	Notas
teleport(location_table)	void	Teletransporta a entidade. A tabela de localização deve ter os campos x, y, z, world; yaw e pitch são opcionais.
remove()	void	Remove a entidade do mundo. Só age se a entidade ainda for válida.
set_silent(flag)	void	Suprime ou reativa os sons da entidade.
set_invulnerable(flag)	void	Torna a entidade invulnerável ou vulnerável a dano.
set_gravity(flag)	void	Habilita ou desabilita a gravidade para a entidade.
set_glowing(flag)	void	Alterna o efeito de contorno brilhante na entidade.

---

Campos da Entidade Viva

Entidades vivas (jogadores, mobs, etc.) têm todos os campos base de entidade mais:

Campo	Tipo	Notas
health	number	Vida atual
maximum_health	number	Vida máxima
name	string	Nome de exibição
is_alive	boolean	Se a entidade está viva

Métodos da Entidade Viva

Método	Retorna	Notas
damage(amount)	void	Causa a quantidade de dano fornecida à entidade
push(x, y, z)	void	Aplica um impulso de velocidade
set_facing(x, y, z)	void	Define a direção que a entidade encara
add_potion_effect(effect, duration, amplifier)	void	Adiciona um efeito de poção. effect é uma string (ex.: "speed", "slowness", "regeneration"). duration é em ticks. amplifier é o nível do efeito menos 1 (0 = nível I).
remove_potion_effect(effect)	void	Remove um efeito de poção pelo nome
get_scale()	number	Retorna a escala atual da entidade (padrão 1.0 em servidores sem o atributo generic.scale)
set_scale(value)	void	Define a escala da entidade via o atributo generic.scale. Sem efeito em servidores anteriores ao 1.20.5.

cuidado

Nem todas as entidades retornadas por get_nearby_entities() são entidades vivas. Você pode usar entity.is_player, entity.is_hostile ou entity.is_passive para filtrar por categoria, ou checar if entity.damage then antes de chamar métodos de entidade viva como damage(), push() ou add_potion_effect().

---

Campos de Integração de Plugins

Tabelas de entidade incluem automaticamente campos para detectar e interagir com entidades gerenciadas por outros plugins do Nightbreak. Esses campos só são populados quando o plugin relevante está instalado -- caso contrário, têm como padrão false / nil sem overhead.

Campos do EliteMobs

Disponíveis quando o EliteMobs está instalado.

Campo	Tipo	Notas
is_elite	boolean	Se a entidade é uma elite do EliteMobs
is_custom_boss	boolean	Se a entidade é um chefe personalizado do EliteMobs (também disponível dentro da subtabela elite)
is_significant_boss	boolean	Se a entidade é um chefe personalizado com multiplicador de vida acima de 1 (ou seja, um encontro projetado, não uma elite filler)
elite	table or nil	Subtabela de informações da elite (veja abaixo). nil se a entidade não for uma elite.

A subtabela elite contém:

Campo	Tipo	Notas
elite.level	int	O nível da elite
elite.name	string	O nome de exibição da elite
elite.health	number	Vida atual
elite.max_health	number	Vida máxima
elite.is_custom_boss	boolean	Se é um chefe personalizado (em oposição a uma elite natural)
elite.health_multiplier	number	Multiplicador de vida definido na config
elite.damage_multiplier	number	Multiplicador de dano definido na config
elite:remove()	void	Remove a elite pelo pipeline adequado de remoção do EliteMobs (limpa rastreamento, loot, etc.)

Exemplo: Causar dano diferente a elites

local entities = context.world:get_nearby_entities(x, y, z, 5)
for _, entity in ipairs(entities) do
    if entity.is_elite then
        -- Causa o dobro de dano em 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 do FreeMinecraftModels

Disponíveis quando o FreeMinecraftModels está instalado.

Campo	Tipo	Notas
is_modeled	boolean	Se a entidade tem um modelo FMM anexado (DynamicEntity ou PropEntity)
is_prop	boolean	Se a entidade é um prop FMM (entidade decorativa estática)
model	table or nil	Subtabela de informações do modelo (veja abaixo). nil se a entidade não tiver modelo.

A subtabela model contém:

Campo	Tipo	Notas
model.model_id	string	O ID do blueprint do modelo (ex.: "torch_01")
model.is_dynamic	boolean	Se a entidade modelada é um DynamicEntity (modelo de mob/chefe) em vez de um prop estático
model:play_animation(name, [blend], [loop])	boolean	Toca uma animação nomeada. blend padrão false, loop padrão false. Retorna true se a animação foi encontrada.
model:stop_animations()	void	Para todas as animações em execução no modelo.
model:remove()	void	Remove a entidade modelada pelo pipeline adequado de remoção do FMM.

Padrões Bridge vs Prop

A ponte de modelo (disponível em qualquer entidade) tem blend e loop com padrão false. A tabela de prop play_animation tem ambos com padrão true, porque props geralmente querem animações com blend e em loop.

Exemplo: 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
        -- Pula props
    elseif entity.is_player then
        entity:damage(5)
    elseif entity.entity_type == "villager" then
        -- Não machuque aldeões
    elseif entity.is_elite then
        entity:damage(20)
    elseif entity.is_hostile then
        entity:damage(10)
    end
end

---

Campos Específicos de Jogador

Entidades de jogador têm todos os campos de entidade e entidade viva mais:

Campo	Tipo	Notas
game_mode	string	O modo de jogo do jogador ("creative", "survival", "adventure", "spectator")

Métodos Específicos de Jogador

Método	Retorna	Notas
send_message(msg)	void	Envia uma mensagem de chat ao jogador. Suporta códigos de cor &.
get_held_item()	tabela ou nil	Retorna {type, amount, display_name} para o item na mão principal do jogador, ou nil se vazia
consume_held_item(amount?)	void	Consome itens da mão principal do jogador. amount tem padrão 1
has_item(material, amount?)	boolean	Retorna true se o jogador tem pelo menos amount (padrão 1) do material fornecido em qualquer lugar do inventário
get_target_entity([range])	tabela de entidade ou nil	Retorna a entidade que o jogador está olhando via raycast, ou nil se nenhuma. Alcance padrão é 50.
get_eye_location()	tabela de localização	Retorna uma tabela de localização na altura dos olhos do jogador
get_look_direction()	tabela	Retorna um vetor de direção {x, y, z} para onde o jogador está olhando
send_block_change(x, y, z, material, [ticks])	boolean	Envia um bloco falso visível apenas para este jogador. Se ticks for fornecido, o bloco falso reseta automaticamente após essa duração. Retorna true em sucesso, false se o material for inválido.
reset_block(x, y, z)	boolean	Reseta um bloco falso de volta para o bloco real para este jogador. Sempre retorna true.
sleep(x, y, z)	void	Faz o jogador entrar em uma animação de sono em cama nas coordenadas fornecidas. O bloco é restaurado automaticamente quando o jogador para de dormir.
wake_up()	void	Acorda um jogador adormecido.

---

Métodos de UI do Jogador

Esses métodos estão disponíveis em qualquer tabela de entidade de jogador e oferecem formas de exibir informações ao jogador através dos elementos de UI nativos do Minecraft.

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

Mostra uma barra de chefe ao jogador.

Parâmetro	Tipo	Padrão	Notas
text	string	obrigatório	O texto a exibir. Suporta códigos de cor &.
color	string	"WHITE"	Cor da barra. Uma de: "RED", "BLUE", "GREEN", "YELLOW", "PURPLE", "PINK", "WHITE"
progress	number	obrigatório	Quantidade preenchida de 0.0 (vazio) a 1.0 (cheio)
ticks	int	nil	Atraso opcional para dispensar automaticamente em ticks. Se omitido, a barra fica até ser ocultada manualmente.

player:hide_boss_bar()

Remove a barra de chefe da tela do jogador. Não recebe parâmetros.

player:show_action_bar(text, [ticks])

Mostra texto na área da action bar (acima da hotbar).

Parâmetro	Tipo	Padrão	Notas
text	string	obrigatório	O texto a exibir. Suporta códigos de cor &.
ticks	int	nil	Duração opcional em ticks. Se fornecida, a mensagem é reenviada a cada 40 ticks para mantê-la visível por toda a duração.

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

Mostra uma tela de título ao jogador.

Parâmetro	Tipo	Padrão	Notas
title	string	obrigatório	Texto principal do título. Suporta códigos de cor &.
subtitle	string	""	Texto do subtítulo abaixo do título principal. Opcional.
fade_in	int	obrigatório	Duração do fade-in em ticks
stay	int	obrigatório	Quanto tempo o título permanece na tela em ticks
fade_out	int	obrigatório	Duração do fade-out em ticks

---

Próximos Passos

Para hooks, APIs e fluxos de trabalho específicos de cada plugin:

• EliteMobs: Primeiros Passos | Hooks & Ciclo de Vida | Chefe & Entidades | Mundo & Ambiente | Zonas & Alvos
• FreeMinecraftModels: Primeiros Passos | API de Prop & Item | Exemplos