
自定义物品数据
一个对Minecraft服务器有用的模组,或供模组开发者轻松在物品上存储数据的框架。
自定义物品数据
一个用于 Minecraft 1.20.6 的 Fabric 库模组,可让你在任何 ItemStack 上存储持久化、带类型、经 schema 校验的数据。
两种使用方式:
- 作为模组开发者,在你自己的模组中调用
ItemDataAPI来读写物品上的值。 - 作为服务器管理员,在游戏内使用
/itemdata命令来定义和编辑物品数据,无需编写代码。
特性
- 在任何
ItemStack上存储带类型的数据(int、float、string、boolean,以及由框架支持的自定义类型)。 - 基于 schema 的校验——框架会拒绝与已注册类型不匹配的值。
- 自动持久化(在存档/读档、给予/克隆等操作后仍保留)。
- 数据不同的物品堆叠不会堆叠在一起。
- 游戏内管理员命令(
/itemdata […]),持久化在世界存档中。 - 通过简单的
CustomDataType<T>接口接入可插拔的自定义类型。
安装(终端用户)
- 为 Minecraft 1.20.6 安装 Fabric Loader:https://fabricmc.net/use/installer/
- 下载适用于 1.20.6 的 Fabric API,并将
.jar放入你的mods/文件夹。 - 将
customitemdata-1.0.0.jar放入同一个mods/文件夹。 - 启动游戏(或服务器)。你应该会在日志中看到
[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(最快):
- 构建此模组:
./gradlew build—— jar 会生成在build/libs/customitemdata-1.0.0.jar。 - 将该 jar 复制到你自己的模组项目中的
libs/文件夹。 - 在你的
build.gradle中:
dependencies {
modImplementation files("libs/customitemdata-1.0.0.jar")
// or: modImplementation fileTree(dir: "libs", include: ["*.jar"])
}
- 在你的
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) |
根据条目校验字符串 |
正在加载版本记录…
正在加载评论…
评论在新手盒子客户端中发表,这里同步展示。