AstraTemplate

AstraTemplate - это продвинутый шаблон для разработки плагинов и модов под Майнкрафт, написанный на Kotlin. Если вы когда-нибудь пытались портировать один и тот же функционал на Paper, Forge и NeoForge, то знаете, сколько времени уходит на дублирование кода и адаптацию под каждую платформу. Этот шаблон решает проблему раз и навсегда: вся логика пишется один раз в общих модулях, а точки входа под каждую платформу - это просто обёртки.

Структура проекта

Проект разделён на две основные зоны: точки входа и модули.

• instances/ - содержит точки входа для конкретных платформ: bukkit (Paper), forge, neoforge. Каждая собирается в fat jar через ShadowJar и ничего не знает о других платформах.
• modules/ - вся общая логика, разделённая на независимые модули.

Модули бывают как полностью платформонезависимые (api, core, feature-command), так и с явными привязками к платформе (feature-gui/bukkit, feature-event/bukkit и т.д.).

Ключевые модули

modules/core - база, от которой зависит всё остальное. Предоставляет:

• Конфигурацию: PluginConfiguration - @Serializable data class, сериализуется в config.yml, перезагружается по команде /atempreload через StateFlowKrate.
• Переводы: PluginTranslation - то же самое с translation.yml. Все строки имеют значения по умолчанию, так что плагин работает сразу без файлов.
• Coroutine-скопы: ioScope, mainScope, unconfinedScope на основе KotlinDispatchers. Все скопы отменяются при onDisable.

modules/api/local - локальная база данных через Jetbrains Exposed ORM. LocalDao предоставляет suspend-функции для CRUD-операций над UserTable и UserRatingTable. Подключение к БД реактивно подтягивается из конфига - сменить H2 на MySQL можно одной строчкой без перезапуска.

Поддерживаемые драйверы: H2, SQLite, MySQL, MariaDB.

modules/api/remote - REST-клиент на Ktor. В демо-примере стучится к Rick & Morty API. Все ошибки возвращаются как Result<T>, никаких исключений наружу.

modules/build-konfig - генерирует константы времени компиляции (id, version и т.д.) через BuildConfig Gradle plugin. Никаких хардкодных строк.

modules/feature-command - кроссплатформенные команды. Живут в одном месте, не содержат импортов платформы. Используют Brigadier DSL из AstraLibs, который абстрагирует разницу между Paper и Forge. Команды компилируются и работают одинаково на всех трёх платформах.

Список команд:

• /add <player> <material> [amount] - выдать предмет игроку.
• /translation - показать текущее значение перевода (полезно после перезагрузки).
• /adamage <player> <amount> - нанести урон игроку.
• /atempgui - открыть демо-интерфейс с постраничным сундуком.
• /rickandmorty random - получить случайного персонажа через REST.
• /rickandmorty specific <id> - получить персонажа по ID.
• /atempreload - перезагрузить конфиг, переводы и подключение к БД.

modules/feature-gui - разделён на api (интерфейсы Router и GuiModule) и bukkit (реализация на сундучном инвентаре с пагинацией, управляемая StateFlow). На Forge/NeoForge заглушка удовлетворяет интерфейс, чтобы общий модуль команд компилировался без Bukkit.

modules/feature-event - слушатели событий для каждой платформы свой подмодуль. Bukkit слушает BlockPlaceEvent, Forge и NeoForge слушают тик сервера.

Архитектура

В основе лежит дерево жизненных циклов (Lifecycle). Каждый модуль реализует три колбэка: onEnable, onDisable, onReload. Точка входа создаёт RootModule, который собирает все дочерние жизненные циклы и делегирует им. Это делает плагин полностью перезагружаемым в рантайме - команда /atempreload проходит по цепочке в обратном порядке и включает всё заново, подхватывая изменения конфига и переводов на лету.

Внедрение зависимостей ручное, без фреймворков. Каждый модуль - простой класс, конструктор которого принимает интерфейсы других модулей. RootModule выступает композиционным корнем и создаёт всё в правильном порядке.

Конфигурация

Конфиг и переводы - обычные @Serializable data классы, сериализуемые в YAML через kaml. Inline-документация в комментариях автоматически попадает в сгенерированный YAML-файл. Переменные хранятся как StateFlowKrate/CachedKrate, поэтому после перезагрузки все модули видят актуальные значения без дополнительной рассылки.

База данных и удалённое API

Подключение к БД меняется реактивно при изменении конфига - соединение пересоздаётся автоматически. Удалённое API через Ktor возвращает ошибки явно через Result<T>, что упрощает обработку.

Сборка

Сборка под каждую платформу: ./gradlew :instances:bukkit:shadowJar, :instances:forge:shadowJar, :instances:neoforge:shadowJar. Плагины попадают в build/libs/ и могут быть автоматически загружены на сервер через FTP Gradle plugin (настройка в libs.versions.toml).

Тестовый сервер через Docker

В проекте лежит docker-compose.yml, который запускает локальный тестовый сервер на itzg/minecraft-server. Перед запуском нужно раскомментировать блок под нужную платформу (Forge, NeoForge или Paper) и соответствующий volumes.

docker compose up

AstraTemplate - это не просто шаблон, а полноценная архитектурная основа для серьёзных проектов. Если вы разрабатываете плагины для Paper и хотите без боли портировать их на Forge или NeoForge - этот шаблон сэкономит вам часы ручной работы. Он подойдёт и тем, кто только начинает писать под Minecraft: сразу получаете правильную структуру, готовую работу с БД, GUI, REST-клиентом и кроссплатформенными командами. Просто скачайте шаблон AstraTemplate и начните кодить.