BKCommonLib

BKCommonLib - это не просто очередной плагин для сервера Minecraft, а мощная библиотека и API для Paper/Spigot/Bukkit. Если ты когда-нибудь писал плагины, то знаешь, как больно работать с NMS (Minecraft Server Code) - при каждом обновлении игры всё ломается. BKCommonLib решает эту проблему раз и навсегда.

Зачем это нужно?

В ванильном Minecraft серверный код постоянно меняется. Разработчикам плагинов приходится переписывать свои проекты под каждую новую версию. BKCommonLib берёт на себя всю работу с NMS, предоставляя стабильный API. Теперь, когда выходит новая версия Minecraft, достаточно обновить только эту библиотеку - все плагины, использующие её, продолжат работать без изменений.

Что внутри?

BKCommonLib - это огромный набор инструментов. Вот основные фишки:

Mountiplex - магия рефлексии

Это ядро библиотеки. Mountiplex позволяет генерировать совместимый код прямо во время работы сервера. Он объединяет ASM, Javassist и Objenesis с шаблонным движком. Это значит, что тебе не нужно компилировать разные классы под Paper, Spigot, Forge и их форки. Если что-то меняется - просто добавь блок #if - #endif.

Cloud Command Framework

Забудь про громоздкие обработчики команд. Cloud позволяет писать чистые команды с аннотациями или builder-паттерном. Подсказки, права, локализация - всё из коробки.

PluginBase - база для твоего плагина

Вместо JavaPlugin используй PluginBase. Получаешь:

• Поддержку предзагрузчика
• Колбэки при включении других плагинов
• Валидацию зависимостей
• Простую регистрацию слушателей
• Permission API с поддержкой wildcard и настройками по умолчанию
• Локализацию с авто-генерацией YAML-файлов

SoftDependency Library

Упрощает работу с мягкими зависимостями. Не нужно вызывать методы в onEnable() - всё делается лениво и автоматически.

Серверные события

Добавляет события, которых нет в Bukkit:

• Chunk Load/Unload Entities event
• CreaturePreSpawnEvent
• Entity Add/Remove events
• MultiBlockChangeEvent (интеграция с WorldEdit)

YAML Configuration

Стандартный Bukkit Configuration API - это боль. BKCommonLib предлагает свою реализацию:

• Быстрое чтение/запись
• Поддержка комментариев для каждого ключа
• Автоконвертация цветов Minecraft (& -> ChatColor)
• Асинхронное сохранение с кэшированием
• Change listeners - узнавай, когда изменился любой узел конфига

NBT - CommonTag API

Удобная обёртка для работы с NBT:

• Чтение/запись .dat файлов
• Модификация NBT предметов, профилей игроков, level.dat
• Работа напрямую с внутренней библиотекой сервера - никакого копирования

ForcedChunk - загрузка чанков без лагов

Нужно загрузить чанк и держать его активным? Используй ForcedChunk:

• Асинхронная загрузка
• Удержание чанка с помощью тикетов (RAII AutoCloseable)
• Поддержка радиуса для тиков сущностей

Chunk Future Provider

Работай с загрузкой/выгрузкой чанков через CompletableFuture. Полезно для:

• Поиска мультиблочных структур
• Чтения табличек с редстоуном
• Спавна кастомных сущностей
• Автоматическая отмена фьючерсов при выгрузке чанка

Block Utilities

Утилиты для работы с блоками:

• OfflineBlock/OfflineWorld - храни ссылки на блоки без риска утечки памяти
• SignChangeTracker - отслеживай изменения табличек без дорогих запросов к серверу
• BlockData - быстрая замена Bukkit BlockData с поддержкой разных версий Minecraft

Интерактивные карты (Map Display API)

Хочешь создавать кастомные интерфейсы на картах? BKCommonLib делает это просто:

• Рендеринг 2D/3D контента на картах и текстурных буферах
• Свой event loop (onTick)
• Автоматическое назначение ID карт через Item Metadata
• Поддержка тайлинга ItemFrame для больших дисплеев
• Научная конвертация RGB в цвета карт Minecraft
• Рендеринг блоков, предметов и ресурспаков
• Обработка кликов по ItemFrame с координатами пикселей
• Виджеты: кнопки, текст, вкладки, меню с управлением WASD/Space/Sneak

Entity Controllers - полный контроль над мобами

Расширяй классы сущностей прямо во время работы сервера:

• Переопределяй onTick() и onMove()
• Хотсвап существующих сущностей на кастомное поведение без потери данных
• Контролируй сетевую синхронизацию (пакеты)
• Именно так работает TrainCarts!

Protocol API - работа с пакетами

Мультиверсионный Packet API:

• Использует ProtocolLib, если он установлен
• Слушатели и мониторы пакетов (модификация, отмена)
• Отправка пакетов с возможностью обхода слушателей
• EntityUtil.getUniqueEntityId() для спавна фейковых сущностей
• Полный API для модификации полей пакетов (движение, DataWatcher)
• VehicleMountController - управление пассажирами и спектаторами без глюков порядка спавна/удаления пакетов

Java Utilities - мелочи, которые спасают жизнь

Коллекции:

• FastUtil Int/LongHashMap
• Implicitly shared collections (copy-on-concurrent-write)
• Immutable cached collections (безопасно для миллионов сетов игроков)
• Octree/DoubleOctree - 3D пространственные запросы (кубоиды)
• FastTrackedUpdateSet - эффективная очередь обновлений для получателей
• SortedIdentityCache - кэш с отслеживанием изменений в сторонних коллекциях
• BlockFaceSet - хранение значений BlockFace в сете без дубликатов

Математика:

• 3D трансформации: Quaternion, Matrix4x4 с конвертацией yaw/pitch/roll
• 3D Rotatable Bounding Box с hit-testing'ом
• IntVector2 (координаты чанков) и IntVector3 (координаты блоков)
• BlockFace логика/повороты/математика
• Быстрые тригонометрические функции (FastTrig)

LogicUtil:

• Функциональные интерфейсы для consumer/supplier с исключениями (throws)
• Хелперы для Java 8 Stream API и CompletableFuture'ов
• Клонирование коллекций с разрешением типа во время выполнения (runtime)
• synchronizeCopyOnWrite - обновление иммутабельных маппингов и кэшей производительности без блокировок на чтение (copy-on-write)

I/O:

• Hastebin uploader/downloader клиент (загрузка/скачивание на hastebin)
• ByteArrayIOStream - мост между Byte Array и Stream API (чтение/запись байтовых массивов как потоков)
• Bit Packet/IO-streams - кодирование/декодирование битового потока (побитовая упаковка данных)
• AsyncTextWriter - асинхронное кодирование текста и запись в файл с фьючером (используется YAML)

LibraryComponent:

• Отслеживай логику плагина и включай/выключай компоненты в правильном порядке (управление зависимостями компонентов)
• Включай разные компоненты в зависимости от условий (например, версия сервера)
• Обработка ошибок (error handling) внутри компонентов без краша всего плагина.

Разное (Miscellaneous)

Много чего ещё спрятано в утилитных классах:

• Эффективная итерация сущностей мира/чанка без создания мусорных массивов или копий списков (не создаёт лишних объектов в куче)
• ChatText: простой Chat Component API (работа с JSON чатом без лишней головной боли)
• HumanHand: поддержка off-hand и held items в кросс-версионном виде (работает в разных версиях Minecraft)
• Inventory utilities: утилиты для работы с инвентарями (создание, модификация, клики)
• Парсинг ввода текста в числа, материалы и другое (конвертация строк в нужные типы)
• Deregister event listeners: отмена регистрации слушателей событий (когда нужно отключить обработчик динамически)
• Чтение текущего тика сервера (current server tick value) - узнай точное время внутриигрового тика.
• Делегирование задач на главный поток и синхронизация (main thread Task delegation and synchronization) - безопасно выполняй код на главном потоке из других потоков.
• DebugUtil: модификация поведения/параметров во время выполнения (runtime) для отладки без перекомпиляции.
• Проверка игровой версии подключенного игрока (ViaVersion / ProtocolSupport) - узнай, какая версия Minecraft у игрока.
• SignEditDialog: покажи игроку попап для ввода 4 строк текста таблички без реального блока таблички (удобно для кастомных интерфейсов).
  • Укажи начальный текст на табличке.
  • Не требует наличия реального блока таблички в мире.
  • Полезно для создания кастомных меню или диалогов.

Совместимость и установка BKCommonLib на сервер Minecraft

BKCommonLib работает на большинстве форков Spigot/Paper: PaperMC, Pufferfish, Purpur, Tuinity, TacoSpigot. Также поддерживаются гибриды Forge+Paper: Mohist 1.12.2/1.16.5, Magma 1.12.2, Arclight 1.12.2/1.15.2/1.16.5/1.18.2, CatServer 1.12.2. Самое крутое - последняя версия BKCommonLib совместима со всеми версиями Minecraft от 1.8 и выше. То есть версия 1.19 будет работать на Spigot 1.12.2 или Paper 1.16.5. Не надо ставить старые версии под старые Minecraft! Если после обновления Minecraft или Paper библиотека перестала работать - загляни на сборочный сервер, там уже могут быть дев-сборки с фиксом.

Для разработчиков: как подключить BKCommonLib к своему проекту?

Если хочешь использовать BKCommonLib в своих плагинах, вот зависимости: Maven:

    <repository>
        <id>MG-Dev Jenkins CI Maven Repository</id>
        <url>https://ci.mg-dev.eu/plugin/repository/everything</url>
    </repository>
</repositories>
<dependencies>
    <dependency>
        <groupId>com.bergerkiller.bukkit</groupId>
        <artifactId>BKCommonLib</artifactId>
        <version>1.20.2-v1</version>
        <scope>provided</scope>
    </dependency>
</dependencies>```
**Gradle:**
```groovyrepositories {
    maven {
        url = 'https://ci.mg-dev.eu/plugin/repository/everything'
    }
}
dependencies {
    compileOnly 'com.bergerkiller.bukkit:BKCommonLib:1.20.2-v1'
}```
Не забудь обновить версию под свою сборку.
## Лицензия и важные моменты 
Проект распространяется по MIT лицензии. Автор разрешает копипастить код из библиотеки в свои плагины, но не рекомендует пытаться переписать сложные фреймворки вроде Map Display API - скорее всего получится криво и будет конфликтовать с самой BKCommonLib.
Внутри библиотеки используются: Cloud Command Framework (форк), ASM, Javassist, Objenesis, SnakeYAML, Google GSON.
Если хочешь собрать BKCommonLib самостоятельно - сначала запусти Build Tools для Spigot, иначе тесты упадут.
Скачать плагин BKCommonLib можно на Modrinth или SpigotMC.