Motor de Scripting Lua do MagmaCore

O MagmaCore fornece um motor de scripting Lua compartilhado utilizado por vários plugins da Nightbreak. O motor lida com sandboxing, agendamento, gerenciamento de zonas, interação com o mundo, tabelas de entidades e interface do jogador -- tudo com uma API consistente entre plugins.

Atualmente, os seguintes plugins utilizam este motor:

• EliteMobs -- Poderes Lua para bosses 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 pagina documenta as funcionalidades compartilhadas do motor. Para hooks, APIs e fluxos de trabalho especificos de cada plugin, consulte as paginas dos plugins linkadas acima.

---

Introducao Rapida ao Lua

Se voce e completamente novo em Lua, aqui esta a sintaxe minima necessaria para escrever scripts para qualquer plugin da Nightbreak.

Variaveis

Use local para armazenar um valor:

local cooldown_key = "fire_burst"
local damage_multiplier = 1.5

local significa que a variavel pertence apenas a este arquivo ou bloco.

Funcoes

Funcoes sao blocos reutilizaveis de logica:

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

Depois, voce pode chama-la:

warn_player(some_player)

Verificacoes com if

Use if quando algo deve acontecer apenas em certas situacoes:

if context.player == nil then
  return
end

Isso significa "se nao houver jogador para este hook, pare aqui".

nil

nil significa "sem valor". E a versao do Lua para "nao ha nada aqui".

Voce frequentemente verificara nil com:

if context.event ~= nil then
  -- fazer algo com o evento
end

~= significa "nao e igual a".

Tabelas

Lua usa tabelas para varias finalidades:

• Listas
• Objetos com chaves nomeadas
• A definicao final do script retornado

Exemplo de uma tabela com chaves nomeadas:

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

Retornando a definicao do script

No final de cada arquivo de script, voce retorna uma tabela:

return {
  api_version = 1,

  on_spawn = function(context)
  end
}

Essa tabela retornada e o arquivo de script.

Comentarios

Use -- para escrever uma nota para humanos:

-- Este cooldown impede o ataque de disparar a cada golpe
context.cooldowns:set_local(60, "fire_burst")

---

Sandbox Lua

Todos os scripts Lua rodam dentro de um ambiente LuaJ com sandbox. Varios globais que poderiam acessar o sistema de arquivos ou o runtime Java sao removidos. As regras do sandbox sao identicas em todos os plugins que usam o MagmaCore.

Globais Removidos

Os seguintes globais padrao do Lua sao definidos como nil e nao podem ser usados:

Removido	Motivo
debug	Expoe o estado interno da VM
dofile	Acesso ao sistema de arquivos
io	Acesso ao sistema de arquivos
load	Carregamento arbitrario de codigo
loadfile	Acesso ao sistema de arquivos
luajava	Acesso direto a classes Java
module	Sistema de modulos (nao necessario)
os	Acesso ao sistema operacional
package	Sistema de modulos (nao necessario)
require	Sistema de modulos / acesso ao sistema de arquivos

Biblioteca Padrao Disponivel

Todo o resto da biblioteca padrao do Lua funciona normalmente:

Categoria	Funcoes
Matematica	math.abs, math.ceil, math.floor, math.max, math.min, math.random, math.sin, math.cos, math.sqrt, math.pi, e todas as outras funcoes 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 funcoes string.*
Tabela	table.insert, table.remove, table.sort, table.concat, e todas as outras funcoes 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 nao esta disponivel

A biblioteca os e completamente removida do sandbox. Se voce precisar de informacoes de tempo, use context.world:get_time() para o tempo do mundo ou armazene timestamps em context.state usando contadores de ticks com on_tick / on_game_tick.

dica

print escreve no console do servidor, mas prefira context.log:info(msg) para saida. Mensagens de log sao prefixadas com o nome do arquivo do script, facilitando rastrear qual script produziu a mensagem.

---

Contrato do Arquivo

Cada script Lua deve retornar (return) uma tabela. Essa tabela e intencionalmente rigorosa.

Campos de Nivel Superior Obrigatorios e Opcionais

Campo	Obrigatorio	Tipo	Notas
api_version	Sim	Number	Atualmente deve ser 1
priority	Nao	Number	Prioridade de execucao. Valores menores rodam primeiro. Padrao e 0
chaves de hook suportadas	Nao	Function	Deve usar um dos nomes exatos de hook suportados pelo plugin

Regras de Validacao

• O arquivo deve retornar uma tabela.
• api_version e obrigatorio e atualmente deve ser 1.
• priority deve ser numerico se presente.
• Cada chave extra de nivel superior deve ser um nome de hook suportado.
• Cada chave de hook deve apontar para uma funcao.
• Chaves de nivel superior desconhecidas sao rejeitadas.

Funcoes auxiliares e constantes locais devem ficar acima do return final, nao dentro da tabela retornada, a menos que sejam hooks reais.

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
}

---

Sintaxe de Metodo: : vs .

Em Lua, object:method(arg) e uma abreviacao para object.method(object, arg). A API do MagmaCore aceita ambas as formas, entao qualquer uma funciona:

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

Toda a documentacao usa : de forma consistente.

---

Orcamento de Execucao

Cada invocacao de hook e cada invocacao de callback sao cronometradas. Se uma unica chamada demorar mais de 50 milissegundos, o script e 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 orcamento:

• Evite loops sem limite dentro de hooks.
• Mantenha os handlers on_game_tick / on_tick leves -- eles rodam a cada tick.
• Use context.scheduler:run_repeating(...) para distribuir trabalho entre ticks.
• Mova trabalho pesado para tras de um cooldown baseado em estado ou um intervalo razoavel.

---

context.state

Uma tabela Lua simples que persiste durante toda a vida da instancia do script. Use-a para armazenar flags, contadores, IDs de tarefas, estados de alternancia e quaisquer dados que voce 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

info

Apenas context.state persiste entre chamadas de hook. Todas as outras tabelas de contexto (context.prop, context.world, context.event, etc.) sao reconstruidas a cada vez. context.state nao e reconstruida -- ela sobrevive desde o momento em que a instancia do script e criada ate ser destruida.

---

context.log

Metodos de log no console. As mensagens sao prefixadas com o nome do arquivo do script no console do servidor.

Metodo	Notas
log:info(message)	Mensagem informativa
log:warn(message)	Mensagem de aviso
log:error(message)	Mensagem de nivel de aviso (registrada no nivel WARN, igual a log:warn)
log:debug(message)	Mensagem de depuracao (aparece como nivel info com um prefixo de depuracao)

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

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

• Cooldowns locais sao por instancia de script e identificados por uma chave string. Se nenhuma chave for fornecida, o nome do arquivo do script e usado como chave padrao.
• Cooldowns globais sao compartilhados entre todos os scripts no mesmo proprietario de entidade (por exemplo, todos os scripts no mesmo prop, ou todos os poderes Lua no mesmo boss).

cooldowns:check_local(key?, duration)

O metodo mais comum. Verifica se o cooldown esta pronto e, se estiver, inicia-o e retorna true. Se nao estiver pronto, retorna false. E um check-and-set atomico — sem condicoes de corrida.

Parametro	Tipo	Notas
key	string (opcional)	Identificador do cooldown. Padrao e o nome do arquivo do script.
duration	int	Duracao do cooldown em 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 se o cooldown local expirou (ou nunca foi definido), false se ainda esta ativo.

cooldowns:local_remaining(key?)

Retorna o numero de ticks restantes no cooldown local, ou 0 se esta pronto.

cooldowns:set_local(duration, key?)

Define um cooldown local sem verificar se ja existe um ativo. Use para reinicializacoes incondicionais de cooldown.

Parametro	Tipo	Notas
duration	int	Duracao em ticks. Passe 0 ou negativo para limpar.
key	string (opcional)	Identificador do cooldown. Padrao e o nome do arquivo do script.

cooldowns:global_ready()

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

cooldowns:set_global(duration)

Define o cooldown global.

Parametro	Tipo	Notas
duration	int	Duracao em ticks

Cooldowns globais do EliteMobs

Nos scripts de poderes do EliteMobs, global_ready() e set_global() usam o sistema de cooldown de poderes integrado do boss, que e compartilhado entre todos os poderes Lua do mesmo boss. Cooldowns locais no EliteMobs tambem sao compartilhados entre todos os poderes na mesma entidade boss (identificados pela sua string escolhida).

---

context.scheduler

O agendador permite executar tarefas com atraso e tarefas repetidas. Todas as tarefas pertencem a instancia do script e sao canceladas automaticamente quando a instancia do script e destruida (por exemplo, quando um prop e removido ou um boss morre).

scheduler:run_later(ticks, callback)

Executa um callback uma vez apos um atraso. Retorna um ID numerico de tarefa.

Parametro	Tipo	Notas
ticks	int	Atraso em ticks do 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 numerico de tarefa.

Parametro	Tipo	Notas
delay	int	Atraso inicial em ticks antes da primeira execucao
interval	int	Ticks entre cada execucao 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.

Parametro	Tipo	Notas
taskId	int	O ID da tarefa retornado por run_later ou run_repeating

Sempre cancele tarefas repetidas

Se voce iniciar uma tarefa repetida, sempre cancele-a no seu hook de limpeza (on_destroy para props, on_exit_combat / on_death para bosses, on_unequip para itens). Esquecer de cancelar deixa uma tarefa em segundo plano rodando ate que a instancia do script seja destruida, o que desperdiça desempenho e pode causar erros.

Callbacks recebem contexto novo

Callbacks agendados recebem um contexto novo como parametro. Sempre use o argumento de contexto do proprio callback, nao o context externo do hook que criou o callback. O contexto externo pode conter referencias desatualizadas.

---

context.world

A tabela world fornece metodos para consultar e interagir com o mundo do Minecraft. Ela e construida a partir do mundo atual da entidade.

Extensoes especificas de plugins

O EliteMobs estende context.world com metodos adicionais para spawnar bosses, reforcos, blocos caindo, fogos de artificio, pocoes de splash e blocos temporarios. Consulte EliteMobs Mundo e Ambiente para a API estendida completa. Os metodos documentados aqui estao disponiveis 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 minusculas (por exemplo, "stone", "air").

Parametro	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. Executa na thread principal.

Parametro	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 Bukkit, em minusculas (por exemplo, "stone", "air", "oak_planks")

Retorna true se o bloco foi definido com sucesso, false caso contrario.

---

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

Gera particulas em uma localizacao.

Parametro	Tipo	Padrao	Notas
particle	string	obrigatorio	Nome do enum Particle do Bukkit, MAIUSCULAS (por exemplo, "FLAME", "DUST")
x	number	obrigatorio	Coordenada X
y	number	obrigatorio	Coordenada Y
z	number	obrigatorio	Coordenada Z
count	int	1	Numero de particulas
dx	number	0	Dispersao/deslocamento X
dy	number	0	Dispersao/deslocamento Y
dz	number	0	Dispersao/deslocamento Z
speed	number	0	Velocidade da particula

Particulas que requerem dados

Alguns tipos de particulas requerem dados de bloco ou item que nao sao suportados por esta API simples. BLOCK_CRACK, FALLING_DUST, BLOCK_DUST e ITEM_CRACK falharao ou nao produzirao efeito visivel. Use alternativas sem dados: CLOUD, SMOKE, CAMPFIRE_COSY_SMOKE, SNOWFLAKE, FLAME, DUST, etc.

---

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

Reproduz um som em uma localizacao.

Parametro	Tipo	Padrao	Notas
sound	string	obrigatorio	Nome do enum Sound do Bukkit, MAIUSCULAS (por exemplo, "ENTITY_EXPERIENCE_ORB_PICKUP")
x	number	obrigatorio	Coordenada X
y	number	obrigatorio	Coordenada Y
z	number	obrigatorio	Coordenada Z
volume	number	1.0	Volume
pitch	number	1.0	Tom

---

world:strike_lightning(x, y, z)

Gera um raio em uma localizacao (visual e causa dano).

Parametro	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.

Parametro	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 entidades para todas as entidades dentro de uma caixa delimitadora centrada nas coordenadas fornecidas.

Parametro	Tipo	Notas
x	number	Centro X
y	number	Centro Y
z	number	Centro Z
radius	number	Raio de busca (usado como meia-extensao nos tres eixos)

cuidado

Isso retorna TODAS as entidades no alcance, incluindo entidades nao-vivas (armor stands, itens dropados, etc.). Sempre verifique com if entity.damage then antes de chamar metodos de entidades vivas.

---

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

Retorna um array de tabelas wrapper de jogadores para todos os jogadores dentro de uma caixa delimitadora centrada nas coordenadas fornecidas.

Parametro	Tipo	Notas
x	number	Centro X
y	number	Centro Y
z	number	Centro Z
radius	number	Raio de busca

---

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

Gera uma entidade vanilla do Minecraft na localizacao fornecida.

Parametro	Tipo	Notas
entity_type	string	Nome do tipo de entidade Bukkit, em minusculas (por exemplo, "zombie", "skeleton", "pig")
x	number	Coordenada X
y	number	Coordenada Y
z	number	Coordenada Z

Retorna uma tabela de entidade para a entidade gerada (com metodos de entidade viva se aplicavel), ou nil se o tipo de entidade for invalido.

---

world:get_highest_block_y(x, z)

Retorna a coordenada Y do bloco nao-ar mais alto na posicao X/Z fornecida.

Parametro	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])

Lanca um raio a partir de um ponto em uma direcao e retorna informacoes sobre o que ele atinge.

Parametro	Tipo	Padrao	Notas
from_x	number	obrigatorio	Origem X
from_y	number	obrigatorio	Origem Y
from_z	number	obrigatorio	Origem Z
dir_x	number	obrigatorio	Componente X da direcao
dir_y	number	obrigatorio	Componente Y da direcao
dir_z	number	obrigatorio	Componente Z da direcao
max_distance	number	50	Distancia maxima 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 localizacao 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])

Gera um foguete de fogos de artificio na localizacao fornecida.

Parametro	Tipo	Padrao	Notas
x	number	obrigatorio	Coordenada X
y	number	obrigatorio	Coordenada Y
z	number	obrigatorio	Coordenada Z
colors	table	obrigatorio	Array de strings de cores, por exemplo {"RED", "BLUE", "WHITE"}
type	string	"BALL"	Formato do fogo de artificio: "BALL", "BALL_LARGE", "STAR", "BURST", "CREEPER"
power	int	1	Potencia de voo, 0-127

-- Exemplo: explosao de fogos de artificio vermelho e dourado
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 automaticamente reverte ao seu estado original apos um atraso.

Parametro	Tipo	Padrao	Notas
x	int	obrigatorio	Coordenada X do bloco
y	int	obrigatorio	Coordenada Y do bloco
z	int	obrigatorio	Coordenada Z do bloco
material	string	obrigatorio	Nome do Material Bukkit (por exemplo, "stone", "ice")
ticks	int	0	Duracao em ticks antes do bloco reverter. 0 significa permanente.
require_air	boolean	false	Se true, so coloca o bloco se o alvo for ar

Retorna true se o bloco foi colocado, false se o material era invalido ou o requisito de ar nao foi atendido.

---

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

Dropa uma entidade de item na localizacao fornecida com dispersao natural.

Parametro	Tipo	Padrao	Notas
x	number	obrigatorio	Coordenada X
y	number	obrigatorio	Coordenada Y
z	number	obrigatorio	Coordenada Z
material	string	obrigatorio	Nome do Material Bukkit
amount	int	1	Tamanho do stack

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

---

context.zones

A tabela zones permite criar zonas espaciais e monitorar eventos de entrada/saida de jogadores. As zonas sao vinculadas a instancia do script e limpas automaticamente quando a instancia do script e destruida.

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

Cria uma zona esferica centrada nas coordenadas fornecidas. Retorna um handle numerico de zona.

Parametro	Tipo	Notas
x	number	Centro X
y	number	Centro Y
z	number	Centro Z
radius	number	Raio da esfera

---

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

Cria uma zona cilindrica. Retorna um handle numerico de zona.

Parametro	Tipo	Notas
x	number	Centro X
y	number	Centro Y (base)
z	number	Centro Z
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 numerico de zona.

Parametro	Tipo	Notas
x	number	Centro X
y	number	Centro Y
z	number	Centro Z
xSize	number	Meia-extensao em X
ySize	number	Meia-extensao em Y
zSize	number	Meia-extensao em Z

---

zones:watch(handle, onEnterCallback, onLeaveCallback)

Comeca a monitorar uma zona para eventos de entrada/saida de jogadores. Quando um jogador entra ou sai da zona, o callback correspondente e disparado (e, se definidos, os hooks on_zone_enter / on_zone_leave).

Parametro	Tipo	Notas
handle	int	Handle de zona de uma chamada create_*
onEnterCallback	function ou nil	Chamado quando um jogador entra na zona
onLeaveCallback	function ou nil	Chamado quando um jogador sai da zona

Retorna true se o monitoramento foi configurado com sucesso, nil se o handle de zona era invalido.

info

Os monitoramentos de zona sao verificados a cada tick do servidor contra todos os jogadores no mesmo mundo. Mantenha a quantidade de zonas razoavel para evitar sobrecarga de desempenho.

---

zones:unwatch(handle)

Para de monitorar uma zona e limpa seus recursos.

Parametro	Tipo	Notas
handle	int	Handle de zona para parar de monitorar

---

Exemplo: Zona de gatilho por proximidade

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

A tabela event esta presente quando o hook atual foi acionado por um evento do jogo (por exemplo, on_right_click, on_zone_enter). Ela nao esta presente durante on_tick ou callbacks agendados.

Campo / Metodo	Tipo	Notas
is_cancelled	boolean	Se o evento foi cancelado
cancel()	method	Cancela o evento (impede o comportamento padrao)
uncancel()	method	Descancela um evento previamente cancelado
player	entity table	O jogador envolvido no evento, se houver

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

Tabela de eventos do EliteMobs

Scripts de poderes do EliteMobs tem uma tabela de eventos mais detalhada com quantidades de dano, causas de dano, referencias ao atacante e metodos de modificacao de dano. Consulte a Referencia da API Lua para os campos completos de eventos do EliteMobs.

---

Namespace Auxiliar em

A tabela em esta disponivel no momento do carregamento do arquivo (antes de qualquer hook rodar). Ela fornece construtores auxiliares para criar tabelas de localizacao, tabelas de vetores e definicoes de zonas usadas em toda a API.

Funcao	Proposito
em.create_location(x, y, z [, world, yaw, pitch])	Cria uma tabela de localizacao com nome de mundo, yaw e pitch opcionais. A tabela retornada tambem tem um metodo .add(dx, dy, dz) que desloca a localizacao no local e retorna ela mesma para encadeamento.
em.create_vector(x, y, z)	Cria uma tabela de vetor
em.zone.create_sphere_zone(radius)	Cria uma definicao de zona esferica
em.zone.create_dome_zone(radius)	Cria uma definicao de zona em domo
em.zone.create_cylinder_zone(radius, height)	Cria uma definicao de zona cilindrica
em.zone.create_cuboid_zone(x, y, z)	Cria uma definicao de zona cuboide
em.zone.create_cone_zone(length, radius)	Cria uma definicao de zona conica
em.zone.create_static_ray_zone(length, thickness)	Cria uma definicao de zona de raio estatico
em.zone.create_rotating_ray_zone(length, point_radius, animation_duration)	Cria uma definicao de zona de raio rotativo
em.zone.create_translating_ray_zone(length, point_radius, animation_duration)	Cria uma definicao de zona de raio em translacao

Os construtores de zonas retornam tabelas encadeaveis com :set_center(loc) (ou :set_origin(loc) / :set_destination(loc) dependendo do tipo de zona):

-- No escopo do arquivo: criar uma forma de zona reutilizavel
local blast_zone = em.zone.create_sphere_zone(5)

return {
  api_version = 1,

  on_spawn = function(context)
    -- Ancorar 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
}

info

O namespace em e particularmente util no EliteMobs, onde definicoes de zonas sao usadas com context.zones:get_entities_in_zone() e context.script. No FreeMinecraftModels, os metodos context.zones:create_sphere(...) / create_cylinder(...) / create_cuboid(...) sao mais comumente usados para zonas simples baseadas em monitoramento.

---

Tabelas de Entidades

Tabelas de entidades sao retornadas de consultas ao mundo, dados de eventos e callbacks de zonas. Elas fornecem um conjunto em camadas de campos e metodos dependendo do tipo de entidade.

Campos Base de Entidade

Campo	Tipo	Notas
uuid	string	O UUID da entidade
entity_type	string	O tipo da entidade (por exemplo, "player", "zombie", "skeleton", "villager")
is_valid	boolean	Se a referencia da entidade ainda e valida
is_dead	boolean	Se a entidade esta morta
is_player	boolean	Se a entidade e um jogador
is_hostile	boolean	Se a entidade e um mob hostil (zombie, skeleton, etc.)
is_passive	boolean	Se a entidade e um mob passivo (cow, pig, chicken, etc.)
current_location	tabela de localizacao	A posicao atual da entidade (x, y, z, world, yaw, pitch)
world	string	O nome do mundo em que a entidade esta

Metodos Base de Entidade

Metodo	Retorno	Notas
teleport(location_table)	void	Teleporta a entidade. A tabela de localizacao deve ter os campos x, y, z, world; yaw e pitch sao opcionais.
remove()	void	Remove a entidade do mundo. So atua se a entidade ainda for valida.
set_silent(flag)	void	Suprime ou reabilita os sons da entidade.
set_invulnerable(flag)	void	Torna a entidade invulneravel ou vulneravel 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 de Entidade Viva

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

Campo	Tipo	Notas
health	number	Vida atual
maximum_health	number	Vida maxima
name	string	Nome de exibicao
is_alive	boolean	Se a entidade esta viva

Metodos de Entidade Viva

Metodo	Retorno	Notas
damage(amount)	void	Causa a quantidade de dano especificada a entidade
push(x, y, z)	void	Aplica um impulso de velocidade
set_facing(x, y, z)	void	Define a direcao para onde a entidade olha
add_potion_effect(effect, duration, amplifier)	void	Adiciona um efeito de pocao. effect e uma string (por exemplo, "speed", "slowness", "regeneration"). duration e em ticks. amplifier e o nivel do efeito menos 1 (0 = nivel I).
remove_potion_effect(effect)	void	Remove um efeito de pocao pelo nome

cuidado

Nem todas as entidades retornadas por get_nearby_entities() sao entidades vivas. Voce pode usar entity.is_player, entity.is_hostile ou entity.is_passive para filtrar por categoria, ou verificar if entity.damage then antes de chamar metodos de entidades vivas como damage(), push() ou add_potion_effect().

---

Campos de Integracao com Plugins

Tabelas de entidades incluem automaticamente campos para detectar e interagir com entidades gerenciadas por outros plugins da Nightbreak. Esses campos so sao preenchidos quando o plugin relevante esta instalado -- caso contrario, eles assumem false / nil sem nenhuma sobrecarga.

Campos do EliteMobs

Disponiveis quando o EliteMobs esta instalado.

Campo	Tipo	Notas
is_elite	boolean	Se a entidade e um elite do EliteMobs
is_custom_boss	boolean	Se a entidade e um boss personalizado do EliteMobs (tambem disponivel dentro da subtabela elite)
is_significant_boss	boolean	Se a entidade e um boss personalizado com multiplicador de vida acima de 1 (ou seja, um encontro projetado, nao um elite generico)
elite	tabela ou nil	Subtabela de informacoes do elite (veja abaixo). nil se a entidade nao for um elite.

A subtabela elite contem:

Campo	Tipo	Notas
elite.level	int	O nivel do elite
elite.name	string	O nome de exibicao do elite
elite.health	number	Vida atual
elite.max_health	number	Vida maxima
elite.is_custom_boss	boolean	Se e um boss personalizado (em oposicao a um elite natural)
elite.health_multiplier	number	Multiplicador de vida definido na configuracao
elite.damage_multiplier	number	Multiplicador de dano definido na configuracao
elite:remove()	void	Remove o elite atraves do pipeline de remocao adequado 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 dano dobrado a 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

Disponiveis quando o FreeMinecraftModels esta instalado.

Campo	Tipo	Notas
is_modeled	boolean	Se a entidade tem um modelo FMM anexado (DynamicEntity ou PropEntity)
is_prop	boolean	Se a entidade e um prop do FMM (entidade decorativa estatica)
model	tabela ou nil	Subtabela de informacoes do modelo (veja abaixo). nil se a entidade nao tiver modelo.

A subtabela model contem:

Campo	Tipo	Notas
model.model_id	string	O ID do blueprint do modelo (por exemplo, "torch_01")
model:play_animation(name, [blend], [loop])	boolean	Reproduz uma animacao nomeada. blend padrao e false, loop padrao e false. Retorna true se a animacao foi encontrada.
model:stop_animations()	void	Para todas as animacoes em reproducao no modelo.
model:remove()	void	Remove a entidade modelada atraves do pipeline de remocao adequado do FMM.

Padrao Bridge vs Prop

O bridge do modelo (disponivel em qualquer entidade) define blend e loop como false por padrao. A play_animation da tabela prop define ambos como true porque props tipicamente querem animacoes 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
        -- Pular props
    elseif entity.is_player then
        entity:damage(5)
    elseif entity.entity_type == "villager" then
        -- Nao machucar aldeoes
    elseif entity.is_elite then
        entity:damage(20)
    elseif entity.is_hostile then
        entity:damage(10)
    end
end

---

Campos Especificos de Jogador

Entidades jogador tem 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")

Metodos Especificos de Jogador

Metodo	Retorno	Notas
send_message(msg)	void	Envia uma mensagem de chat ao jogador. Suporta codigos de cor com &.
get_held_item()	tabela ou nil	Retorna {type, amount, display_name} para o item na mao principal do jogador, ou nil se vazia
consume_held_item(amount?)	void	Consome itens da mao principal do jogador. amount padrao e 1
has_item(material, amount?)	boolean	Retorna true se o jogador tiver pelo menos amount (padrao 1) do material fornecido em qualquer lugar do inventario
get_target_entity([range])	tabela de entidade ou nil	Retorna a entidade para a qual o jogador esta olhando via raycast, ou nil se nenhuma. Alcance padrao e 50.
get_eye_location()	tabela de localizacao	Retorna uma tabela de localizacao na altura dos olhos do jogador
get_look_direction()	tabela	Retorna um vetor de direcao {x, y, z} para onde o jogador esta olhando
send_block_change(x, y, z, material, [ticks])	void	Envia um bloco falso visivel apenas para este jogador. Se ticks for fornecido, o bloco falso se restaura automaticamente apos essa duracao.
reset_block(x, y, z)	void	Restaura um bloco falso de volta ao bloco real para este jogador
sleep(x, y, z)	void	Faz o jogador entrar na animacao de dormir em uma cama nas coordenadas fornecidas. O bloco e restaurado automaticamente quando o jogador para de dormir.
wake_up()	void	Acorda um jogador dormindo.

---

Metodos de Interface do Jogador

Estes metodos estao disponiveis em qualquer tabela de entidade de jogador e fornecem maneiras de exibir informacoes ao jogador atraves dos elementos de interface integrados do Minecraft.

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

Mostra uma barra de boss ao jogador.

Parametro	Tipo	Padrao	Notas
text	string	obrigatorio	O texto a exibir. Suporta codigos de cor com &.
color	string	"WHITE"	Cor da barra. Uma de: "RED", "BLUE", "GREEN", "YELLOW", "PURPLE", "PINK", "WHITE"
progress	number	obrigatorio	Preenchimento de 0.0 (vazio) a 1.0 (cheio)
ticks	int	nil	Atraso opcional de auto-ocultacao em ticks. Se omitido, a barra permanece ate ser manualmente ocultada.

player:hide_boss_bar()

Remove a barra de boss da tela do jogador. Nao recebe parametros.

player:show_action_bar(text, [ticks])

Mostra texto na area da barra de acao (acima da hotbar).

Parametro	Tipo	Padrao	Notas
text	string	obrigatorio	O texto a exibir. Suporta codigos de cor com &.
ticks	int	nil	Duracao opcional em ticks. Se fornecido, a mensagem e reenviada a cada 40 ticks para permanecer visivel pela duracao total.

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

Mostra uma tela de titulo ao jogador.

Parametro	Tipo	Padrao	Notas
title	string	obrigatorio	Texto do titulo principal. Suporta codigos de cor com &.
subtitle	string	""	Texto do subtitulo abaixo do titulo principal. Opcional.
fade_in	int	obrigatorio	Duracao do fade-in em ticks
stay	int	obrigatorio	Quanto tempo o titulo permanece na tela em ticks
fade_out	int	obrigatorio	Duracao do fade-out em ticks

---

Proximos Passos

Para hooks, APIs e fluxos de trabalho especificos de cada plugin:

• EliteMobs: Primeiros Passos | Hooks e Ciclo de Vida | Boss e Entidades | Mundo e Ambiente | Zonas e Alvos
• FreeMinecraftModels: Primeiros Passos | API de Props e Itens | Exemplos