Custom Item Data
一个用于 Minecraft 1.20.6 的 Fabric 库模组,允许你在任何 ItemStack 上存储持久化、类型化且经过模式验证的数据。
两种使用方式:
- 作为 模组开发者,可以从你的模组中调用
ItemDataAPI来读取或写入物品上的值。 - 作为 服务器管理员,可以在游戏中使用
/itemdata命令来定义和编辑物品数据,而无需编写代码。
功能特性
- 在任何
ItemStack上存储类型化数据(int、float、string、boolean+ 框架支持的用户自定义类型)。 - 基于模式的验证 —— 框架会拒绝不符合已注册类型的值。
- 自动持久化(在保存/加载、给予/克隆等操作后保留数据)。
- 拥有不同数据的物品堆叠 不会合并。
- 游戏内管理员命令 (
/itemdata […]) 保存在世界存档中。 - 通过简单的
CustomDataType<T>接口实现可插拔的自定义类型。
安装方法(面向终端用户)
- 为 Minecraft 1.20.6 安装 Fabric Loader:
- 下载适用于 1.20.6 的 Fabric API,并将
.jar文件放入你的mods/文件夹。 - 将
customitemdata-1.0.0.jar放入同一个mods/文件夹。 - 启动游戏(或服务器)。你应该能在日志中看到
[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(最快):
- 构建此模组:
./gradlew build—— jar 包会生成在build/libs/customitemdata-1.0.0.jar。 - 将该 jar 复制到你自己模组项目的
libs/文件夹中。 - 在你的
build.gradle中:
dependencies {
modImplementation files("libs/customitemdata-1.0.0.jar")
// 或者:modImplementation fileTree(dir: "libs", include: ["*.jar"])
}
- 在你的
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) |
根据条目验证字符串 |
你是这个资源的作者?登录后可认领此资源。
相似资源
一个用于收集生物掉落物的多区块模组。
显示你正在注视的方块的信息。(适用于 Minecraft 1.16+ 的 Hwyla/Waila 分支)
使用 JavaScript 编辑配方、添加自定义物品、编写世界事件!
查看物品与配方
在游戏画面角落显示附近世界地形、玩家、生物和实体的地图。可创建路径点,帮助你找到标记过的位置。
AE2:一款流行的自动化与存储模组
评论 0
登录后参与评分
还没有评论,来抢沙发吧