E-Utils

E-Utils

一个提供可复用组件的模组工具，用于配置文件、命令系统和用户界面

基础库

EverlastingUtils

EverlastingUtils 是一个功能强大的、服务端实用工具与 API 库，适用于 Fabric 模组开发工具链。它为模组开发者经常需要的常见但复杂的功能提供了健壮的框架，使开发者能够更专注于其模组的独特内容。

给玩家的话： 如果你下载的模组需要“EverlastingUtils”，你只需将此库安装到你的 mods 文件夹中。你可以忽略以下所有技术信息。

旧版本： 如果你使用的是需要此库的旧版模组，请下载 EverlastingUtils 版本 1.0.2。

依赖项

开发者注意

以下信息面向希望在自身项目中使用 EverlastingUtils 作为依赖项的模组开发者。

核心特性

EverlastingUtils 旨在通过提供即用型、高质量的系统来加速开发，涵盖以下方面：

  • 配置管理：类型安全、多文件的配置系统，支持 JSONC、热重载和自动版本迁移。
  • 任务调度：一个了解服务器环境的调度器，可正确处理同步（主线程）和异步任务，避免常见的并发问题。
  • 命令系统：一个基于 Brigadier 的流畅命令构建器，集成了权限处理。
  • GUI 框架：一个简单而强大的框架，用于创建基于物品栏的交互式 GUI，包括标准类型和铁砧类型。
  • 实用工具：一系列辅助工具，例如 MiniMessage 颜色解析和可切换的、按模组区分的调试日志记录。

系统亮点

配置系统（ConfigManager）

ConfigManager 是一个精密的系统，旨在以最少的样板代码处理配置管理的所有方面。

关键功能：

  • 类型安全且现代化：使用 Kotlin 数据类实现类型安全的配置访问，并使用 JSONC 实现带注释且人类可读的文件。
  • 热重载：当配置文件在磁盘上被修改时自动重新加载，允许服务器所有者无需重启即可调整设置。
  • 多文件支持：管理一个主 config.jsonc 文件和子目录中任意数量的“次要”配置，非常适合组织复杂数据，如宝可梦或战利品表。
  • 自动迁移：当你发布新版本的模组时，ConfigManager 会将用户配置文件中的版本号与你模组的当前版本进行比较。如果它们不匹配，它会自动将用户现有的设置合并到新的、更新后的配置结构中，保留他们的更改。
  • 元数据与注释：以编程方式向配置文件添加头部注释、尾部注释和字段描述，使文件具有自文档性。

使用示例：

// 1. 定义你的配置结构
data class MyConfig(
    override val version: String = "1.0.0",
    override val configId: String = "mymod", // 用于配置文件夹名称
    var debugMode: Boolean = false,
    var welcomeMessage: String = "<green>欢迎来到我的服务器！"
) : ConfigData

// 2. 在模组入口点初始化管理器
val configManager = ConfigManager(
    currentVersion = "1.0.0", // 你模组的当前版本
    defaultConfig = MyConfig(),
    configClass = MyConfig::class,
    metadata = ConfigMetadata(
        headerComments = listOf("MyMod 的主配置文件。"),
        sectionComments = mapOf("debugMode" to "启用详细的控制台日志记录。")
    )
)

// 3. 在任意位置访问你的配置
val isDebug = configManager.getCurrentConfig().debugMode

任务调度器（SchedulerManager）

SchedulerManager 提供了一种安全高效的方式来调度延迟或重复任务，专为 Minecraft 服务器环境而构建。

关键功能：

  • 服务器感知：调度器与服务器生命周期绑定。它会在服务器停止时自动关闭，并在重启时重新创建线程池，防止线程泄漏和错误。
  • 同步与异步：轻松指定任务应在主服务器线程上同步运行（几乎所有 Minecraft API 调用都需要）还是在工作线程上异步运行（用于非 API 的重型操作，如数据库查询）。
  • 高效线程管理：使用共享的、受管理的线程池，防止单个模组创建过多线程而拖慢服务器。
  • 任务追踪：所有计划任务都通过唯一 ID 进行跟踪，以便在需要时取消它们。

使用示例：

// 在服务端初始化器中（例如，在 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("已经过去 5 分钟了！"), 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("你好，世界！") }, false)
        1 // 成功
    }
    subcommand("admin") {
        executes { context -> /* ... */ }
    }
}
// 别忘了注册它！
commandManager.register()

GUI 框架（CustomGui 与 AnvilGuiManager）

通过基于回调的逻辑、动态更新以及标题和描述行完整的 MiniMessage 支持，快速为你的玩家创建交互式 GUI。

// 简单箱子 GUI 示例
CustomGui.openGuiFormatted(
    player = player,
    title = "<gradient:gold:yellow>我的超棒 GUI",
    layout = listOf(
        CustomGui.createFormattedButton(
            ItemStack(Items.DIAMOND), 
            "<blue>点击我！", 
            listOf("<gray>这是一个按钮。"), 
            player
        )
    ),
    onInteract = { context ->
        if (context.slotIndex == 0) {
            player.sendMessage(Text.literal("你点击了按钮！"))
            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" // 替换为你正在使用的版本
}