Konfig

Konfig

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

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

Konfig 专为共享通用代码而设计。与加载器相关的集成保留在各自的加载器目录中，而配置声明、验证、迁移、同步元数据和界面元数据则可以与模组的其他逻辑放在一起。

功能一览

• 支持布尔值、数字、枚举、字符串、字符串列表、RGB/ARGB 颜色和自定义编解码器等带类型的配置项
• 按端区分配置范围：CLIENT、COMMON 和 SERVER
• 生成带注释的 TOML 文件，路径为 config/<modid>/<name>.toml
• 内置同步模式：NONE、LOGIN 和 LOGIN_AND_RELOAD
• 支持架构版本管理和逐步迁移
• 为已注册的句柄生成配置界面
• 支持界面内嵌装饰元素：标题、图片、说明文字和可点击链接
• 为生成的界面行提供显式工具提示
• 支持全局、分类和单个配置项的丰富悬停帮助面板
• 集成 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 版本系列中使用同一个语义化版本号。+<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。请使用对应加载器的专用构件。

帮助翻译 Konfig

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

参与翻译

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

问答

问：如果这里没有我想问的问题，可以在哪里提问？

A：请在这里提交问题，或加入Discord给我发消息。

问：可以将它移植到 [MC version/Mod loader] 吗？

答：如果有足够多的人提出请求，我会抽时间尝试，不过这确实只有我一个人在做，所以可能需要一段时间。

问：我可以将它加入整合包吗？

答：可以，无需注明出处或征求许可。

我制作的其他模组

Bonded

Kaf’s Valentine Special

Liteminer

Mochila

Torch Toss