E-Utils

EverlastingUtils

EverlastingUtils — это мощная серверная библиотека утилит и API для тулчейна модов Fabric. Она предоставляет надёжный фреймворк для распространённых, но сложных функций, которые часто нужны разработчикам модов, позволяя им сосредоточиться на уникальном контенте своего мода.

Для игроков: Если скачанный вами мод требует "EverlastingUtils", просто установите эту библиотеку в папку mods. Всю техническую информацию ниже можно игнорировать.Старые версии: Если вы используете старые версии модов, требующих эту библиотеку, скачайте EverlastingUtils версии 1.0.2.

Зависимости

• Fabric API
• Fabric Language Kotlin

Внимание, разработчики

Информация ниже предназначена для разработчиков модов, которые хотят использовать EverlastingUtils как зависимость в своих проектах.

Основные возможности

EverlastingUtils создана, чтобы ускорить разработку, предоставляя готовые к использованию высококачественные системы для:

• Конфигурация: Типобезопасная система конфигурации с поддержкой нескольких файлов, JSONC, живой перезагрузкой и автоматической миграцией версий.
• Планирование задач: Серверный планировщик, который корректно обрабатывает синхронные (в главном потоке) и асинхронные задачи, предотвращая типичные проблемы с конкурентностью.
• Команды: Гибкий конструктор команд на основе Brigadier со встроенной обработкой прав.
• GUI: Простой, но мощный фреймворк для создания интерактивных GUI на основе инвентаря, включая стандартные и наковальневые типы.
• Утилиты: Набор помощников для таких вещей, как парсинг цветов MiniMessage и переключаемое отладочное логирование для каждого мода.

Обзор систем

Система конфигурации (ConfigManager)

ConfigManager — это продуманная система, созданная для управления всеми аспектами конфигурации с минимальным количеством шаблонного кода.

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

• Типобезопасность и современность: Использует data-классы Kotlin для типобезопасного доступа к конфигу и JSONC для читаемых человеком файлов с комментариями.
• Живая перезагрузка: Автоматически перезагружает файлы конфигурации с диска при их изменении, позволяя владельцам серверов менять настройки без перезапуска.
• Поддержка нескольких файлов: Управляет основным config.jsonc и любым количеством "вторичных" конфигов в подпапках — идеально для организации сложных данных вроде покемонов или лут-пулов.
• Автоматическая миграция: Когда вы выпускаете новую версию мода, ConfigManager сравнивает номер версии в файле конфигурации пользователя с текущей версией вашего мода. Если они не совпадают, он автоматически переносит существующие настройки в новую обновлённую структуру конфига, сохраняя их изменения.
• Метаданные и комментарии: Программно добавляйте комментарии в шапку, подвал и описания к отдельным полям ваших конфигов, делая их самодокументируемыми.

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

// 1. Define your configuration structure
data class MyConfig(
    override val version: String = "1.0.0",
    override val configId: String = "mymod", // Used for the config folder name
    var debugMode: Boolean = false,
    var welcomeMessage: String = "<green>Welcome to my server!"
) : ConfigData

// 2. Initialize the manager in your mod's entry point
val configManager = ConfigManager(
    currentVersion = "1.0.0", // Your mod's current version
    defaultConfig = MyConfig(),
    configClass = MyConfig::class,
    metadata = ConfigMetadata(
        headerComments = listOf("Main configuration for MyMod."),
        sectionComments = mapOf("debugMode" to "Enables detailed console logging.")
    )
)

// 3. Access your config anywhere
val isDebug = configManager.getCurrentConfig().debugMode

### Планировщик задач (`SchedulerManager`)

`SchedulerManager` предоставляет безопасный и эффективный способ планирования отложенных или повторяющихся задач, созданный специально для серверного окружения Minecraft.

**Основные возможности:**
*   **Учёт сервера**: Планировщик привязан к жизненному циклу сервера. Он автоматически завершает работу при остановке сервера и пересоздаёт свой пул потоков при перезапуске, предотвращая утечки потоков и ошибки.
*   **Синхронно и асинхронно**: Легко указать, должна ли задача выполняться **синхронно** в главном потоке сервера (необходимо почти для всех вызовов Minecraft API) или **асинхронно** в рабочем потоке (для тяжёлой работы без API, например запросов к базе данных).
*   **Эффективная многопоточность**: Использует общий управляемый пул потоков, чтобы отдельные моды не создавали лишние потоки и не тормозили сервер.
*   **Отслеживаемые задачи**: Все запланированные задачи отслеживаются по уникальному ID, что позволяет отменить их позже при необходимости.

**Пример использования:**
```kotlin
// В вашем серверном инициализаторе (например, внутри ServerLifecycleEvents.SERVER_STARTED)
val server = ... // Получите экземпляр MinecraftServer

// Запланировать задачу, выполняющуюся каждые 5 минут в главном потоке сервера
SchedulerManager.scheduleAtFixedRate(
    id = "mymod-broadcast-task", // Уникальный ID для этой задачи
    server = server,
    initialDelay = 0,
    period = 5,
    unit = TimeUnit.MINUTES,
    runAsync = false, // ВАЖНО: false запускает в главном потоке сервера
    task = {
        // Этот код безопасен для выполнения, потому что runAsync = false
        server.playerManager.broadcast(Text.literal("It has been 5 minutes!"), false)
    }
)

Другие возможности

Система команд (CommandManager)

Удобный билдер для создания команд Brigadier с меньшим количеством шаблонного кода. Он автоматически обрабатывает проверки прав, поддерживая как ванильные OP-уровни, так и Fabric Permissions API.

val commandManager = CommandManager(modId = "mymod")

commandManager.command("hello", permission = "mymod.hello") {
    executes { context ->
        context.source.sendFeedback({ Text.literal("Hello, world!") }, false)
        1 // Success
    }
    subcommand("admin") {
        executes { context -> /* ... */ }
    }
}
// Не забудьте зарегистрировать её!
commandManager.register()

Фреймворк GUI (CustomGui & AnvilGuiManager)

Быстро создавайте интерактивные GUI для ваших игроков с логикой на основе колбэков, динамическими обновлениями и полной поддержкой MiniMessage для заголовков и описаний.

// Пример простого сундучного GUI
CustomGui.openGuiFormatted(
    player = player,
    title = "<gradient:gold:yellow>My Awesome GUI",
    layout = listOf(
        CustomGui.createFormattedButton(
            ItemStack(Items.DIAMOND), 
            "<blue>Click Me!", 
            listOf("<gray>This is a button."), 
            player
        )
    ),
    onInteract = { context ->
        if (context.slotIndex == 0) {
            player.sendMessage(Text.literal("You clicked the button!"))
            CustomGui.closeGui(player)
        }
    },
    onClose = { /* ... */ }
)

Для разработчиков: с чего начать

Чтобы использовать EverlastingUtils в своём проекте, добавьте его в зависимости.

build.gradle.kts

repositories {
    // Добавьте репозиторий, где размещён EverlastingUtils
    maven { url = "https://api.modrinth.com/maven" }
}

dependencies {
    // Добавьте библиотеку как зависимость
    modImplementation("maven.modrinth:e-utils:1.1.2") // Замените на последнюю версию
}

fabric.mod.json

Не забудьте объявить зависимость в вашем файле fabric.mod.json.

"depends": {
    "everlastingutils": ">=1.1.2" // Замените на используемую вами версию
}