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。
你是这个资源的作者?登录后可认领此资源。
相似资源
一个用于收集生物掉落物的多区块模组。
显示你正在注视的方块的信息。(适用于 Minecraft 1.16+ 的 Hwyla/Waila 分支)
查看物品与配方
在游戏画面角落显示附近世界地形、玩家、生物和实体的地图。可创建路径点,帮助你找到标记过的位置。
使用 JavaScript 编辑配方、添加自定义物品、编写世界事件!
适用于 MC 1.18+ 的 Effekseer 加载器
评论 0
登录后参与评分
还没有评论,来抢沙发吧