Configuração do CannonRTP

O CannonRTP divide suas configurações globais entre vários arquivos em plugins/CannonRTP/, além de um arquivo de configuração por canhão em plugins/CannonRTP/cannons/.

Estrutura de Arquivos

Arquivo	Propósito
plugins/CannonRTP/config.yml	Flags de runtime de alto nível (estado da configuração inicial, idioma, intervalo de partículas, prioridade de modelos de canhão, id do recurso no Spigot, toggle de atualização automática do Nightbreak)
plugins/CannonRTP/landing.yml	Ajustes da busca de pouso (tamanho da fila, tentativas de timeout, duração do Slow Falling, listas de materiais inseguros, comportamento de fail-open)
plugins/CannonRTP/sounds.yml	Sons reproduzidos durante a sequência de lançamento
plugins/CannonRTP/messages.yml	Todas as mensagens voltadas ao jogador, prefixos e conjuntos de títulos
plugins/CannonRTP/protection.yml	Toggles de integração com plugins de proteção
plugins/CannonRTP/cannons/<id>.yml	Um arquivo por canhão (cada um pode controlar múltiplas instâncias)
plugins/CannonRTP/cannons_disabled/	Pasta de retenção para configurações de canhão que vêm com pacotes de conteúdo mas estão atualmente desativadas. O menu /wc setup move arquivos entre cannons/ e cannons_disabled/ quando você ativa ou desativa um pacote de conteúdo.
plugins/CannonRTP/content_packages/<package>.yml	Metadados gerados para cada pacote de conteúdo do Nightbreak (versão, link de download, prefixos usados para encontrar seus arquivos). Normalmente não é editado à mão.

O plugin já vem com três exemplos de configuração de canhão:

• example_cannonrtp.yml -- modelo de referência vazio (nome de exibição Example World Cannon), desativado por padrão. Use-o como referência de YAML ao escrever arquivos de canhão à mão.
• cannonrtp_free_cannon.yml -- ativado, sem instâncias, aponta para o modelo FMM gratuito cannonrtp.
• cannonrtp_premium_cannon.yml -- ativado, sem instâncias, aponta para o modelo FMM premium cannonrtp_premium.

Nenhum deles tem cannonLocations preenchido por padrão, então nada aparece no mundo até que um administrador execute /wc create ou /wc place.

config.yml

Chave	Padrão	Comportamento
setupDone	false	Indica se a configuração inicial do Nightbreak foi concluída
language	english	Arquivo de tradução a carregar. O Release 1 inclui apenas inglês; a chave existe para futuros pacotes de tradução
runtime.particleIntervalTicks	15	Intervalo exato entre as renderizações das partículas ociosas do canhão, em ticks do servidor (mínimo 1; use 1 para renderizar a cada tick)
runtime.launchCooldownSeconds	30	Segundos que um jogador precisa esperar entre lançamentos de canhão aceitos (mínimo 0; use 0 para desativar). Um CannonRTPLaunchEvent cancelado não inicia o cooldown.
runtime.cannonModelPriority	[cannonrtp_premium, cannonrtp]	Lista de prioridade de nomes de modelos do FreeMinecraftModels, verificada de cima para baixo. O primeiro modelo encontrado no servidor é usado para qualquer canhão que não defina seu próprio customModel. Se nenhum for encontrado, é usada a alternativa de partículas em órbita.
runtime.spigotResourceId	""	Id do recurso no Spigot usado pelo verificador de versão. Deixe em branco para desativar.
nightbreak.autoDownloadPluginUpdates	false	Adicionado pela biblioteca embutida MagmaCore. Quando true, o CannonRTP baixa automaticamente os arquivos de atualização de plugin e de conteúdo disponíveis na inicialização (aplicados após a próxima reinicialização do servidor). Os downloads automáticos de plugin exigem um token válido de conta Nightbreak e uma assinatura de apoiador ativa. Deixe false para usar o botão de atualização no jogo.

landing.yml

Chave	Padrão	Comportamento
preloadedLocationsPerCannon	10	Número total de destinos seguros que o plugin tenta manter em fila por canhão (mínimo 1)
chargedLocationsPerCannon	1	Quantos locais um canhão precisa ter antes que sua etiqueta de status mude para Ready (mínimo 1, limitado por preloadedLocationsPerCannon). Os canhões lançam jogadores assim que a fila tem pelo menos um local -- esse limite afeta somente a etiqueta visual.
searchTimeoutAttempts	100	Quantas tentativas de busca falhas até um canhão ser marcado como Exhausted (mínimo 10). As tentativas são globalmente limitadas a uma por tick (20 por segundo), distribuídas de forma justa entre todos os canhões ativos.
slowFallingSeconds	60	Duração máxima do Slow Falling após o airdrop (mínimo 1). O efeito é removido antes do tempo quando o jogador pousa.
failOpenOnProtectionErrors	false	Se a API de um plugin de proteção falhar, bloqueia o pouso por padrão. Defina como true para permitir que os pousos continuem quando um plugin de proteção não puder ser consultado com segurança.
unsafeGroundMaterials	[LAVA, MAGMA_BLOCK, CAMPFIRE, SOUL_CAMPFIRE, CACTUS, POWDER_SNOW]	Materiais que desqualificam uma superfície de pouso
unsafeBodyMaterials	[LAVA, WATER, FIRE, SOUL_FIRE, SWEET_BERRY_BUSH, POWDER_SNOW, COBWEB]	Materiais que desqualificam o espaço dos pés ou da cabeça em um pouso

Os materiais são nomes do enum Material do Bukkit. Entradas inválidas são registradas como avisos e ignoradas.

sounds.yml

Chave	Padrão	Comportamento
levitationStart.sound	BLOCK_BEACON_ACTIVATE	Som tocado quando a fase de busca começa
levitationStart.volume	1.0
levitationStart.pitch	1.15
blastOff.sound	ENTITY_GENERIC_EXPLODE	Som tocado no início da fase de disparo
blastOff.volume	1.0
blastOff.pitch	0.9

Os valores de som podem ser nomes do enum Sound do Bukkit (ex.: BLOCK_BEACON_ACTIVATE) ou chaves com namespace (ex.: minecraft:block.beacon.activate). Nomes de som inválidos são registrados como avisos e o som é silenciosamente ignorado naquele passo.

messages.yml

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

Para a lista completa de chaves de mensagem, placeholders e conjuntos de títulos usados pela sequência de lançamento, consulte a página Mensagens e Títulos.

Campos de Configuração por Canhão

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

Campo	Padrão	Notas
isEnabled	true (para canhões recém-criados)	Canhões desativados não são acionados e aparecem como Disabled
displayName	CannonRTP (ou o nome passado na criação)	Usado em mensagens, na saída de status e na etiqueta flutuante
cannonLocations	lista vazia	Lista de strings serializadas world,x,y,z,pitch,yaw. Uma configuração de canhão pode gerar várias instâncias no mundo. Gerenciada por /wc create, /wc place, /wc remove.
targetWorld	mundo atual no momento da criação	Mira entre mundos é suportada -- defina isto para fazer o jogador pousar em um mundo diferente do canhão. Precisa estar carregado em runtime; enquanto não estiver, o canhão para de pré-carregar e o detalhe do seu /wc status mostra Target world <name> is not loaded.
searchCenter	null	Se não definido, o plugin irradia a partir da própria localização do canhão (quando o canhão está no mundo de destino) ou do spawn do mundo de destino
triggerRadius	1.75	Raio ao redor do canhão usado para detectar jogadores próximos (mínimo 0.5 blocos)
minSearchRadius	500	Distância mínima de busca de pouso a partir do centro de busca (mínimo 0)
maxSearchRadius	5000	Distância máxima de busca de pouso (sempre limitada a no mínimo 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)
verticalBoostVelocity	1.35	Velocidade vertical aplicada a cada tick da fase de disparo (mínimo 0)
enableParticles	true	Controla a animação de partículas em órbita no estado ocioso. Só é renderizada quando nenhum modelo customizado está ativo e um jogador está a até 36 blocos.
requiredPermission	""	Restrição de permissão extra opcional para este canhão específico. Jogadores com cannonrtp.use mas sem este nó veem a mensagem de "sem permissão" configurada.
customModel	""	Nome opcional de modelo do FreeMinecraftModels para este canhão específico. Se vazio, o plugin recorre a runtime.cannonModelPriority.

Valores Padrão na Criação do Canhão

Quando você executa /wc create <id>:

• o id do canhão é convertido para minúsculas e caracteres fora de a-z, 0-9, _, - são substituídos por _
• displayName é definido como CannonRTP a menos que /wc create <id> <display_name> tenha sido usado (sublinhados em <display_name> são convertidos em espaços)
• a localização atual do jogador é adicionada a cannonLocations
• targetWorld é definido como o mundo atual do jogador
• searchCenter não é definido (recorre à própria localização do canhão se ela estiver no mundo de destino, caso contrário ao spawn do mundo de destino)

Após a criação, o plugin responde com o caminho absoluto do arquivo de configuração para que você possa editar manualmente displayName, customModel, requiredPermission, os raios de busca e os ajustes de lançamento.

Integração com o FreeMinecraftModels

Quando um canhão resolve para um modelo válido do FreeMinecraftModels -- seja por seu próprio campo customModel ou pela lista global runtime.cannonModelPriority -- e o FreeMinecraftModels está instalado:

• uma entidade de modelo estático é gerada no local do canhão
• a etiqueta de texto flutuante é elevada para 2.0 blocos acima do canhão (em vez de 1.2 sem modelo) para não sobrepor o modelo
• a animação ociosa de partículas em órbita é suprimida enquanto um modelo está ativo
• durante um lançamento, o canhão executa sua animação fire (se existir) no início da fase de busca; o jogador fica oculto com Invisibilidade durante a fase de busca para que a animação fique nítida

Se o FreeMinecraftModels for ativado ou desativado com o servidor em execução, o cache de modelos de canhão é invalidado e os visuais são atualizados no próximo tick.

Alternativa de Partículas Ociosas

Quando nenhum modelo está ativo, o canhão renderiza um par de partículas DUST_COLOR_TRANSITION + FIREWORK orbitando ao redor do centro do canhão. As cores mudam com base no estado efetivo do canhão:

Estado	Primária	Realce
Ready	laranja (255, 179, 71)	dourado claro (255, 241, 168)
Searching (charging / maintaining)	laranja quente (255, 140, 66)	dourado (255, 209, 102)
Exhausted	vermelho (255, 107, 107)	laranja quente (255, 159, 104)

As partículas ociosas só são renderizadas quando há um jogador a até 36 blocos do canhão, enableParticles está como true e nenhum modelo customizado está ativo.

Etiqueta de Status Flutuante

Cada canhão gera um TextDisplay sempre virado para o jogador acima de sua base, mostrando o nome de exibição e o status atual (Ready, Charging, Maintaining, Exhausted ou Disabled). A etiqueta não é persistente (nunca é salva nos dados do chunk) e é recriada automaticamente ao recarregar o chunk. Ela fica 1.2 blocos acima do canhão, ou 2.0 blocos quando um modelo do FreeMinecraftModels está ativo.

Comportamento de Validação em Runtime

O CannonRTP rejeita locais de pouso candidatos quando qualquer uma destas verificações falha:

• o mundo de destino não está carregado
• o centro de busca não pode ser resolvido (o que só acontece quando o mundo de destino não está carregado)
• a amostra aleatória cai fora do limite do mundo
• o chunk do candidato falha ao carregar
• nenhuma superfície sólida não líquida segura é encontrada
• qualquer bloco da coluna de airdrop de 52 blocos acima do ponto de pouso está obstruído
• a superfície ou qualquer bloco da coluna corresponde às listas de materiais inseguros configuradas
• uma integração de proteção bloqueia o pouso
• um listener de CannonRTPLocationValidationEvent veta o candidato

Após searchTimeoutAttempts pesquisas falhadas (100 por predefinição), o pré-carregamento pode ficar Exhausted. Os destinos já na fila continuam disponíveis. A mensagem de falha só aparece ao ativar com a fila vazia e resume os motivos de rejeição mais comuns. Uma vaga libertada após um lançamento repõe o contador.

Gere ou explore a área de pesquisa configurada no mundo de destino antes de usar o canhão. CannonRTP carrega chunks existentes sem gerar terreno; um raio por explorar pode ficar sem destinos.

Bloqueio de Interação

O CannonRTP impede que um jogador acione um canhão enquanto ele já está em uma sequência de lançamento ativa. Esse acionamento permanece travado até que o lançamento termine e o jogador tenha realmente saído do raio de ativação do canhão, de modo que a recuperação de volta ao assento do canhão não possa iniciar outro lançamento imediatamente. Depois que um lançamento é aceito, um cooldown por jogador em todo o gerenciador também bloqueia todos os canhões por runtime.launchCooldownSeconds (padrão de 30 segundos). O cooldown sobrevive a desconexões enquanto o servidor continua rodando, usa um relógio monotônico e é limpo por /wc reload ou pelo desligamento do plugin. Entrar em um canhão antes da hora envia a mensagem configurável launchCooldown; defina o valor da configuração como 0 para desativar esse bloqueio.