Patrulhas de NPCs e bosses

O EliteMobs permite que NPCs configurados e Bosses Personalizados sigam rotas criadas pelo administrador usando a navegação nativa do Minecraft. O mesmo sistema disponibiliza walk_to, hold e teleport para scripts Lua.

Fluxo rápido de criação

1. Gere ou coloque o NPC ou Boss Personalizado.
2. Olhe diretamente para ele a até 12 blocos e execute /em patrol edit.
3. Fique em cada destino e execute /em patrol add. As rotas novas começam com o nó 0 no local de aparecimento configurado do ator.
4. Use /em patrol mode LOOP para ligar o último nó ao primeiro ou /em patrol mode REVERSE para percorrer a lista de volta.
5. Execute /em patrol save para guardar a rota e atualizar o ator.

O editor mostra as ligações entre os nós e uma pré-visualização do caminho resolvido. /em patrol remove remove o último nó, /em patrol undo restaura uma edição anterior e /em patrol status indica o estado do controlador de edição. /em patrol cancel encerra a sessão sem guardar alterações de rota. Todos os comandos de edição são exclusivos para jogadores e exigem elitemobs.patrol.admin. Os destinos têm de estar no mundo de origem; o editor rejeita pontos numa região do WorldGuard com elitemob-spawning em deny.

As rotas novas usam coordenadas relativas. Ao editar uma rota existente, o editor preserva a definição patrol.relative da mesma e guarda os pontos adicionados nesse formato. Defina o formato na configuração YAML.

Se um ficheiro de NPC ou de boss regional tiver vários spawnLocations, guardar uma rota para um ator cria um ficheiro secundário para esse local e remove o local do ficheiro original. Isto mantém a edição específica desse ator, tanto em rotas relativas como absolutas. O ficheiro secundário herda do original através de extends. Um ficheiro secundário de boss também copia leashRadius, powers e eliteScript do original, que o extends não herda.

Configuração

Os nós são coordenadas x,y,z. Com relative: true, o valor predefinido, são deslocamentos a partir do local de aparecimento configurado do ator. Com relative: false, são coordenadas exatas no mundo do ator, incluindo o mundo da instância de masmorra ativa. Os nós absolutos não incluem o nome do mundo.

patrol:
  enabled: true
  relative: true
  mode: LOOP
  speed: 1.0
  virtualSpeed: 0.2
  nodes:
  - 0,0,0
  - 1000,0,0
  - 1000,0,250

Chave	Valores	Predefinição	Descrição
patrol.enabled	true / false	true quando existem nós	Ativa a rota.
patrol.relative	true / false	true	Usa deslocamentos a partir do local de aparecimento configurado quando true, ou coordenadas exatas no mundo do ator quando false. Aplica-se a todos os nós da rota.
patrol.mode	LOOP / REVERSE	LOOP	LOOP liga o último nó ao nó 0; REVERSE volta pela lista.
patrol.speed	número positivo finito	1.0	Multiplicador de velocidade da navegação nativa.
patrol.virtualSpeed	número positivo finito	atributo de velocidade × velocidade da patrulha	Blocos percorridos por tick ao longo do caminho resolvido em cache enquanto um ator persistente não tem corpo carregado. Normalmente, omita-o.
patrol.startNodeWaitSeconds	número finito, 0 ou mais	0	Segundos que o ator descansa no nó 0 sempre que volta a ele: uma vez por volta em LOOP, uma vez por ida e volta em REVERSE. Um ator que aparece no nó 0 também descansa antes da primeira volta. Durante o descanso, fica virado para a direção do seu local de aparecimento.
patrol.nodes	pelo menos duas coordenadas	nenhum	Destinos ordenados, interpretados conforme patrol.relative. Aceita strings x,y,z e mapas com x, y e z. As coordenadas têm de ser finitas e os nós consecutivos têm de ser diferentes.

Por exemplo, esta rota visita três locais exatos antes de voltar ao primeiro:

patrol:
  enabled: true
  relative: false
  mode: LOOP
  nodes:
  - 299,91,215
  - 286,91,213
  - 279,91,230

As rotas existentes sem patrol.relative continuam a usar deslocamentos. Mudar esta opção muda a interpretação de todos os nós; não converte os números armazenados. Converta também os nós ao mudar o formato de uma rota existente.

Não existe limite público de distância por troço. Um troço de 1.000 blocos é válido. A antiga chave experimental patrol.maxLegDistance está obsoleta e não tem efeito.

Ao guardar, o editor preserva a velocidade de navegação, qualquer virtualSpeed explícito e o descanso no nó inicial. Ao ler uma rota com mais de dois nós, uma cópia do primeiro nó repetida no final é removida automaticamente.

Pausas de NPCs perto de jogadores

Os NPCs também aceitam patrol.pauseNearPlayersRadius (predefinição 0, desativado) e patrol.faceNearbyPlayers (predefinição false). Um raio positivo finito pausa a patrulha perto de jogadores vivos que não sejam espectadores; a opção de orientação faz o NPC olhar para o jogador elegível mais próximo. A proximidade é verificada a cada 20 ticks. Raios inválidos ou negativos desativam a pausa.

Estas definições são independentes dos diálogos e das pausas manuais por Lua. São opções de NPCs, não campos adicionais de patrulhas de bosses.

Descanso no nó inicial

Com patrol.startNodeWaitSeconds, o ator para no nó 0 antes de começar a próxima volta. A contagem do descanso continua mesmo com o ator descarregado. Uma pausa por proximidade ou por combate interrompe a contagem até terminar. walk_to, hold, teleport e patrol_resume() encerram o descanso imediatamente. O instrutor de combate da Guilda usa um descanso de 60 segundos para que os jogadores possam encontrá-lo na cadeira entre as voltas.

Pesquisa de caminhos de longa distância

Os troços longos são resolvidos automaticamente. O EliteMobs pede ao MagmaCore uma rota progressiva pelo terreno carregado, divide-a em destinos curtos para a navegação nativa e recalcula conforme o ator avança.

O acesso ao terreno e a pesquisa do caminho são separados:

• Os snapshots de chunks carregados são capturados na thread do servidor pelo sistema partilhado de cargas de trabalho com orçamento por tick do MagmaCore.
• A pesquisa A* limitada é executada de forma assíncrona sobre snapshots imutáveis.
• O pathfinder nativo do Minecraft valida e percorre os troços curtos finais.
• O planeamento nunca força o carregamento de chunks. Se faltar terreno, aguarda e tenta novamente. Um ator persistente sem corpo só pode avançar pelo caminho resolvido em cache e aguarda quando ele termina. O seu corpo só pode voltar numa área que processe entidades.

Isto permite cruzar cidades sem examinar tudo num único tick nem atravessar edifícios descarregados em linha reta. As criaturas voadoras e aquáticas usam pesquisas volumétricas; as criaturas terrestres exigem apoio e espaço livre e evitam perigos comuns.

Comportamento dos atores

• As patrulhas de NPC ativam automaticamente a IA do corpo e a sincronização de movimento do modelo. syncMovement continua útil fora de patrulhas, mas não é um segundo interruptor.
• Os Bosses Personalizados exigem ai: true, velocidade positiva e não podem ser passageiros.
• Os bosses pausam a patrulha durante o combate e retomam depois.
• Os NPCs não instanciados e os bosses persistentes não instanciados guardam a posição segura em patrol-state.yml durante descarregamentos e recarregamentos. Uma posição guardada é descartada quando os nós da rota ou a opção relative mudam, e o ator recomeça a partir do nó 0.
• Um ator só se materializa numa área que processa entidades. Sem corpo, a sua posição guardada ainda pode avançar por um caminho já resolvido; não descobre uma nova rota por terreno desconhecido.
• Um passageiro não pode ter patrulha; configure a montaria.

Controlo por Lua

Estes métodos são expostos em context.npc e context.boss; as suas operações de patrulha exigem um controlador configurado. As coordenadas em Lua continuam a ser deslocamentos do local de aparecimento configurado do ator, independentemente de patrol.relative, e cada método devolve se o pedido foi aceite. walk_to, hold e teleport também precisam de um corpo vivo. Aceitar uma caminhada não comprova a chegada: combate, pausas por proximidade, IA desativada ou falhas de caminho podem interrompê-la.

Método	Comportamento
patrol_pause()	Para a rota atual sem apagar a configuração.
patrol_resume()	Encerra uma espera ou caminhada temporária e retoma a patrulha.
walk_to(x, y, z)	Caminha até ao deslocamento e depois retoma a patrulha.
hold(x, y, z)	Caminha até ao deslocamento e permanece aí até à chamada de patrol_resume().
teleport(x, y, z)	Teletransporta o corpo vivo até ao deslocamento no mesmo mundo quando o destino processa entidades e o Bukkit aceita o teletransporte. Não remove uma pausa de script nem um alvo temporário existentes; use patrol_resume() para voltar à rota.

return {
  api_version = 1,
  on_npc_interact = function(context)
    context.npc:walk_to(40, 0, -12)
  end
}

walk_to usa o mesmo solucionador de longa distância; não é preciso criar pontos intermédios manualmente.

Diagnóstico

Fora de uma sessão de edição, olhe para o ator e execute /em patrol status. A saída mostra o estado, os nós atual e alvo, o progresso, a localização lógica, a velocidade virtual, a presença do corpo e o motivo de espera. start_node_wait indica o descanso no nó inicial. terrain_unavailable indica que o movimento sem corpo já não tem um caminho resolvido disponível; um ator carregado à espera do planeamento pode mostrar yielded. A localização lógica representa o progresso na rota e pode diferir da posição segura guardada para restaurar o corpo.

O controlador tenta novamente uma vez após falhas comuns de caminho antes de avançar para o nó seguinte. Uma caminhada ou espera temporária que falha também recebe uma nova tentativa; isto não comprova que o destino foi alcançado. Verifique o terreno e a navegação nativa quando o ator salta um ponto ou permanece parado.