Scripting Lua: Programas de Comportamento
Um programa de comportamento substitui a IA nativa de um mob por comportamentos Lua que decidem para onde ele se move, para onde olha, que entidade tem como alvo e quando ataca. O EliteMobs executa estes programas no sistema nativo Brain do Minecraft através do runtime Mind do MagmaCore.
Os programas de comportamento não são poderes Lua. Um poder Lua reage a eventos do boss como on_boss_damaged_by_player; um programa de comportamento é executado a cada tick e controla os movimentos do mob. Um boss pode usar ambos: um comportamento pode pedir aos poderes do boss que executem uma ação através de on_mind_action.
Os comportamentos de mascotes do FreeMinecraftModels são ficheiros ai.module no mesmo formato e seguem as mesmas regras. Consulte Módulos de comportamento de mascotes para as partes específicas das mascotes, incluindo os campos de contexto c.pet e c.settings. Os comportamentos de mobs do FreeMinecraftModels, que assumem um mob que o plugin não fez aparecer, são outra vez o mesmo tipo de ficheiro, com c.overlay e c.settings.
Os comportamentos de mobs do FreeMinecraftModels exigem a versão do FreeMinecraftModels posterior à 2.15.0.
Defina behavior num ficheiro de boss personalizado, como descrito em Criar Bosses, ou no ficheiro de propriedades de mob do tipo de entidade. behavior: native mantém a IA vanilla. Se a versão do servidor não tiver suporte nativo para Mind, o EliteMobs regista Native Mind interface is unavailable on this Minecraft version. no arranque. Nesse caso, um boss personalizado que selecione um programa não spawna e regista Cannot spawn <boss file>: .... Um boss cujo behavior indique um programa em falta ou inválido falha da mesma forma em qualquer versão.
Ficheiros
Os ficheiros de comportamento ficam em plugins/EliteMobs/behaviors/. O EliteMobs escreve estes ficheiros incluídos quando estão em falta:
plugins/
EliteMobs/
behaviors/
basic_melee.lua
modules/
target.lua
pursuit.lua
melee.lua
wander.lua
- Um ficheiro
.luadentro de qualquer pasta chamadamodulesé um módulo. Todos os outros ficheiros.luasão programas. - Um boss referencia um programa pelo seu caminho relativo a
behaviors/, por exemplobasic_melee.luaouguards/patrol_guard.lua. - O EliteMobs carrega os ficheiros de comportamento quando o seu serviço Mind arranca. Um ficheiro que falhe a validação é ignorado, e a consola regista
Could not load behavior <file>ouCould not load behavior module <file>com o motivo. - Os IDs de programas e módulos usam o espaço de nomes
elitemobs, comoelitemobs:behavior/basic_melee. Os IDs estão em minúsculas e podem contera-z,0-9,.,_e-, além de/depois dos dois-pontos. Dois programas não podem partilhar um ID, e cada ID de módulo deve ser declarado por um único ficheiro. - Um espaço de nomes contém no máximo 256 módulos. Um módulo pode listar no máximo 32 dependências, um programa pode resolver no máximo 64 módulos, e cada ficheiro de código está limitado a 1.000.000 caracteres.
Sandbox e carregamento
As mesmas regras de sandbox dos outros scripts Lua aplicam-se aqui. Consulte a Sandbox Lua. Os ficheiros de comportamento diferem em dois pontos:
coroutinenão está disponível.xpcallnunca chama o seu manipulador de mensagens. Devolvefalsee a mensagem de erro simples, por isso usepcall.
Cada ficheiro é compilado quando é carregado, e não para cada mob, e o seu código de nível superior é executado nesse momento para o verificar. Cada mob que executa um programa recebe o seu próprio ambiente Lua e volta a executar o código de nível superior do programa e dos seus módulos, pelo que as variáveis locais do ficheiro não são partilhadas entre mobs. Uma variável global definida por um ficheiro só é visível nesse ficheiro. Cada execução tem de devolver os mesmos id, revision e modules ou dependencies.
O código de nível superior de um programa e de todos os seus módulos partilha um único limite de 250.000 instruções Lua e 50 milissegundos de tempo de CPU. Se outra chamada Lua já estiver em execução quando o programa arranca, por exemplo um script que faz spawn do mob, o código de nível superior usa em vez disso o limite restante dessa chamada. Mantenha o código de nível superior limitado a definições e constantes.
Ficheiro de programa
Um ficheiro de programa devolve ai.program { ... }:
return ai.program {
id = 'elitemobs:behavior/basic_melee', revision = 1,
modules = {
'elitemobs:behavior/target', 'elitemobs:behavior/pursuit',
'elitemobs:behavior/melee', 'elitemobs:behavior/wander'
},
budget = {
callback_micros = 2000, entity_micros = 4000, server_micros = 5000,
max_callbacks = 20, max_instructions = 12000, max_action_requests = 2
}
}
| Campo | Tipo | Notas |
|---|---|---|
id | string | Obrigatório. ID com espaço de nomes, elitemobs:... para ficheiros em behaviors/. Não pode ser o ID de um dos módulos do programa. |
revision | inteiro positivo | Obrigatório. |
modules | array de strings | Opcional. IDs dos módulos cujas memórias, sensores e comportamentos se juntam ao programa. As dependências são carregadas antes dos módulos que precisam delas. Duplicados e ciclos de dependências são rejeitados. |
memories, sensors, behaviors | tabelas | Opcional. Um programa pode declarar os seus próprios, no mesmo formato de um módulo. |
budget | tabela | Opcional. Limites flexíveis de agendamento. Consulte Orçamentos. |
runaway | tabela | Opcional. Limites rígidos por callback. Consulte Orçamentos. |
Ficheiro de módulo
Um ficheiro de módulo devolve ai.module { ... } e agrupa memórias, sensores e comportamentos reutilizáveis:
| Campo | Tipo | Notas |
|---|---|---|
id | string | Obrigatório. ID do módulo com espaço de nomes. |
revision | inteiro positivo | Obrigatório. |
dependencies | array de strings | Opcional. IDs de outros módulos de que este módulo precisa. |
memories | tabela | Opcional. Consulte Memórias. |
sensors | array | Opcional. Entradas ai.sensor { ... }. |
behaviors | array | Opcional. Entradas ai.behavior { ... }. |
settings | tabela | Opcional. Valores predefinidos com nome que um plugin anfitrião pode substituir por criatura. Consulte Definições do módulo. |
sensors, behaviors, modules e dependencies têm de ser arrays simples, sem lacunas nem chaves com nome. Os nomes de sensores, comportamentos e memórias têm de ser únicos em todos os módulos de um programa.
Definições do módulo
settings declara os valores ajustáveis de um módulo e as respetivas predefinições:
settings = {
radius = 8,
glow = true,
mode = 'circle',
foods = { 'minecraft:apple', 'minecraft:carrot' }
}
| Valor | Exemplo |
|---|---|
| número finito | radius = 8 |
true ou false | glow = true |
| texto | mode = 'circle' |
| lista de textos | foods = { 'minecraft:apple' } |
Cada chave tem de ser um nome. Uma lista tem de ser um array simples de textos, sem lacunas nem chaves com nome. Qualquer outro valor, como uma função ou uma tabela de valores com nome, faz o módulo ser rejeitado. A tabela é lida tal como foi escrita; uma metatabela nela é ignorada.
O MagmaCore só verifica as predefinições e entrega-as ao plugin anfitrião, que decide como os scripts as veem. O EliteMobs não lê as definições dos módulos, pelo que não têm efeito em ficheiros de behaviors/. As mascotes do FreeMinecraftModels combinam os valores de cada criatura sobre as predefinições e dão aos callbacks de cada módulo as definições desse módulo como c.settings. Consulte Módulos de comportamento de mascotes. Os comportamentos de mobs do FreeMinecraftModels, que exigem a versão do FreeMinecraftModels posterior à 2.15.0, fazem o mesmo com os valores que uma substituição dá; consulte Comportamentos de mobs.
Memórias
As memórias são valores tipados que os sensores e os comportamentos partilham para um mob. Declare cada uma pelo nome:
memories = {
candidate = { type = 'uuid', persistent = false },
next_attack = 'integer'
}
| Tipo | Valor Lua |
|---|---|
string | string |
boolean | booleano |
integer | número inteiro |
number | número |
uuid | string de UUID |
position | { world = 'world', x = 0, y = 64, z = 0 } |
Um nome sem dois-pontos é colocado no espaço de nomes do programa. persistent é false por predefinição; true marca a memória para ser serializada com o estado guardado do Mind. Leia e escreva memórias com c.memory:get(name), c.memory:set(name, value, ttl_ticks), c.memory:forget(name) e c.memory:contains(name). O terceiro argumento de set é opcional; quando é fornecido, o valor expira ao fim desse número de ticks. Usar um nome não declarado gera um erro.
Sensores
Um sensor recolhe informação, normalmente para memórias. Os sensores são executados antes dos comportamentos.
ai.sensor {
id = 'elitemobs:behavior/find_target', interval = 20,
sense = function(c)
local target = c.perception:nearest_player(35)
if target then c.memory:set('candidate', target.uuid, 21)
else c.memory:forget('candidate') end
end
}
| Campo | Tipo | Predefinição | Notas |
|---|---|---|---|
id | string | Obrigatório. | |
interval | inteiro positivo | 1 | Ticks entre execuções. |
sense | função | Obrigatório. Recebe o contexto Mind. |
Os sensores não podem usar c.actuator; chamar um método do atuador a partir de um sensor gera um erro.
Temporização dos sensores
Um sensor é executado no primeiro tick em que o corpo do seu mob é processado: após um spawn, o carregamento de um chunk ou uma mudança de programa. Depois disso, é executado a cada interval ticks, numa fase própria para cada mob, para que os mobs criados em conjunto não detetem todos no mesmo tick. A segunda execução ocorre até um interval depois da primeira. Uma execução ignorada porque o mob atingiu um orçamento é repetida no tick seguinte e depois volta à sua fase.
Comportamentos
Um comportamento atua sobre o mob enquanto detém os controlos que declara.
ai.behavior {
id = 'elitemobs:behavior/attack', priority = 10,
controls = { ai.controls.attack },
can_start = function(c) return c.perception:current_target() ~= nil end,
can_continue = function(c) return c.perception:current_target() ~= nil end,
tick = function(c)
local target = c.perception:current_target()
if target then c.actuator:attack(target) end
end
}
| Campo | Tipo | Predefinição | Notas |
|---|---|---|---|
id | string | Obrigatório. | |
priority | inteiro | 0 | Os números mais baixos têm precedência. |
controls | array | nenhum | Controlos que este comportamento reserva enquanto está ativo. |
probe_interval | número inteiro | 1 | Ticks entre verificações de can_start enquanto o comportamento está parado. No mínimo 1; os valores acima de 200 contam como 200. Consulte Intervalo de verificação. |
can_start | função | sempre true | Tem de devolver true ou false. |
can_continue | função | igual a can_start | Tem de devolver true ou false. |
start | função | nenhuma | Executada uma vez quando o comportamento começa. |
tick_interval | número inteiro | 1 | Ticks entre execuções de can_continue e tick enquanto o comportamento está ativo. No mínimo 1; os valores acima de 200 contam como 200. Precisa da versão do EliteMobs posterior à 10.9.14, ou da versão do FreeMinecraftModels posterior à 2.15.0. |
tick | função | Obrigatório. Executada a cada tick enquanto o comportamento está ativo, ou a cada tick_interval ticks. | |
stop | função | nenhuma | function(c, reason); executada quando o comportamento para. |
Ciclo de vida
- Enquanto está parado, o comportamento verifica
can_starta cada tick, ou a cadaprobe_intervalticks. Quando esta devolvetruee o comportamento consegue reservar todos os controlos declarados,starté executada. - Em cada tick em que está ativo, ou a cada
tick_intervalticks, e sempre no tick em que começou,can_continueé executada primeiro. Quando devolvefalse, o comportamento para com o motivocompleted; caso contrário,tické executada. stop(c, reason)recebe um decompleted,preempted,program_replaced,entity_removed,callback_failedouhandle_closed. Parar liberta os controlos do comportamento e interrompe o movimento, o alvo ou o ataque que detinha.
Um erro Lua em can_continue, start ou tick para o comportamento com callback_failed. Devolver algo que não seja um booleano em can_start ou can_continue é um erro. A consola regista Mind <program> callback <callback> failed with ... por cada falha.
Intervalo de verificação
Por predefinição, um comportamento parado verifica can_start em cada tick. Com probe_interval = N, verifica a cada N ticks, numa fase própria para cada mob, para que uma multidão de mobs com o mesmo comportamento, ou os vários comportamentos de um mob, não verifiquem todos no mesmo tick. Use-o quando a condição de início é dispendiosa ou não precisa de resposta no tick exato.
- A primeira verificação, depois de o corpo começar a ser processado, espera pela fase do comportamento, até N - 1 ticks.
- Um comportamento começa, e tira controlos a outro comportamento, até N - 1 ticks depois de o poder ter feito.
- Um comportamento que para é verificado de novo no tick da sua fase seguinte, até N ticks depois.
- Uma verificação ignorada porque o mob atingiu um orçamento, ou um início adiado por um, é repetida no tick seguinte e depois volta à fase.
- Nada muda enquanto o comportamento está ativo:
can_continueetickcontinuam a ser executados a cada tick, ou a cadatick_intervalticks, estopnão é adiada. Um comportamento semcan_continuecontinua a chamarcan_starta cada tick enquanto está ativo, porquecan_continueassumecan_startpor predefinição.
O valor tem de ser um número sem parte fracionária, 1 ou mais; qualquer outra coisa faz o ficheiro ser rejeitado. Os valores acima de 200 (10 segundos) contam como 200.
Controlos
| Controlo | Permite |
|---|---|
ai.controls.move | c.actuator:move_to(...), c.actuator:flee(...), c.actuator:stop_moving() |
ai.controls.look | c.actuator:look_at(...) |
ai.controls.move e ai.controls.look em conjunto | c.actuator:steer_flight(...) |
ai.controls.jump | c.actuator:jump() |
ai.controls.target | c.actuator:set_target(...), c.actuator:clear_target() |
ai.controls.attack | c.actuator:attack(...), c.actuator:shoot(...) |
ai.controls.action | c.actions:request(...) |
ai.controls.use_item | Reservado; o atuador Lua não tem nenhum método para itens. |
Cada controlo pertence a um único comportamento ativo de cada vez. Um comportamento com um número de priority mais baixo tira um controlo a um comportamento com um número mais alto, que para com o motivo preempted. Não pode tirar um controlo detido por um comportamento com um número mais baixo. Entre prioridades iguais, fica com o controlo o comportamento cujo id vem primeiro por ordem alfabética. Chamar um método do atuador sem deter o respetivo controlo gera um erro. c.actuator:stop_all() para apenas o que o comportamento detém.
Nos módulos incluídos, a seleção de alvo usa a prioridade 5, os ataques corpo a corpo 10, a perseguição 20 e o vaguear em repouso 50, pelo que a perseguição tira o movimento ao vaguear assim que existe um alvo.
Fugir, disparar e definir o dano
Estas três chamadas precisam da versão do EliteMobs posterior à 10.9.14.
c.actuator:flee(location, speed)planeia um caminho de cerca de dez blocos que se afasta da posição e segue-o. Devolvefalsequando o corpo não consegue planear caminhos, não encontra uma saída tão longa ou outro sistema controla o seu movimento. O planeamento tenta várias saídas, por isso chame-a a cada poucos ticks; o caminho é seguido entretanto.c.actuator:shoot(target)faz o ataque à distância do tipo do próprio corpo: a flecha de um esqueleto, a poção de uma bruxa, ou a besta de um pillager, que é carregada primeiro quando está vazia. Devolvefalsepara um tipo que não tem nenhum.c.actuator:attack(target, damage)dá uma pancada e causa esse dano, atribuído ao corpo, em vez do dano de ataque do próprio corpo.
Dirigir o voo
c.actuator:steer_flight(x, y, z) move um corpo voador por essa velocidade, em blocos por tick, apenas durante o tick atual. Chame-o em cada tick em que o mob deva continuar a voar; num tick sem chamada, o corpo volta a mover-se pela sua navegação normal. A chamada interrompe qualquer percurso iniciado com move_to, colide com blocos e vira o corpo para a sua direção horizontal de deslocação em no máximo 8 graus por tick. Uma velocidade superior a 4 blocos por tick (80 blocos por segundo) é reduzida a 4 na mesma direção.
O comportamento tem de deter ai.controls.move e ai.controls.look. Um controlo em falta ou um valor que não seja um número finito gera um erro. A chamada devolve false e não faz nada quando o corpo não pode voar ou outro sistema está a controlar o seu movimento, e true nos restantes casos. O EliteMobs dá um corpo voador aos tipos de mob voadores, como morcegos, blazes, ghasts, phantoms e vexes.
Pedir ações ao boss
Um comportamento que detém ai.controls.action pode chamar c.actions:request(identifier, payload). O EliteMobs envia o pedido aos poderes Lua do boss através de on_mind_action. O identificador tem de ser uma chave com espaço de nomes, em minúsculas, com no máximo 128 caracteres, como 'elitemobs:slam'. O payload contém no máximo 16 entradas com chaves em minúsculas de no máximo 64 caracteres, e os valores de texto estão limitados a 256 caracteres; um identificador ou payload inválido gera um erro. A chamada devolve accepted, deferred ou rejected; os pedidos que ultrapassem o max_action_requests do programa num tick devolvem deferred. Consulte o contexto de ação Mind para o formato do payload.
Orçamentos
budget define limites flexíveis de agendamento. Quando um mob atinge um deles num tick, o runtime Mind ignora os callbacks restantes desse mob até ao tick seguinte. Um callback que já esteja em execução termina sempre. Uma execução de sensor ou uma verificação de can_start ignorada é repetida no tick seguinte.
| Chave | Predefinição | Notas |
|---|---|---|
callback_micros | 2000 | Um callback que demore mais do que isto termina os callbacks do mob nesse tick. |
entity_micros | 4000 | Tempo total de callbacks por mob e por tick. |
server_micros | 20000 | Os callbacks do mob param nesse tick quando todos os programas Mind juntos tiverem usado este tempo. |
max_callbacks | 128 | Callbacks por mob e por tick. |
max_action_requests | 8 | Pedidos de ação por mob e por tick; no máximo 64. |
Todos os valores têm de ser positivos, e callback_micros não pode exceder entity_micros, que por sua vez não pode exceder server_micros.
runaway define limites rígidos que interrompem um único callback:
| Chave | Predefinição | Máximo | Notas |
|---|---|---|---|
cpu_micros | 50000 | 50000 | Tempo de CPU da thread por callback. |
max_instructions | 50000 | 250000 | Instruções Lua por callback. |
budget também aceita max_instructions, como no basic_melee.lua incluído. Declare-o em budget ou em runaway, não em ambos. Os dois limites têm de ser positivos. Um valor maior continua a ser carregado, mas é reduzido ao máximo sem aviso.
Os limites interrompem um callback enquanto é executado, pelo que um ciclo que nunca termina falha em vez de bloquear o servidor. As instruções são contadas à medida que são executadas; o tempo de CPU é verificado a cada 1024 instruções e quando o callback termina. Se o servidor não conseguir medir o tempo de CPU da thread, cpu_micros limita o tempo decorrido a cinco vezes o seu valor. Um callback que ultrapasse um limite de runaway falha como qualquer outro erro de callback, e a linha da consola indica failed with RUNAWAY_LIMIT_EXCEEDED.
Próximos passos
- Criar Bosses: behavior -- selecionar um programa para um boss
- Referência da API Lua: contexto de um programa Mind -- todos os métodos de
c.memory,c.perception,c.actuatorec.actions - Hooks e Ciclo de Vida --
on_mind_actione os outros hooks de poderes Lua - Módulos de comportamento de mascotes do FreeMinecraftModels -- módulos de comportamento de mascotes e os respetivos campos
c.petec.settings
