Custom Item Data

# Custom Item Data !(https://img.shields.io/badge/Minecraft-1.20.6-green) !(https://img.shields.io/badge/Loader-Fabric-blue) !(https://img.shields.io/badge/Status-In_Development-orange) A **Fabric library mod** for Minecraft **1.20.6** that lets you store persistent, typed, schema-validated data on any `ItemStack`. ### Two ways to use it: - As a **mod developer**, call the `ItemDataAPI` from your own mod to read/write values on items. - As a **server admin**, use the `/itemdata` commands in-game to define and edit item data without writing code. --- ## Features - Store typed data (`int`, `float`, `string`, `boolean` + your own types for framework) on any `ItemStack`. - Schema-based validation — the framework rejects values that don't match the registered type. - Automatic persistence (survives save/load, gives/clones, etc.). - Stacks with different data **don't stack together**. - In-game admin commands (`/itemdata `) persisted in the world save. - Pluggable custom types via a simple `CustomDataType<T>` interface. --- ## Installation (end users) 1. Install **Fabric Loader** for Minecraft 1.20.6: https://fabricmc.net/use/installer/ 2. Download **Fabric API** for 1.20.6 and drop the `.jar` into your `mods/` folder. 3. Drop `customitemdata-1.0.0.jar` into the same `mods/` folder. 4. Launch the game (or server). You should see ` Initialisé avec succès.` in the log. That's it — 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. --- ## Admin commands tutorial All commands require OP level 2. They operate on the item **currently held in the main hand**. ```text /itemdata define <param_name> <type> /itemdata define <param_name> <type> <visible> <nullable> /itemdata remove <param_name> /itemdata set <param_name> <value> /itemdata get <param_name> /itemdata list /itemrename ``` Example session — give a stick a "points" counter: ```text /itemdata define nb_point int /itemdata set nb_point 42 /itemdata get nb_point → 42 /itemdata list → nb_point (int) ``` Schemas defined this way are saved in the world save, so they persist across restarts. --- ## Framework tutorial (for mod developers) This section walks you through using ItemDataFramework from your own Fabric mod — from zero to a working example in four steps. ### Step 1 — Add the dependency Until the mod is published to a Maven repository, the simplest approach is to drop its `.jar` into your project and reference it locally. **Option A — local jar** (fastest): 1. Build this mod: `./gradlew build` — the jar lands in `build/libs/customitemdata-1.0.0.jar`. 2. Copy that jar into a `libs/` folder in your own mod project. 3. In your `build.gradle`: ```gradle dependencies { modImplementation files("libs/customitemdata-1.0.0.jar") // or: modImplementation fileTree(dir: "libs", include: ) } ``` 4. In your `fabric.mod.json`, declare it as a dependency so it loads first: ```json "depends": { "fabricloader": ">=0.18.4", "minecraft": "~1.20.6", "fabric-api": "*", "customitemdata": "*" } ``` ### Step 2 — Register a schema 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. ```java 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()); } } ``` Available primitive types: `int`, `float`, `string`, `boolean`. > Schemas registered via the API are re-applied every time the server starts — they are **not** persisted to the world. Only schemas created via `/itemdata define` are persisted. ### Step 3 — Read and write with `ItemDataAPI` 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. ```java import fr.hdi.customitemdata.api.ItemDataAPI; import net.minecraft.item.ItemStack; ItemStack stack = player.getMainHandStack