Scripting Lua: Boss e Entidades
Esta página cobre tudo sobre os wrappers de boss e de entidades nos poderes Lua do EliteMobs: context.boss, context.player, context.players, context.entities e as tabelas de wrapper de entidade que eles devolvem. Se é novo nos poderes Lua, comece primeiro por Como começar.
Wrappers de entidade
Quando acede a entidades através da API Lua -- seja a partir de context.boss, context.player, resultados de consultas como context.players:nearby_players(), ou campos de eventos -- recebe sempre tabelas de wrapper. Estas não são objetos Bukkit em bruto. Cada wrapper fornece um conjunto de campos (valores de instantâneo capturados no momento da criação) e métodos (chamadas em tempo real que acedem ao servidor).
Esta página descreve os wrappers nativos dos poderes de boss do EliteMobs. Os auxiliares partilhados do MagmaCore, como context.world:get_entity(uuid), podem devolver outro wrapper com campos consultados em tempo real e assinaturas diferentes. Consulte a referência da API partilhada para esses wrappers. Os métodos nativos aceitam dois-pontos ou ponto sem um argumento self explícito. Atribuir um campo só altera a tabela Lua; use um método para alterar a entidade.
Duas regras a lembrar:
- Campos como
health,current_locationemaximum_healthsão instantâneos (snapshots). Refletem o estado no momento em que o wrapper foi criado e não se atualizam automaticamente. - Métodos como
get_location(),get_health()eis_alive()realizam uma verificação em tempo real cada vez que os chama.
Campos comuns de entidade
Cada wrapper de entidade viva inclui estes campos.
| Campo | Tipo | Notas |
|---|---|---|
entity.name | string | Nome de exibição |
entity.uuid | string | UUID como texto |
entity.entity_type | string | Nome do EntityType do Bukkit (por exemplo, "ZOMBIE", "PLAYER") |
entity.is_player | boolean | true para jogadores |
entity.is_elite | boolean | true se o EliteMobs o regista como um elite |
entity.is_mount | boolean | true se este wrapper representa uma montaria de boss |
entity.is_monster | boolean | true para entidades do tipo monstro |
entity.health | number | Vida atual (instantâneo) |
entity.maximum_health | number | Vida máxima (instantâneo) |
entity.current_location | tabela de localização | Posição no momento em que o wrapper foi criado |
entity.is_valid | boolean | Validade Bukkit quando o wrapper foi criado (instantâneo) |
is_valid é um campo em entidades vivas, não um métodoEm wrappers de entidades vivas (incluindo context.player e context.boss), is_valid é um simples booleano captado no momento em que o wrapper foi construído. Chamar entity:is_valid() gera attempt to call a boolean value e desativa o poder.
- Leia o instantâneo com
entity.is_valid(ponto). - Para uma verificação em tempo real, chame antes
entity:is_alive()-- essa consulta o servidor de cada vez.
is_valid() é um método real nos wrappers de referência mais leves para entidades não-vivas devolvidos por summon_projectile, spawn_falling_block_at_location e semelhantes. Esses são os wrappers que tem mais probabilidade de guardar entre ticks, e é aí que a verificação em tempo real importa.
Para ler dados específicos de elites, como o nível do boss, use os campos e métodos de context.boss descritos na secção context.boss abaixo. Para fazer desaparecer (despawn) um elite a partir de um script, chame o método entity:remove_elite().
Exemplo
return {
api_version = 1,
on_enter_combat = function(context)
context.log:info("Boss level: " .. context.boss.level)
end
}
Exemplo
return {
api_version = 1,
on_enter_combat = function(context)
local target = context.players:current_target()
if target ~= nil then
context.log:info("Target: " .. target.name .. " HP: " .. target.health)
end
end
}
Métodos comuns de entidade
Os métodos seguintes fazem chamadas em tempo real ao servidor. Movimento, vida, equipamento e efeitos pertencem aos wrappers de entidades vivas. Chat, barras de ação, títulos, barras de boss e comandos exigem um wrapper de jogador. context.boss:send_message(...) é um método distinto que envia mensagens aos jogadores próximos. Salvo quando está documentado um retorno, os métodos que alteram entidades devolvem nil, sem confirmação de sucesso.
As alterações de IA, perceção, invulnerabilidade e escala pertencem ao poder que as fez. Cada uma regista o valor que substituiu: uma duração positiva repõe esse valor após os ticks indicados, e fechar o script repõe qualquer alteração ainda ativa. Quando vários poderes alteram a mesma propriedade, terminar uma alteração repõe a alteração restante mais recente, ou o valor original quando já não resta nenhuma. Se outro plugin ou comando alterar a propriedade entretanto, o seu valor é mantido. Pausar o script não desfaz estas alterações. As durações das etiquetas, os impulsos adiados e as barras de boss dos jogadores usam tarefas independentes do relógio de jogo, que continuam a correr depois de o script fechar. As outras alterações nas entidades não são desfeitas.
entity:is_alive()
Devolve true se a entidade ainda for válida e não estiver morta.
Exemplo
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
if context.player:is_alive() then
context.player:send_message("&aYou're still standing!")
end
end
}
entity:get_location()
Devolve a localização atual em tempo real como uma tabela de localização.
Exemplo
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
local loc = context.player:get_location()
context.world:play_sound_at_location(loc, "entity.experience_orb.pickup")
end
}
entity:get_eye_location()
Devolve a localização ao nível dos olhos como uma tabela de localização.
Exemplo
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
local eye = context.player:get_eye_location()
context.world:spawn_particle_at_location(eye, "FLAME")
end
}
entity:get_health() / entity:get_maximum_health()
Devolve a vida atual ou máxima em tempo real.
Exemplo
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
local pct = context.player:get_health() / context.player:get_maximum_health()
if pct < 0.25 then
context.player:send_message("&cYou're running low!")
end
end
}
entity:get_velocity()
Devolve a velocidade atual da entidade como uma tabela de vetor.
Exemplo
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
local vel = context.player:get_velocity()
context.log:info("Player speed Y: " .. vel.y)
end
}
entity:send_message(text)
Envia uma mensagem de chat a um jogador. Suporta a formatação de cores do EliteMobs.
| Parâmetro | Tipo | Notas |
|---|---|---|
text | string | Mensagem com códigos de cor |
Exemplo
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
context.player:send_message("&6[Boss] &fPrepare yourself!")
end
}
entity:show_action_bar(message)
Envia uma mensagem à barra de ação de um jogador através da fonte Lua do EliteMobs. Participa no compositor de barras de ação, sem reservar a apresentação para este script.
| Parâmetro | Tipo | Notas |
|---|---|---|
message | string | Texto da barra de ação com códigos de cor |
Exemplo
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
context.player:show_action_bar("&c&lDANGER ZONE")
end
}
entity:show_title(title[, subtitle][, fadeIn][, stay][, fadeOut])
Envia um título e um subtítulo opcional a um jogador, com as cores do EliteMobs. Os tempos são números inteiros de ticks.
| Parâmetro | Tipo | Predefinição | Notas |
|---|---|---|---|
title | string | Texto do título | |
subtitle | string | "" | Texto do subtítulo |
fadeIn | number | 10 | Ticks de aparecimento gradual |
stay | number | 40 | Ticks de permanência |
fadeOut | number | 10 | Ticks de desaparecimento gradual |
Exemplo
return {
api_version = 1,
on_enter_combat = function(context)
local nearby = context.players:nearby_players(20)
for _, p in ipairs(nearby) do
p:show_title("&4PHASE 2", "&7The boss is enraged!", 10, 40, 10)
end
end
}
entity:show_boss_bar(title[, color][, style][, duration])
Cria uma nova barra de boss para um jogador através do gestor de ordem das barras. Os nomes de cor e estilo ignoram maiúsculas; valores desconhecidos usam WHITE e SOLID. Uma duração positiva agenda a remoção independente. Valores não positivos não adicionam temporizador, e o método não devolve referência nem chave para remover a barra depois. Use uma duração positiva. Esta assinatura difere da API partilhada do MagmaCore, que identifica as barras por chaves.
| Parâmetro | Tipo | Predefinição | Notas |
|---|---|---|---|
title | string | Texto do título da barra | |
color | string | "WHITE" | Valor de BarColor |
style | string | "SOLID" | Valor de BarStyle |
duration | number | 40 | Duração em ticks |
Exemplo
return {
api_version = 1,
on_enter_combat = function(context)
local nearby = context.players:nearby_players(20)
for _, p in ipairs(nearby) do
p:show_boss_bar("&cIncoming Attack!", "RED", "SOLID", 100)
end
end
}
entity:teleport_to_location(location)
Pede um teletransporte Bukkit e devolve nil, sem indicar se teve sucesso. A conversão nativa aceita x, y, z, yaw/pitch opcionais, o nome de um world carregado ou uma tabela current_location aninhada. Coordenadas em falta passam a 0; sem mundo explícito, usa o mundo do boss que executa o poder, não necessariamente o da entidade alvo. Um mundo explicitamente desconhecido faz falhar a conversão. nil ou um valor que não seja tabela usa a posição do boss. Não acrescenta verificações de destino seguro nem de proteção de regiões.
| Parâmetro | Tipo | Notas |
|---|---|---|
location | tabela de localização | Destino |
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("teleport_pull", 200) then return end
context.player:teleport_to_location(context.boss:get_location())
context.player:send_message("&cThe boss pulls you in!")
end
}
entity:set_velocity_vector(vector)
Define a velocidade da entidade de imediato.
| Parâmetro | Tipo | Notas |
|---|---|---|
vector | tabela de vetor | { x, y, z } ou { x = 0, y = 1, z = 0 } |
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("launch", 100) then return end
context.player:set_velocity_vector({ x = 0, y = 1.5, z = 0 })
context.player:send_message("&cYou are launched into the air!")
end
}
entity:apply_push_vector(vector[, additive][, delay])
Aplica uma velocidade capturada após um atraso de 1 tick por predefinição. O temporizador independente verifica se a entidade ainda é válida. Com additive = true, soma o vetor à velocidade no momento da execução; caso contrário, substitui-a. Pausar ou fechar o script não cancela o impulso.
| Parâmetro | Tipo | Predefinição | Notas |
|---|---|---|---|
vector | tabela de vetor | Direção e força | |
additive | boolean | false | Adicionar à velocidade existente em vez de substituir |
delay | number | 1 | Atraso em ticks antes de aplicar |
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("push_up", 100) then return end
context.player:apply_push_vector({ x = 0, y = 2.0, z = 0 })
context.player:send_message("&cUpward blast!")
end
}
entity:face_direction_or_location(directionOrLocation)
Orienta a entidade teletransportando-a para a posição atual com nova rotação. Uma tabela com um world do tipo string ou current_location aninhado é interpretada como destino, que deve estar no mundo da entidade. Uma tabela apenas com x/y/z é interpretada como vetor de direção. Direções nulas não alteram nada.
| Parâmetro | Tipo | Notas |
|---|---|---|
directionOrLocation | tabela de vetor ou de localização | Alvo para o qual se virar |
Exemplo
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
context.player:face_direction_or_location(context.boss:get_location())
context.player:send_message("&cThe boss forces you to look at it!")
end
}
entity:set_fire_ticks(ticks)
Define os ticks de fogo Bukkit. A política de efeitos de instância verifica novamente o alvo em cada chamada. Os jogadores devem estar ligados, vivos e no mundo de origem; numa instância, devem pertencer à partida ativa e à lista de participantes. Outros alvos vivos devem ser válidos. Isto não garante que o fogo cause dano.
| Parâmetro | Tipo | Notas |
|---|---|---|
ticks | number | Duração do fogo em ticks (20 ticks = 1 segundo) |
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("ignite", 100) then return end
context.player:set_fire_ticks(60)
context.player:send_message("&cYou catch fire!")
end
}
entity:add_visual_freeze_ticks([ticks])
Acrescenta ticks ao valor real de congelamento Bukkit, sujeito à mesma política de efeitos de instância que set_fire_ticks. Apesar do nome, não é apenas uma sobreposição enviada por pacotes nem suspende diretamente a IA ou o movimento. O comportamento normal de congelamento do Minecraft pode aplicar-se.
| Parâmetro | Tipo | Predefinição | Notas |
|---|---|---|---|
ticks | number | 1 | Quantidade de ticks de congelamento |
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("freeze", 200) then return end
context.player:add_visual_freeze_ticks(100)
context.player:send_message("&bYou feel a chilling frost!")
end
}
entity:apply_potion_effect(effect, duration[, amplifier])
Aplica um efeito de poção Bukkit depois da mesma verificação de instância que set_fire_ticks. Os nomes ignoram maiúsculas; nomes desconhecidos geram um aviso e não aplicam nada. Aplicam-se as regras de substituição do Bukkit, sem forçar a substituição de todos os efeitos existentes.
| Parâmetro | Tipo | Predefinição | Notas |
|---|---|---|---|
effect | string | Nome de PotionEffectType | |
duration | number | Duração em ticks | |
amplifier | number | 0 | Nível do efeito (0 = nível I) |
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("slow", 200) then return end
context.player:apply_potion_effect("SLOWNESS", 60, 1)
context.player:send_message("&7You feel sluggish...")
end
}
remove_potion_effect(effect) não está disponível nos wrappers nativos dos poderes de boss do EliteMobs. Existe nos wrappers partilhados do MagmaCore. Aplique os efeitos com uma duração adequada; aplicar outro efeito com duração zero não remove de forma fiável um efeito existente.
entity:deal_damage(amount) / entity:deal_custom_damage(amount) / entity:deal_damage_from_boss(amount)
Submete dano ao Bukkit. Os três métodos devolvem nil; o valor pedido não comprova a vida perdida. As regras de combate e listeners posteriores podem alterar ou cancelar o golpe.
| Método | Notas |
|---|---|
deal_damage(amount) | Chama o dano Bukkit sem atacante explícito |
deal_custom_damage(amount) | Usa BossCustomAttackDamage com o boss que executa o poder; rejeita golpes contra si próprio, alvos invulneráveis ou mortos e jogadores fora de Survival/Adventure, submete um golpe personalizado e depois limpa o cooldown de dano nativo |
deal_damage_from_boss(amount) | Chama o dano Bukkit com o boss como atacante; pode aplicar-se o processamento normal de combate do EliteMobs |
Exemplo
return {
api_version = 1,
on_enter_combat = function(context)
local nearby = context.players:nearby_players(10)
for _, p in ipairs(nearby) do
p:deal_custom_damage(10)
p:send_message("&cThe boss unleashes a shockwave!")
end
end
}
entity:restore_health(amount)
Para elites registados, chama a cura do EliteMobs e dispara o evento cancelável EliteMobHealEvent. Outras entidades vivas são curadas diretamente até ao valor base do atributo de vida máxima, que pode diferir do máximo efetivo devolvido por get_maximum_health(). Indique uma quantidade não negativa; este auxiliar não é uma API de dano que limite automaticamente os valores de entrada.
| Parâmetro | Tipo | Notas |
|---|---|---|
amount | number | Quantidade a curar |
Exemplo
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
-- Heal the player slightly when they hit the boss
context.player:restore_health(5)
context.player:send_message("&aYou drain life from the boss!")
end
}
entity:set_invulnerable(enabled[, duration])
Define a invulnerabilidade da entidade e regista o valor que substituiu. Uma duração positiva repõe esse valor após os ticks indicados; caso contrário, a alteração dura até este poder encerrar, o que também a repõe. Chamá-lo de novo a partir do mesmo poder substitui a alteração anterior desse poder.
| Parâmetro | Tipo | Predefinição | Notas |
|---|---|---|---|
enabled | boolean | true para ativar a invulnerabilidade | |
duration | number | 0 | Repõe o valor substituído após estes ticks; 0 mantém a alteração até o poder encerrar |
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("shield", 200) then return end
context.player:set_invulnerable(true, 40)
context.player:send_message("&6A brief shield protects you!")
end
}
entity:set_ai_enabled(enabled[, duration])
Define a IA da entidade e regista o valor que substituiu. Uma duração positiva repõe esse valor após os ticks indicados; caso contrário, a alteração dura até este poder encerrar, o que também a repõe. Chamar set_ai_enabled(true) enquanto este poder mantém uma alteração de IA termina essa alteração e repõe o valor substituído, em vez de aplicar uma nova.
| Parâmetro | Tipo | Predefinição | Notas |
|---|---|---|---|
enabled | boolean | true para ativar a IA | |
duration | number | 0 | Repõe o valor substituído após estes ticks; 0 mantém a alteração até o poder encerrar |
Exemplo
return {
api_version = 1,
on_enter_combat = function(context)
-- Disable boss AI for 3 seconds at combat start
context.boss:set_ai_enabled(false, 60)
context.boss:send_message("&7The boss is stunned!")
end
}
entity:add_tag(tag[, duration]) / entity:remove_tag(tag) / entity:has_tag(tag)
Gere etiquetas EliteMobs sensíveis a maiúsculas em elites registados e jogadores com dados de inventário EliteMobs carregados. Mobs normais não registados não guardam estas etiquetas. Não são etiquetas de scoreboard Bukkit. Uma duração positiva agenda uma remoção independente; voltar a adicionar a mesma etiqueta não cancela o temporizador anterior.
| Método | Parâmetro | Notas |
|---|---|---|
add_tag(tag[, duration]) | string, number opcional | Adiciona a etiqueta, opcionalmente removendo-a automaticamente após ticks |
remove_tag(tag) | string | Remove a etiqueta |
has_tag(tag) | string | Devolve true se a etiqueta estiver presente |
Exemplo
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
if not context.player:has_tag("marked") then
context.player:add_tag("marked", 200)
context.player:send_message("&cYou have been marked!")
end
end
}
entity:run_command(command)
Executa imediatamente um comando como o jogador, com as suas permissões. Use texto sem / inicial. Este método exclusivo de jogadores devolve nil, não indica o sucesso do comando nem substitui placeholders.
| Parâmetro | Tipo | Notas |
|---|---|---|
command | string | Texto do comando sem a / inicial |
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("curse_cmd", 200) then return end
context.player:run_command("say I have been cursed!")
end
}
entity:set_scale(scale[, duration])
Define o valor base do atributo de escala, quando disponível, e regista o valor que substituiu. Uma duração positiva repõe esse valor após os ticks indicados; caso contrário, a alteração dura até este poder encerrar, o que também a repõe. Modificadores de atributos podem alterar o tamanho efetivo.
| Parâmetro | Tipo | Predefinição | Notas |
|---|---|---|---|
scale | number | Multiplicador de escala | |
duration | number | 0 | Repõe a escala substituída após estes ticks; 0 mantém a alteração até o poder encerrar |
Exemplo
return {
api_version = 1,
on_enter_combat = function(context)
-- Boss grows to double size for 5 seconds
context.boss:set_scale(2.0, 100)
context.boss:send_message("&4The boss grows in size!")
end
}
entity:set_gravity(enabled)
Alterna a gravidade. Não há reposição automática quando o script fecha. Um callback adiado pertencente ao script pode nunca executar depois do fecho; não dependa dele para garantir a reposição em entidades que sobrevivam.
| Parâmetro | Tipo | Notas |
|---|---|---|
enabled | boolean | true para gravidade normal |
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("levitate", 200) then return end
-- Change the boss's gravity; the callback runs only while this script stays active.
context.boss:set_gravity(false)
context.scheduler:run_after(60, function(tick_context)
if tick_context.boss.exists then
tick_context.boss:set_gravity(true)
end
end)
end
}
entity:play_sound_at_entity(sound[, volume][, pitch])
Reproduz um som na localização da entidade.
| Parâmetro | Tipo | Predefinição | Notas |
|---|---|---|---|
sound | string | Chave de som Minecraft, como "entity.ender_dragon.growl", ou nome do enum Spigot Sound. As chaves de pacotes de recursos também funcionam. | |
volume | number | 1.0 | Volume |
pitch | number | 1.0 | Tom (pitch) |
Exemplo
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
context.player:play_sound_at_entity("entity.ender_dragon.growl", 1.0, 0.5)
end
}
entity:play_sound_at_self(sound[, volume][, pitch])
Alias para play_sound_at_entity. Reproduz um som na localização da entidade.
entity:spawn_particle_at_self(particleOrSpec[, count])
Gera partículas na localização atual da entidade. Usa a mesma especificação de partículas que o auxiliar nativo do mundo. O amount de uma tabela prevalece sobre o count alternativo; os nomes são convertidos para maiúsculas e partículas com dados não suportados geram um aviso em vez de aparecerem.
| Parâmetro | Tipo | Predefinição | Notas |
|---|---|---|---|
particleOrSpec | string ou tabela | Nome da partícula ou tabela de especificação | |
count | number | 1 | Número de partículas |
Exemplo
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
context.player:spawn_particle_at_self("HEART", 5)
end
}
entity:spawn_particles_at_location(location, particle[, count])
Faz surgir partículas numa localização específica.
| Parâmetro | Tipo | Predefinição | Notas |
|---|---|---|---|
location | tabela de localização | Localização alvo | |
particle | string | Nome do tipo de partícula | |
count | number | 1 | Número de partículas |
Exemplo
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
local loc = context.player:get_location()
context.player:spawn_particles_at_location(loc, "FLAME", 10)
end
}
entity:play_model_animation(name)
Pede uma animação apenas quando o EliteMobs regista a entidade como boss personalizado com modelo personalizado. Devolve nil; não espera pela conclusão nem indica se o nome da animação existe. Uma entidade genérica com modelo não basta para este auxiliar nativo.
| Parâmetro | Tipo | Notas |
|---|---|---|
name | string | Nome da animação |
Exemplo
return {
api_version = 1,
on_enter_combat = function(context)
context.boss:play_model_animation("attack_swing")
end
}
Métodos de veículo e passageiro
Os wrappers de entidades vivas também expõem auxiliares Bukkit de veículo e passageiro. Os wrappers recebidos são resolvidos pelo UUID Bukkit; strings de UUID diretamente não são aceites. Montar rejeita entidades ausentes, idênticas ou inválidas, ignora temporariamente a proteção EliteMobs contra abusos de montarias e devolve a aceitação Bukkit. Estes métodos não registam uma rota de transporte nem organizam a limpeza quando o script fecha.
| Método | Devolve | Notas |
|---|---|---|
entity:is_inside_vehicle() | boolean | True se a entidade estiver a montar outra entidade. |
entity:has_vehicle() | boolean | True se a entidade tiver atualmente um veículo. |
entity:get_vehicle() | wrapper de entidade ou nil | Devolve o wrapper do veículo atual. |
entity:set_vehicle(vehicle) | boolean | Faz esta entidade montar vehicle. |
entity:leave_vehicle() | boolean | Faz esta entidade abandonar o seu veículo atual. |
entity:has_passengers() | boolean | True se esta entidade tiver passageiros. |
entity:get_passenger_count() | number | Número de passageiros. |
entity:get_passengers() | table | Array de wrappers de passageiro. |
entity:add_passenger(passenger) | boolean | Adiciona um passageiro a esta entidade. |
entity:remove_passenger(passenger) | boolean | Remove um passageiro desta entidade. |
entity:eject_passengers() | boolean | Ejeta todos os passageiros. |
Exemplo
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
if context.player:has_vehicle() then
context.player:leave_vehicle()
end
end
}
entity:push_relative_to(source[, strength][, xOffset][, yOffset][, zOffset])
Substitui imediatamente a velocidade pelo deslocamento normalizado da origem até à entidade, multiplicado por strength, e soma os deslocamentos nos eixos do mundo. Posições coincidentes recebem na mesma os deslocamentos adicionais. Um wrapper fornece o seu current_location guardado; passe source:get_location() quando precisar da posição atual. O auxiliar não compara mundos, por isso use apenas posições do mesmo mundo.
| Parâmetro | Tipo | Predefinição | Notas |
|---|---|---|---|
source | localização ou wrapper | Origem do impulso | |
strength | number | 1.0 | Multiplicador da força do impulso |
xOffset | number | 0 | Deslocamento X adicional |
yOffset | number | 0 | Deslocamento Y adicional |
zOffset | number | 0 | Deslocamento Z adicional |
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("knockback", 60) then return end
context.player:push_relative_to(context.boss:get_location(), 2.0, 0, 0.5, 0)
context.player:send_message("&cThe boss knocks you back!")
end
}
entity:set_custom_name(name) / entity:reset_custom_name()
Define o nome personalizado Bukkit com formatação de cores. A reposição usa o nome configurado do elite registado; para uma entidade não registada, usa o seu getName() atual, sem restaurar um nome original guardado. Não altera o nome de conta do jogador nem o campo de instantâneo do wrapper.
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("mark", 200) then return end
context.boss:set_custom_name("&c&lEnraged Boss")
context.boss:send_message("&cThe boss is enraged!")
-- Reset after 5 seconds
context.scheduler:run_after(100, function(tick_context)
if tick_context.boss:is_alive() then
tick_context.boss:reset_custom_name()
end
end)
end
}
entity:place_temporary_block(material[, duration][, requireAir])
Coloca um bloco temporário na localização atual da entidade e devolve nil, mesmo quando requireAir impede a colocação. Com uma duração positiva, os dados guardados do bloco (não o conteúdo de recipientes) são restaurados quando o temporizador termina, quando o chunk ou o mundo é descarregado, ou quando o plugin desliga, mas só enquanto o bloco ainda contiver o bloco temporário. Colocar de novo sobre o mesmo bloco temporário reinicia o seu temporizador. Blocos com entidades de bloco, como baús, e blocos detidos por outro dono de blocos temporários são ignorados. Partir o bloco não larga nada. Uma duração não positiva coloca o bloco de forma permanente, sem registo. Use um material de bloco e verifique as proteções por sua conta.
| Parâmetro | Tipo | Predefinição | Notas |
|---|---|---|---|
material | string | Nome do material do bloco | |
duration | number | 0 | Ticks positivos até à reposição; valores não positivos colocam o bloco de forma permanente |
requireAir | boolean | false | Só coloca se o bloco for atualmente ar |
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("ice_trap", 200) then return end
context.player:place_temporary_block("ICE", 60, true)
context.player:send_message("&bIce forms at your feet!")
end
}
entity:get_height()
Devolve a altura da entidade em blocos.
entity:is_on_ground()
Devolve a flag atual isOnGround() do Bukkit. Não faz uma nova consulta de blocos nem de espaço livre acima.
entity.is_valid
Num wrapper de entidade viva, este campo booleano regista a validade Bukkit quando o wrapper foi criado. Leia-o com um ponto (entity.is_valid); chamá-lo como método dá erro.
Como se trata de um instantâneo, fica desatualizado, pelo que não substitui uma verificação em tempo real. Use entity:is_alive() quando precisar do estado atual, e is_valid() (o método) em wrappers de referência de entidades não-vivas que tenha guardado entre ticks.
entity:is_frozen()
Devolve true se a entidade (quando acompanhada como um boss personalizado) tiver a flag de congelado definida.
entity:set_awareness_enabled(aware[, duration])
Define a perceção do mob e regista o valor que substituiu. Só afeta entidades do tipo mob. Uma duração positiva repõe esse valor após os ticks indicados; caso contrário, a alteração dura até este poder encerrar, o que também a repõe. Chamá-lo com true enquanto este poder mantém uma alteração de perceção termina essa alteração, em vez de aplicar uma nova.
| Parâmetro | Tipo | Predefinição | Notas |
|---|---|---|---|
aware | boolean | true para ativar a perceção | |
duration | number | 0 | Repõe o valor substituído após estes ticks; 0 mantém a alteração até o poder encerrar |
entity:is_healing() / entity:set_healing(enabled)
Consulta ou define a flag de cura de um elite registado. Isto não recupera vida nem inicia um temporizador de cura. set_healing(true) marca o elite como em cura quando ainda não o está; set_healing(false) limpa apenas a cura que este poder definiu. Quando o poder encerra, limpa qualquer flag de cura que ainda lhe pertença. Entidades não registadas devolvem false na consulta e não são alteradas pela definição.
entity:overlaps_box_at_location(center[, halfX][, halfY][, halfZ])
Devolve true se a caixa delimitadora se sobrepuser à caixa numérica alinhada aos eixos. Não compara mundos; indique um centro no mundo da entidade. Um centro que não se consiga resolver devolve false.
| Parâmetro | Tipo | Predefinição | Notas |
|---|---|---|---|
center | tabela de localização | Centro da caixa de teste | |
halfX | number | 0.5 | Meia-largura no eixo X |
halfY | number | igual a halfX | Meia-altura no eixo Y |
halfZ | number | igual a halfX | Meia-largura no eixo Z |
entity:remove_elite()
Remove a entidade elite do acompanhamento do EliteMobs. Se a entidade for um elite, isto fá-lo desaparecer (despawn) corretamente através do EliteMobs.
entity:remove()
Remove uma entidade viva simples que um script fez aparecer, como um suporte de armadura. Devolve true quando é removida. Os jogadores e os elites são recusados com false; faça desaparecer os elites com remove_elite().
entity:set_invisible(enabled) e entity:set_silent(enabled)
set_invisible esconde o corpo da entidade; os itens vestidos e segurados continuam visíveis. set_silent silencia os sons da própria entidade.
entity:set_marker(enabled)
Apenas suportes de armadura. Estes quatro métodos existem nos wrappers de suportes de armadura e não existem em nenhuma outra entidade.
| Método | Efeito |
|---|---|
set_marker(enabled) | Um suporte marcador não tem hitbox e não pode ser atingido nem colidir com nada |
set_small(enabled) | Suporte de metade do tamanho |
set_base_plate(enabled) | Mostra ou esconde a base de pedra |
set_arms(enabled) | Mostra ou esconde os braços |
Para um item ou bloco flutuante puramente visual, prefira world:spawn_display_at_location, que não precisa de nenhum destes métodos.
entity:set_custom_name_visible(visible)
Define se o nome personalizado da entidade está sempre visível ou apenas quando se olha para ela.
| Parâmetro | Tipo | Notas |
|---|---|---|
visible | boolean | true para sempre visível |
entity:set_equipment(slot, material[, options])
Substitui o slot selecionado por um item novo do material indicado. Nomes de slot, material e encantamento ignoram maiúsculas. Slots ou materiais desconhecidos não alteram nada; encantamentos desconhecidos são ignorados, enquanto os reconhecidos usam níveis sem as restrições normais. Não carrega ficheiros de itens personalizados nem preserva os metadados do item anterior. Devolve nil.
| Parâmetro | Tipo | Predefinição | Notas |
|---|---|---|---|
slot | string | Slot de equipamento: "HEAD", "CHEST", "LEGS", "FEET", "HAND", "OFF_HAND" | |
material | string | Nome do material (por exemplo, "DIAMOND_SWORD", "IRON_HELMET") | |
options | table | {} | Definições opcionais (ver abaixo) |
Tabela de opções:
| Chave | Tipo | Predefinição | Notas |
|---|---|---|---|
enchantments | array de tabelas | nil | Cada entrada: { type = "SHARPNESS", level = 2 } |
unbreakable | boolean | false | Se o item é inquebrável |
Exemplo
return {
api_version = 1,
on_enter_combat = function(context)
-- Give the boss a glowing diamond sword
context.boss:set_equipment("HAND", "DIAMOND_SWORD", {
unbreakable = true,
enchantments = {
{ type = "SHARPNESS", level = 5 }
}
})
end
}
entity:damage_equipment(slot, amount)
Danifica o item em HAND, OFF_HAND, HEAD, CHEST, LEGS ou FEET e devolve o dano de durabilidade aplicado. Peça entre 1 e 64 pontos por chamada. Itens ausentes, não danificáveis ou inquebráveis devolvem 0.
Para jogadores, dispara PlayerItemDamageEvent e respeita o cancelamento ou a quantidade alterada. Um listener pode elevar o valor acima do limite inicial de 64 pontos; o resultado continua limitado pela durabilidade restante. Um item que atinja o dano máximo é removido do slot, incluindo toda a pilha, e dispara PlayerItemBreakEvent. Respeita os metadados de dano máximo personalizado. O método não calcula reduções de Unbreaking. Slots inválidos ou pedidos fora de 1..64 provocam um erro de argumento Lua.
entity:is_ai_enabled()
Devolve true se a IA da entidade estiver ativada. Para elites registados, consulta o estado lógico de IA do EliteMobs, incluindo a gestão do comportamento nativo, em vez de depender apenas da flag Bukkit subjacente.
Exemplo
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.boss:is_ai_enabled() then
context.log:info("Boss AI is active")
else
context.log:info("Boss AI is disabled (stunned?)")
end
end
}
Wrappers de referência de entidades não-vivas
Quando uma entidade gerada não é uma LivingEntity -- por exemplo, um bloco em queda, projétil ou bola de fogo -- recebe um wrapper de referência mais leve. Estes são devolvidos por métodos como context.world:spawn_falling_block_at_location() ou context.boss:summon_projectile().
Campos de instantâneo: name, uuid, entity_type, is_player (sempre false), is_elite (sempre false), is_mount (normalmente false; boss:get_mount() define-o como true), current_location.
Métodos:
| Método | Notas |
|---|---|
is_valid() | Verificação de validade em tempo real. Nestes wrappers é um método, ao contrário dos wrappers de entidades vivas |
get_location() | Localização atual em tempo real |
get_velocity() | Vetor de velocidade atual |
is_on_ground() | Se está no chão |
teleport_to_location(location) | Teletransporta a entidade |
set_velocity_vector(vector) | Define a velocidade |
set_direction_vector(vector) | Define a direção (apenas Fireball) |
set_yield(value) | Define o rendimento (yield) da explosão (apenas Fireball) |
set_gravity(enabled) | Alterna a gravidade |
detonate() | Pede a detonação de fogos de artifício; sem efeito noutros tipos |
remove() | Remove a entidade do mundo |
unregister([reason]) | Executa a remoção pelo rastreador EliteMobs para entidades registadas reconhecidas; uma entidade não registada fica inalterada |
Estes wrappers também fornecem todos os métodos de veículo e passageiro, incluindo is_inside_vehicle(), get_vehicle(), set_vehicle(v), add_passenger(p) e eject_passengers(). Permitem, por exemplo, montar um boss numa entidade não viva.
unregister aceita um nome de motivo de remoção sem distinguir maiúsculas e usa OTHER por predefinição; não é uma consulta booleana de sucesso. Os métodos guardam a referência à entidade subjacente, por isso verifique is_valid() antes de usar uma referência guardada. Uma remoção adiada pela instância Lua é cancelada se a instância fechar. Use uma duração nativa adequada ou o registo com o proprietário quando a limpeza deva sobreviver ao script.
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", 100) then return end
local fb = context.boss:summon_projectile("FIREBALL",
context.boss:get_eye_location(),
context.player:get_location(),
1.5
)
if fb == nil then return end
-- fb is a non-living reference wrapper; remove it after 5 seconds if still alive
context.scheduler:run_after(100, function()
if fb:is_valid() then
fb:remove()
end
end)
end
}
context.player
Disponível quando o alvo direto ou o ator do evento é um jogador, incluindo on_boss_damaged_by_player e on_player_damaged_by_boss. Os wrappers de jogador incluem os métodos comuns de entidades vivas, mas os que exigem um elite registado ou boss personalizado não afetam um jogador normal. Os extras abaixo são exclusivos de jogadores.
context.player é nil em hooks que não têm um jogador associado, como on_spawn, callbacks agendados e hooks de temporizador. Verifique sempre se é nil antes de usar.
Exemplo
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
context.player:send_message("&cHello!")
end
}
Campos exclusivos do jogador
| Campo | Tipo | Notas |
|---|---|---|
game_mode | string | Instantâneo do modo de jogo em maiúsculas (por exemplo, "SURVIVAL") |
Métodos exclusivos do jogador
| Método | Notas |
|---|---|
send_message(message) | Mensagem de chat com formatação de cores do EliteMobs |
show_action_bar(message) | Texto da barra de ação |
show_title(title[, subtitle][, fadeIn][, stay][, fadeOut]) | Sobreposição no ecrã de título |
show_boss_bar(title[, color][, style][, duration]) | Barra de boss temporária |
run_command(command) | Executar um comando como o jogador (sem a / inicial) |
Exemplo
return {
api_version = 1,
on_player_damaged_by_boss = function(context)
if context.player == nil then return end
local hp_pct = context.player:get_health() / context.player:get_maximum_health()
if hp_pct < 0.3 then
context.player:show_title("&4LOW HEALTH", "&7Find cover!", 5, 30, 10)
context.player:show_boss_bar("&cBoss Enrage Incoming", "RED", "SEGMENTED_6", 80)
end
end
}
context.boss
O wrapper de boss para o elite mob que possui este poder Lua. Está sempre disponível em todos os hooks.
Enquanto existir uma entidade viva subjacente, o wrapper do boss herda os métodos comuns de entidades vivas, incluindo push_relative_to, apply_push_vector, set_gravity, set_scale, set_invulnerable, spawn_particle_at_self e overlaps_box_at_location. Não herda a interface nem os comandos exclusivos de jogadores. Os métodos abaixo são específicos do boss ou usam a camada EliteEntity. Se faltar a entidade subjacente, a tabela continua a existir, mas não se garante o conjunto completo de métodos herdados.
Campos do boss
| Campo | Tipo | Notas |
|---|---|---|
boss.name | string | Nome de exibição |
boss.uuid | string | UUID do elite (boss) |
boss.entity_type | string | Nome do EntityType do Bukkit |
boss.is_monster | boolean | true se a entidade subjacente for um Monster |
boss.level | number | Nível do elite |
boss.health | number | Vida atual (instantâneo) |
boss.maximum_health | number | Vida máxima (instantâneo) |
boss.damager_count | number | Número de causadores de dano (instantâneo) |
boss.is_in_combat | boolean | Instantâneo do estado de combate |
boss.exists | boolean | Se o elite existia quando esta tabela foi construída |
boss.current_location | tabela de localização | Posição na criação do wrapper (instantâneo) |
Exemplo
return {
api_version = 1,
on_spawn = function(context)
context.log:info(context.boss.name .. " level " .. context.boss.level)
end
}
Métodos do boss
Métodos de movimento de patrulha
Chefes com uma patrulha configurada expõem patrol_pause(), patrol_resume(), walk_to(x, y, z), hold(x, y, z) e teleport(x, y, z). As coordenadas são deslocamentos desde o local de aparecimento e cada método devolve se o pedido foi aceito. walk_to retoma a rota ao chegar; hold espera por patrol_resume(); trajetos longos usam o solucionador automático.
boss:is_alive()
Devolve true se a entidade do boss for válida, não estiver morta e o elite ainda existir. Use isto em vez do campo exists para verificações em tempo real.
Exemplo
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if not context.boss:is_alive() then return end
context.boss:send_message("&cI still live!")
end
}
boss:get_location()
Devolve a localização atual do boss em tempo real como uma tabela de localização.
Exemplo
return {
api_version = 1,
on_enter_combat = function(context)
local loc = context.boss:get_location()
context.world:spawn_particle_at_location(loc, "FLAME")
end
}
boss:get_eye_location()
Devolve a localização do boss ao nível dos olhos.
Exemplo
return {
api_version = 1,
on_enter_combat = function(context)
local eye = context.boss:get_eye_location()
context.world:spawn_particle_at_location(eye, "SMOKE")
end
}
boss:set_ai_enabled(enabled[, duration])
Define a IA do boss com as mesmas regras de alterações próprias de entity:set_ai_enabled: uma duração positiva repõe o valor substituído, e fechar o poder repõe qualquer alteração ainda ativa.
| Parâmetro | Tipo | Predefinição | Notas |
|---|---|---|---|
enabled | boolean | true para ativar a IA | |
duration | number | 0 | Repõe o valor substituído após estes ticks; 0 mantém a alteração até o poder encerrar |
Exemplo
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if not context.cooldowns:check_local("stun", 200) then return end
context.boss:set_ai_enabled(false, 60)
context.boss:send_message("&7The boss is stunned for 3 seconds!")
end
}
boss:teleport_to_location(location)
Pede um teletransporte Bukkit com as regras nativas de conversão descritas acima. Devolve nil, sem confirmação de sucesso. Não altera a localização de aparecimento configurada nem define um destino de patrulha.
| Parâmetro | Tipo | Notas |
|---|---|---|
location | tabela de localização | Destino |
Exemplo
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if not context.cooldowns:check_local("retreat", 300) then return end
local spawn = context.entities:get_boss_spawn_location()
context.boss:teleport_to_location(spawn)
context.boss:send_message("&7The boss retreats to its lair!")
end
}
boss:set_velocity_vector(vector)
Define a velocidade do boss de imediato.
| Parâmetro | Tipo | Notas |
|---|---|---|
vector | tabela de vetor | { x, y, z } ou { x = 0, y = 1, z = 0 } |
Exemplo
return {
api_version = 1,
on_enter_combat = function(context)
-- Boss leaps into the air at combat start
context.boss:set_velocity_vector({ x = 0, y = 2.0, z = 0 })
context.boss:send_message("&cThe boss leaps!")
end
}
boss:restore_health(amount)
Chama a cura EliteMobs, que dispara o evento cancelável EliteMobHealEvent e limita a vida ao menor valor entre o máximo EliteMobs e o valor base do atributo de vida máxima Bukkit. Devolve nil; o cancelamento pode impedir a cura.
| Parâmetro | Tipo | Notas |
|---|---|---|
amount | number | Quantidade a curar |
Exemplo
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if not context.cooldowns:check_local("heal", 200) then return end
context.boss:restore_health(20)
context.boss:send_message("&aThe boss regenerates!")
context.boss:spawn_particle_at_self("HEART")
end
}
boss:play_sound_at_self(sound[, volume][, pitch])
Reproduz um som na localização do boss.
| Parâmetro | Tipo | Predefinição | Notas |
|---|---|---|---|
sound | string | Chave de som Minecraft, como "entity.wither.spawn", ou nome do enum Spigot Sound. As chaves de pacotes de recursos também funcionam. | |
volume | number | 1.0 | Volume |
pitch | number | 1.0 | Tom (pitch) |
Exemplo
return {
api_version = 1,
on_spawn = function(context)
context.boss:play_sound_at_self("entity.wither.spawn", 1.0, 0.8)
end
}
boss:spawn_particle_at_self(particleOrSpec[, count])
Faz surgir partículas na localização do boss.
| Parâmetro | Tipo | Predefinição | Notas |
|---|---|---|---|
particleOrSpec | string ou tabela | Nome da partícula ou tabela de especificação | |
count | number | 1 | Número de partículas |
Exemplo
return {
api_version = 1,
on_enter_combat = function(context)
context.boss:spawn_particle_at_self("SMOKE", 20)
context.boss:send_message("&8Smoke billows from the boss!")
end
}
boss:play_model_animation(name)
Reproduz uma animação de modelo personalizado no boss, se disponível.
| Parâmetro | Tipo | Notas |
|---|---|---|
name | string | Nome da animação |
Exemplo
return {
api_version = 1,
on_enter_combat = function(context)
context.boss:play_model_animation("slam")
end
}
boss:has_mount() / boss:get_mount()
Verifica ou devolve a entidade que este boss está atualmente a montar. boss:get_mount() devolve nil se o boss não tiver montaria. Quando uma montaria é devolvida, o seu wrapper tem is_mount = true.
Exemplo
return {
api_version = 1,
on_enter_combat = function(context)
local mount = context.boss:get_mount()
if mount ~= nil then
context.log:info("Boss is mounted on " .. mount.entity_type)
end
end
}
boss:set_mount(entity) / boss:clear_mount() / boss:dismount()
Monta ou desmonta o boss. boss:set_mount(entity) faz o boss montar o wrapper de entidade fornecido e devolve true se o Bukkit aceitar a alteração de passageiro. boss:clear_mount() e boss:dismount() fazem ambos o boss abandonar o seu veículo atual.
Exemplo
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if not context.cooldowns:check_local("mount_check", 100) then return end
if context.boss:has_mount() then
context.boss:dismount()
end
end
}
boss:face_direction_or_location(vectorOrLocation)
Faz o boss virar-se para uma direção ou localização.
| Parâmetro | Tipo | Notas |
|---|---|---|
vectorOrLocation | tabela de vetor ou de localização | Direção para a qual se virar |
Exemplo
return {
api_version = 1,
on_boss_damaged_by_player = function(context)
if context.player == nil then return end
context.boss:face_direction_or_location(context.player:get_location())
end
}
boss:navigate_to_location(location[, speed][, forceTeleport][, timeout])
Usa a procura de caminhos para fazer o boss caminhar até uma localização. Só funciona com bosses personalizados.
| Parâmetro | Tipo | Predefinição | Notas |
|---|---|---|---|
location | tabela de localização | Destino | |
speed | number | 1.0 | Multiplicador da velocidade de movimento |
forceTeleport | boolean | false | Teletransporta o boss para o destino se timeout terminar antes da chegada |
timeout | number | 0 | Tempo máximo em ticks. 0 usa o valor predefinido de 100 ticks (5 segundos) |
A navegação também termina quando o boss está a menos de um bloco do destino, deixa de existir ou sai do mundo de destino. Iniciar uma nova navegação cancela a que já estivesse ativa nesse boss. Usa uma tarefa Bukkit independente; pausar ou fechar Lua não a cancela. O método devolve nil, não um resultado de chegada, e captura o destino no momento da chamada.
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("charge", 200) then return end
context.boss:navigate_to_location(context.player:get_location(), 1.5)
context.boss:send_message("&cThe boss charges at you!")
end
}
boss:add_tag(tag[, duration]) / boss:remove_tag(tag) / boss:has_tag(tag)
Gere etiquetas (tags) no boss.
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("phase2") then
context.boss:add_tag("phase2")
context.boss:send_message("&4Entering Phase 2!")
end
end
}
boss:send_message(message[, range])
Envia uma mensagem de chat formatada a todos os jogadores no raio esférico 3D do boss, no seu mundo. Não filtra por modo de jogo, linha de visão, participação no combate ou pertença a uma instância.
| Parâmetro | Tipo | Predefinição | Notas |
|---|---|---|---|
message | string | Texto da mensagem com códigos de cor | |
range | number | 20 | Raio em blocos |
Exemplo
return {
api_version = 1,
on_enter_combat = function(context)
context.boss:send_message("&4You dare challenge me?!")
end
}
boss:summon_projectile(entityType, origin, destination[, speed][, options])
Cria uma entidade e devolve o seu wrapper nativo, ou nil se uma posição não puder ser resolvida ou o tipo for desconhecido. Tipos reconhecidos que não podem ser gerados ainda podem falhar. Projéteis Bukkit normais partem do boss, salvo com spawn_at_origin = true; a origem fornecida continua a determinar a direção para o destino. Mantenha ambas as posições no mesmo mundo, pois o auxiliar não o verifica. Outros tipos surgem na origem indicada e usam o wrapper adequado de entidade viva ou não viva.
| Parâmetro | Tipo | Predefinição | Notas |
|---|---|---|---|
entityType | string | Tipo de entidade (por exemplo, "FIREBALL", "ARROW") | |
origin | tabela de localização | Posição de lançamento | |
destination | tabela de localização | Posição alvo | |
speed | number | 1.0 | Velocidade do projétil |
options | table | {} | Ver opções abaixo |
Tabela de opções:
| Chave | Tipo | Notas |
|---|---|---|
duration | number | Valores positivos agendam uma remoção independente após estes ticks; valores não positivos não adicionam temporizador |
max_ticks | number | Limite do monitor de aterragem; predefinição 6000 |
custom_damage | number | Metadados de dano personalizado para o combate do projétil, sem garantir a vida perdida |
detonation_power | string | Nome de ficheiro de poder usado como metadado de projétil explosivo, não uma força numérica de explosão |
yield | number | Rendimento (yield) da explosão (Fireball) |
persistent | boolean | Define a persistência Bukkit quando indicado; não anula a duração, colisões ou remoção pelo proprietário |
effect | string | Nome de EntityEffect a reproduzir ao surgir |
incendiary | boolean | Se a explosão é incendiária |
gravity | boolean | Se o projétil tem gravidade |
glowing | boolean | Efeito de brilho |
invulnerable | boolean | Se o projétil é invulnerável |
track | boolean | Predefinição true: regista o projétil no EliteMobs; não o faz perseguir o alvo. |
spawn_at_origin | boolean | Predefinição false: os projéteis normais partem do boss. Use true para os criar na origem indicada. |
direction_only | boolean | Para bolas de fogo geradas numa origem explícita, define a direção sem atribuição adicional de velocidade |
on_land | function | Callback (landing_location, spawned_entity) ao tocar no chão, ficar inválido ou ultrapassar max_ticks; não é exclusivo de impactos |
direction_only afeta bolas de fogo geradas explicitamente na origem fornecida; omite a atribuição adicional de velocidade depois de definir a direção. O destino continua a determinar essa direção. Os projéteis Bukkit recebem o boss como atirador. Com track = true, o projétil é registado no EliteMobs e fica ligado ao ciclo de vida dos reforços do boss. Isto não se aplica a tipos que não sejam projéteis. track = false desativa essa limpeza pelo proprietário; organize outra forma de remoção.
O monitor on_land pertence à instância Lua e termina quando esta fecha. Chama uma vez (landing_location, spawned_entity) ao tocar no chão, ficar inválido ou exceder o contador, sem remover a entidade por si próprio. O temporizador de duration positiva é independente e continua depois do fecho. O callback não comprova que o projétil tenha atingido algo.
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", 100) then return end
context.boss:summon_projectile(
"FIREBALL",
context.boss:get_eye_location(),
context.player:get_location(),
1.5,
{
custom_damage = 10,
on_land = function(loc, entity)
context.world:spawn_particle_at_location(loc, "EXPLOSION")
end
}
)
end
}
boss:summon_reinforcement(filename[, zoneOrLocation][, duration])
Invoca silenciosamente um reforço de um ficheiro de boss personalizado, regista o invocador e herda combate normalizado se o boss invocador o usar. A configuração própria do reforço e as regras de nível dinâmico determinam o seu nível. Uma zona escolhe uma localização amostrada aleatória, ou o centro se não existirem localizações. Um resultado não resolvido usa a localização do boss. Devolve o wrapper de entidade viva, ou nil se não foi produzido um reforço vivo.
| Parâmetro | Tipo | Notas |
|---|---|---|
filename | string | Nome do ficheiro de configuração do boss |
zoneOrLocation | tabela de localização ou zona | Localização de spawn ou definição de zona opcional. Por predefinição, a localização do boss. |
duration | number | Tempo positivo opcional até à fuga, em ticks. A predefinição 0 não adiciona temporizador; isto não altera o nível. |
Exemplo
return {
api_version = 1,
on_enter_combat = function(context)
context.boss:summon_reinforcement("my_minion.yml", context.boss:get_location(), 0)
context.boss:send_message("&cMinions, come to my aid!")
end
}
boss:despawn()
Remove o boss através do EliteMobs com o motivo OTHER. boss:remove() é um alias com o mesmo ciclo de remoção. Não é um golpe nem um pedido normal de recompensas de morte.
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.1 then
context.boss:send_message("&7The boss vanishes into thin air!")
context.boss:despawn()
end
end
}
boss:get_nearby_players(range)
Devolve wrappers de jogadores no raio esférico 3D no mundo do boss. Não filtra por modo de jogo, linha de visão ou participação numa instância, nem ordena por distância.
| Parâmetro | Tipo | Notas |
|---|---|---|
range | number | Raio em blocos |
Exemplo
return {
api_version = 1,
on_enter_combat = function(context)
local players = context.boss:get_nearby_players(30)
for _, p in ipairs(players) do
p:show_action_bar("&cThe boss sees you!")
end
end
}
boss:get_damager_count()
Devolve o tamanho atual do registo de atacantes do boss. Ao contrário de damager_count, é uma leitura em tempo real; não conta apenas participantes próximos ou atualmente ligados.
boss:get_nearby_elites(radius)
Devolve até 32 elites vivos registados no mundo do boss, excluindo o próprio boss. O raio deve ser finito, superior a 0 e de, no máximo, 64 blocos. Os resultados usam wrappers de entidades vivas e são ordenados por distância, com o UUID do elite para desempatar. Esta consulta não determina por si só se um efeito pode atingir todos os resultados.
boss:get_target_player()
Devolve o alvo atual do mob (boss) como um wrapper de jogador, ou nil se o alvo não for um jogador ou não estiver definido.
Métodos de zona e partículas
Estes métodos combinam zonas com efeitos de partículas. Requerem uma tabela de zona como entrada.
boss:get_nearby_players_in_zone(zone)
Devolve wrappers de jogadores cujas entidades cumprem a forma de zona nativa no mundo do boss. Não filtra por modo de jogo nem participação numa instância. É uma consulta nova, não um monitor persistente.
| Parâmetro | Tipo | Notas |
|---|---|---|
zone | tabela de zona | Uma definição de forma de zona |
boss:spawn_particles_in_zone(zone, particle[, amount][, x][, y][, z][, speed][, coverage])
Preenche o interior de uma zona com partículas. Os argumentos são posicionais; este método não aceita uma tabela de especificação.
| Parâmetro | Tipo | Predefinição | Notas |
|---|---|---|---|
zone | tabela de zona | Forma nativa com kind; consulte Zonas e seleção de alvos | |
particle | string | Nome do tipo de partícula | |
amount | number | 1 | Partículas por localização amostrada |
x, y, z | number | 0 | Dispersão, ou direção quando amount é 0 |
speed | number | 0 | Velocidade das partículas |
coverage | number | 1.0 | Probabilidade independente de amostragem por localização, limitada a 0.01–1.0; um conjunto não vazio contribui com pelo menos uma localização |
boss:spawn_particles_in_zone_border(zone, particle[, amount][, x][, y][, z][, speed][, coverage])
Igual ao método anterior, mas amostra a borda da zona em vez do interior.
boss:get_particles_from_self_toward_zone(zone, particle[, speed])
Devolve especificações de partículas situadas nas posições amostradas da zona e orientadas para longe do boss. Não gera partículas no boss nem anima o percurso desde ele. Passe o resultado a boss:spawn_particles_with_vector(...).
| Parâmetro | Tipo | Predefinição | Notas |
|---|---|---|---|
zone | tabela de zona | Zona alvo | |
particle | string | Nome do tipo de partícula | |
speed | number | 0.1 | Velocidade de viagem escrita em cada especificação |
Cada entrada tem a forma { location = ..., particle = ..., amount = 0, x/y/z = <unit direction>, speed = ... }. Cada posição tem 20 % de probabilidade de seleção, com pelo menos uma escolhida de um conjunto não vazio; depois são ignoradas as posições coincidentes com o boss. O comportamento direcional real depende do tipo de partícula.
boss:get_particles_toward_self(zone, particle, speed)
Faz o mesmo com a direção invertida; cada partícula aponta da sua localização na zona para o boss. Também devolve o array em vez de gerar as partículas.
| Parâmetro | Tipo | Predefinição | Notas |
|---|---|---|---|
zone | tabela de zona | Zona de origem | |
particle | string | Nome do tipo de partícula | |
speed | number | Indique um valor explícito, como 0.1; se o omitir, o método tenta ler o nome da partícula como número e falha. |
boss:spawn_particles_with_vector(particles)
Faz surgir um array de partículas direcionais, cada uma com a sua própria posição e vetor de velocidade.
| Parâmetro | Tipo | Notas |
|---|---|---|
particles | array de tabelas | Cada entrada define uma partícula com posição e direção |
Métodos do Ender Dragon
Estes métodos só se aplicam quando a entidade do boss é um Ender Dragon.
boss:get_ender_dragon_phase()
Devolve o nome da EnderDragon.Phase atual como uma string, ou nil se o boss não for um Ender Dragon.
boss:set_ender_dragon_phase(phase)
Define a fase do Ender Dragon.
| Parâmetro | Tipo | Notas |
|---|---|---|
phase | string | Nome de EnderDragon.Phase (por exemplo, "CIRCLING", "CHARGE_PLAYER") |
Métodos de suporte a poderes especiais
Estes métodos suportam mecânicas de poderes incorporadas no EliteMobs a partir de scripts Lua.
boss:start_tracking_fireball_system(speed?)
Inicia um controlador para este poder num boss do tipo monstro. Na primeira execução, no tick seguinte, e depois a cada 8 segundos, lança bolas de fogo de perseguição contra jogadores Survival e Adventure a 20 blocos ou menos em cada eixo, enquanto o monstro tiver um alvo. Uma execução sem alvo termina o controlador, incluindo a primeira; outra chamada pode reiniciá-lo. Chamadas repetidas enquanto está ativo não alteram a velocidade. O controlador pertence ao script do poder: pausar o script pausa-o, e fechar o script termina-o. Quando a chamada inicia um controlador, a velocidade tem de ser finita e positiva, caso contrário a chamada gera um erro.
As bolas têm potência de explosão 3 e são incendiárias. A tarefa de perseguição de cada bola é independente do script. Termina após cerca de 3 minutos ou um contexto inválido, mas terminar essa tarefa não remove a bola por si só. Um golpe não cancelado numa bola registada alterna a perseguição entre jogador e invocador.
| Parâmetro | Tipo | Predefinição | Notas |
|---|---|---|---|
speed | number | 0.5 | Velocidade da bola de fogo; tem de ser finita e positiva |
boss:handle_spirit_walk_damage(cause)
Passa uma causa de dano ao auxiliar Spirit Walk. Fogo, ticks de fogo, veneno, wither, espinhos e ataques de varrimento não avançam o contador. Afogamento e sufocação iniciam uma fuga imediata; outras causas aceites iniciam-na a cada nono golpe. O auxiliar procura um destino válido próximo e anima o movimento com invulnerabilidade temporária. Não cancela o evento de dano fornecido nem garante uma posição atrás do atacante.
| Parâmetro | Tipo | Notas |
|---|---|---|
cause | string | Nome de DamageCause do Bukkit (por exemplo, "ENTITY_ATTACK", "PROJECTILE") |
boss:shield_wall_is_active()
Devolve a flag de atividade do controlador de escudo. Não garante que uma direção concreta ainda tenha uma reserva positiva.
boss:initialize_shield_wall(openingDirection?)
Inicializa reservas direcionais e efeitos visuais, salvo se já houver uma parede ativa. Cada direção protegida começa com vida igual ao nível do boss. O argumento escolhe a abertura desprotegida, não um número de cargas. O método Lua devolve nil e não instala um handler de eventos de dano.
| Parâmetro | Tipo | Predefinição | Notas |
|---|---|---|---|
openingDirection | number | 1 | 1 = norte, 2 = este, 3 = sul, 4 = oeste; outros inteiros deixam os quatro lados protegidos |
boss:shield_wall_absorb_damage(player, damage)
Verifica a posição do atacante em relação ao boss e subtrai o dano da reserva dessa direção. Devolve true se a reserva era positiva antes da subtração, mesmo que o golpe exceda o valor restante. Devolve false se faltar jogador ou estado, se o mundo for diferente ou se a direção estiver aberta ou esgotada. Não cancela o evento de dano. Quando devolve true, o seu hook deve chamar context.event.cancel_event() para bloquear o golpe. Passe uma quantidade de dano não negativa.
| Parâmetro | Tipo | Notas |
|---|---|---|
player | wrapper de jogador | O jogador atacante |
damage | number | Quantidade de dano a absorver |
boss:deactivate_shield_wall()
Termina a tarefa visual independente da parede e remove o estado e os suportes de armadura dos escudos. Fechar a instância Lua não chama este método; desative explicitamente a parede quando a mecânica terminar.
boss:start_zombie_necronomicon(target, chant)
Inicia o controlador Necronomicon com um alvo vivo e um cântico deslizante. O segundo argumento é texto de apresentação, não um ficheiro de boss. Invoca os ficheiros fixos necronomicon_zombie.yml com 80 % de probabilidade e necronomicon_skeleton.yml com 20 %, ao nível do invocador, um a cada 60 ticks. Uma nova ativação só é aceite com, no máximo, nove reforços registados e sem controlador ativo. O controlador em execução preenche até onze, ativa a IA enquanto está cheio e retoma a invocação quando o número baixa.
A invocação desativa a IA do boss e altera o nome apresentado; os avisos visuais respeitam a definição de efeitos de aviso. O alvo deve continuar válido, no mesmo mundo e a, no máximo, 30 blocos. Um contexto inválido ou a remoção do proprietário termina os controladores, restaura a apresentação e elimina os seus reforços. São tarefas Bukkit independentes; fechar Lua por si só não as termina. O método devolve nil.
| Parâmetro | Tipo | Notas |
|---|---|---|
target | wrapper de entidade | Entidade alvo para o necronomicon |
chant | string | Texto de apresentação deslizante; se estiver vazio, usa o nome do boss, e se for curto, acrescenta preenchimento |
context.players
Auxiliares de consulta de jogadores centrados no boss. Use estes para encontrar jogadores sem precisar de um jogador específico do evento.
Estas consultas não filtram por modo de jogo, linha de visão, estado vivo, participação no combate ou pertença a uma instância, nem ordenam por distância. current_target() dá prioridade ao ator do evento, ao contrário da prioridade do alvo direto em context.player. Um contexto agendado novo não tem ator de evento e recorre ao alvo atual do mob.
| Método | Devolve | Notas |
|---|---|---|
players:current_target() | wrapper de jogador ou nil | O jogador do evento ou o alvo do mob (boss) se for um jogador |
players:nearby_players(radius) | array de wrappers de jogador | Todos os jogadores dentro do raio do boss |
players:all_players_in_world() | array de wrappers de jogador | Todos os jogadores no mundo do boss |
Exemplo
return {
api_version = 1,
on_enter_combat = function(context)
local nearby = context.players:nearby_players(20)
for _, player in ipairs(nearby) do
player:send_message("&cThe boss is enraged!")
player:apply_potion_effect("GLOWING", 60, 0)
end
end
}
Exemplo
return {
api_version = 1,
on_spawn = function(context)
-- Warn everyone in the world
local everyone = context.players:all_players_in_world()
for _, p in ipairs(everyone) do
p:show_title("&4WARNING", "&7A world boss has spawned!", 10, 60, 20)
end
end
}
context.entities
Auxiliares gerais de consulta de entidades centrados no boss.
| Método | Devolve | Notas |
|---|---|---|
entities:get_nearby_entities(radius[, filter]) | array de wrappers de entidade | Entidades próximas em torno do boss |
entities:get_entities_in_box(center, halfX, halfY, halfZ[, filter]) | array de wrappers de entidade | Entidades vivas cujos pés estão nos limites inclusivos da caixa, no mundo do centro; não testa a sobreposição de caixas delimitadoras |
entities:get_all_entities([filter]) | array de wrappers de entidade | Todas as entidades correspondentes no mundo do boss |
entities:get_direct_target_entity() | wrapper de entidade ou nil | Alvo direto para o evento atual |
entities:get_boss_spawn_location() | tabela de localização | A localização de spawn original do boss |
Filtros válidos: living (predefinição), player / players, elite / elites, mob / mobs, all / entities
Só get_nearby_entities respeita all / entities. Inclui entidades não vivas, como itens no chão e projéteis, devolvidas como wrappers de referência mais leves. Os resultados vivos continuam a usar os wrappers completos. Este filtro pesquisa uma caixa alinhada aos eixos com o raio indicado em cada eixo; os filtros de entidades vivas usam distância esférica. Noutras consultas, all / entities recorre a living. O próprio boss fica excluído de todos os resultados.
Os filtros ignoram maiúsculas; filtros desconhecidos também usam living. mob significa qualquer entidade viva que não seja jogador, não apenas monstros hostis. Estas consultas não têm filtro automático de participantes de instâncias, limite de resultados nem ordenação por distância. Consultas amplas percorrem as entidades vivas carregadas do mundo; use um raio limitado e evite pesquisas repetidas desnecessárias. get_direct_target_entity() usa o alvo direto do evento e pode ser nil; não recorre ao alvo de combate atual do mob.
Exemplo
return {
api_version = 1,
on_enter_combat = function(context)
-- Damage all nearby elites
local elites = context.entities:get_nearby_entities(10, "elites")
for _, elite in ipairs(elites) do
elite:deal_damage(5)
end
end
}
Exemplo
return {
api_version = 1,
on_enter_combat = function(context)
-- Find players in a box area
local center = context.boss:get_location()
local players = context.entities:get_entities_in_box(center, 10, 5, 10, "players")
for _, p in ipairs(players) do
p:send_message("&eYou are in the danger zone!")
end
end
}