API CannonRTP

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

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

CannonRTPLaunchEvent

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

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

Отмена события полностью прерывает запуск: игрок остаётся на месте, никакие эффекты не применяются, а точка назначения возвращается в начало очереди пушки для повторного использования при следующем запуске. Полезно для региональных чёрных списков, плагинов задержки, экономических ограничений или проверок 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.