API do CannonRTP

O CannonRTP expõe três eventos do Bukkit para que outros plugins possam reagir. Todos os eventos ficam no pacote com.magmaguy.cannonrtp.api e são disparados na thread principal do servidor.

Para escutar, basta registrar um @EventHandler normal do Bukkit -- não há nenhum passo separado de registro.

CannonRTPLaunchEvent

Disparado no momento em que um jogador está prestes a iniciar uma sequência de lançamento de canhão, antes que quaisquer visuais ou efeitos sejam aplicados. Cancelável.

Propriedade	Tipo	Descrição
player	Player	O jogador que acionou o canhão
cannonId	String	O id de configuração (nome do arquivo sem .yml) do canhão
cannonDisplayName	String	O campo displayName do canhão
cannonLocation	Location	A instância exata que foi acionada
destination	Location	O local de pouso seguro pré-validado escolhido para este lançamento

Cancelar o evento aborta o lançamento por completo: o jogador permanece onde está, nenhum efeito é aplicado, nenhum cooldown de lançamento interno é iniciado e o destino retorna para o início da fila do canhão. Para evitar disparar um evento persistentemente cancelado a cada tick de varredura de jogadores, o CannonRTP aumenta progressivamente o intervalo das novas tentativas de 1 segundo até 30 segundos enquanto aquele jogador permanecer dentro do gatilho; sair do gatilho ou concluir um lançamento aceito limpa esse recuo. Útil para blacklists baseadas em regiões, plugins de cooldown, restrições de economia ou verificações de regiões de PvP.

@EventHandler
public void onLaunch(CannonRTPLaunchEvent event) {
    if (event.getPlayer().getWorld().getName().equals("event_world")) {
        event.setCancelled(true);
    }
}

CannonRTPLocationValidationEvent

Disparado para cada local de pouso candidato à medida que o CannonRTP o valida durante a busca de pré-carregamento, e disparado novamente para o destino consumido quando um lançamento o revalida no momento da confirmação (logo antes do teletransporte do airdrop). Só é disparado após todas as verificações internas (limite do mundo, superfície, materiais inseguros, integrações de proteção) passarem.

Propriedade	Tipo	Descrição
cannonId	String	O id de configuração do canhão que está fazendo a busca
cannonDisplayName	String	O campo displayName do canhão
candidate	Location	O local de pouso candidato em análise

Este evento não é cancelável no sentido tradicional do Bukkit. Para vetar um candidato, chame:

event.setRejected("dentro da proteção de spawn da arena");

Durante o pré-carregamento, o CannonRTP então descarta o candidato como se ele tivesse falhado em uma verificação interna e continua a busca. No momento da confirmação, rejeitar cancela o lançamento e recupera o jogador, em vez de teleportá-lo para um local que um listener não aceita mais. Listeners podem implementar regras de região personalizadas além dos adaptadores de proteção internos.

Observação: os dois disparos acontecem na thread principal, e as tentativas de pré-carregamento rodam uma por tick globalmente, em round-robin entre os canhões ativos. Mantenha o handler rápido.

CannonRTPLandingEvent

Disparado depois que o jogador foi teleportado para o destino e a sequência de lançamento foi totalmente concluída (a fase LANDING já rodou, o Slow Falling foi removido e a rajada de impacto foi exibida). Não cancelável -- use CannonRTPLaunchEvent para vetar um lançamento antes que ele aconteça.

Propriedade	Tipo	Descrição
player	Player	O jogador que acabou de pousar
cannonId	String	O id de configuração do canhão que o lançou
cannonDisplayName	String	O campo displayName do canhão
destination	Location	Uma cópia do destino para onde ele foi enviado

Útil para conceder recompensas na primeira chegada, disparar efeitos de acompanhamento, conceder permissões de região, anunciar chegadas ou para análises.

Threading e Ciclo de Vida

• Todos os três eventos são despachados na thread principal.
• CannonRTPLocationValidationEvent é despachado durante o tick global de pré-carregamento (uma tentativa por tick do servidor, round-robin entre os canhões ativos), então trabalho pesado em listeners vai retardar visivelmente o quão rápido os canhões carregam suas filas. Ele é despachado mais uma vez por lançamento, no momento da confirmação, quando o destino da fila é revalidado.
• CannonRTPLaunchEvent é despachado imediatamente antes da construção de uma LaunchSequence, então qualquer estado que você modifique (efeitos de poção, inventário, gamemode) entra em vigor antes do início da fase de busca.
• CannonRTPLandingEvent é despachado uma vez por lançamento, no tick da fase LANDING, após a rajada de impacto.

Trabalhando com cannonId

cannonId é o mesmo id usado por todo comando administrativo (/wc place, /wc target, etc.) e corresponde ao nome do arquivo de configuração do canhão sem .yml. Note que uma única configuração de canhão pode controlar várias instâncias no mundo; todas compartilham o mesmo cannonId e cannonDisplayName. Se você precisar da instância exata, use cannonLocation de CannonRTPLaunchEvent.