Custom Item Data

模组

· 作者 Hdi

一个实用的 Minecraft 模组,或供模组开发者使用的框架,用于轻松地在物品中存储数据。

0 本站下载 0 关注 更新于 6 个月前

最新 0.1.7 · 1.20.6 · Fabric / Quilt

一键开服(送7天)

Custom Item Data

一个用于 Minecraft 1.20.6 的 Fabric 库模组,允许你在任何 ItemStack 上存储持久化、类型化且经过模式验证的数据。

两种使用方式:

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

功能特性

  • 在任何 ItemStack 上存储类型化数据(int、float、string、boolean + 框架支持的用户自定义类型)。
  • 基于模式的验证 —— 框架会拒绝不符合已注册类型的值。
  • 自动持久化(在保存/加载、给予/克隆等操作后保留数据)。
  • 拥有不同数据的物品堆叠 不会合并。
  • 游戏内管理员命令 (/itemdata […]) 保存在世界存档中。
  • 通过简单的 CustomDataType<T> 接口实现可插拔的自定义类型。

安装方法(面向终端用户)

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

这就完成了 —— 模组现已激活。单独运行时它没有任何可见效果;当其他模组调用其 API 或 OP 玩家使用 /itemdata 命令时,它才会变得有用。


管理员命令教程

所有命令都需要至少 2 级的 OP 权限。它们操作的是主手当前持有的物品。

/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)

以此方式定义的模式会保存在世界存档中,因此它们在重启后也会保留。


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

本节将引导你从自己的 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")
    // 或者:modImplementation fileTree(dir: "libs", include: ["*.jar"])
}
  1. 在你的 fabric.mod.json 中声明它为依赖项,以确保它优先加载:
"depends": {
    "fabricloader": ">=0.18.4",
    "minecraft": "~1.20.6",
    "fabric-api": "*",
    "customitemdata": "*"
}

第 2 步 —— 注册模式

模式 (schema) 告诉框架哪些参数是某种物品类型所允许携带的,以及它们的类型。在模组的 onInitialize() 中注册你的模式,务必在 Minecraft 的注册表准备就绪之后进行。

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();

        // 棍子上一个简单的整数计数器,显示在工具提示中,
        // 默认为 "0" 且为必填(不可为空)。
        schemas.registerSchema("minecraft:stick",
            new SchemaEntry.Builder("nb_point", "int")
                .visible(true)
                .nullable(false)
                .defaultValue("0")
                .build());

        // 钻石剑上的字符串 "所有者" 字段。
        schemas.registerSchema("minecraft:diamond_sword",
            new SchemaEntry.Builder("owner", "string")
                .visible(true)
                .build());
    }
}

可用的基本类型:int、float、string、boolean。

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

第 3 步 —— 使用 ItemDataAPI 读写数据

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

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

ItemStack stack = player.getMainHandStack();

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

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

// 读取(带默认回退值)
int points   = ItemDataAPI.getInt(stack, "nb_point", 0);
String owner = ItemDataAPI.getString(stack, "owner", "unknown");

// 以 Optional 形式读取(如果键不存在则为空)
ItemDataAPI.getInt(stack, "nb_point").ifPresent(value -> ...);

// 检查 / 删除
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]));
    }

    // 更美观的工具提示显示:"(3, 7)" 而不是 "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));
    }
}

在引用它的任何架构之前注册它:

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);

完整的工作示例

一个最小的模组,定义棍子上的两个参数,在第一刻设置它们并重新读取:

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());

        // 右键点击棍子以增加其计数器。
        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 (静态方法)

Method Purpose
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

Method Default Description
visible(boolean) true 在物品工具提示中显示
nullable(boolean) true 允许该参数不存在
defaultValue(String) null 默认编码值(例如 "0"、"false")
fromCommand(boolean) false 标记为命令来源(触发持久化)

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

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

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

评论 0

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

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源