Scripting Lua: Mundo e ambiente

Esta página explica os métodos disponíveis em context.world, context.vectors, context.settings e context.event. Permitem que os seus poderes Lua interajam com o mundo do Minecraft: gerar entidades, reproduzir efeitos, consultar blocos e muito mais. Se está a começar a criar poderes Lua, leia primeiro Primeiros passos.

Contexto de chefe do EliteMobs

Os poderes de chefe do EliteMobs reutilizam o ambiente isolado Lua do MagmaCore. A tabela context.world do chefe parte da tabela de mundo partilhada do MagmaCore, pelo que as funções genéricas de coordenadas, como get_block_at(...), set_block_at(...) e spawn_particle(...), continuam disponíveis. Esta página centra-se nas adições e substituições do EliteMobs para context.world, context.vectors, context.settings e context.event nos poderes de chefe. Para a API genérica do mundo, consulte Motor de scripting Lua do MagmaCore.

Quando existe um método com o mesmo nome nas duas tabelas, prevalece a versão do EliteMobs. Os métodos abaixo mantêm o seu comportamento: ignorar cancelamentos da geração de relâmpagos, especificações alargadas de partículas e acompanhamento de blocos temporários. Os restantes métodos partilhados continuam disponíveis, incluindo get_entity(uuid), block_is_passable(x, y, z), location_is_protected(location), spawn_dust(...) e raycast(...). Consulte os argumentos e o comportamento com chunks descarregados na referência da API partilhada; essas garantias não se aplicam automaticamente às substituições do EliteMobs.

As funções de saque do FreeMinecraftModels não estão disponíveis aqui

O FreeMinecraftModels acrescenta drop_elitemobs_procedural_loot, drop_elitemobs_random_loot, drop_elitemobs_custom_loot e start_elitemobs_transport ao context.world apenas nos seus próprios scripts de props. Cada plugin inclui uma cópia separada da biblioteca de scripting partilhada, por isso estas funções não aparecem nos poderes de chefe nem nos scripts de NPC do EliteMobs, mesmo com o FreeMinecraftModels instalado. Os poderes de chefe usam generate_player_loot e drop_bonus_coins em vez disso.

---

context.world

A tabela de mundo permite gerar entidades, reproduzir efeitos, modificar blocos e alterar o mundo. Os métodos aceitam dois pontos (world:method()) ou um ponto sem argumento self explícito.

As substituições de chefe abaixo convertem tabelas com x, y, z, yaw/pitch opcionais e o nome de um mundo carregado em world. Coordenadas ausentes valem 0; omitir o mundo usa o mundo atual do chefe, mas um nome explícito desconhecido impede a conversão. Também aceitam uma tabela aninhada current_location. Uma localização nil ou que não seja uma tabela usa a localização do chefe. Os métodos partilhados mantêm o seu próprio contrato de localização e o mundo capturado ao criar a tabela.

Fechar a instância Lua não desfaz automaticamente alterações do mundo nem remove entidades geradas. Os monitores do script param, mas temporizadores independentes de remoção, regeneração de explosões, relâmpagos potenciados e projéteis de ouro têm os seus próprios ciclos de vida. As substituições de blocos e geração não aplicam automaticamente location_is_protected nem as verificações partilhadas de chunks carregados; verifique as condições necessárias antes de alterar o mundo.

---

world:spawn_particle_at_location(location, particleSpec)

Gera partículas numa localização. O segundo argumento aceita um nome ou tabela de especificação. Um terceiro inteiro opcional fornece a quantidade quando falta amount; o valor predefinido é 1. Os nomes são convertidos para maiúsculas antes da procura. Nomes inválidos ou dados não suportados produzem um aviso e nenhuma partícula.

Parâmetro	Tipo	Notas
location	tabela de localização	Onde gerar as partículas
particleSpec	cadeia de texto ou tabela	Nome da partícula ou tabela de especificação de partículas (ver abaixo)

Exemplo

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Simple particle by name
    context.world:spawn_particle_at_location(context.boss:get_location(), "FLAME")

    -- Full particle spec table with red dust
    context.world:spawn_particle_at_location(context.boss:get_location(), {
      particle = "DUST",
      amount = 10,
      x = 0.5,
      y = 0.5,
      z = 0.5,
      speed = 0.02,
      red = 255,
      green = 0,
      blue = 0,
    })
  end
}

Formato da tabela de partículas

Chave	Tipo	Valor predefinido	Notas
particle	cadeia de texto	obrigatório	Nome da partícula
amount	inteiro	1	Número de partículas
x, y, z	número	0	Dispersão/deslocamento em cada eixo
speed	número	0	Velocidade das partículas
red, green, blue	inteiro	255	Cor RGB para DUST e DUST_COLOR_TRANSITION
toRed, toGreen, toBlue	inteiro	255	Cor final da transição para DUST_COLOR_TRANSITION

dica

Para DUST_COLOR_TRANSITION, também pode usar to_red, to_green, to_blue; os valores camelCase têm prioridade. Ambos os tipos de pó usam tamanho fixo 1, com componentes RGB entre 0..255. As outras partículas não recebem dados adicionais, pelo que nem todas as que exigem esses dados são suportadas.

atenção

Ao contrário das configurações YAML do EliteScript, os nomes de partículas em Lua não admitem a conversão de nomes antigos. Deve usar os nomes atuais da API do Spigot (por exemplo, FIREWORK em vez de FIREWORKS_SPARK, SMOKE em vez de SMOKE_NORMAL e DUST em vez de REDSTONE). Consulte a lista de partículas válidas para ver todos os nomes atuais e os seus equivalentes antigos.

---

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

Reproduz um som numa localização.

Parâmetro	Tipo	Valor predefinido	Notas
location	tabela de localização		Onde reproduzir o som
sound	cadeia de texto		Chave de som do Minecraft (por exemplo, "entity.blaze.shoot") ou nome do enum Sound do Spigot. Também aceita chaves de pacotes de recursos.
volume	número	1.0	Volume
pitch	número	1.0	Tom

Exemplo

return {
  api_version = 1,
  on_spawn = function(context)
    context.world:play_sound_at_location(
      context.boss:get_location(),
      "entity.wither.spawn",
      1.0,
      0.5
    )
  end
}

---

world:strike_lightning_at_location(location)

Gera um relâmpago real que causa dano e ativa o mecanismo do EliteMobs que ignora cancelamentos da sua geração. Não é a função partilhada de relâmpagos apenas visuais, nem garante que todas as regras de dano ou proteção de outros plugins sejam ignoradas.

Parâmetro	Tipo	Notas
location	tabela de localização	Onde fazer cair o relâmpago

Exemplo

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if not context.cooldowns:check_local("lightning", 100) then return end
    context.world:strike_lightning_at_location(context.player:get_location())
    context.player:send_message("&eA bolt of lightning strikes you!")
  end
}

---

world:spawn_entity_at_location(entityType, location, options)

Gera uma entidade vanilla diretamente no mundo da localização. Nomes desconhecidos devolvem nil; um tipo reconhecido mas impossível de gerar ainda pode causar um erro. Não define automaticamente o atirador de um projétil nem regista a entidade como reforço élite.

Parâmetro	Tipo	Notas
entityType	cadeia de texto	Nome do tipo de entidade (por exemplo, "FIREBALL", "ARROW")
location	tabela de localização	Onde gerar a entidade
options	tabela (opcional)	Opções de geração (ver abaixo)

Opções de geração de entidades

Chave	Tipo	Valor predefinido	Notas
velocity	tabela de vetor	nil	Velocidade inicial {x, y, z}
effect	cadeia de texto	nil	EntityEffect a reproduzir ao aparecer
duration	inteiro	0	Valores positivos agendam a remoção após estes ticks; valores não positivos não acrescentam temporizador
on_land	função	nil	function(land_location, entity_ref) ao tocar no chão, tornar-se inválida ou ultrapassar max_ticks; não é um evento de impacto nem prova de aterragem
max_ticks	inteiro	6000	Máximo de ticks de monitorização antes de forçar a função on_land
persistent	booleano	predefinição do Minecraft	false impede que a entidade seja guardada com o chunk, para que um encerramento ou o descarregamento do chunk a meio do efeito não a possa deixar no mundo

Devolve uma tabela que representa a entidade. As entidades não vivas (FIREBALL, ARROW, TNT, ...) devolvem uma tabela de referência de entidade não viva, na qual is_valid() é um método. Os tipos de entidade viva (ZOMBIE, GIANT, ...) devolvem uma tabela completa de entidade viva, na qual is_valid é um campo booleano. Chamar entity:is_valid() numa delas causa o erro attempt to call a boolean value.

O monitor verifica a entidade a cada tick enquanto o script está ativo e para com as suas tarefas. O temporizador positivo de duration é independente e pode remover a entidade após o fecho do script. Os nomes desconhecidos de effect são ignorados.

Exemplo

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if not context.cooldowns:check_local("fireball_spawn", 100) then return end
    -- Spawn a fireball aimed at the player
    local boss_loc = context.boss:get_location()
    local dir = context.vectors.get_vector_between_locations(boss_loc, context.player:get_location())
    dir = context.vectors.normalize_vector(dir)

    context.world:spawn_entity_at_location("FIREBALL", boss_loc, {
      velocity = { x = dir.x * 2, y = dir.y * 2, z = dir.z * 2 },
      duration = 100,
    })
  end
}

Exemplo

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Spawn a primed TNT with a landing callback
    context.world:spawn_entity_at_location("TNT", context.boss:get_location(), {
      velocity = { x = 0, y = 1.5, z = 0 },
      on_land = function(land_location, entity_ref)
        context.world:spawn_particle_at_location(land_location, {
          particle = "EXPLOSION_EMITTER",
          amount = 1,
        })
      end,
    })
  end
}

---

world:spawn_display_at_location(location, options)

Faz aparecer um display de item ou de bloco: um visual flutuante sem hitbox, gravidade nem IA. Use-o para pedras em órbita, adereços lançados e outros efeitos que só precisam de ser vistos, em vez de estilizar um suporte de armadura. O display fica centrado em location e é orientado segundo o seu yaw.

Opção	Tipo	Valor predefinido	Notas
item	cadeia de texto		Material mostrado como item. Um item de bloco, como "AMETHYST_BLOCK", aparece como um bloco centrado
block	cadeia de texto		Bloco mostrado como display de bloco, como material ou como dados de bloco, por exemplo "lantern[hanging=true]"
scale	número ou tabela de vetor	1	Um número escala todos os eixos; {x, y, z} escala cada um. Com 1, um bloco tem um bloco de largura
duration	inteiro	0	Valores positivos removem o display após estes ticks
teleport_duration	inteiro	0	Ticks que o cliente demora a deslizar para cada nova localização, de 0 a 59. Use 1 quando teletransportar o display a cada tick
billboard	cadeia de texto	FIXED	FIXED, VERTICAL, HORIZONTAL ou CENTER
glowing	booleano	false	Contorno brilhante
brightness	inteiro	luz do mundo	0 a 15, substituindo a luz no display
bedrock_fallback	booleano	true	Ver abaixo

Indique exatamente um de item ou block. Um item ou block em falta ou desconhecido, os dois em simultâneo, ou um scale que não seja positivo devolve nil e regista um aviso com o nome do poder. Um valor de billboard desconhecido mantém FIXED.

Os displays nunca são guardados com o chunk. São removidos quando duration termina, quando chama remove() ou quando o poder é encerrado, o que acontecer primeiro.

Os clientes Bedrock não conseguem desenhar entidades de display. Os jogadores Bedrock que estão no mundo quando o display aparece veem, em vez disso, um suporte de armadura invisível com o mesmo item, ou com o item do bloco no caso de um display de bloco, e o display fica escondido para eles. O suporte acompanha o display e é removido com ele. Os jogadores Bedrock que entram no mundo mais tarde não recebem suporte, e um bloco sem forma de item, como fire, não recebe suporte nenhum. Desative-o com bedrock_fallback = false nos efeitos que os jogadores Bedrock não precisam de ver.

A tabela devolvida tem uuid e entity_type e estes métodos:

Método	Notas
is_valid(), is_alive()	Indica se o display ainda existe
get_location()	Localização atual
teleport_to_location(location)	Move o display e o seu suporte Bedrock
remove()	Remove o display e o seu suporte Bedrock
set_scale(scale)	Mesmos valores da opção scale
set_item(material)	Apenas displays de item; devolve false nos outros
set_block(block)	Apenas displays de bloco; devolve false nos outros
set_glowing(enabled)	Contorno brilhante
set_brightness(level)	0 a 15, ou nil para voltar a usar a luz do mundo
set_teleport_duration(ticks)	Igual à opção teleport_duration

Exemplo

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

---

world:spawn_falling_block_at_location(location, material, options)

Gera um bloco em queda usando um material de bloco. Com on_land, EliteMobs interceta o evento de alteração de bloco, cancela a colocação e chama uma vez function(land_location, entity_ref). Sem a função, a colocação normal pode ocorrer. Não existem opções duration/max_ticks nem chamadas por invalidez ou tempo esgotado.

Parâmetro	Tipo	Notas
location	tabela de localização	Onde gerar a entidade
material	cadeia de texto	Nome do material (por exemplo, "STONE", "MAGMA_BLOCK")
options	tabela (opcional)	Opções de geração (ver abaixo)

Opções de blocos em queda

Chave	Tipo	Valor predefinido	Notas
velocity	tabela de vetor	nil	Velocidade inicial {x, y, z}
drop_item	booleano	false	Se o bloco é largado como item
hurt_entities	booleano	false	Se o bloco causa dano às entidades sobre as quais cai
on_land	função	nil	Função function(land_location, entity_ref) executada quando o bloco aterra

Devolve uma referência de entidade não viva ou nil se não for possível resolver a localização ou o material. Um material reconhecido que não seja um bloco pode falhar ao criar os dados de bloco.

Exemplo

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Rain magma blocks from above
    local loc = context.boss:get_location()
    for i = 1, 5 do
      local offset_loc = {
        x = loc.x + math.random(-3, 3),
        y = loc.y + 10,
        z = loc.z + math.random(-3, 3),
        world = loc.world
      }
      context.world:spawn_falling_block_at_location(offset_loc, "MAGMA_BLOCK", {
        velocity = { x = 0, y = -0.5, z = 0 },
        hurt_entities = true,
        on_land = function(land_location, entity_ref)
          context.world:spawn_particle_at_location(land_location, { particle = "LAVA", amount = 8 })
        end,
      })
    end
  end
}

---

world:spawn_custom_boss_at_location(filename, location, options)

Gera um chefe personalizado do EliteMobs a partir de um ficheiro de configuração.

Parâmetro	Tipo	Notas
filename	cadeia de texto	Nome do ficheiro de configuração do chefe (por exemplo, "my_boss.yml")
location	tabela de localização	Onde gerar a entidade
options	tabela (opcional)	Opções de geração (ver abaixo)

Opções de geração de chefes personalizados

Chave	Tipo	Valor predefinido	Notas
level	inteiro	nível configurado do chefe gerado	Substitui o nível. Se omitido, aplicam-se a configuração e as regras de nível dinâmico do próprio chefe; não herda o nível de quem o gera.
silent	booleano	false	Suprimir as mensagens de aparecimento
velocity	tabela de vetor	nil	Velocidade inicial
add_as_reinforcement	booleano	false	Registar como reforço do chefe atual

Devolve uma tabela que representa o chefe, ou nil se não foi possível criá-lo.

Exemplo

return {
  api_version = 1,
  on_enter_combat = function(context)
    local minion = context.world:spawn_custom_boss_at_location(
      "skeleton_minion.yml",
      context.boss:get_location(),
      { level = 10, add_as_reinforcement = true }
    )
    if minion ~= nil then
      context.boss:send_message("&cMinions, arise!")
    end
  end
}

---

world:spawn_boss_at_location(filename, location, level)

Método simplificado: a localização e o nível omitidos usam os do chefe que o gera. Não regista o resultado como reforço. Omita o terceiro argumento para usar o valor predefinido; passar explicitamente nil nessa posição não é aceite.

Parâmetro	Tipo	Valor predefinido	Notas
filename	cadeia de texto		Nome do ficheiro de configuração do chefe
location	tabela de localização	localização do chefe	Onde gerar a entidade (opcional; por predefinição, a localização do chefe)
level	inteiro	nível do chefe	Substituir o nível de aparecimento (opcional)

Devolve uma tabela que representa a entidade, ou nil.

Exemplo

return {
  api_version = 1,
  on_enter_combat = function(context)
    context.world:spawn_boss_at_location("zombie_guard.yml", context.boss:get_location(), 5)
    context.boss:send_message("&cGuards, defend me!")
  end
}

---

world:spawn_reinforcement_at_location(filename, location, duration, velocity)

Gera silenciosamente um reforço, regista quem o invocou e herda o combate normalizado se o chefe personalizado invocador o usar. O nível segue a configuração e as regras de nível dinâmico do próprio reforço; duration é um temporizador de fuga, não um nível.

Parâmetro	Tipo	Valor predefinido	Notas
filename	cadeia de texto		Nome do ficheiro de configuração do chefe
location	tabela de localização		Onde gerar a entidade
duration	inteiro	0	Temporizador de fuga em ticks; 0 não acrescenta temporizador. Não substitui o nível do reforço.
velocity	tabela de vetor	nil	Velocidade inicial (opcional)

Devolve uma tabela que representa a entidade, ou nil.

Exemplo

return {
  api_version = 1,
  on_enter_combat = function(context)
    context.world:spawn_reinforcement_at_location(
      "necro_skeleton.yml",
      context.boss:get_location(),
      0,
      { x = 0, y = 0.5, z = 0 }
    )
    context.boss:send_message("&5Rise, my servant!")
  end
}

---

world:spawn_fireworks_at_location(location, spec)

Gera fogo de artifício real, sem suprimir automaticamente o dano. Forneça pelo menos uma cor válida por efeito; criar um efeito sem cores pode falhar.

Parâmetro	Tipo	Notas
location	tabela de localização	Onde gerar a entidade
spec	tabela	Especificação do fogo de artifício (ver abaixo)

Tabela de especificação de fogos de artifício

Chave	Tipo	Valor predefinido	Notas
power	inteiro	1	Potência de voo (altura)
velocity	tabela de vetor	nil	Velocidade inicial
shot_at_angle	booleano	true	Se o fogo de artifício é lançado em ângulo (usado quando a velocidade é definida)
effects	tabela de tabelas	nil	Lista de especificações de efeitos do fogo de artifício. Se for omitida, a especificação principal é tratada como um único efeito.

Especificação de efeitos de fogos de artifício

Chave	Tipo	Valor predefinido	Notas
type	cadeia de texto	"BALL_LARGE"	"BALL", "BALL_LARGE", "STAR", "BURST", "CREEPER"
flicker	booleano	true	Efeito de cintilação
trail	booleano	true	Efeito de rasto
colors	tabela	obrigatório por efeito	Lista não vazia de nomes de cores ou tabelas {red = 255, green = 0, blue = 0}
fade_colors	tabela	nil	Lista de nomes de cores de desvanecimento ou tabelas {red, green, blue}

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

Devolve uma referência de entidade não viva, ou nil se não for possível resolver a localização. :detonate() pede a detonação. Os tipos e nomes de cores ignoram maiúsculas/minúsculas; um tipo desconhecido usa BALL_LARGE e uma cor desconhecida usa branco. Os componentes RGB devem estar entre 0..255.

Exemplo

return {
  api_version = 1,
  on_spawn = function(context)
    local fw = context.world:spawn_fireworks_at_location(context.boss:get_location(), {
      power = 0,
      effects = {
        {
          type = "STAR",
          flicker = true,
          trail = true,
          colors = { "RED", "ORANGE", { red = 255, green = 200, blue = 0 } },
          fade_colors = { "YELLOW" },
        },
      },
    })

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

---

world:spawn_splash_potion_at_location(location, spec)

Gera uma poção arremessável real. Efeitos Bukkit desconhecidos produzem um aviso e são ignorados. Não define um atirador nem aplica o filtro de efeitos de instância dos métodos diretos de poção do chefe; aplica-se o comportamento normal das poções arremessáveis.

Parâmetro	Tipo	Notas
location	tabela de localização	Onde gerar a entidade
spec	tabela	Especificação da poção (ver abaixo)

Tabela de especificação de poções arremessáveis

Chave	Tipo	Notas
velocity	tabela de vetor	Velocidade inicial da poção lançada
effects	tabela de tabelas	Lista de especificações de efeitos de poção

Especificação de efeitos de poção

Chave	Tipo	Valor predefinido	Notas
type	cadeia de texto	obrigatório	Nome do tipo de efeito de poção (por exemplo, "SLOWNESS", "POISON")
duration	inteiro	0	Duração em ticks
amplifier	inteiro	0	Amplificador do efeito (0 = nível I)
overwrite	booleano	true	Substitui um efeito anterior do mesmo tipo nos metadados desta poção; não regula os efeitos já ativos num jogador

Devolve uma tabela de referência de entidade, ou nil.

Exemplo

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if not context.cooldowns:check_local("potion_throw", 200) then return end

    local dir = context.vectors.get_vector_between_locations(
      context.boss:get_location(),
      context.player:get_location()
    )
    dir = context.vectors.normalize_vector(dir)

    context.world:spawn_splash_potion_at_location(context.boss:get_location(), {
      velocity = { x = dir.x * 1.5, y = 0.5, z = dir.z * 1.5 },
      effects = {
        { type = "SLOWNESS", duration = 100, amplifier = 1 },
        { type = "WEAKNESS", duration = 60, amplifier = 0 },
      },
    })
  end
}

---

world:place_temporary_block_at_location(location, material, duration, requireAir)

Coloca um bloco registado que restaura os dados anteriores após uma duração positiva. Guarda dados de bloco, não conteúdos de recipientes. O bloco original volta quando o temporizador termina, quando o chunk ou o mundo é descarregado, ou quando o plugin fecha, mas só enquanto o bloco ainda contiver o bloco temporário, pelo que uma edição posterior não é sobrescrita. Colocar de novo sobre um bloco que ainda contém um bloco temporário reinicia o seu temporizador e mantém o primeiro original guardado. Blocos com entidades de bloco, como baús e placas, chunks não carregados e blocos detidos por outro dono de blocos temporários são ignorados. Partir um bloco registado não larga nada e termina o registo sem restaurar. Use um material de bloco. Esta substituição devolve nil, mesmo se requireAir ou uma exclusão impedir a colocação; não confirma sucesso nem verifica automaticamente a proteção regional.

Parâmetro	Tipo	Valor predefinido	Notas
location	tabela de localização		Onde colocar o bloco
material	cadeia de texto		Nome do material
duration	inteiro	0	Ticks até à restauração; zero ou valores negativos colocam o bloco de forma permanente, sem registo
requireAir	booleano	false	Se for true, só coloca o bloco se o bloco atual for ar

Exemplo

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Create a temporary ice floor under the boss
    local loc = context.boss:get_location()
    for dx = -2, 2 do
      for dz = -2, 2 do
        context.world:place_temporary_block_at_location(
          { x = loc.x + dx, y = loc.y - 1, z = loc.z + dz, world = loc.world },
          "PACKED_ICE",
          100,
          false
        )
      end
    end
  end
}

---

world:set_block_at_location(location, material, requireAir)

Coloca um bloco de forma permanente através do gestor de blocos temporários, sem temporizador de restauração e sem registo, pelo que a alteração se mantém depois de o plugin fechar. Se o bloco contiver atualmente um bloco temporário com temporizador, esse bloco deixa de ser registado e não é restaurado. Os blocos detidos por outro dono de blocos temporários ficam inalterados. Use uma duração positiva com place_temporary_block_at_location para restaurar o original após um prazo.

Parâmetro	Tipo	Valor predefinido	Notas
location	tabela de localização		Onde colocar o bloco
material	cadeia de texto		Nome do material
requireAir	booleano	false	Se for true, só coloca o bloco se o bloco atual for ar

Exemplo

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Place fire at the boss's location
    context.world:set_block_at_location(context.boss:get_location(), "FIRE", true)
  end
}

---

world:get_block_type_at_location(location)

Devolve o nome do material em maiúsculas, ou nil se não for possível resolver a localização. Ao contrário da consulta partilhada por coordenadas, acede diretamente ao bloco sem verificar se o chunk está carregado.

Parâmetro	Tipo	Notas
location	tabela de localização	Localização a consultar

Exemplo

return {
  api_version = 1,
  on_enter_combat = function(context)
    local block_type = context.world:get_block_type_at_location(context.boss:get_location())
    if block_type == "WATER" then
      context.boss:send_message("&bThe boss is empowered by water!")
      context.boss:apply_potion_effect("SPEED", 200, 1)
    end
  end
}

---

world:get_highest_block_y_at_location(location)

Devolve a coordenada Y do bloco mais alto segundo Bukkit na posição X/Z, ou nil se não resolver a localização. Não verifica se o chunk já está carregado nem se o destino é seguro para teletransporte.

Parâmetro	Tipo	Notas
location	tabela de localização	Localização a consultar (são usados X e Z)

Exemplo

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if not context.cooldowns:check_local("skyport", 200) then return end
    local loc = context.player:get_location()
    local ground_y = context.world:get_highest_block_y_at_location(loc)
    -- Teleport the player to the surface
    context.player:teleport_to_location({
      x = loc.x, y = ground_y + 1, z = loc.z, world = loc.world
    })
    context.player:send_message("&eYou are teleported to the surface!")
  end
}

---

world:get_blast_resistance_at_location(location)

Devolve a resistência a explosões do material, ou 0 se não for possível resolver a localização.

Parâmetro	Tipo	Notas
location	tabela de localização	Localização a consultar

Exemplo

return {
  api_version = 1,
  on_enter_combat = function(context)
    local resistance = context.world:get_blast_resistance_at_location(context.boss:get_location())
    context.log:info("Blast resistance at boss: " .. resistance)
  end
}

---

world:is_air_at_location(location)

Devolve true se o bloco na localização for ar.

Parâmetro	Tipo	Notas
location	tabela de localização	Localização a consultar

Exemplo

return {
  api_version = 1,
  on_enter_combat = function(context)
    local loc = context.boss:get_location()
    local above = { x = loc.x, y = loc.y + 2, z = loc.z, world = loc.world }
    if context.world:is_air_at_location(above) then
      -- There is space above the boss, launch upward
      context.boss:set_velocity_vector({ x = 0, y = 1.5, z = 0 })
    end
  end
}

---

world:is_passable_at_location(location)

Devolve o resultado Bukkit de Block.isPassable(), ou false se não resolver a localização. Consulta um único bloco; não verifica se uma entidade inteira cabe ou consegue navegar nesse espaço.

Parâmetro	Tipo	Notas
location	tabela de localização	Localização a consultar

Exemplo

return {
  api_version = 1,
  on_enter_combat = function(context)
    if context.world:is_passable_at_location(context.boss:get_location()) then
      context.log:info("Boss is in a passable block")
    end
  end
}

---

world:is_passthrough_at_location(location)

Devolve true se o bloco na localização não for sólido. É semelhante à verificação de transitabilidade, mas baseia-se em saber se o bloco é sólido.

Parâmetro	Tipo	Notas
location	tabela de localização	Localização a consultar

Exemplo

return {
  api_version = 1,
  on_enter_combat = function(context)
    local loc = context.boss:get_location()
    local above = { x = loc.x, y = loc.y + 1, z = loc.z, world = loc.world }
    if context.world:is_passthrough_at_location(above) then
      context.log:info("Boss can move upward")
    end
  end
}

---

world:is_on_floor_at_location(location)

Devolve true se o bloco da localização não for sólido e o bloco uma unidade Y abaixo for sólido. Não verifica o contacto de uma entidade com o chão, a caixa de colisão nem o espaço sobre a cabeça.

Parâmetro	Tipo	Notas
location	tabela de localização	Localização a consultar

Exemplo

return {
  api_version = 1,
  on_enter_combat = function(context)
    if context.world:is_on_floor_at_location(context.boss:get_location()) then
      context.boss:send_message("&aThe boss slams the ground!")
      context.world:spawn_particle_at_location(context.boss:get_location(), {
        particle = "CLOUD",
        amount = 30,
      })
    end
  end
}

---

world:is_standing_on_material(location, material)

Devolve true se o bloco imediatamente abaixo da localização corresponder ao material indicado.

Parâmetro	Tipo	Notas
location	tabela de localização	Localização a consultar
material	cadeia de texto	Nome do material a verificar

Exemplo

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if context.world:is_standing_on_material(context.player:get_location(), "SOUL_SAND") then
      context.player:send_message("&8The soul sand saps your strength!")
      context.player:apply_potion_effect("SLOWNESS", 60, 2)
    end
  end
}

---

world:set_world_time(time) / world:set_world_time(location, time)

Altera a hora de todo o mundo. Uma localização opcional seleciona o mundo. A hora anterior não é restaurada ao fechar o script.

Parâmetro	Tipo	Notas
location	tabela de localização (opcional)	Mundo a alterar. Por predefinição, o mundo do chefe.
time	inteiro	Hora do mundo em ticks (0 = amanhecer, 6000 = meio-dia, 13000 = noite, 18000 = meia-noite)

Exemplo

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Set to midnight when combat starts
    context.world:set_world_time(18000)
    context.boss:send_message("&8Darkness falls...")
  end
}

---

world:set_world_weather(weather, duration) / world:set_world_weather(location, weather, duration)

Altera o tempo no mundo do chefe ou da localização opcional. Os nomes ignoram maiúsculas/minúsculas; nomes desconhecidos apenas produzem um aviso. RAIN/CLEAR definem o temporizador meteorológico; THUNDER define o temporizador do trovão. Afeta todo o mundo e não restaura o estado anterior ao fechar o script.

Parâmetro	Tipo	Valor predefinido	Notas
location	tabela de localização (opcional)	mundo do chefe	Mundo a alterar
weather	cadeia de texto		"CLEAR", "RAIN" (ou "PRECIPITATION"), "THUNDER"
duration	inteiro	6000	Duração do estado do tempo em ticks

Exemplo

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Start a thunderstorm for 200 ticks
    context.world:set_world_weather("THUNDER", 200)
    context.boss:send_message("&eA storm gathers!")
  end
}

---

world:generate_fake_explosion(blockLocations, sourceLocation)

Remove blocos reais e cria destroços de blocos em queda através da regeneração de explosões do EliteMobs. Os destroços têm dano a entidades ativo; não é um efeito de partículas inofensivo. Exige doExplosionRegen; a flag de regeneração do WorldGuard é verificada quando se fornece uma localização de origem. Ignora ar, fogo, líquidos e blocos temporários registados, e pode incluir blocos vizinhos dependentes. A restauração começa após 1200 ticks e processa um bloco registado por tick. Mantenha todas as localizações no mundo do chefe. Devolve nil e fechar o script não desfaz a operação.

Parâmetro	Tipo	Notas
blockLocations	tabela de tabelas de localização	Lista de localizações dos blocos a «explodir»
sourceLocation	tabela de localização (opcional)	Origem da explosão para os cálculos de direção

Exemplo

return {
  api_version = 1,
  on_enter_combat = function(context)
    local loc = context.boss:get_location()
    local blocks = {}
    for dx = -1, 1 do
      for dz = -1, 1 do
        table.insert(blocks, { x = loc.x + dx, y = loc.y, z = loc.z + dz, world = loc.world })
      end
    end
    context.world:generate_fake_explosion(blocks, loc)
  end
}

---

world:run_console_command(command)

Executa imediatamente um comando de consola como o servidor e devolve nil, sem expor se teve sucesso. Não substitui automaticamente marcadores de jogador ou chefe.

Os comandos vanilla comunicam o seu resultado e, com o valor predefinido broadcast-console-to-ops=true, o servidor mostra cada resultado a todos os operadores online. Os comandos executados com frequência, como data merge entity, kill ou damage, inundam o chat deles. Use antes os métodos nativos: spawn_display_at_location para visuais, os métodos de suportes de armadura para suportes, entity:remove() para remover o que um script fez aparecer e entity:deal_custom_damage(amount) para dano exato do boss.

Parâmetro	Tipo	Notas
command	cadeia de texto	Comando a executar (sem a / inicial)

Exemplo

return {
  api_version = 1,
  on_enter_combat = function(context)
    context.world:run_console_command("say The boss has entered phase 2!")
  end
}

---

world:run_empowered_lightning_task_at_location(location)

Inicia uma tarefa Bukkit independente na localização capturada. Emite SOUL_FIRE_FLAME durante 60 iterações; depois gera um relâmpago real ignorando cancelamentos da geração e uma bola de fogo descendente com potência explosiva 5, marcada como ender_dragon_empowered_lightning.yml. É um ataque que causa dano. Fechar ou pausar Lua não cancela esta tarefa; a função também não consulta a opção de efeitos de aviso.

Parâmetro	Tipo	Notas
location	tabela de localização	Onde fazer cair o relâmpago

Exemplo

return {
  api_version = 1,
  on_enter_combat = function(context)
    context.world:run_empowered_lightning_task_at_location(context.boss:get_location())
    context.boss:send_message("&eFeel the power of the storm!")
  end
}

---

world:spawn_fake_gold_nugget_at_location(location, velocity, hasGravity)

Cria uma pepita de ouro visual através de pacotes de rede para jogadores próximos; jogadores e funis não a podem recolher. Criá-la não inicia o movimento nem o dano. Passe-a uma vez a run_fake_gold_nugget_damage como parte de um conjunto, ou remova-a explicitamente.

Parâmetro	Tipo	Valor predefinido	Notas
location	tabela de localização		Localização de aparecimento
velocity	tabela de vetor		Velocidade inicial
hasGravity	booleano	false	Se o projétil tem gravidade

Devolve uma tabela de projétil falso, ou nil se não resolver a localização ou o vetor, com get_location(), set_gravity(bool), remove() e is_removed().

Exemplo

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if not context.cooldowns:check_local("nugget", 60) then return end

    local dir = context.vectors.get_vector_between_locations(
      context.boss:get_location(),
      context.player:get_location()
    )
    dir = context.vectors.normalize_vector(dir)

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

---

world:run_fake_gold_nugget_damage(projectiles)

Inicia uma tarefa Bukkit independente que move e verifica o conjunto a cada tick. Chame-a uma vez por conjunto: cada chamada cria outra tarefa. Consulta entidades vivas numa caixa com semidimensão 0.5 na nova posição, ignora o chefe de origem e jogadores a bloquear, e submete dano personalizado de 1 através das regras de dano do chefe. Uma colisão pode remover o projétil mesmo que o dano seja rejeitado. O contacto com o chão ou o limite de 100 ticks também o remove. A verificação usa posições amostradas, não um raio ao longo de todo o percurso; fechar ou pausar Lua não cancela a tarefa.

Parâmetro	Tipo	Notas
projectiles	tabela	Lista de tabelas de projéteis falsos obtidas com spawn_fake_gold_nugget_at_location

Exemplo

return {
  api_version = 1,
  on_enter_combat = function(context)
    -- Keep this batch separate from later combat entries.
    local projectiles = {}
    local loc = context.boss:get_location()
    for i = 1, 5 do
      local angle = (i / 5) * math.pi * 2
      local nugget = context.world:spawn_fake_gold_nugget_at_location(
        loc,
        { x = math.cos(angle) * 0.5, y = 0.3, z = math.sin(angle) * 0.5 }
      )
      if nugget ~= nil then table.insert(projectiles, nugget) end
    end

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

---

world:generate_player_loot(times)

Executa o gerador normal de saque times vezes; valores não positivos não fazem nada. Exige eliteLoot, nenhuma proteção contra abusos acionada, dados do jogador carregados e dano registado de pelo menos 10% da saúde máxima. Ignora jogadores com bloqueio de recompensas da instância. Cada passagem pode incluir moedas e, com saque aleatório ativo, saque aleatório/especial e pergaminhos segundo as definições e regras de grupo. Não repete todos os drops personalizados definidos nem garante um item por sorteio. Chamadas repetidas concedem mais tentativas; não existe um limite de uma chamada por chefe.

Parâmetro	Tipo	Valor predefinido	Notas
times	inteiro	1	Número de sorteios de saque

Exemplo

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    local pct = context.boss:get_health() / context.boss:get_maximum_health()
    if pct < 0.5 and not context.boss:has_tag("bonus_loot") then
      context.boss:add_tag("bonus_loot")
      context.world:generate_player_loot(2)
      context.boss:send_message("&6Bonus loot drops!")
    end
  end
}

---

world:drop_bonus_coins(multiplier)

Larga moedas adicionais para jogadores cujo dano registado excede 10% da saúde máxima do chefe. Ignora NPC e jogadores sem dados EliteMobs carregados. A quantidade usa o nível de recompensa ajustado do jogador multiplicado por multiplier.

Parâmetro	Tipo	Valor predefinido	Notas
multiplier	número	2.0	Multiplicador da quantidade de moedas

Exemplo

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    local pct = context.boss:get_health() / context.boss:get_maximum_health()
    if pct < 0.25 and not context.boss:has_tag("bonus_coins") then
      context.boss:add_tag("bonus_coins")
      context.world:drop_bonus_coins(3.0)
      context.boss:send_message("&6Gold spills everywhere!")
    end
  end
}

---

context.vectors

As funções vetoriais aceitam ponto ou dois pontos. As entradas admitem campos x, y, z, índices numéricos 1..3 ou uma tabela aninhada direction. Componentes ausentes valem 0. Os resultados são tabelas novas; as entradas não são alteradas.

Método	Devolve	Notas
vectors.get_vector_between_locations(loc1, loc2[, options])	tabela de vetor	Deslocamento loc2 - loc1, não normalizado por predefinição
vectors.normalize_vector(vec)	tabela de vetor	Vetor unitário para entradas não nulas; zero mantém-se zero
vectors.rotate_vector(vec, pitch, yaw)	tabela de vetor	Roda primeiro em torno do eixo X do mundo, depois de Y, em graus

Todas as tabelas de vetor têm os campos x, y e z.

vectors.get_vector_between_locations(loc1, loc2, options)

Parâmetro	Tipo	Notas
loc1	tabela de localização	Ponto inicial
loc2	tabela de localização	Ponto final
options	tabela (opcional)	Opções de pós-processamento (ver abaixo)

Opções de vetores

Chave	Tipo	Valor predefinido	Notas
normalize	booleano	false	Normalizar o vetor resultante
multiplier	número	1.0	Escalar o vetor
offset	tabela de vetor	nil	Adicionar um vetor de deslocamento

Ordem das opções: normalizar o deslocamento não nulo, multiplicar e adicionar o desvio nos eixos do mundo. Localizações não resolvidas ou de mundos diferentes devolvem zero antes de aplicar opções. Localizações válidas coincidentes ainda podem receber um desvio.

Exemplo

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if not context.cooldowns:check_local("dash", 100) then return end
    -- Compute a normalized direction from boss to player, scaled to speed 2
    local dir = context.vectors.get_vector_between_locations(
      context.boss:get_location(),
      context.player:get_location(),
      { normalize = true, multiplier = 2.0 }
    )
    -- Launch the boss toward the player
    context.boss:set_velocity_vector(dir)
  end
}

vectors.normalize_vector(vec)

Parâmetro	Tipo	Notas
vec	tabela de vetor	Vetor de entrada

Exemplo

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    local raw = context.vectors.get_vector_between_locations(
      context.boss:get_location(),
      context.player:get_location()
    )
    local unit = context.vectors.normalize_vector(raw)
    context.log:info("Direction: " .. unit.x .. ", " .. unit.y .. ", " .. unit.z)
  end
}

vectors.rotate_vector(vec, pitch, yaw)

Parâmetro	Tipo	Notas
vec	tabela de vetor	Vetor de entrada
pitch	número	Rotação em torno do eixo X em graus
yaw	número	Rotação em torno do eixo Y em graus

Exemplo

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.player == nil then return end
    if not context.cooldowns:check_local("spread_shot", 100) then return end
    local forward = context.vectors.normalize_vector(
      context.vectors.get_vector_between_locations(
        context.boss:get_location(),
        context.player:get_location()
      )
    )
    -- Fire three fireballs in a spread pattern
    for _, yaw_offset in ipairs({ -30, 0, 30 }) do
      local dir = context.vectors.rotate_vector(forward, 0, yaw_offset)
      context.boss:summon_projectile(
        "FIREBALL",
        context.boss:get_eye_location(),
        {
          x = context.boss:get_location().x + dir.x * 10,
          y = context.boss:get_location().y + dir.y * 10,
          z = context.boss:get_location().z + dir.z * 10,
          world = context.boss:get_location().world
        },
        1.0
      )
    end
  end
}

dica

Pode criar um leque de direções rodando um vetor base dentro de um ciclo:

local base = context.vectors.normalize_vector(
  context.vectors.get_vector_between_locations(boss_loc, target_loc)
)
for angle = 0, 330, 30 do
  local dir = context.vectors.rotate_vector(base, 0, angle)
  -- Use dir for spawning projectiles in a ring
end

---

context.settings

Acesso de leitura à configuração dos poderes. A função lê a definição atual quando é chamada; não suprime automaticamente partículas ou efeitos. O script deve usar o resultado para decidir se apresenta um aviso.

Método	Devolve	Notas
settings:warning_visual_effects_enabled()	booleano	Se os efeitos visuais de aviso estão ativados nas definições de combate dos mobs

Exemplo

return {
  api_version = 1,
  on_enter_combat = function(context)
    if context.settings:warning_visual_effects_enabled() then
      context.world:spawn_particle_at_location(context.boss:get_location(), {
        particle = "DUST",
        amount = 20,
        red = 255, green = 0, blue = 0,
      })
    end
  end
}

---

context.event

Dados do evento do hook atual. Os campos dependem do evento subjacente; verifique os opcionais antes de os usar. Os modificadores numéricos de dano exigem ponto (event.set_damage_amount(value)); transfer_damage aceita ponto ou dois pontos. Esta tabela de eventos de chefe não expõe os membros partilhados cancel, uncancel ou is_cancelled.

Campo ou método	Quando está disponível	Notas
event.damage_amount	Hooks de dano	Dano capturado quando a tabela diferida do evento é resolvida pela primeira vez
event.get_damage_amount()	Hooks de dano	Lê a quantidade atual após alterações
event.damage_cause	Hooks de dano	Nome do enum DamageCause do Bukkit (por exemplo, "ENTITY_ATTACK")
event.cancel_event()	Eventos canceláveis	Cancela o evento
event.set_damage_amount(value)	Hooks baseados em EliteDamageEvent	Define o dano diretamente
event.multiply_damage_amount(multiplier)	Hooks baseados em EliteDamageEvent	Multiplica o dano atual
event.damager	Eventos de dano com uma entidade atacante	Atacante original Bukkit: o próprio projétil num impacto, não quem o lançou
event.projectile	Eventos de dano em que o atacante é um projétil	Tabela de referência da entidade do projétil
event.spawn_reason	on_spawn	Nome do enum do motivo de aparecimento
event.entity	Dano de jogador a chefe, on_death, eventos de zona	Chefe atingido, entidade morta ou que atravessa a zona; para dano a um reforço, é o reforço
event.is_damage_transfer	Dano de jogador a chefe, incluindo o reencaminhado por reforços	Indica se o golpe foi criado por transferência
event:transfer_damage(target, amount)	Dano de jogador a chefe, incluindo o reencaminhado por reforços	Submete um golpe separado a outro élite elegível; consulte o contrato de transferência de dano

Exemplo: Reduzir para metade o dano recebido

Exemplo

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.event ~= nil then
      local dmg = context.event.damage_amount
      context.log:info("Boss took " .. dmg .. " damage, halving it")
      context.event.multiply_damage_amount(0.5)
    end
  end
}

Exemplo: Cancelar o dano de projéteis

Exemplo

return {
  api_version = 1,
  on_boss_damaged_by_player = function(context)
    if context.event ~= nil and context.event.damage_cause == "PROJECTILE" then
      context.event.cancel_event()
      if context.player ~= nil then
        context.player:send_message("&cThe boss deflects your projectile!")
      end
    end
  end
}

Exemplo: Ler a causa do dano

Exemplo

return {
  api_version = 1,
  on_player_damaged_by_boss = function(context)
    if context.event ~= nil then
      context.log:info("Damage cause: " .. (context.event.damage_cause or "unknown"))
    end
  end
}

nota

• damage_amount é um valor capturado. Não é atualizado automaticamente depois de chamar set_damage_amount() ou multiply_damage_amount().
• O contexto novo recebido por uma função agendada tem event = nil. Capturar o contexto antigo não permite modificar validamente o seu evento já terminado; modifique eventos durante o respetivo hook.
• Os modificadores alteram o evento pendente, não a saúde já perdida. Outros listeners podem ainda modificar ou cancelar o golpe. Uma transferência aceite submete um golpe adicional; não reduz nem cancela automaticamente o original.

---

Próximos passos

• Primeiros passos | Scripts de NPC | Hooks e ciclo de vida | Chefes e entidades | Zonas e seleção de alvos | Exemplos | Enums | Resolução de problemas
• Referência da API | Motor de scripting