Обзор

nx-gs-adapter — Java-библиотека, которую игровой сервер встраивает, чтобы подключиться к платформе L2NX. Она работает внутри JVM ядра семейства L2J, Lucera или Essence: ядро один раз вызывает адаптер при загрузке, и дальше адаптер сам держит сервер зарегистрированным на платформе и передаёт туда его данные.

Что получает хост

• Подключение к платформе. Адаптер обменивает ключ сервера на учётные данные платформы, раз в 60 секунд сообщает, что сервер жив, и сам переподключается с backoff. Хосту не нужно работать с API платформы напрямую.
• Синхронизация БД. Персонажи, кланы, предметы и другие сущности, которые описывает хост, читаются из игровой базы и синхронизируются с платформой, включая строки, удалённые, пока сервер был выключен.
• Синхронизация runtime-состояния. Состояние, которое живёт только в памяти сервера (HP/MP/CP, координаты, vitality), доходит до платформы за секунды.
• Синхронизация игровых данных. Разобранный датапак (шаблоны предметов, NPC, скиллов, рецептов и другие) публикуется как каталог для вики, маркета и gear score.
• События и команды. Хост публикует игровые события через адаптер, а платформа присылает команды обратно (доставка почты, баны, сообщения в чат, администрирование персонажей); адаптер передаёт каждую команду обработчику, который зарегистрировал хост, и возвращает результат.

Каждая возможность — отдельный модуль: хост кладёт в classpath только то, чем пользуется.

Кто что делает

• Разработчик хоста (автор сборки игрового сервера) добавляет модули в зависимости, вызывает NxAdapter.start() при загрузке и реализует провайдеры, из которых читают модули: подключение к базе, описание схемы, состояние в памяти, каталоги игровых данных.
• Оператор (тот, кто запускает сервер) кладёт рядом с сервером l2nx.properties с ключом сервера и запускает его. Код не нужен.

Оба пути описаны в быстром старте.

Open core

Публичные модули открыты под лицензией Apache License 2.0 и публикуются в открытый репозиторий maven-oss как app.l2nx:*. Оператор может проверить каждый артефакт, который загружается в JVM игрового сервера, а сборка получает их без приватного репозитория.

Модули, в которых зашита проприетарная схема БД или раскладка датапака одного клиента, передаются только этому клиенту приватно и никогда не публикуются, чтобы схема одного клиента не утекала к другим.

Требования

• Java 8 или новее. Все модули, кроме одного, собраны под Java 8 и работают на актуальных JDK.
• Java 17 для nx-gs-db-migrator-liquibase5. Он построен на Liquibase 5, которому нужна Java 17. Игровому серверу этот мигратор нужен (см. ниже), поэтому сейчас игровой сервер работает на Java 17 или новее.
• Подключение к базе. Хост игрового сервера регистрирует ровно один JdbcConnectionSource, который выдаёт соединения из уже существующего пула. Своё состояние адаптер хранит в таблицах l2nx_* игровой базы и сам создаёт их через nx-gs-db-migrator-liquibase5 с org.liquibase:liquibase-core 5.x, который добавляет хост. Пользователю базы нужны SELECT на игровые таблицы, права на запись и DDL для таблиц l2nx_* и CREATE в схеме. Учётные данные базы остаются на хосте и никогда не передаются на платформу.
• Исходящая сеть. HTTPS к URL платформы из конфигурации и соединение с брокером Kafka, адрес которого платформа возвращает при подключении.
• Логирование. Если у хоста есть binding SLF4J, адаптер пишет логи через него; иначе — в консоль.

Модули

Модуль	Назначение
nx-gs-adapter-core	Runtime: подключение, heartbeat, поиск модулей, события, команды
nx-gs-adapter-api	Контракты и SPI, которые реализуют хост и модули
nx-gs-db-sync-core	Синхронизация БД для сущностей, которые описывает хост
nx-gs-runtime-sync-core	Синхронизация состояния из памяти сервера
nx-gs-gd-sync-core	Синхронизация каталогов игровых данных (датапака)
nx-gs-db-migrations	Changelog таблиц l2nx_*, которыми владеет адаптер
nx-gs-db-migrator-liquibase5	Применяет этот changelog через Liquibase 5 (Java 17+)
nx-gs-kafka	Лёгкий клиент Kafka, которым пользуются остальные модули
nx-gs-commons	Общие утилиты остальных модулей

Версии

У каждого модуля своя версия и свой выпуск: тег релиза выглядит как core/v0.44.0 или db-sync/v0.12.0 и публикует только этот модуль. Релизы всех модулей собраны в changelog; к breaking changes прилагаются шаги в руководстве по миграции.