Konfig - Konfig 配置库

Konfig

Konfig 是一个适用于 Minecraft 模组的多加载器配置库。

它允许模组在通用代码中声明带类型的配置值，将其保存为带注释的 TOML，同步选定值到客户端，并为 Fabric、Forge 和 NeoForge 生成配置界面。

Konfig 专为共享的通用代码而构建。加载器相关的集成保留在各自的 loader roots 中，而配置声明、校验、迁移、同步元数据和界面元数据都可以与模组的其余逻辑放在一起。

你将获得

• 支持类型的配置值：布尔值、数字、枚举、字符串、字符串列表、RGB/ARGB 颜色，以及自定义 codec
• 按端区分的配置作用域：CLIENT、COMMON 和 SERVER
• 位于 config//.toml 的带注释 TOML 文件
• 内置同步模式：NONE、LOGIN 和 LOGINANDRELOAD
• 模式版本控制和逐步迁移
• 为已注册的 handle 生成配置界面
• 内联界面装饰：标题、图片、描述文本和可点击 URL
• 为生成的界面行提供显式提示文本
• 用于全局、分类和特定值帮助的丰富悬停信息面板
• Fabric Mod Menu 集成
• Forge 和 NeoForge 配置按钮辅助

图片

支持的版本

Konfig 0.4.0 支持从 1.14.4 到 26.2 的所有 Minecraft 版本线。

• Fabric 从 1.14.4 开始
• Forge 从 1.16.5 开始
• NeoForge 从 1.21.1 开始

Konfig 在所有受支持的 Minecraft 版本线上使用同一个语义化版本。+ 后缀告诉你该构建面向哪个 Minecraft 版本，例如 0.4.0+1.21.11 或 0.4.0+26.2。

快速示例

import com.iamkaf.konfig.api.v1.ConfigBuilder;
import com.iamkaf.konfig.api.v1.ConfigHandle;
import com.iamkaf.konfig.api.v1.ConfigScope;
import com.iamkaf.konfig.api.v1.ConfigValue;
import com.iamkaf.konfig.api.v1.Konfig;
import com.iamkaf.konfig.api.v1.RestartRequirement;
import com.iamkaf.konfig.api.v1.SyncMode;

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。生成界面的悬停文本通过 tooltip(...) 显式提供，而更丰富的 info(...) 内容则可以让配置文件与 UI 帮助在需要时表达不同的信息。

依赖

添加 Kaf Maven 仓库：

repositories {
    maven { url = "https://maven.kaf.sh" }
}

使用你所目标 Minecraft 版本线对应的 loader 依赖：

modImplementation "com.iamkaf.konfig:konfig-fabric:"
modImplementation "com.iamkaf.konfig:konfig-forge:"
modImplementation "com.iamkaf.konfig:konfig-neoforge:"

不要直接依赖 Konfig common。请使用对应 loader 的构件。

帮助翻译 Konfig

想帮助将这个模组翻译成你的语言吗？加入社区翻译项目：

贡献翻译

🇺🇸 🇪🇸 🇧🇷 🇫🇷 🇩🇪 🇷🇺 🇹🇷 🇯🇵 🇰🇷 🇨🇳

问答

Q: 我可以在哪里询问这里没有列出的问题？

A: 在 这里 提交 issue，或者加入 Discord 给我发消息。

Q: 你能把它移植到 [MC version/Mod loader] 吗？

A: 如果有足够多人请求，我会抽时间考虑，但这确实是一个只有 1 个人的团队，所以可能会花一段时间。

Q: 我可以把它包含在我的整合包里吗？

A: 可以，不需要致谢，也不需要询问。

我制作的更多模组

Bonded

Kaf's Valentine Special

Liteminer

Mochila

Torch Toss