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)
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)

O plugin inclui um exemplo de configuração de canhão chamado example_world_cannon. Por padrão ele está desativado e não possui instâncias -- existe puramente como referência para a estrutura YAML.

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	Com que frequência as partículas ociosas do canhão são renderizadas (mínimo 5)
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.

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. 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. 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,yaw,pitch. 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, caso contrário o canhão aparece como Invalid.
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	dourado
Searching (charging / maintaining)	laranja quente	dourado
Exhausted	vermelho	vermelho quente
Configuração inválida	vermelho profundo	vermelho

As partículas ociosas só são renderizadas quando há um jogador a até 36 blocos do canhão.

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, Disabled ou Invalid). A etiqueta não é persistente (nunca é salva nos dados do chunk) e é recriada automaticamente ao recarregar o chunk.

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 é inválido
• 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
• o espaço dos pés ou da cabeça está bloqueado
• o terreno ou os blocos corporais correspondem às listas de materiais inseguros configuradas
• uma integração de proteção bloqueia o pouso
• um listener de CannonRTPLocationValidationEvent veta o candidato

Se um canhão esgota searchTimeoutAttempts (padrão 100) sem completar sua reserva, ele fica Exhausted e passa a retornar a mensagem de falha configurada em vez de lançar jogadores. A mensagem de falha inclui um resumo dos motivos de rejeição mais comuns. O canhão reinicia seu contador de timeout sempre que uma vaga abre na fila (ex.: após um lançamento).

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. Quando o lançamento atual termina (pouso ou desconexão), o jogador pode usar um canhão novamente. Não há cooldown adicional.