Konfig

.detail-panel[hidden] { display: block !important; } .detail-tabs { display: none; } /* These three panels are rendered by the browser. */ [data-versions], [data-changelog-panel], [data-comments] { display: none; }

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

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

Konfig 专为共享通用代码而构建。加载器特定的集成保留在加载器根目录中，而配置声明、验证、迁移、同步元数据和界面元数据则可以与模组其余逻辑一起存放。

您将获得

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

图片

Konfig 概览，包含内联文档和信息面板

Konfig 布尔、枚举和数字控件

Konfig 注册表支持的字符串和颜色控件

Konfig 带注册表图标的字符串列表控件

Konfig 注册表支持的字符串列表编辑器

Konfig ARGB 颜色编辑器，带通道滑块

支持的版本

Konfig 0.4.0 支持从 1.14.4 到 26.2 的每个 Minecraft 版本线。

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

Konfig 在所有支持的 Minecraft 版本线上使用单一语义版本号。+<mc> 后缀标识工件所针对的 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<Boolean> ENABLED;
    public static final ConfigValue<Integer> 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(...) 提供更丰富的内容，因此您的配置文件与界面帮助可以在需要时显示不同的内容。

依赖

添加 Kaf Maven 仓库：

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

使用目标 Minecraft 版本线对应的加载器工件：

modImplementation "com.iamkaf.konfig:konfig-fabric:<version>"
modImplementation "com.iamkaf.konfig:konfig-forge:<version>"
modImplementation "com.iamkaf.konfig:konfig-neoforge:<version>"

请勿直接依赖 Konfig common。请使用特定于加载器的工件。