Полный гид по созданию Minecraft Datapack с Kore

Рука-рука создание Minecraft datapack'ов похоже на сбор мебели без инструкций: технически возможно, но вы потратите часы на отладку синтаксических ошибок и дублированный код. Kore помогает обойти эту проблему, позволяя строить datapack'и на Kotlin, типобезопасном языке, который находит ошибки до того, как они станут сломанными игровыми механиками.

Что делает этот проект

Kore - это библиотека на Kotlin, превращающая создание datapack'ов из утомительного управления файлами в реальное программирование. Вместо ручного написания JSON-файлов и скриптов команд вы пишете код на Kotlin, который генерирует все для вас. Она предназначена для Minecraft Java 1.20 и новее (включая текущий релиз 26.1.2), и обрабатывает повторяющиеся задачи: пространство имен функций, генерация тегов, структура таблиц добычи, валидация синтаксиса команд.

Библиотека поставляется в модульных частях. Начните с основного модуля `kore` и добавляйте другие только когда это необходимо. И это важно, потому что datapack'и сильно различаются по объему. Маленький проект улучшения vanilla не требует тех же инструментов, что и проект, строящий целую кастомную систему прогресса.

Почему вы бы использовали это

Дело в том: если вы игрок Minecraft, который когда-либо думал «Я хотел бы, чтобы был datapack, делающий X», вы, вероятно, пытались либо скачать чужую работу, либо отказались. Но что, если вы программист? Это все меняет.

Реальный сценарий: Вы хотите создать кастомную систему крафта с уникальными инструментами, работающими только с определенными блоками. В vanilla datapack JSON вы пишете одни и те же шаблоны предикатов снова и снова. С Kore вы пишете это один раз, ссылаетесь на это везде, и если вам нужно изменить логику, вы меняете это в одном месте. Типобезопасность означает, что вы не сможете случайно опечататься в свойствах селектора или сослаться на несуществующую функцию.

Другой сценарий: Вы строите сервер с сотнями кастомных цепочек достижений. Ручное редактирование JSON-файлов в таком масштабе - это приглашение для ошибок. Kore позволяет использовать циклы, переменные и функции для генерации их программно. Хотите создать 50 вариантов механики прогресса? Один цикл и все.

Или вы создаете косметические datapack'и с эффектами частиц. Typed selector builders Kore делают действительно простым построение сложного целевого выбора игроков без запоминания полной синтаксиса селектора. Это важно, когда вы наложите условия: целевые игроки в режиме выживания, в пределах радиуса, у которых нет определенного тега.

Начало работы

Установка проста, если вы уже используете Gradle. Добавьте зависимость в ваш `build.gradle.kts`:

dependencies {
 implementation("io.github.ayfri.kore:kore:2.0.2-1.21.11")
}

kotlin {
 compilerOptions {
 freeCompilerArgs.add("-Xcontext-parameters")
 }
 jvmToolchain(21)
}

Флаг `-Xcontext-parameters` важен; он активирует магию DSL Kore. Требуется Java 21 или новее, что не должно быть проблемой в наше время.

Самый простой способ начать - это клонировать проект Kore Template, который дает вам рабочую настройку сборки и примерную структуру, уже настроенную. Альтернативно, создайте файл `Main.kt` и начните с Руководства по началу работы из официальной документации.

Если вы хотите самые свежие версии, собранные из каждого коммита, добавьте репозиторий Sonatype snapshots и используйте суффикс `-SNAPSHOT`. Большинство людей не нуждаются в этом; придерживайтесь стабильных релизов из Maven Central.

Ключевые особенности, которые имеют значение

Typed Selectors: Построение целевых селекторов Minecraft - это то, где люди обычно начинают делать ошибки. Kore предоставляет API-строитель, предотвращающий неверные комбинации. Вы получаете автозамену в IDE, а не гадание по синтаксису селектора. Хотите игроков с баллом от 5 до 10? Напишите это с правильными методами вместо поиска в документации.

Построение команд: Библиотека знает синтаксис каждой команды Minecraft 1.20+. Это означает валидацию на этапе компиляции. Если вы опечатались в аргументе команды, ваш сборка завершится неудачно, а не ваш datapack. Руководство по командам в документации полное, охватывая все - от базовых команд `tell` до сложных блоков `say` с форматированием.

Модульная архитектура: Основная функциональность отделена от специализированных модулей. Хотите работать с деревьями достижений? Добавьте модуль advancements. Строите предикаты предметов? Добавьте этот модуль. Вы загружаете только то, что используете, что снижает время сборки и когнитивную нагрузку.

В последнем релизе добавлен раздел «Книга рецептов» в документацию, в которой пройдуты общие шаблоны: манипуляция NBT сущностями, условные операторы на основе счетчиков, эффекты частиц. Это не очевидно, когда вы начинаете, поэтому наличие документации экономит время, избегая проб и ошибок.

Что подводит людей подводкой

Самая большая проблема: кривая обучения Kotlin. Если вы никогда не касались Kotlin раньше, есть период адаптации. Это похоже на Java, но с достаточным количеством синтаксиса-сахара, чтобы случайные предположения ломались. Ничто не непреодолимое для кого-либо с опытом программирования, но стоит знать заранее.

Второе: Структура каталога вывода сборки. Убедитесь, что вы понимаете, куда Kore записывает сгенерированные файлы, и что ваша среда разработки (тестовый сервер, папка сборки) настроена на загрузку их. Забывание этого стоит времени отладки.

Флаг компилятора `-Xcontext-parameters` обязательен для работы DSL. Забудьте его, и вы получите криптические ошибки о пропущенных контекстных получателях. Он есть во всех руководствах по настройке, но подводит людей, которые настраивают сборку кастомно.

Как это сравнивается с альтернативами

Точного эквивалента нет. DataPack Crafters - это визуальный редактор datapack'ов, но он ограничен и не справится со сложной логикой. Вариант написания datapack'ов на JavaScript существует, но тогда вам придется изучать еще один язык и разбираться с другим инструментарием.

Честный взгляд: Kore предполагает, что вы либо знаете Kotlin, либо хотите его изучить. Если вы комфортно чувствуете себя с Python или Java и хотите DSL для datapack'ов, это ваш лучший выбор. Если вы никогда не хотите касаться кода, Kore не является инструментом.

Проект имеет хорошую поддержку сообщества через Slack и Discord, и мейнтейнер (Ayfri) активно рассматривает проблемы и запросы на слияние. Документация тщательна и идёт на пароли с релизами Minecraft.