API CannonRTP

Сгенерированный справочник Java позволяет искать классы, методы и сигнатуры; для каждого модуля указаны версия исходного кода и коммит.

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

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

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

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

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

Во время предзагрузки CannonRTP затем отбросит кандидата, как если бы тот не прошёл внутреннюю проверку, и продолжит поиск. Переданная вами причина отображается в подробностях пушки в /wc status как Rejected by another plugin: <reason>, пока её не заменит следующее изменение статуса, например точка, добавленная в очередь, или исчерпанный поиск. В момент подтверждения отклонение вместо этого отменяет запуск и возвращает игрока в безопасное место, а не телепортирует его туда, где слушатель больше не разрешает приземление. Слушатели могут реализовывать собственные правила регионов сверх встроенных адаптеров защиты.

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

CannonRTPLandingEvent

Вызывается после телепортации игрока и полного завершения последовательности: фаза LANDING выполнена, CannonRTP снял собственный эффект замедленного падения и воспроизвёл эффект удара. Предыдущий эффект может быть восстановлен с оставшейся длительностью; более новый эффект из другого источника сохраняется. Событие нельзя отменить — используйте CannonRTPLaunchEvent, чтобы отклонить запуск до его начала.

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

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

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

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

Вспомогательная проверка защиты

Главный класс плагина также предоставляет проверку защиты, которую использует /wc probe:

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

Метод возвращает true, если каждая включённая интеграция защиты разрешает эту точку, с учётом failOpenOnProtectionErrors. Он не проверяет рельеф, столб для высадки, границу мира и слушателей CannonRTPLocationValidationEvent. Пока CannonRTP не загрузил свои пушки при запуске, метод возвращает false. CannonRTP — это com.magmaguy.cannonrtp.CannonRTP.

Работа с cannonId

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