dmulloy2/ProtocolLib
Предоставляет доступ к протоколу Minecraft с помощью Bukkit.
Посмотреть на GitHub ↗Знаете ли вы, как создать плагин для сервера Minecraft, который делает что-то, чего не позволяет стандартный API Bukkit? Да, именно здесь большинство разработчиков сталкиваются со стеной. Вам либо приходится обратно проектировать обфусцированный код Minecraft (который ломается при каждом обновлении), либо подключаться к внутренним классам CraftBukkit (и молиться, чтобы ни один другой плагин не делал того же), или просто сдаться. ProtocolLib - это проект, который существует именно для того, чтобы вам не пришлось этого делать.
Что решает этот проект
ProtocolLib - это библиотека Java, предоставляющая чистый, безопасный доступ к сетевому протоколу Minecraft. Вместо борьбы с обфусцированным байт-кодом или хаками с использованием отражения, вы получаете правильный API событий, позволяющий слушать, модифицировать или отменять пакеты, отправляемые между сервером и клиентами. Представьте себе Bukkit события, но для протокольного слоя.
Большая победа: вы не ссылаетесь на CraftBukkit вовсе. Нет версионно-зависимых импортов, которые ломаются в 1.21. Нет хрупких предположений о внутренних структурах классов. Только слушатели пакетов, которые остаются стабильными при обновлениях.
Реальные примеры использования в Minecraft
Фильтрация и модерация чата - это наиболее очевидное применение. Слушайте клиентские пакеты чата, читайте содержимое сообщения через API ProtocolLib, и отменяйте пакет, если игрок пытается сделать что-то запрещенное. Сообщение даже не достигает сервера. Чисто, просто, и работает при каждом обновлении.
Пользовательские сетевые функции - это то, где все становится интересным. Вы могли бы построить невидимые эффекты частиц, изменить внешний вид игрока без изменений в скинах, или отправить данные на сервер, которые официально не поддерживаются стандартным протоколом. Система дуэлей с пользовательскими визуальными эффектами? Интерфейс голосования, реагирующий на пакеты движения игрока? Это именно то, что ProtocolLib делает возможным.
Но реальная причина, по которой большинство людей обращаются к нему, - это совместимость плагинов. Когда несколько плагинов подключаются к одним и тем же внутренним классам, все становится хаотичным. Плагины крах themselves, данные悄悄 повреждены. ProtocolLib централизует обработку пакетов, чтобы разные плагины могли действительно сосуществовать без поднятия на ноги друг друга. Это не гламурно, но это то, что держит серверы в рабочем состоянии.
Установка и Настройка
Если вы строите плагин Bukkit, настройка проста. Сначала добавьте зависимость в ваш файл сборки.
Для Maven:
<dependencies>
<dependency>
<groupId>net.dmulloy2</groupId>
<artifactId>ProtocolLib</artifactId>
<version>5.4.0</version>
<scope>provided</scope>
</dependency>
</dependencies>Примечание: версия 5.4.0 требует Java 17 или выше, поэтому убедитесь, что ваша среда сборки актуальна. Если вы на старом сервере, возьмите более ранний релиз вместо этого.
Пользователям Gradle следует добавить его так:
repositories {
mavenCentral()
}
dependencies {
compileOnly 'net.dmulloy2:ProtocolLib:5.4.0'
}Затем добавьте ProtocolLib в качестве зависимости в ваш файл plugin.yml:
depend: [ ProtocolLib ]Это сообщает серверу, что ваш плагин не запустится, если ProtocolLib не загрузится первым. Критично для избежания исключений null при запуске. Затем получите ссылку на ProtocolManager в методе onLoad() вашего плагина:
private ProtocolManager protocolManager;
public void onLoad() {
protocolManager = ProtocolLibrary.getProtocolManager();
}Готово. Вы готовы начать слушать пакеты.
Как работают слушатели пакетов
Самый простой слушатель просто отключает что-то. Скажем, вы хотите отключить все звуковые эффекты на сервере:
protocolManager.addPacketListener(new PacketAdapter(
this,
ListenerPriority.NORMAL,
PacketType.Play.Server.NAMED_SOUND_EFFECT
) {
@Override
public void onPacketSending(PacketEvent event) {
event.setCancelled(true);
}
});Большая часть сложности уже здесь. Вы создаете PacketAdapter, указываете тип пакета, на который слушаете, переопределяете обратный вызов и изменяете событие.
Где это становится полезным - это чтение и изменение содержимого пакета. Вот пример глобального фильтра чата:
protocolManager.addPacketListener(new PacketAdapter(
this,
ListenerPriority.NORMAL,
PacketType.Play.Client.CHAT
) {
@Override
public void onPacketReceiving(PacketEvent event) {
PacketContainer packet = event.getPacket();
String message = packet.getStrings().read(0);
if (message.contains("badword")) {
event.setCancelled(true);
}
}
});Вызов getPacket() дает вам данные пакета. Вы читаете поля по типу (строки, целые числа, байты) через их индекс. Нет имен полей, только позиции. Это абстрактно сначала, но это означает, что вы никогда не зависите от внутренних имен Minecraft, которые постоянно меняются из-за обфусцирования.
Вы также можете изменять пакеты. Данные пакета изменяемы, поэтому вы можете записывать новые значения перед их отправкой. Приоритет слушателя также важен - если несколько плагинов слушают один и тот же тип пакета, LOWEST запускается первым, HIGHEST - последним, позволяя вам контролировать порядок выполнения.
Ключевые особенности, делающие это полезным
Слои абстракции - это главное. Вместо работы с обфусцированными классами NMS (net.minecraft.server), ProtocolLib обертывает все в типизированные доступы. Хотите прочитать позицию игрока? Это просто packet.getDoubles().read(0), а не поиск в лабиринте методов getter в каком-то внутреннем классе, который, вероятно, переименовали в последней снапшоте.
Совместимость версий огромна. ProtocolLib поддерживает определения пакетов для каждого主要 релиза Minecraft. Когда вы обновляете сервер с 1.20 до 1.21.4, ваш код ProtocolLib просто работает. Библиотека внутренне обрабатывает изменения протокола. Вам не нужно перекомпилировать ничего.
Внедрение пакетов - еще одна полезная функция. Вы можете создавать пакеты с нуля и отправлять их игрокам:
PacketContainer packet = protocolManager.createPacket(PacketType.Play.Server.NAMED_SOUND_EFFECT);
// заполните поля...
protocolManager.sendServerPacket(player, packet);Это чисто по сравнению с попыткой直接 инстанцировать классы NMS пакетов. И снова, это выживает при обновлениях без изменений.
Библиотека также включает в себя вспомогательные классы, такие как WrappedChatComponent, ChunkData и PlayerInfoData - по сути, все, что сложно конструировать, обернуто в удобные генераторы. Недавний релиз 5.4.0 исправил проблемы инициализации для версий 1.20.4 через 1.21.5, поэтому они активно поддерживаются.
Что подбрасывает новичков
Доступ к полям по индексу требует привыкания. Вам нужно посмотреть вики пакетов, чтобы понять, какой индекс соответствует какому полю. Для общих пакетов это документировано, но если вы имеете дело с чем-то пользовательским или очень новым, вы на свой счет. Это компромисс за то, что вы не привязаны к внутренним именам классов.
Важно безопасность потоков. Minecraft выполняет обработку пакетов в сетевом потоке, и ваш код слушателя также выполняется там. Если вы делаете что-то тяжелое, запланируйте это в основной поток сервера через Bukkit.getScheduler(). Блокировка вашего слушателя пакетов парализует整个 сетевой конвейер.
Несовпадение версий уничтожит вас. Если вы компилируете против ProtocolLib 5.4.0, но сервер имеет 5.3.0, вы получаете ошибку «класс не найден» во время выполнения. Убедитесь, что версии совпадают точно. Не полагайтесь на функции из более новых релизов, если не указали минимальную версию в вашем plugin.yml.
Отладка сложнее, чем обычный код, потому что все это основано на слушателях. Если пакет не ведет себя правильно, добавьте логирование на каждом шаге. Убедитесь, что ваш слушатель вызывается. Проверьте, что индексы полей соответствуют тому, что вы ожидаете. Вики протокола - ваш друг здесь.
Альтернативы и когда их рассматривать
PacketEvents существует как другой вариант, хотя он новее и менее проверен на баттах. Если вы строите что-то, требующее глубокого доступа к протоколу с современными инструментами и не возражаете против немного менее стабильной почвы, PacketEvents может привлечь ваше внимание. Но ProtocolLib - это устоявшийся выбор - 1285 звезд на GitHub, активно поддерживается, и последний релиз поддерживает Minecraft 1.21.4 через 1.21.8.
Некоторые разработчики работают напрямую с NMS для высокоспециализированных случаев использования. Это обычно ошибка, потому что вы подписываетесь на работу по обслуживанию при каждом релизе Minecraft. ProtocolLib делает это за вас.
Если вам нужно исследовать, что игроки могут делать с вашим сервером, посмотрите наши инструменты Создатель Скинов для Minecraft и Поиск Блоков для Minecraft.
dmulloy2/ProtocolLib - GPL-2.0, ★1285


