API CannonRTP

CannonRTP предоставляет три события Bukkit, к которым могут подключаться другие плагины. Все события находятся в пакете com.magmaguy.cannonrtp.api и вызываются в основном потоке сервера.

Чтобы прослушивать их, зарегистрируйте обычный Bukkit @EventHandler — отдельного шага регистрации нет.

CannonRTPLaunchEvent

Вызывается в момент, когда игрок собирается начать последовательность запуска пушки, до применения каких-либо визуальных эффектов. Отменяемое.

Свойство	Тип	Описание
player	Player	Игрок, активировавший пушку
cannonId	String	Id конфигурации (имя файла без .yml) пушки
cannonDisplayName	String	Поле displayName пушки
cannonLocation	Location	Точное размещение, которое было активировано
destination	Location	Предварительно проверенная безопасная точка приземления, выбранная для этого запуска

Отмена события полностью прерывает запуск: игрок остаётся на месте, никакие эффекты не применяются, встроенная задержка запуска не начинается, а точка назначения возвращается в начало очереди пушки. Чтобы не вызывать постоянно отменяемое событие в каждый тик сканирования игроков, CannonRTP увеличивает интервал повторных попыток с 1 секунды до 30 секунд, пока игрок остаётся внутри зоны срабатывания; выход из зоны или завершение принятого запуска сбрасывает эту задержку. Полезно для региональных чёрных списков, плагинов задержки, экономических ограничений или проверок PvP-зон.

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

CannonRTPLocationValidationEvent

Вызывается для каждой точки-кандидата на приземление, когда CannonRTP проверяет её во время поиска для предзагрузки, и вызывается ещё раз для использованной точки назначения, когда запуск повторно проверяет её в момент подтверждения (непосредственно перед телепортацией высадки). Вызывается только после того, как пройдут все встроенные проверки (граница мира, поверхность, небезопасные материалы, интеграции с защитой).

Свойство	Тип	Описание
cannonId	String	Id конфигурации пушки, выполняющей поиск
cannonDisplayName	String	Поле displayName пушки
candidate	Location	Рассматриваемая точка-кандидат для приземления

Это событие не отменяемое в смысле Bukkit. Чтобы отклонить кандидата, вызовите:

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

Во время предзагрузки CannonRTP затем отбросит кандидата, как если бы тот не прошёл внутреннюю проверку, и продолжит поиск. В момент подтверждения отклонение вместо этого отменяет запуск и возвращает игрока в безопасное место, а не телепортирует его туда, где слушатель больше не разрешает приземление. Слушатели могут реализовывать собственные правила регионов сверх встроенных адаптеров защиты.

Примечание: обе отправки события происходят в основном потоке, а попытки предзагрузки выполняются по одной в тик глобально, round-robin между активными пушками. Делайте обработчик быстрым.

CannonRTPLandingEvent

Вызывается после того, как игрок был телепортирован в точку назначения и последовательность запуска полностью завершена (фаза LANDING отработала, эффект Замедленного падения снят и проигрался эффект удара). Не отменяемое — используйте CannonRTPLaunchEvent, чтобы отклонить запуск до его начала.

Свойство	Тип	Описание
player	Player	Игрок, который только что приземлился
cannonId	String	Id конфигурации пушки, которая его запустила
cannonDisplayName	String	Поле displayName пушки
destination	Location	Копия точки назначения, в которую он был отправлен

Полезно для выдачи наград при первом прибытии, запуска последующих эффектов, выдачи региональных прав, оповещения о прибытии или аналитики.

Потоки и жизненный цикл

• Все три события диспетчеризуются в основном потоке.
• CannonRTPLocationValidationEvent диспетчеризуется во время глобального тика предзагрузки (одна попытка в тик сервера, round-robin между активными пушками), поэтому тяжёлая работа в слушателях будет заметно замедлять заполнение очередей пушек. Оно диспетчеризуется ещё раз при каждом запуске, в момент подтверждения, когда точка назначения из очереди проверяется повторно.
• CannonRTPLaunchEvent диспетчеризуется непосредственно перед созданием LaunchSequence, так что любое состояние, которое вы изменяете (эффекты зелий, инвентарь, режим игры), вступает в силу до начала фазы поиска.
• CannonRTPLandingEvent диспетчеризуется один раз за запуск, в тик фазы LANDING, после эффекта удара.

Работа с cannonId

cannonId — это тот же id, что используется всеми командами администратора (/wc place, /wc target и т. д.) и совпадает с именем файла конфигурации пушки без .yml. Обратите внимание, что одна конфигурация пушки может управлять многими размещениями в мире; все они разделяют один и тот же cannonId и cannonDisplayName. Если вам нужно конкретное размещение, используйте cannonLocation из CannonRTPLaunchEvent.