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: cada método *_at_location documentado abaixo substitui o partilhado para manter o comportamento do EliteMobs nos scripts de chefe: relâmpagos que ignoram as proteções, especificações alargadas de partículas e acompanhamento de blocos temporários.

As funções de saque só aparecem com FreeMinecraftModels instalado

Quando FreeMinecraftModels também está instalado no servidor, regista três métodos adicionais na tabela de mundo partilhada, herdados pelos poderes de chefe: world:drop_elitemobs_procedural_loot(player, level[, location]), world:drop_elitemobs_random_loot(player, level[, location]) e world:drop_elitemobs_custom_loot(player, filename, level[, location]). Cada método aceita uma tabela de jogador, uma cadeia UUID ou o nome do jogador; usa a localização do próprio jogador se location for omitida ou inválida, e devolve um booleano. Devolvem false em vez de lançar um erro se faltar algum dos dois plugins.

---

context.world

A tabela de mundo fornece métodos para gerar entidades, reproduzir efeitos, modificar blocos e alterar o estado do mundo. Todos os métodos são chamados com dois pontos (world:method()).

---

world:spawn_particle_at_location(location, particleSpec)

Gera partículas numa localização. O segundo argumento pode ser uma cadeia com o nome da partícula ou uma tabela de especificação completa para controlo avançado.

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 chaves em snake_case: to_red, to_green, to_blue.

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)

Faz cair um relâmpago numa localização, com efeito visual e dano.

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 do Minecraft vanilla.

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	Remover automaticamente após este número de ticks (0 = nunca)
on_land	função	nil	Função de retorno quando a entidade aterra no chão
max_ticks	inteiro	6000	Máximo de ticks de monitorização antes de forçar a função on_land

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.

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

Gera uma entidade de bloco em queda.

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 tabela de referência de entidade.

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 do chefe	Substituir o nível do chefe gerado
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 para gerar um chefe personalizado numa localização, com um nível opcional.

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

Gera um reforço que é registado no sistema de reforços do EliteMobs.

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
level	inteiro	0	Nível do reforço. Com 0, a função de invocação determina o nível segundo o seu comportamento predefinido.
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 uma entidade de fogo de artifício com controlo completo dos seus efeitos.

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	nil	Lista de nomes de cores ou tabelas {red, green, blue}
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 tabela de referência de entidade. Pode chamar :detonate() para forçar a sua detonação imediata.

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

    -- Detonate immediately for a visual burst
    context.scheduler:run_after(1, function()
      fw:detonate()
    end)
  end
}

---

world:spawn_splash_potion_at_location(location, spec)

Gera uma entidade de poção arremessável lançada.

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	Se os efeitos existentes do mesmo tipo são substituídos

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 temporário que é restaurado automaticamente após a duração indicada.

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é restaurar o bloco (0 = permanente)
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)

Altera um bloco de forma permanente. Use place_temporary_block_at_location se quiser restaurá-lo mais tarde.

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 como cadeia de texto o nome do material do bloco numa 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 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 que não seja ar na posição X/Z indicada.

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 como número a resistência a explosões do bloco numa 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 true se o bloco na localização for transitável: as entidades podem atravessá-lo.

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 na localização não for sólido E o bloco imediatamente abaixo for sólido; ou seja, a localização está «sobre o chã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_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)

Define a hora do mundo. Pode passar uma localização opcional para indicar o mundo a alterar.

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)

Define o estado do tempo no mundo do chefe.

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)

Cria o efeito visual de uma explosão falsa através do sistema de regeneração de explosões do EliteMobs: os blocos partem-se e regeneram-se.

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 um comando de consola como o servidor.

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)

Executa a tarefa visual de relâmpago potenciado, usada pelos poderes do Ender Dragon. Produz um relâmpago mais intenso com efeitos adicionais.

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)

Gera um projétil de pepita de ouro falsa usado pelo sistema de chuva de projéteis.

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 com os métodos 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)

    context.world:spawn_fake_gold_nugget_at_location(
      context.boss:get_location(),
      { x = dir.x, y = dir.y, z = dir.z }
    )
  end
}

---

world:run_fake_gold_nugget_damage(projectiles)

Processa o dano de uma tabela de projéteis de pepitas de ouro falsas contra entidades próximas.

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)
    -- Spawn some projectiles and store them
    context.state.active_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 }
      )
      table.insert(context.state.active_projectiles, nugget)
    end

    -- Process damage each tick for 3 seconds
    local task_id
    task_id = context.scheduler:run_every(1, function(tick_context)
      tick_context.world:run_fake_gold_nugget_damage(tick_context.state.active_projectiles)
    end)
    context.scheduler:run_after(60, function(later_context)
      later_context.scheduler:cancel_task(task_id)
    end)
  end
}

---

world:generate_player_loot(times)

Gera saque para os jogadores que causaram dano ao 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 todos os jogadores que contribuíram para causar dano ao chefe.

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

Funções auxiliares de cálculo vetorial. São chamadas como funções normais, com um ponto, e não como métodos.

Método	Devolve	Notas
vectors.get_vector_between_locations(loc1, loc2[, options])	tabela de vetor	Direção de loc1 para loc2
vectors.normalize_vector(vec)	tabela de vetor	Devolve um vetor de comprimento unitário
vectors.rotate_vector(vec, pitch, yaw)	tabela de vetor	Roda um vetor pelos graus indicados de inclinação e orientação

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

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, 360, 30 do
  local dir = context.vectors.rotate_vector(base, 0, angle)
  -- Use dir for spawning projectiles in a ring
end

---

context.settings

Acesso só de leitura aos valores de configuração dos poderes.

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 para o hook atual. Os campos disponíveis dependem do hook que desencadeou a chamada.

Campo ou método	Quando está disponível	Notas
event.damage_amount	Hooks de dano	Quantidade de dano atual (valor capturado ao chamar o hook)
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	Tabela de referência da entidade atacante
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	on_death, eventos de zona	Tabela que representa a entidade correspondente

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 ao chamar o hook. Não é atualizado automaticamente depois de chamar set_damage_amount() ou multiply_damage_amount().
• Nas funções agendadas, context.event é nil. Use hooks de evento para modificar eventos.

---

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