Konfig

Konfig — универсальная библиотека конфигурации для модов

Konfig — это эргономичная библиотека конфигурации, предназначенная для разработчиков модов Minecraft. Она позволяет объявлять типизированные значения конфигурации в общем коде, сохранять их в закомментированные файлы TOML, синхронизировать выбранные параметры между клиентами и автоматически генерировать экраны настроек. Библиотека создана для использования в общем коде, разделяя интеграцию с загрузчиками (Fabric, Forge, NeoForge) от логики объявления, валидации и миграции настроек.

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

Konfig предоставляет разработчикам полный набор инструментов для создания удобных систем настроек. Библиотека поддерживает типизированные значения для булевых флагов, чисел, перечислений (enums), строк, списков строк, цветов RGB/ARGB и пользовательских кодеров.

Одной из главных особенностей является поддержка контекстно-зависимых областей конфигурации: настройки могут быть помечены как CLIENT (только для клиента), COMMON (доступны всем частям) или SERVER (только для сервера). Это позволяет гибко управлять доступом к данным.

Библиотека автоматически генерирует экраны настроек для зарегистрированных обработчиков, предоставляя встроенные элементы управления. Разработчики могут добавлять кастомные элементы: заголовки, изображения, описательный текст и кликабельные URL-ссылки. Для каждого элемента можно задать явные подсказки (tooltips) и расширенные панели с информацией (hover info) для глобальной помощи или специфичной для категории и значения.

Управление синхронизацией и миграция

Для управления изменениями конфигурации Konfig предлагает встроенные режимы синхронизации: NONE (без синхронизации), LOGIN (синхронизация при входе) и LOGIN_AND_RELOAD (синхронизация при входе и перезагрузке мира). Это позволяет разработчикам точно контролировать, когда обновления настроек должны быть применены к клиенту.

Система включает поддержку версионирования схемы и пошаговую миграцию данных. Если конфигурация модов меняется, Konfig помогает безопасно переносить старые значения в новые поля, избегая потери данных пользователями.

Экраны настроек генерируются автоматически, но их можно дорабатывать. Поддерживаются встроенные декорации: заголовки, изображения, текстовые описания и ссылки. Для строк и цветов доступны редакторы с использованием реестра ресурсов игры, что позволяет выбирать предметы, сущности или цвета из списка доступных в игре с помощью иконок.

Интеграция с загрузчиками и установка

Konfig работает на платформах Fabric, Forge и NeoForge. Для каждого загрузчика существует отдельный артефакт, который нужно добавить в проект. Например, для Fabric используется konfig-fabric, для Forge — konfig-forge, а для NeoForge — konfig-neoforge. Прямая зависимость от общего модуля konfig-common запрещена; всегда следует использовать версию, соответствующую целевому загрузчику.

Для добавления репозитория в Gradle используется репозиторий Kaf Maven:
`groovy
repositories {
maven {
url = "https://maven.kaf.sh"
}
}
`

Интеграция с Fabric Mod Menu позволяет отображать кнопку настройки мода в меню модов. Для Forge и NeoForge доступны помощники для создания кнопок конфигурации в интерфейсе загрузки сервера.

Пример использования в коде

Библиотека позволяет объявлять настройки в статическом блоке класса. Пример создания конфигурации для общего кода:

`java
public final class ExampleConfig {
public static final ConfigHandle HANDLE;
public static final ConfigValue ENABLED;
public static final ConfigValue RANGE;

static {
ConfigBuilder builder = Konfig.builder("examplemod", "common")
.scope(ConfigScope.COMMON)
.syncMode(SyncMode.LOGIN)
.comment("Example mod config")
.info(info -> info
.header("Example Mod")
.inlineText("These settings control shared gameplay behavior.")
.url("Documentation", "https://example.invalid/docs"));

builder.header("Example Mod Settings");
builder.inlineText("These entries are saved automatically.");
builder.url("Documentation", "https://example.invalid/docs");

builder.push("general");
builder.categoryComment("General gameplay tuning");
builder.categoryTooltip("General gameplay tuning");
builder.categoryInfo(info -> info
.header("General")
.inlineText("Values in this section affect the whole mod."));

ENABLED = builder.bool("enabled", true)
.comment("Master toggle")
.tooltip("Enable example mod features")
.sync(true)
.info(info -> info
.header("Master Toggle")
.inlineText("Turns the main feature set on or off."))
.build();

RANGE = builder.intRange("range", 8, 1, 64)
.comment("Effect radius")
.tooltip("Controls the effect radius in blocks")
.sync(true)
.restart(RestartRequirement.WORLD)
.build();

builder.pop();
HANDLE = builder.build();
}
}
`

Для чтения значения используется метод ConfigValue#get(), а для программной настройки — ConfigValue#set(value). Комментарии автоматически пишутся в файл TOML, а текст подсказок и панелей информации позволяет создавать различную документацию для файла конфигурации и интерфейса.

Совместимость и лицензии

Konfig распространяется под лицензией MIT, что позволяет свободно использовать её в любых проектах, включая коммерческие. В файлах артефакта отсутствуют встроенные JAR-файлы и миксины. Библиотека не имеет зависимостей от других модов.

Для пользователей, желающих помочь с локализацией, существует проект сообщества переводов. В текущих версиях артефактов подтверждено наличие языковых ресурсов для английского (en_us) и португальского (pt_br). Русский язык (ru_ru) в проверенных архивах не найден, однако наличие перевода зависит от версии и конкретного артефакта.

При возникновении вопросов разработчик рекомендует создавать запросы (issues) в репозитории GitHub или обращаться в официальный Discord-канал проекта.

Связанные материалы

• Mod Menu — похожий мод
• YetAnotherConfigLib (YACL) — похожий мод
• [ETF] Entity Texture Features — похожий мод
• [EMF] Entity Model Features — похожий мод

Автор: iamkaf · Лицензия: MIT