Configuração do CannonRTP

O CannonRTP distribui as definições globais por vários ficheiros em plugins/CannonRTP/ e guarda uma configuração por canhão em plugins/CannonRTP/cannons/.

Organização dos ficheiros

Ficheiro	Função
plugins/CannonRTP/config.yml	Opções gerais de funcionamento: estado da configuração inicial, idioma, intervalo de partículas, tempo de espera entre lançamentos, prioridade dos modelos de canhão, ID do recurso Spigot e definições de atualização do Nightbreak
plugins/CannonRTP/landing.yml	Ajustes da pesquisa de destinos: tamanho da fila, limite de tentativas, duração da queda lenta, materiais inseguros e comportamento perante erros de proteção
plugins/CannonRTP/sounds.yml	Sons da sequência de lançamento
plugins/CannonRTP/messages.yml	Mensagens aos jogadores, prefixos e conjuntos de títulos
plugins/CannonRTP/protection.yml	Opções de integração com cada plugin de proteção
plugins/CannonRTP/cannons/<id>.yml	Um ficheiro por canhão, que pode controlar várias posições no mundo
plugins/CannonRTP/cannons_disabled/	Configurações de canhões incluídas em pacotes de conteúdo e atualmente desativadas. O menu /wc setup move os ficheiros entre cannons/ e cannons_disabled/ ao ativar ou desativar um pacote.
plugins/CannonRTP/content_packages/<package>.yml	Metadados gerados para cada pacote Nightbreak: versão, ligação de transferência e prefixos usados para localizar os seus ficheiros. Normalmente não se editam à mão.
plugins/CannonRTP/imports/	Pasta para importações manuais de conteúdo. Consulte Pacotes de conteúdo.
plugins/CannonRTP/nightbreak-changelogs.yml	Estado de leitura da caixa de entrada partilhada /wcchangelog. Consulte Notificações de notas de lançamento.

O plugin inclui três configurações de exemplo:

• example_cannonrtp.yml: modelo de referência vazio, com o nome Example World Cannon, desativado por predefinição. Use-o como referência YAML ao escrever ficheiros de canhão manualmente.
• cannonrtp_free_cannon.yml: ativado, sem posições definidas, usa o modelo FMM gratuito cannonrtp.
• cannonrtp_premium_cannon.yml: ativado, sem posições definidas, usa o modelo FMM premium cannonrtp_premium.

Nenhum tem cannonLocations preenchido inicialmente. Nada aparece no mundo até um administrador executar /wc create ou /wc place. Nenhum define targetWorld, pelo que cada colocação envia os jogadores para o mundo onde se encontra.

O CannonRTP recria qualquer um destes três ficheiros que falte em cannons/ sempre que carrega as configurações dos canhões. Eliminar um deles com /wc delete, ou retirá-lo ao desativar o respetivo pacote de conteúdo, deixa uma cópia predefinida nova, sem posições, após o recarregamento.

config.yml

Chave	Predefinição	Comportamento
setupDone	false	Regista se a configuração inicial do Nightbreak foi concluída
language	english	Ficheiro de tradução a carregar. A versão 1 inclui apenas inglês; a chave permite futuros pacotes de tradução
runtime.particleIntervalTicks	15	Intervalo exato, em ticks do servidor, entre apresentações das partículas do canhão em repouso. Mínimo 1; use 1 para as apresentar em todos os ticks
runtime.launchCooldownSeconds	30	Segundos que um jogador deve esperar entre lançamentos aceites. Mínimo 0; 0 desativa a espera. Eventos CannonRTPLaunchEvent cancelados não iniciam este período.
runtime.cannonModelPriority	[cannonrtp_premium, cannonrtp]	Lista de modelos FreeMinecraftModels por ordem de preferência. O primeiro disponível no servidor é usado pelos canhões sem customModel próprio. Se nenhum existir, são usadas partículas em órbita.
runtime.spigotResourceId	""	ID do recurso Spigot usado pelo verificador de versões. Deixe vazio para desativar.
nightbreak.autoDownloadPluginUpdates	false	Adicionado pela biblioteca MagmaCore incorporada. Com true, o CannonRTP transfere automaticamente as atualizações disponíveis do plugin e do conteúdo alguns minutos após o arranque. As atualizações de conteúdo são usadas após o próximo reinício do servidor; uma atualização do plugin segue nightbreak.applyPluginUpdatesWithoutRestart. As transferências automáticas do plugin exigem um token Nightbreak válido e uma subscrição de apoiante ativa. Mantenha false para usar o botão de atualização no jogo.
nightbreak.applyPluginUpdatesWithoutRestart	never	Adicionado pela biblioteca MagmaCore incorporada. Decide quando uma atualização do plugin transferida é aplicada, recarregando o CannonRTP a partir do novo JAR. never aguarda o próximo reinício. when-empty aplica-a de imediato se não houver jogadores online; caso contrário, verifica a cada 30 segundos e aplica-a quando o servidor ficar vazio. immediately aplica-a assim que a transferência termina. Qualquer outro valor conta como never. O recarregamento cancela os lançamentos ativos, conforme descrito em Proteção contra ativações repetidas. /wc applypluginupdate aplica manualmente uma atualização transferida, independentemente desta definição.

landing.yml

Chave	Predefinição	Comportamento
preloadedLocationsPerCannon	10	Número total de destinos seguros que o plugin tenta manter na fila de cada canhão. Mínimo 1
chargedLocationsPerCannon	1	Destinos necessários para o rótulo passar a Ready. Mínimo 1, limitado a preloadedLocationsPerCannon. Um canhão já lança jogadores com um único destino na fila; este limiar só afeta o rótulo visual.
searchTimeoutAttempts	100	Tentativas de pesquisa falhadas antes de o canhão ficar Exhausted. Mínimo 10. Existe um limite global de uma tentativa por tick, 20 por segundo, repartida de forma equilibrada pelos canhões ativos.
slowFallingSeconds	60	Duração máxima da queda lenta após o teletransporte aéreo. Mínimo 1. O efeito é removido antecipadamente quando o jogador aterra.
failOpenOnProtectionErrors	false	Um erro na API de um plugin de proteção bloqueia a aterragem por predefinição. Com true, as aterragens continuam quando não é possível consultar esse plugin com segurança. Com false, uma integração de proteção ativa que não conseguiu carregar também impede todos os canhões de pesquisar (consulte Integrações de proteção).
unsafeGroundMaterials	[LAVA, MAGMA_BLOCK, CAMPFIRE, SOUL_CAMPFIRE, CACTUS, POWDER_SNOW]	Materiais que tornam a superfície de aterragem inválida
unsafeBodyMaterials	[LAVA, WATER, FIRE, SOUL_FIRE, SWEET_BERRY_BUSH, POWDER_SNOW, COBWEB]	Materiais proibidos em toda a coluna vertical de aterragem e queda, incluindo o espaço para a cabeça na chegada

Os materiais usam nomes do enum Bukkit Material. Entradas inválidas geram avisos no registo e são ignoradas.

sounds.yml

Chave	Predefinição	Comportamento
levitationStart.sound	BLOCK_BEACON_ACTIVATE	Som reproduzido no início da fase de pesquisa
levitationStart.volume	1.0
levitationStart.pitch	1.15
blastOff.sound	ENTITY_GENERIC_EXPLODE	Som reproduzido no início da fase de disparo
blastOff.volume	1.0
blastOff.pitch	0.9

Os sons aceitam nomes do enum Bukkit Sound, como BLOCK_BEACON_ACTIVATE, ou chaves com namespace, como minecraft:block.beacon.activate. Um nome no estilo do enum é convertido substituindo cada sublinhado por um ponto, pelo que um som cuja chave contenha um sublinhado, como minecraft:block.note_block.pling, tem de ser escrito com a chave com namespace. Nomes inválidos geram avisos no registo e o som dessa etapa é omitido. Deixe um som em branco para não reproduzir nada. Volume e tom abaixo de 0 passam a 0.

messages.yml

Todas as mensagens aceitam gradientes MagmaCore, tags MiniMessage e códigos de cor antigos com &. O marcador $prefix é substituído pelo prefixo configurado.

Consulte Mensagens e títulos para ver todas as chaves, os marcadores e os conjuntos de títulos da sequência de lançamento.

Campos de configuração por canhão

Cada ficheiro de canhão (plugins/CannonRTP/cannons/<id>.yml) guarda estes campos:

Campo	Predefinição	Observações
isEnabled	true para novos canhões	Canhões desativados não são acionados, não criam rótulo nem modelo e apresentam Disabled em /wc list e /wc status
displayName	CannonRTP, ou o nome indicado na criação	Usado nas mensagens, na informação de estado e no rótulo flutuante
cannonLocations	lista vazia	Lista de posições serializadas como world,x,y,z,yaw,pitch. Uma configuração pode criar vários canhões no mundo. Gerida por /wc create, /wc place e /wc remove.
targetWorld	mundo atual no momento da criação	Permite enviar jogadores para um mundo diferente daquele onde está o canhão. Se estiver vazio ou ausente, cada colocação envia os jogadores para o seu próprio mundo. O mundo deve estar carregado durante o funcionamento; enquanto não estiver, o pré-carregamento para e /wc status apresenta Target world <name> is not loaded.
searchCenter	null	Se não estiver definido, a pesquisa parte da posição do canhão quando este está no mundo de destino, ou do spawn desse mundo. Se estiver definido como uma posição noutro mundo, as suas coordenadas X e Z são usadas no mundo de destino.
triggerRadius	1.75	Raio de deteção de jogadores à volta do canhão. Mínimo 0.5 blocos
minSearchRadius	500	Distância mínima da pesquisa de destinos em relação ao centro. Mínimo 0
maxSearchRadius	5000	Distância máxima da pesquisa, sempre ajustada para pelo menos minSearchRadius + 1
launchWarmupTicks	42	Duração da fase Searching em ticks. Mínimo 1
verticalBoostTicks	45	Duração da fase Firing em ticks. Mínimo 0. Com 0, o impulso ascendente é omitido; o som de disparo, a explosão visual e o título do destino continuam a ser apresentados antes do teletransporte.
verticalBoostVelocity	1.35	Velocidade ascendente aplicada em cada tick da fase de disparo. Mínimo 0
enableParticles	true	Controla as partículas em órbita durante o repouso. Só aparecem sem um modelo personalizado ativo e com um jogador a menos de 36 blocos.
requiredPermission	""	Permissão adicional opcional para este canhão. Jogadores com cannonrtp.use mas sem esta permissão recebem a mensagem de falta de permissão configurada.
customModel	""	Nome opcional de um modelo FreeMinecraftModels para este canhão. Se estiver vazio ou indisponível, o plugin recorre a runtime.cannonModelPriority.

Predefinições na criação de canhões

Ao executar /wc create <id>:

• o ID é convertido para minúsculas e todos os caracteres fora de a-z, 0-9, _ e - são substituídos por _
• displayName fica como CannonRTP, exceto se usar /wc create <id> <display_name>; os sublinhados em <display_name> tornam-se espaços
• a posição atual do jogador é acrescentada a cannonLocations
• targetWorld recebe o mundo atual do jogador
• searchCenter fica por definir, usando a posição do canhão se este estiver no mundo de destino, ou o spawn desse mundo caso contrário

Após a criação, o plugin apresenta o caminho absoluto do ficheiro de configuração. Pode editar manualmente displayName, customModel, requiredPermission, os raios de pesquisa e os parâmetros de lançamento.

Integração com FreeMinecraftModels

Quando o FreeMinecraftModels está instalado e o canhão encontra um modelo válido, pelo seu campo customModel ou pela lista global runtime.cannonModelPriority:

• é criada uma entidade de modelo estático na posição do canhão
• o rótulo flutuante sobe para 2.0 blocos acima do canhão, em vez de 1.2 sem modelo, para não o atravessar
• as partículas em órbita deixam de aparecer enquanto o modelo estiver ativo
• durante um lançamento, o canhão reproduz a animação fire, se existir, no início da fase de pesquisa; o jogador recebe Invisibilidade nessa fase para não interferir visualmente com a animação

Se o FreeMinecraftModels for ativado ou desativado com o servidor em execução, a cache de modelos do canhão é invalidada. As versões atuais do FMM também notificam o CannonRTP quando termina um recarregamento de conteúdo: as referências antigas são descartadas e os modelos são recriados a partir do registo atualizado. O CannonRTP também deteta diretamente instâncias de modelos removidas, incluindo com o FMM 2.4.0, anterior ao evento de conclusão de recarregamento. Enquanto o FMM estiver ativo, as recriações pendentes são repetidas a cada 20 ticks até existir um modelo utilizável.

Partículas de repouso sem modelo

Sem um modelo ativo, o canhão apresenta um par de partículas DUST_COLOR_TRANSITION + FIREWORK em órbita à volta do centro. As cores dependem do estado efetivo:

Estado	Cor principal	Cor de realce
Pronto	laranja (255, 179, 71)	dourado claro (255, 241, 168)
A pesquisar, a carregar ou a manter a fila	laranja quente (255, 140, 66)	dourado (255, 209, 102)
Esgotado	vermelho (255, 107, 107)	laranja quente (255, 159, 104)

Estas partículas só aparecem com um jogador a menos de 36 blocos, enableParticles a true e nenhum modelo personalizado ativo.

Rótulo flutuante de estado

Cada canhão ativo cria um TextDisplay acima da base, orientado para o observador, com o nome e o estado atual: Ready, Charging, Maintaining ou Exhausted. Os canhões desativados não criam rótulo. O rótulo não é persistente, nunca é guardado nos dados do chunk e é recriado automaticamente ao recarregar esse chunk. Fica 1.2 blocos acima do canhão, ou 2.0 com um modelo FreeMinecraftModels ativo.

Validação durante o funcionamento

O CannonRTP rejeita destinos candidatos quando falha qualquer uma destas verificações:

• o mundo de destino não está carregado
• não é possível determinar o centro de pesquisa, o que só acontece se o mundo de destino não estiver carregado
• a posição aleatória fica fora do limite do mundo
• o chunk candidato não carrega
• não existe uma superfície sólida, segura e não líquida
• algum bloco da coluna de queda de 52 blocos acima do destino está obstruído
• a superfície ou algum bloco da coluna pertence às listas de materiais inseguros configuradas
• uma integração de proteção bloqueia a aterragem
• um listener de CannonRTPLocationValidationEvent rejeita o candidato

Após searchTimeoutAttempts pesquisas falhadas, 100 por predefinição, o pré-carregamento pode passar a Exhausted. Os destinos já na fila continuam utilizáveis. Uma ativação só devolve a mensagem de falha configurada quando a fila está vazia; essa mensagem resume os motivos de rejeição comuns. Libertar uma posição da fila após um lançamento repõe o contador de tentativas.

O terreno de destino já deve existir: os chunks candidatos são carregados sem gerar terreno novo. Gere ou explore a área de pesquisa primeiro; num mundo novo, um raio ainda por explorar pode deixar a fila vazia.

Proteção contra ativações repetidas

O CannonRTP impede um jogador de ativar outro canhão durante uma sequência de lançamento. O bloqueio só termina quando o lançamento acaba e o jogador sai realmente do raio de ativação. Assim, regressar ao assento do canhão durante a recuperação não inicia imediatamente outro lançamento. Depois de um lançamento ser aceite, um tempo de espera por jogador, comum a todos os canhões, bloqueia novos lançamentos durante runtime.launchCooldownSeconds, 30 segundos por predefinição. Este período mantém-se após uma desconexão enquanto o servidor continuar em execução, usa um relógio monotónico e é limpo sempre que o CannonRTP reconstrói os seus canhões: /wc reload, uma atualização do plugin sem reinício, o encerramento do plugin ou qualquer comando que edite canhões (create, place, remove, delete, target, center). Uma reconstrução também cancela os lançamentos ativos, devolve esses jogadores ao assento do respetivo canhão e descarta todos os destinos em fila. Entrar num canhão antes de terminar apresenta a mensagem configurável launchCooldown; use 0 na configuração para desativar esta restrição.