# Custom Item Data<\/p>\n
  <\/p>\n
A **Fabric library mod** for Minecraft **1.20.6** that lets you store persistent, typed, schema-validated data on any `ItemStack`.<\/p>\n
### Two ways to use it:
\n– As a **mod developer**, call the `ItemDataAPI` from your own mod to read\/write values on items.
\n– As a **server admin**, use the `\/itemdata` commands in-game to define and edit item data without writing code.<\/p>\n
—<\/p>\n
## Features<\/p>\n
– Store typed data (`int`, `float`, `string`, `boolean` + your own types for framework) on any `ItemStack`. —<\/p>\n ## Installation (end users)<\/p>\n 1. Install **Fabric Loader** for Minecraft 1.20.6: https:\/\/fabricmc.net\/use\/installer\/ That’s it \u2014 the mod is now active. By itself it does nothing visible; it becomes useful when another mod calls its API, or when an OP uses the `\/itemdata` commands.<\/p>\n —<\/p>\n ## Admin commands tutorial<\/p>\n All commands require OP level 2. They operate on the item **currently held in the main hand**.<\/p>\n “`text Example session \u2014 give a stick a “points” counter:<\/p>\n “`text Schemas defined this way are saved in the world save, so they persist across restarts.<\/p>\n —<\/p>\n ## Framework tutorial (for mod developers)<\/p>\n This section walks you through using ItemDataFramework from your own Fabric mod \u2014 from zero to a working example in four steps.<\/p>\n ### Step 1 \u2014 Add the dependency<\/p>\n Until the mod is published to a Maven repository, the simplest approach is to drop its `.jar` into your project and reference it locally.<\/p>\n **Option A \u2014 local jar** (fastest):<\/p>\n 1. Build this mod: `.\/gradlew build` \u2014 the jar lands in `build\/libs\/customitemdata-1.0.0.jar`. “`gradle 4. In your `fabric.mod.json`, declare it as a dependency so it loads first:<\/p>\n “`json ### Step 2 \u2014 Register a schema<\/p>\n A **schema** tells the framework which parameters an item type is allowed to carry, and of what type. Register your schemas once, in your mod’s `onInitialize()`, *after* Minecraft’s registries are ready.<\/p>\n “`java import fr.hdi.customitemdata.schema.SchemaEntry; public class MyMod implements ModInitializer {<\/p>\n @Override \/\/ A simple integer counter on sticks, visible in the tooltip, \/\/ A string “owner” field on diamond swords. Available primitive types: `int`, `float`, `string`, `boolean`.<\/p>\n > Schemas registered via the API are re-applied every time the server starts \u2014 they are **not** persisted to the world. Only schemas created via `\/itemdata define` are persisted.<\/p>\n ### Step 3 \u2014 Read and write with `ItemDataAPI`<\/p>\n Once a schema exists, use `ItemDataAPI` anywhere you have an `ItemStack`. The API validates against the schema automatically; if validation fails, `set*` returns `false` and the stack is left unchanged.<\/p>\n “`java ItemStack stack = player.getMainHandStack();<\/p>\n ItemDataAPI.setCustomName(stack, “My Item”);<\/p>\n \/\/ Write \/\/ Read (with default fallback) \/\/ Read as Optional (absent if the key isn’t present) \/\/ Check \/ delete Under the hood, every value is serialized as a `String` inside a single `ItemDataComponent` attached to the stack. Two stacks with different data **will not merge**, because that’s how vanilla Data Components work.<\/p>\n ### Step 4 \u2014 Create a custom data type<\/p>\n When `int` \/ `float` \/ `string` \/ `boolean` aren’t enough, implement `CustomDataType – a unique string ID (`namespace:name`), “`java import com.mojang.serialization.Codec; public final class PointDataType implements CustomDataType public static final String TYPE_ID = “mymod:point”; private PointDataType() {}<\/p>\n @Override public String getId() { return TYPE_ID; }<\/p>\n @Override public Codec @Override @Override \/\/ Nicer tooltip display: “(3, 7)” instead of “Point[x=3, y=7]” public record Point(int x, int y) { Register it **before** any schema that uses it:<\/p>\n “`java schemas.registerCustomType(PointDataType.INSTANCE);<\/p>\n schemas.registerSchema(“minecraft:compass”, Then read\/write through the generic `get`\/`set` overloads:<\/p>\n “`java Optional ### Full working example<\/p>\n A minimal mod that defines two parameters on a stick, sets them on the first tick, and reads them back:<\/p>\n “`java import fr.hdi.customitemdata.api.ItemDataAPI; public class MyMod implements ModInitializer {<\/p>\n @Override schemas.registerSchema(“minecraft:stick”, schemas.registerSchema(“minecraft:stick”, \/\/ Right-click a stick to increment its counter. int current = ItemDataAPI.getInt(stack, “nb_point”, 0); player.sendMessage( —<\/p>\n ## Reference<\/p>\n ### `ItemDataAPI` (static methods)<\/p>\n | Method | Purpose | ### `SchemaEntry.Builder`<\/p>\n | Method | Default | Description | ### `SchemaManager` (singleton via `getInstance()`)<\/p>\n | Method | Purpose | —<\/p>\n","protected":false},"excerpt":{"rendered":" A useful mod for Minecraft servers or framework for mod developers to store easily data on item.<\/p>\n","protected":false},"featured_media":52799,"template":"","meta":{"_minecraft_slug":"custom-item-data","_minecraft_project_id":"ErlykZCV","_minecraft_author":"Hdi","_minecraft_license":"LicenseRef-All-Rights-Reserved","_minecraft_downloads":54,"_minecraft_follows":1,"_minecraft_client_side":"required","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"custom-item-data.zip","_minecraft_size_bytes":291395,"_minecraft_version_count":7,"_minecraft_updated_at":"2026-05-16T18:07:12.308289Z","_minecraft_date_created":"2026-04-25T15:15:24.193170Z","_minecraft_date_modified":"2026-05-12T18:23:43.621460Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/custom-item-data","_minecraft_icon_attachment_id":52799,"_minecraft_imported_at":"2026-06-02T22:06:00+00:00","_minecraft_import_hash":"5c723a5d52e912ca20ecc4ac0d8b2f09","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[97,873,98,91,92],"mod_loader":[99,100],"minecraft_version":[102],"class_list":["post-52798","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-fabric","mod_category-library","mod_category-quilt","mod_category-storage","mod_category-utility","mod_loader-fabric","mod_loader-quilt","minecraft_version-1-20-6"],"yoast_head":"\n
\n– Schema-based validation \u2014 the framework rejects values that don’t match the registered type.
\n– Automatic persistence (survives save\/load, gives\/clones, etc.).
\n– Stacks with different data **don’t stack together**.
\n– In-game admin commands (`\/itemdata [\u2026]`) persisted in the world save.
\n– Pluggable custom types via a simple `CustomDataType
\n2. Download **Fabric API** for 1.20.6 and drop the `.jar` into your `mods\/` folder.
\n3. Drop `customitemdata-1.0.0.jar` into the same `mods\/` folder.
\n4. Launch the game (or server). You should see `[ItemDataFramework] Initialis\u00e9 avec succ\u00e8s.` in the log.<\/p>\n
\n\/itemdata define
\n\/itemdata define
\n\/itemdata remove
\n\/itemdata get
\n\/itemrename [name]
\n“`<\/p>\n
\n\/itemdata define nb_point int
\n\/itemdata set nb_point 42
\n\/itemdata get nb_point \u2192 42
\n\/itemdata list \u2192 nb_point (int)
\n“`<\/p>\n
\n2. Copy that jar into a `libs\/` folder in your own mod project.
\n3. In your `build.gradle`:<\/p>\n
\ndependencies {
\n modImplementation files(“libs\/customitemdata-1.0.0.jar”)
\n \/\/ or: modImplementation fileTree(dir: “libs”, include: [“*.jar”])
\n}
\n“`<\/p>\n
\n“depends”: {
\n “fabricloader”: “>=0.18.4”,
\n “minecraft”: “~1.20.6”,
\n “fabric-api”: “*”,
\n “customitemdata”: “*”
\n}
\n“`<\/p>\n
\npackage com.example.mymod;<\/p>\n
\nimport fr.hdi.customitemdata.schema.SchemaManager;
\nimport net.fabricmc.api.ModInitializer;<\/p>\n
\n public void onInitialize() {
\n SchemaManager schemas = SchemaManager.getInstance();<\/p>\n
\n \/\/ defaulting to “0” and required (not nullable).
\n schemas.registerSchema(“minecraft:stick”,
\n new SchemaEntry.Builder(“nb_point”, “int”)
\n .visible(true)
\n .nullable(false)
\n .defaultValue(“0”)
\n .build());<\/p>\n
\n schemas.registerSchema(“minecraft:diamond_sword”,
\n new SchemaEntry.Builder(“owner”, “string”)
\n .visible(true)
\n .build());
\n }
\n}
\n“`<\/p>\n
\nimport fr.hdi.customitemdata.api.ItemDataAPI;
\nimport net.minecraft.item.ItemStack;<\/p>\n
\nItemDataAPI.setInt(stack, “nb_point”, 42);
\nItemDataAPI.setString(stack, “owner”, “Steve”);<\/p>\n
\nint points = ItemDataAPI.getInt(stack, “nb_point”, 0);
\nString owner = ItemDataAPI.getString(stack, “owner”, “unknown”);<\/p>\n
\nItemDataAPI.getInt(stack, “nb_point”).ifPresent(value -> …);<\/p>\n
\nboolean has = ItemDataAPI.has(stack, “nb_point”);
\nItemDataAPI.remove(stack, “nb_point”);
\n“`<\/p>\n
\n– an `encode` that turns your object into a string,
\n– a `decode` that parses it back,
\n– a `Codec
\npackage com.example.mymod;<\/p>\n
\nimport com.mojang.serialization.codecs.RecordCodecBuilder;
\nimport fr.hdi.customitemdata.api.CustomDataType;<\/p>\n
\n public static final PointDataType INSTANCE = new PointDataType();<\/p>\n
\n public String encode(Point value) {
\n return value.x() + “,” + value.y();
\n }<\/p>\n
\n public Point decode(String stored) {
\n String[] parts = stored.split(“,”, 2);
\n return new Point(Integer.parseInt(parts[0]), Integer.parseInt(parts[1]));
\n }<\/p>\n
\n @Override
\n public String display(String stored) {
\n Point p = decode(stored);
\n return “(” + p.x() + “, ” + p.y() + “)”;
\n }<\/p>\n
\n public static final Codec
\n Codec.INT.fieldOf(“x”).forGetter(Point::x),
\n Codec.INT.fieldOf(“y”).forGetter(Point::y)
\n ).apply(i, Point::new));
\n }
\n}
\n“`<\/p>\n
\nSchemaManager schemas = SchemaManager.getInstance();<\/p>\n
\n new SchemaEntry.Builder(“target”, PointDataType.TYPE_ID).build());
\n“`<\/p>\n
\nItemDataAPI.set(stack, “target”, new PointDataType.Point(3, 7), PointDataType.INSTANCE);<\/p>\n
\n ItemDataAPI.get(stack, “target”, PointDataType.INSTANCE);
\n“`<\/p>\n
\npackage com.example.mymod;<\/p>\n
\nimport fr.hdi.customitemdata.schema.SchemaEntry;
\nimport fr.hdi.customitemdata.schema.SchemaManager;
\nimport net.fabricmc.api.ModInitializer;
\nimport net.fabricmc.fabric.api.event.player.UseItemCallback;
\nimport net.minecraft.item.ItemStack;
\nimport net.minecraft.item.Items;
\nimport net.minecraft.util.ActionResult;
\nimport net.minecraft.util.TypedActionResult;<\/p>\n
\n public void onInitialize() {
\n SchemaManager schemas = SchemaManager.getInstance();<\/p>\n
\n new SchemaEntry.Builder(“nb_point”, “int”)
\n .nullable(false).defaultValue(“0”).build());<\/p>\n
\n new SchemaEntry.Builder(“owner”, “string”).build());<\/p>\n
\n UseItemCallback.EVENT.register((player, world, hand) -> {
\n ItemStack stack = player.getStackInHand(hand);
\n if (stack.getItem() != Items.STICK) {
\n return TypedActionResult.pass(stack);
\n }<\/p>\n
\n ItemDataAPI.setInt(stack, “nb_point”, current + 1);
\n ItemDataAPI.setString(stack, “owner”, player.getName().getString());<\/p>\n
\n net.minecraft.text.Text.literal(“Points: ” + (current + 1)), true);
\n return TypedActionResult.success(stack);
\n });
\n }
\n}
\n“`<\/p>\n
\n|————————————————————|——————————————|
\n| `getRaw(stack, key)` \/ `setRaw(stack, key, value)` | Raw string access |
\n| `getInt` \/ `setInt` | Integer values |
\n| `getFloat` \/ `setFloat` | Float values |
\n| `getString` \/ `setString` | String values |
\n| `getBoolean` \/ `setBoolean` | Boolean values |
\n| `get(stack, key, customType)` \/ `set(stack, key, v, t)` | Custom typed values |
\n| `has(stack, key)` \/ `hasData(stack)` | Presence checks |
\n| `remove(stack, key)` | Delete a key (removes component if empty)|
\n| `getComponent(stack)` | Access the raw `ItemDataComponent` |<\/p>\n
\n|———————-|———|————————————————|
\n| `visible(boolean)` | `true` | Show in item tooltip |
\n| `nullable(boolean)` | `true` | Allow the parameter to be absent |
\n| `defaultValue(String)`| `null` | Default encoded value (e.g. `”0″`, `”false”`) |
\n| `fromCommand(boolean)`| `false`| Mark as command-sourced (triggers persistence) |<\/p>\n
\n|————————————————–|————————————–|
\n| `registerSchema(itemId, entry)` | API-side schema registration |
\n| `registerCustomType(customDataType)` | Register a `CustomDataType
\n| `getEntry(itemId, paramName)` | Look up a single entry |
\n| `getEntries(itemId)` | Look up all entries for an item |
\n| `hasSchema(itemId)` | Does the item have any schema? |
\n| `isKnownType(typeId)` | Is the type ID primitive or custom? |
\n| `validateValue(entry, value)` | Validate a string against an entry |<\/p>\n