EverlastingUtils
EverlastingUtils 是一个功能强大、面向服务端的实用工具与 API 库,专为 Fabric 模组开发工具链设计。它提供了一个稳健的框架,用于处理模组开发者经常需要但实现起来较为复杂的功能,让他们能够更专注于模组独特的内容。
对于玩家: 如果你下载的某个模组依赖“EverlastingUtils”,你只需将此库安装到你的 mods 文件夹中即可。你可以忽略以下所有技术信息。
旧版本兼容: 如果你使用的是需要此库的旧版模组,请下载 EverlastingUtils 版本 1.0.2。
依赖项
致开发者注意
从此刻起的信息旨在供希望在项目中将 EverlastingUtils 作为依赖项使用的模组开发者参考。
核心功能
EverlastingUtils 旨在通过提供即用型的高质量系统来加速开发过程,这些系统包括:
- 配置管理 (Configuration):一个类型安全的多文件配置系统,支持 JSONC、实时重载以及自动版本迁移。
- 任务调度 (Task Scheduling):一个感知服务器的调度器,能正确处理同步(主线程)和异步任务,从而避免常见的并发问题。
- 命令系统 (Commands):基于 Brigadier 的流畅命令构建器,集成了权限处理功能。
- GUI 界面 (GUIs):一个简单而强大的框架,用于创建基于库存交互的 GUI,包括标准型和铁砧型。
- 实用工具 (Utilities):一系列辅助工具,例如 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>Welcome to my server!"
) : ConfigData
// 2. 在模组的入口点初始化管理器
val configManager = ConfigManager(
currentVersion = "1.0.0", // 你模组的当前版本
defaultConfig = MyConfig(),
configClass = MyConfig::class,
metadata = ConfigMetadata(
headerComments = listOf("Main configuration for MyMod."),
sectionComments = mapOf("debugMode" to "Enables detailed console logging.")
)
)
// 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("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)
使用基于回调的逻辑、动态更新以及对标题和描述(lore)的完整 MiniMessage 支持,快速为玩家创建交互式 GUI。
// 简单箱子 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" // 替换为你使用的版本
}
EverlastingUtils
EverlastingUtils is a powerful, server-side utility and API library for the Fabric modding toolchain. It provides a robust framework for common, yet complex, features that mod developers frequently need, allowing them to focus more on their mod's unique content.
For Players: If a mod you downloaded requires "EverlastingUtils," you just need to install this library in your mods folder. You can ignore all the technical information below.
Legacy Versions: If you are using older versions of mods that require this library, please download EverlastingUtils version 1.0.2.
Dependencies
Attention Developers
The information from this point forward is intended for mod developers looking to use EverlastingUtils as a dependency in their own projects.
Core Features
EverlastingUtils is designed to accelerate development by providing ready-to-use, high-quality systems for:
- Configuration: A type-safe, multi-file configuration system with JSONC support, live reloading, and automatic version migration.
- Task Scheduling: A server-aware scheduler that properly handles synchronous (main thread) and asynchronous tasks, preventing common concurrency issues.
- Commands: A fluent, Brigadier-based command builder with integrated permission handling.
- GUIs: A simple yet powerful framework for creating interactive inventory-based GUIs, including standard and anvil types.
- Utilities: A collection of helpers for things like MiniMessage color parsing and toggleable, per-mod debug logging.
System Spotlights
Configuration System (ConfigManager)
The ConfigManager is a sophisticated system designed to handle all aspects of configuration management with minimal boilerplate.
Key Functionalities:
- Type-Safe & Modern: Uses Kotlin data classes for type-safe config access and JSONC for human-readable files with comments.
- Live Reloading: Automatically reloads configuration files from disk when they are changed, allowing server owners to adjust settings without a restart.
- Multi-File Support: Manages a main
config.jsonc and any number of "secondary" configs in sub-directories, perfect for organizing complex data like Pokémon or loot pools.
- Automatic Migration: When you release a new version of your mod, the
ConfigManager compares the version number in the user's config file with your mod's current version. If they don't match, it automatically merges their existing settings into a new, updated config structure, preserving their changes.
- Metadata & Comments: Programmatically add header comments, footer comments, and per-field descriptions to your config files, making them self-documenting.
Example Usage:
// 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
Task Scheduler (SchedulerManager)
The SchedulerManager provides a safe and efficient way to schedule delayed or repeating tasks, built specifically for the Minecraft server environment.
Key Functionalities:
- Server-Aware: The scheduler is tied to the server lifecycle. It automatically shuts down when the server stops and recreates its thread pool on restart, preventing thread leaks and errors.
- Sync vs. Async: Easily specify whether a task should run synchronously on the main server thread (necessary for almost all Minecraft API calls) or asynchronously on a worker thread (for heavy, non-API work like database queries).
- Efficient Threading: Uses a shared, managed thread pool to prevent individual mods from creating excessive threads and bogging down the server.
- Tracked Tasks: All scheduled tasks are tracked by a unique ID, allowing you to cancel them later if needed.
Example Usage:
// In your server-side initializer (e.g., inside ServerLifecycleEvents.SERVER_STARTED)
val server = ... // Get the MinecraftServer instance
// Schedule a task to run every 5 minutes on the main server thread
SchedulerManager.scheduleAtFixedRate(
id = "mymod-broadcast-task", // Unique ID for this task
server = server,
initialDelay = 0,
period = 5,
unit = TimeUnit.MINUTES,
runAsync = false, // IMPORTANT: false runs on the main server thread
task = {
// This code is safe to run because runAsync is false
server.playerManager.broadcast(Text.literal("It has been 5 minutes!"), false)
}
)
Other Features
Command System (CommandManager)
A fluent builder for creating Brigadier commands with less boilerplate. It handles permission checks automatically, supporting both vanilla OP levels and the 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 -> /* ... */ }
}
}
// Don't forget to register it!
commandManager.register()
GUI Framework (CustomGui & AnvilGuiManager)
Quickly create interactive GUIs for your players with callback-based logic, dynamic updates, and full MiniMessage support for titles and lore.
// Example of a simple chest 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 = { /* ... */ }
)
For Developers: Getting Started
To use EverlastingUtils in your project, add it to your dependencies.
build.gradle.kts
repositories {
// Add the repository where EverlastingUtils is hosted
maven { url = "https://api.modrinth.com/maven" }
}
dependencies {
// Add the library as a dependency
modImplementation("maven.modrinth:e-utils:1.1.2") // Replace with the latest version
}
fabric.mod.json
Make sure to declare the dependency in your fabric.mod.json file.
"depends": {
"everlastingutils": ">=1.1.2" // Replace with the version you are using
}
评论 0
登录后参与评分
还没有评论,来抢沙发吧