自定义物品数据

自定义物品数据

一个对Minecraft服务器有用的模组,或供模组开发者轻松在物品上存储数据的框架。

基础库

自定义物品数据

版本 加载器 状态

一个用于 Minecraft 1.20.6 的 Fabric 库模组,可让你在任何 ItemStack 上存储持久化、带类型、经 schema 校验的数据。

两种使用方式:

  • 作为模组开发者,在你自己的模组中调用 ItemDataAPI 来读写物品上的值。
  • 作为服务器管理员,在游戏内使用 /itemdata 命令来定义和编辑物品数据,无需编写代码。

特性

  • 在任何 ItemStack 上存储带类型的数据(int、float、string、boolean,以及由框架支持的自定义类型)。
  • 基于 schema 的校验——框架会拒绝与已注册类型不匹配的值。
  • 自动持久化(在存档/读档、给予/克隆等操作后仍保留)。
  • 数据不同的物品堆叠不会堆叠在一起。
  • 游戏内管理员命令(/itemdata […]),持久化在世界存档中。
  • 通过简单的 CustomDataType<T> 接口接入可插拔的自定义类型。

安装(终端用户)

  1. 为 Minecraft 1.20.6 安装 Fabric Loader:https://fabricmc.net/use/installer/
  2. 下载适用于 1.20.6 的 Fabric API,并将 .jar 放入你的 mods/ 文件夹。
  3. 将 customitemdata-1.0.0.jar 放入同一个 mods/ 文件夹。
  4. 启动游戏(或服务器)。你应该会在日志中看到 [ItemDataFramework] Initialisé avec succès.。

就这么简单——模组现在已激活。它本身不会产生任何可见效果;当其他模组调用其 API,或 OP 使用 /itemdata 命令时,它才会发挥作用。


管理员命令教程

所有命令都需要 OP 等级 2。它们作用于主手中当前持有的物品。

/itemdata define <param_name> <type>
/itemdata define <param_name> <type> <visible> <nullable> [default]
/itemdata remove <param_name>
/itemdata set <param_name> <value>
/itemdata get <param_name>
/itemdata list
/itemrename [name]

示例会话——给一根木棍添加一个“点数”计数器:

/itemdata define nb_point int
/itemdata set nb_point 42
/itemdata get nb_point → 42
/itemdata list → nb_point (int)

以这种方式定义的 schema 会保存在世界存档中,因此重启后依然存在。


框架教程(面向模组开发者)

本节将带你从零开始,分四步在自己的 Fabric 模组中使用 ItemDataFramework,直至运行一个可用的示例。

第 1 步 — 添加依赖

在该模组发布到 Maven 仓库之前,最简单的方法是将它的 .jar 放入你的项目并本地引用。

选项 A — 本地 jar(最快):

  1. 构建此模组:./gradlew build —— jar 会生成在 build/libs/customitemdata-1.0.0.jar。
  2. 将该 jar 复制到你自己的模组项目中的 libs/ 文件夹。
  3. 在你的 build.gradle 中:
dependencies {
    modImplementation files("libs/customitemdata-1.0.0.jar")
    // or: modImplementation fileTree(dir: "libs", include: ["*.jar"])
}
  1. 在你的 fabric.mod.json 中将其声明为依赖,以便它先加载:
"depends": {
    "fabricloader": ">=0.18.4",
    "minecraft": "~1.20.6",
    "fabric-api": "*",
    "customitemdata": "*"
}

第 2 步 — 注册 schema

schema 告诉框架某个物品类型允许携带哪些参数,以及它们是什么类型。在你的模组的 onInitialize() 中,在 Minecraft 的注册表就绪之后,一次性注册你的 schema。

package com.example.mymod;

import fr.hdi.customitemdata.schema.SchemaEntry;
import fr.hdi.customitemdata.schema.SchemaManager;
import net.fabricmc.api.ModInitializer;

public class MyMod implements ModInitializer {

    @Override
    public void onInitialize() {
        SchemaManager schemas = SchemaManager.getInstance();

        // A simple integer counter on sticks, visible in the tooltip,
        // defaulting to "0" and required (not nullable).
        schemas.registerSchema("minecraft:stick",
            new SchemaEntry.Builder("nb_point", "int")
                .visible(true)
                .nullable(false)
                .defaultValue("0")
                .build());

        // A string "owner" field on diamond swords.
        schemas.registerSchema("minecraft:diamond_sword",
            new SchemaEntry.Builder("owner", "string")
                .visible(true)
                .build());
    }
}

可用的原始类型:int、float、string、boolean。

通过 API 注册的 schema 会在每次服务器启动时重新应用——它们不会持久化到世界中。只有通过 /itemdata define 创建的 schema 才会持久化。

第 3 步 — 使用 ItemDataAPI 读写

一旦 schema 存在,就可以在任何拥有 ItemStack 的地方使用 ItemDataAPI。该 API 会自动根据 schema 进行校验;如果校验失败,set* 会返回 false,并且物品堆叠保持不变。

import fr.hdi.customitemdata.api.ItemDataAPI;
import net.minecraft.item.ItemStack;

ItemStack stack = player.getMainHandStack();

ItemDataAPI.setCustomName(stack, "My Item");

// Write
ItemDataAPI.setInt(stack, "nb_point", 42);
ItemDataAPI.setString(stack, "owner", "Steve");

// Read (with default fallback)
int points   = ItemDataAPI.getInt(stack, "nb_point", 0);
String owner = ItemDataAPI.getString(stack, "owner", "unknown");

// Read as Optional (absent if the key isn't present)
ItemDataAPI.getInt(stack, "nb_point").ifPresent(value -> ...);

// Check / delete
boolean has = ItemDataAPI.has(stack, "nb_point");
ItemDataAPI.remove(stack, "nb_point");

在底层,每个值都会被序列化为 String,存放在附加到物品堆叠的单个 ItemDataComponent 中。数据不同的两个物品堆叠不会合并,因为原版数据组件的工作方式就是如此。

第 4 步 — 创建自定义数据类型

当 int / float / string / boolean 不够用时,实现 CustomDataType<T> 来接入你自己的类型。你需要提供:

  • 一个唯一的字符串 ID(namespace:name),
  • 一个 encode,将你的对象转换为字符串,
  • 一个 decode,将其解析回来,
  • 一个 Codec<T>(用于 Minecraft 数据集成,例如数据包)。
package com.example.mymod;

import com.mojang.serialization.Codec;
import com.mojang.serialization.codecs.RecordCodecBuilder;
import fr.hdi.customitemdata.api.CustomDataType;

public final class PointDataType implements CustomDataType<PointDataType.Point> {

    public static final String TYPE_ID = "mymod:point";
    public static final PointDataType INSTANCE = new PointDataType();

    private PointDataType() {}

    @Override public String getId() { return TYPE_ID; }

    @Override public Codec<Point> getCodec() { return Point.CODEC; }

    @Override
    public String encode(Point value) {
        return value.x() + "," + value.y();
    }

    @Override
    public Point decode(String stored) {
        String[] parts = stored.split(",", 2);
        return new Point(Integer.parseInt(parts[0]), Integer.parseInt(parts[1]));
    }

    // Nicer tooltip display: "(3, 7)" instead of "Point[x=3, y=7]"
    @Override
    public String display(String stored) {
        Point p = decode(stored);
        return "(" + p.x() + ", " + p.y() + ")";
    }

    public record Point(int x, int y) {
        public static final Codec<Point> CODEC = RecordCodecBuilder.create(i -> i.group(
            Codec.INT.fieldOf("x").forGetter(Point::x),
            Codec.INT.fieldOf("y").forGetter(Point::y)
        ).apply(i, Point::new));
    }
}

在任何使用它的 schema 之前注册它:

SchemaManager schemas = SchemaManager.getInstance();

schemas.registerCustomType(PointDataType.INSTANCE);

schemas.registerSchema("minecraft:compass",
    new SchemaEntry.Builder("target", PointDataType.TYPE_ID).build());

然后通过通用的 get/set 重载进行读写:

ItemDataAPI.set(stack, "target", new PointDataType.Point(3, 7), PointDataType.INSTANCE);

Optional<PointDataType.Point> target =
    ItemDataAPI.get(stack, "target", PointDataType.INSTANCE);

完整可运行示例

一个最小模组,在木棍上定义两个参数,在第一次 tick 时设置它们,然后读回:

package com.example.mymod;

import fr.hdi.customitemdata.api.ItemDataAPI;
import fr.hdi.customitemdata.schema.SchemaEntry;
import fr.hdi.customitemdata.schema.SchemaManager;
import net.fabricmc.api.ModInitializer;
import net.fabricmc.fabric.api.event.player.UseItemCallback;
import net.minecraft.item.ItemStack;
import net.minecraft.item.Items;
import net.minecraft.util.ActionResult;
import net.minecraft.util.TypedActionResult;

public class MyMod implements ModInitializer {

    @Override
    public void onInitialize() {
        SchemaManager schemas = SchemaManager.getInstance();

        schemas.registerSchema("minecraft:stick",
            new SchemaEntry.Builder("nb_point", "int")
                .nullable(false).defaultValue("0").build());

        schemas.registerSchema("minecraft:stick",
            new SchemaEntry.Builder("owner", "string").build());

        // Right-click a stick to increment its counter.
        UseItemCallback.EVENT.register((player, world, hand) -> {
            ItemStack stack = player.getStackInHand(hand);
            if (stack.getItem() != Items.STICK) {
                return TypedActionResult.pass(stack);
            }

            int current = ItemDataAPI.getInt(stack, "nb_point", 0);
            ItemDataAPI.setInt(stack, "nb_point", current + 1);
            ItemDataAPI.setString(stack, "owner", player.getName().getString());

            player.sendMessage(
                net.minecraft.text.Text.literal("Points: " + (current + 1)), true);
            return TypedActionResult.success(stack);
        });
    }
}

参考

ItemDataAPI(静态方法)

方法 用途
getRaw(stack, key) / setRaw(stack, key, value) 原始字符串访问
getInt / setInt 整数值
getFloat / setFloat 浮点值
getString / setString 字符串值
getBoolean / setBoolean 布尔值
get(stack, key, customType) / set(stack, key, v, t) 自定义类型值
has(stack, key) / hasData(stack) 存在性检查
remove(stack, key) 删除一个键(若为空则移除组件)
getComponent(stack) 访问原始 ItemDataComponent

SchemaEntry.Builder

方法 默认值 描述
visible(boolean) true 在物品提示中显示
nullable(boolean) true 允许参数不存在
defaultValue(String) null 默认编码值(例如 "0"、"false")
fromCommand(boolean) false 标记为来自命令(触发持久化)

SchemaManager(通过 getInstance() 获取单例)

方法 用途
registerSchema(itemId, entry) API 侧 schema 注册
registerCustomType(customDataType) 注册一个 CustomDataType<T>
getEntry(itemId, paramName) 查找单个条目
getEntries(itemId) 查找某个物品的所有条目
hasSchema(itemId) 该物品是否有任何 schema?
isKnownType(typeId) 类型 ID 是原始类型还是自定义类型?
validateValue(entry, value) 根据条目校验字符串