Lite Config

模组

· 作者 Riser876

一个 Minecraft JSON5/TOML 配置库

0 本站下载 0 关注 更新于 1 周前

需要前置:Fabric API

最新 1.3.0-1.21 · 1.21.10 · Fabric

一键开服(送7天)

Lite Config

Lite Config 是一个用于 Fabric 和 NeoForge 上 Minecraft 模组的 JSON5/TOML 配置库。只需在任意 Java 类上添加 @Config 注解并将其传递给构建器,即可获得一个 ConfigHolder,它会自动管理文件解析、安全 I/O、生命周期事件、同步等功能。

功能:

  • 文件: 读写 JSON5 或 TOML 格式,支持默认值以及从损坏文件中恢复。
  • 更新: 验证更改,并在需要编辑配置数据时提供副本。
  • 灵活读取: 可从任何线程读取当前配置。
  • 所有权: 可选择客户端/服务器设置或世界拥有的设置。
  • 可选网络同步: 自动将标记的配置或单个字段从服务器同步到客户端。
  • 重启设置: CLIENT(客户端)更改等待游戏启动;WORLD(世界)更改在该世界再次加载时生效;SERVER(服务器)重启设置在游戏重启后生效。
  • 自定义更新 API: update 和 updateAndSave 返回带有接受状态和验证违规信息的 UpdateResult。
  • 失败策略: 对读取、写入和更新错误进行细粒度控制,从优雅降级到严格异常。
  • 生命周期事件与钩子: 同步的加载、保存和更新事件,以及配置级别的标准化和验证钩子。
  • 声明式约束: 通过加载/更新时的注解强制执行数值范围、字符串模式和集合大小等限制。
  • 运行时元数据: 可在运行时访问每个字段的路径、类型、默认值、注释、翻译键和约束。
  • 版本迁移: 使用带时间戳的文件修订版逐步升级旧配置,而不会丢失玩家数据。
  • 持久化控制: 完全自定义文件路径、字段名称、自动生成的注释以及忽略的字段。

不在 Lite Config 范围内(目前):

  • 配置界面: Lite Config 是一个数据层解决方案,本身不渲染配置界面,允许你将其与任何 UI 库或自定义界面配合使用。

文档: Wiki

设置

Lite Config 发布在 Maven Central 上,组 ID 为 com.gmalvestiti.minecraft,每个加载器对应一个构件:

加载器 构件
Fabric liteconfig-fabric
NeoForge liteconfig-neoforge

版本号同时包含 Lite Config 版本和目标 Minecraft 版本:

Minecraft Lite Config
1.21-1.21.10 1.3.0-1.21
1.21.11 1.3.0-1.21.11
26.1-latest 1.3.0-26.1

以下示例使用的是 1.21 构建。

Fabric
repositories {
    mavenCentral()
}

dependencies {
    modImplementation 'com.gmalvestiti.minecraft:liteconfig-fabric:1.3.0-1.21'
}

在 fabric.mod.json 中声明依赖项,以便 Fabric 在没有 Lite Config 的情况下拒绝加载模组:

{
    "depends": {
        "liteconfig": ">=1.3.0-1.21"
    }
}
NeoForge
repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.gmalvestiti.minecraft:liteconfig-neoforge:1.3.0-1.21'
}

在 META-INF/neoforge.mods.toml 中声明依赖项:

[[dependencies.yourmodid]]
modId = "liteconfig"
type = "required"
versionRange = "[1.3.0,)"
ordering = "NONE"
side = "BOTH"

快速入门

从一个普通的配置类开始。为每个持久化字段赋予默认值。

@Config(name = "mymod", type = ConfigType.CLIENT) // JSON5, config/mymod.json5
public final class MyModConfig {
    public boolean showHints = true;
    public int hudScale = 2;
}

若要改用 TOML 格式,请在 @Config 中添加 format = ConfigFormat.TOML。

在模组初始化期间创建一个持有者实例,并在整个模组生命周期内保持引用:

public final class MyMod implements ModInitializer {

    public static final ConfigHolder<MyModConfig> CONFIG = LiteConfig.holder(MyModConfig.class)
        .label("mymod")
        .create();
}

或者直接在配置类中:

@Config(name = "mymod", type = ConfigType.CLIENT)
public final class MyModConfig {
    public boolean showHints = true;
    public int hudScale = 2;

    public static final ConfigHolder<MyModConfig> CONFIG;
    
    static {
        CONFIG = LiteConfig.holder(MyModConfig.class)
            .label("mymod")
            .create();
    }
}

create() 会验证配置模型并加载活动的本地设置,如果文件尚不存在,则写入默认值。

持有者可以在游戏启动前创建。请确保构造函数、迁移逻辑和自定义状态克隆器独立于 Minecraft 的运行时状态。

使用 data() 读取当前已发布的状态:

if (MyMod.CONFIG.data().showHints) {
    // ...
}

使用 update(...) 或 updateAndSave(...) 应用运行时更改:

MyMod.CONFIG.update(config -> config.hudScale = 3);        // 仅内存
MyMod.CONFIG.updateAndSave(config -> config.hudScale = 4); // 内存 + 磁盘

将 data() 及其嵌套值视为只读。若需编辑单独的副本,请使用 copy()。

如果更改无效,Lite Config 将拒绝该更改并保持当前状态:

UpdateResult result = MyMod.CONFIG.update(config -> config.hudScale = 99);
if (!result.accepted()) {
    result.violations().forEach(v -> LOGGER.warn("{}: {}", v.id(), v.message()));
}

保存后的 JSON5 文件如下所示:

{
  "showHints": true,
  "hudScale": 4
}

完整配置示例

@Config(
    name = "mymodfile",
    path = "mymod/mymoddir1/mymoddir2",
    type = ConfigType.SERVER,
    readOnly = false,
    format = ConfigFormat.JSON,
    comment = "MyMod settings.",
    version = 3,
    stateCloner = MyModConfigCloner.class,
    readFailurePolicy = FailurePolicy.FALLBACK,
    writeFailurePolicy = FailurePolicy.STRICT,
    updateFailurePolicy = FailurePolicy.FALLBACK,
    restartSyncPolicy = RestartSyncPolicy.DISCONNECT
)
public final class MyModConfig implements ConfigExtension {

```java
@Entry(
        name = "hud_scale",
        comment = "HUD 的缩放比例,范围为 1 到 4。",
        translationKey = "mymod.config.hud_scale",
        sync = SyncMode.ENABLED,
        listener = "onHudScaleChanged"
    )
    @Range(min = 1, max = 4)
    public int hudScale = 2;

    @Entry(
        comment = "渲染后端。在下次重启后生效。",
        restart = true,
        sync = SyncMode.ENABLED
    )
    public Renderer renderer = Renderer.DEFAULT;

    @AllowedValues(
        value = {"mysql", "sqlite"},
        normalize = EntryNormalization.NONE,
        trim = true
    )
    public String database = "sqlite";

    @AllowedValues(value = {"fast", "safe"}, normalize = EntryNormalization.UPPER_CASE)
    public String mode = "SAFE";

    @AllowedValues(value = {"Custom", "Default"}, normalize = EntryNormalization.NONE, trim = false)
    public String label = "Custom";

    @NotBlank
    @Length(max = 16)
    @Pattern("[a-z0-9_]+")
    @Entry(comment = {"服务器规则使用的配置文件。", "必须为小写、字母数字或下划线。"})
    public String profileName = "default";

    @NotNull
    @Entry(comment = "服务器拥有的出生点范围。", sync = SyncMode.ENABLED)
    public IntRange spawnRange = new IntRange(1, 12);

    public Display display = new Display();

    @Ignore
    public Map<String, String> runtimeCache = new HashMap<>();

    @Override
    public void afterLoad() {
        if (profileName != null) {
            profileName = profileName.strip().toLowerCase(Locale.ROOT);
        }
    }

    @Override
    public void beforeSave() {
        if (display != null && display.hiddenHints != null) {
            display.hiddenHints.sort(String::compareTo);
        }
    }

    @Override
    public void validate(List<Violation> violations) {
        if (spawnRange == null || spawnRange.minimum() > spawnRange.maximum()) {
            violations.add(Violation.of(
                "spawn-range.order",
                "spawnRange 的最小值不得大于最大值"
            ));
        }
    }

    private void onHudScaleChanged(Integer oldValue, Integer newValue, boolean fromSync) {
        System.out.printf("HUD 缩放: %d -> %d (来自服务器: %s)%n",
            oldValue, newValue, fromSync);
    }

    @Migration(from = 1)
    static void toVersion2(ConfigData data) {
        data.rename("hudScale", "hud_scale");
    }

    @Migration(from = 2)
    static void toVersion3(ConfigData data) {
        if (!data.has("spawnRange")) {
            data.set("spawnRange.minimum", 1)
                .set("spawnRange.maximum", 12);
        }
    }

    public static final class Display {
        @Entry(comment = "显示上下文提示。")
        public boolean showHints = true;

        @Length(max = 32)
        public List<String> hiddenHints = new ArrayList<>();
    }

    public enum Renderer {
        DEFAULT,
        COMPATIBILITY
    }
}

// 自定义类型
public record IntRange(int minimum, int maximum) {
    public static final Codec<IntRange> CODEC = RecordCodecBuilder.create(instance ->
        instance.group(
            Codec.INT.fieldOf("minimum").forGetter(IntRange::minimum),
            Codec.INT.fieldOf("maximum").forGetter(IntRange::maximum)
        ).apply(instance, IntRange::new)
    );

    public static final StreamCodec<ByteBuf, IntRange> STREAM_CODEC =
        StreamCodec.composite(
            ByteBufCodecs.VAR_INT, IntRange::minimum,
            ByteBufCodecs.VAR_INT, IntRange::maximum,
            IntRange::new
        );
}

// 自定义配置状态克隆器
public final class MyModConfigCloner implements StateCloner<MyModConfig> {
    @Override
    public MyModConfig copy(MyModConfig source) {
        MyModConfig copy = new MyModConfig();
        copy.hudScale = source.hudScale;
        copy.renderer = source.renderer;
        copy.database = source.database;
        copy.profileName = source.profileName;
        copy.spawnRange = source.spawnRange;
        copy.display = copyDisplay(source.display);
        copy.runtimeCache = source.runtimeCache == null
            ? new HashMap<>()
            : new HashMap<>(source.runtimeCache);
        return copy;
    }

    private static MyModConfig.Display copyDisplay(MyModConfig.Display source) {
        if (source == null) {
            return null;
        }
        MyModConfig.Display copy = new MyModConfig.Display();
        copy.showHints = source.showHints;
        copy.hiddenHints = source.hiddenHints == null
            ? null
            : new ArrayList<>(source.hiddenHints);
        return copy;
    }
}

注册用于文件持久化和状态复制的自定义 Codec,以及用于同步的 StreamCodec。

public final class MyMod implements ModInitializer {

    public static ConfigHolder<MyModConfig> config = LiteConfig.holder(MyModConfig.class, codecs -> codecs
            .registerCodec(IntRange.class, IntRange.CODEC)
            .registerStreamCodec(IntRange.class, IntRange.STREAM_CODEC))
        .label("mymod")
        .onUpdate(state -> System.out.println("HUD 缩放现在为 " + state.hudScale))
        .onSave(state -> System.out.println("已保存 MyMod 配置"))
        .create();

    @Override
    public void onInitialize() {
        // 快速共享读取。将返回的对象视为只读。
        int currentScale = config.data().hudScale;

        // 稳定的深拷贝,由当前调用者拥有。
        MyModConfig snapshot = config.copy();
        snapshot.display.hiddenHints.add("crafting");

        // 验证内存中的更新。
        UpdateResult result = config.update(state -> {
            state.hudScale = 3;
            state.display.hiddenHints = new ArrayList<>(
                snapshot.display.hiddenHints
            );
        });
        if (!result.accepted()) {
            result.violations().forEach(violation ->
                System.err.println(violation.id() + ": " + violation.message()));
        }

// 更新并保存。
        UpdateResult saved = config.updateAndSave(state ->
            state.spawnRange = new IntRange(2, 24)
        );
        System.out.println("已保存: " + saved.accepted());

        // 用于屏幕、命令、生成的帮助等的结构元数据。
        config.metadata().flatten().forEach(property ->
            System.out.println(property.path() + " -> " + property.type().getSimpleName()));
    }
}

第一个 create() 加载 config/mymod/mymoddir1/mymoddir2/mymodfile.json5,应用迁移, 验证结果并保存它。没有 configVersion 的文件从版本 1 开始。

只有 hud_scale、renderer 和 spawnRange 会同步,因为它们通过 SyncMode.ENABLED 选择了启用同步。

内置值包括基本类型及其包装类、枚举、数组、带类型的 List/Set/Map 集合、 UUID、BigInteger、BigDecimal、Duration、Instant、LocalDate、LocalTime 和 LocalDateTime。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源