E-Utils

EverlastingUtils

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

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

>

> 旧版本： 如果您正在使用需要此库的旧版本模组，请下载 EverlastingUtils 版本 1.0.2。

依赖项

• Fabric API
• Fabric Language Kotlin

>

>

开发者须知

> 从本部分开始的信息，面向希望在其项目中使用 EverlastingUtils 作为依赖项的模组开发者。

> </div>

核心功能

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 = "Welcome to my server!"
) : 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 服务器环境构建。

主要功能：

• 服务器感知：调度器与服务器生命周期绑定。它会在服务器停止时自动关闭，并在重启时重新创建其线程池，防止线程泄漏和错误。
• 同步 vs. 异步：轻松指定任务应同步在主服务器线程上运行（对于几乎所有 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("Hello, world!") }, false)
        1 // 成功
    }
    subcommand("admin") {
        executes { context -> /* ... */ }
    }
}
// 别忘了注册它！
commandManager.register()

GUI 框架 (CustomGui & AnvilGuiManager)

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

// 一个简单箱子 GUI 的示例
CustomGui.openGuiFormatted(
    player = player,
    title = "My Awesome GUI",
    layout = listOf(
        CustomGui.createFormattedButton(
            ItemStack(Items.DIAMOND), 
            "Click Me!", 
            listOf("This is a button."), 
            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" // 替换为您正在使用的版本
}