API do CannonRTP

A referência Java gerada permite pesquisar classes, métodos e assinaturas, com a versão e o commit do código-fonte registados para cada módulo.

O CannonRTP disponibiliza três eventos Bukkit aos quais outros plugins podem responder. Todos pertencem ao pacote com.magmaguy.cannonrtp.api e são disparados na thread principal do servidor.

Para os receber, registe um @EventHandler Bukkit normal; não existe uma etapa de registo adicional.

CannonRTPLaunchEvent

É disparado quando um jogador está prestes a iniciar uma sequência de lançamento, antes de aplicar qualquer efeito visual ou outro efeito. Pode ser cancelado.

Propriedade	Tipo	Descrição
player	Player	Jogador que ativou o canhão
cannonId	String	ID de configuração do canhão: nome do ficheiro sem .yml
cannonDisplayName	String	Campo displayName do canhão
cannonLocation	Location	Posição exata do canhão que foi ativado
destination	Location	Destino de aterragem seguro, previamente validado, escolhido para este lançamento

Cancelar o evento interrompe completamente o lançamento: o jogador permanece no mesmo sítio, não recebe efeitos, o tempo de espera interno entre lançamentos não começa e o destino regressa ao início da fila do canhão. Para não disparar um evento continuamente cancelado a cada tick de deteção de jogadores, o CannonRTP aumenta o intervalo entre tentativas de 1 até 30 segundos enquanto o jogador permanecer na área de ativação. Sair dessa área ou concluir um lançamento aceite repõe o intervalo. Isto permite implementar bloqueios por região, plugins de tempos de espera, requisitos económicos ou verificações de regiões PvP.

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

CannonRTPLocationValidationEvent

É disparado para cada destino candidato durante a pesquisa de pré-carregamento e novamente para o destino retirado da fila quando o lançamento o revalida na confirmação, imediatamente antes do teletransporte para a queda. No pré-carregamento, ocorre depois de passarem as verificações do limite do mundo, da superfície, dos materiais inseguros e das proteções. Na confirmação do lançamento, a referência atual do mundo, a coluna de aterragem e as integrações de proteção são novamente verificadas antes do evento. A confirmação não repete a verificação do limite do mundo.

Propriedade	Tipo	Descrição
cannonId	String	ID de configuração do canhão que está a pesquisar
cannonDisplayName	String	Campo displayName do canhão
candidate	Location	Destino de aterragem candidato em avaliação

Este evento não é cancelável no sentido habitual do Bukkit. Para rejeitar um candidato, use:

event.setRejected("inside arena spawn protection");

Durante o pré-carregamento, o CannonRTP descarta o candidato como se tivesse falhado uma verificação interna e continua a pesquisa. O motivo indicado aparece no detalhe de /wc status desse canhão como Rejected by another plugin: <reason>, até ser substituído por uma alteração de estado posterior, como um local colocado na fila ou uma pesquisa esgotada. Na confirmação, a rejeição cancela o lançamento e recupera o jogador, evitando teleportá-lo para um local que o listener já não aceita. Os listeners podem implementar regras de regiões para além dos adaptadores de proteção incluídos.

Ambos os disparos ocorrem na thread principal. O pré-carregamento realiza uma tentativa por tick no total, alternando entre os canhões ativos. Mantenha o processamento do evento rápido.

CannonRTPLandingEvent

É disparado depois de o jogador ser teleportado para o destino e de a sequência de lançamento terminar completamente: a fase LANDING já decorreu, o CannonRTP removeu o seu próprio efeito de queda lenta e a explosão visual de impacto foi reproduzida. Um efeito preexistente pode ser restaurado com a duração restante; um efeito mais recente de outra origem é preservado. Não pode ser cancelado; use CannonRTPLaunchEvent para impedir um lançamento antes de começar.

Propriedade	Tipo	Descrição
player	Player	Jogador que acabou de aterrar
cannonId	String	ID de configuração do canhão que o lançou
cannonDisplayName	String	Campo displayName do canhão
destination	Location	Cópia do destino para onde o jogador foi enviado

Permite atribuir recompensas na primeira chegada, iniciar efeitos posteriores, conceder permissões de região, anunciar chegadas ou recolher estatísticas.

Threads e ciclo de vida

• Os três eventos são disparados na thread principal.
• CannonRTPLocationValidationEvent é disparado durante o tick global de pré-carregamento: uma tentativa por tick do servidor, alternando entre os canhões ativos. Processamento pesado nos listeners abranda visivelmente o enchimento das filas. O evento volta a ser disparado uma vez por lançamento, na confirmação, quando o destino da fila é revalidado.
• CannonRTPLaunchEvent é disparado imediatamente antes da construção de uma LaunchSequence. Assim, qualquer estado alterado, como efeitos de poções, inventário ou modo de jogo, entra em vigor antes da fase de pesquisa.
• CannonRTPLandingEvent é disparado uma vez por lançamento, no tick da fase LANDING, depois da explosão visual de impacto.

Auxiliar de verificação de proteção

A classe principal do plugin também disponibiliza a verificação de proteção usada por /wc probe:

boolean allowed = CannonRTP.getInstance().isPotentialLandingLocationAllowed(location);

Devolve true quando todas as integrações de proteção ativas permitem o local, respeitando failOpenOnProtectionErrors. Não verifica o terreno, a coluna de queda, o limite do mundo nem os listeners de CannonRTPLocationValidationEvent. Devolve false até o CannonRTP ter carregado os seus canhões durante o arranque. CannonRTP é com.magmaguy.cannonrtp.CannonRTP.

Utilizar cannonId

cannonId é o ID utilizado em todos os comandos administrativos (/wc place, /wc target, etc.) e corresponde ao nome do ficheiro de configuração do canhão sem .yml. Uma única configuração pode controlar várias posições no mundo, todas com o mesmo cannonId e cannonDisplayName. Para identificar a posição exata ativada, use cannonLocation de CannonRTPLaunchEvent.