自定义服务器数据

自定义服务器数据

一个对Minecraft服务器有用的模组,也是模组开发者的框架。

基础库

自定义服务器数据

版本 加载器 状态

概述

Custom Server Data 是一个 Fabric 服务端库模组,为 Minecraft 1.20.6 提供结构化、持久化的全局数据框架。它允许模组开发者(以及服务器本身)存储数据。

数据以人类可读的 JSON 文件形式存储在存档目录中:

world/customserverdata/<modid>/<filename>.json

每个变量通过模式系统(schema system) 定义类型、默认值、约束和可空性,然后在运行时通过静态 API 进行读取/写入。

开发者指南

1. 创建自定义类型

任何你想要存储的自定义对象都必须实现 IJsonSerializable:

import com.google.gson.JsonObject;
import fr.hdi.api.IJsonSerializable;

public class QuestData implements IJsonSerializable {
    private int nbPoints;
    private String status;

    public QuestData() {
        this.nbPoints = 0;
        this.status = "inactive";
    }

    public int getNbPoints() { return nbPoints; }
    public void setNbPoints(int nbPoints) { this.nbPoints = nbPoints; }

    public String getStatus() { return status; }
    public void setStatus(String status) { this.status = status; }

    @Override
    public JsonObject toJson() {
        JsonObject json = new JsonObject();
        json.addProperty("nb_points", nbPoints);
        json.addProperty("status", status);
        return json;
    }

    @Override
    public void fromJson(JsonObject json) {
        this.nbPoints = json.has("nb_points") ? json.get("nb_points").getAsInt() : 0;
        this.status = json.has("status") ? json.get("status").getAsString() : "inactive";
    }
}

2. 注册数据

使用 ServerSchemaManager 在你的模组 onInitialize 方法中注册模式:

import fr.hdi.schema.ServerDataType;
import fr.hdi.schema.ServerSchemaManager;
import fr.hdi.schema.ServerVariableDefinition;
import net.fabricmc.api.ModInitializer;

public class MyMod implements ModInitializer {
    public static final String MOD_ID = "mymod";

    @Override
    public void onInitialize() {
        // 注册一个带最小/最大约束的整数
        ServerSchemaManager.register(MOD_ID, "quests",
            ServerVariableDefinition.builder("nb_point")
                .type(ServerDataType.INT)
                .defaultValue(10)
                .min(0)
                .max(1000)
                .build()
        );

        // 注册一个字符串
        ServerSchemaManager.register(MOD_ID, "quests",
            ServerVariableDefinition.builder("status")
                .type(ServerDataType.STRING)
                .defaultValue("active")
                .build()
        );

        // 注册一个布尔值
        ServerSchemaManager.register(MOD_ID, "settings",
            ServerVariableDefinition.builder("pvp_enabled")
                .type(ServerDataType.BOOLEAN)
                .defaultValue(false)
                .build()
        );

        // 注册一个自定义类型
        ServerSchemaManager.register(MOD_ID, "quests",
            ServerVariableDefinition.builder("quest_data", "QuestData")
                .type(ServerDataType.CUSTOM)
                .customFactory(QuestData::new)
                .nullable(true)
                .build()
        );

        // 注册一个自定义类型列表
        ServerSchemaManager.register(MOD_ID, "warps",
                ServerVariableDefinition.builder("warps")
                        .type(ServerDataType.LIST)
                        .elementType(ServerDataType.CUSTOM)
                        .elementFactory(Warp::new)
                        .defaultValue(List.of())
                        .build()
        );
    }
}

这会在磁盘上生成两个 JSON 文件:

  • world/customserverdata/mymod/quests.json
  • world/customserverdata/mymod/settings.json

3. 读取 / 写入数据

在服务器线程的任意位置使用静态 ServerDataStore API:

import fr.hdi.store.ServerDataStore;

// 读取值
int points = ServerDataStore.getInt("mymod", "quests", "nb_point");
String status = ServerDataStore.getString("mymod", "quests", "status");
boolean pvp = ServerDataStore.getBoolean("mymod", "settings", "pvp_enabled");

// 写入值(会根据模式进行校验)
ServerDataStore.setData("mymod", "quests", "nb_point", 42);
ServerDataStore.setData("mymod", "quests", "status", "completed");
ServerDataStore.setData("mymod", "settings", "pvp_enabled", true);

// 自定义对象
QuestData quest = ServerDataStore.getCustom("mymod", "quests", "quest_data");
if (quest != null) {
    quest.setNbPoints(100);
    ServerDataStore.setData("mymod", "quests", "quest_data", quest);
}

List<Warp> warps = ServerDataStore.getList(EssentialsUtilsCommands.MOD_ID, "warps", "warps");
if (warps != null){
    warps.remove(1);
    ServerDataStore.setData(EssentialsUtilsCommands.MOD_ID, "warps","warps",warps);
}