Custom Player Data

Fabric Framework 1.20.6 for managing persistent and synchronized player data.

This mod allows you to define custom variables attached to each player, which are saved in Minecraft's native player.dat file and automatically synchronized between the server and the client.

Features

JSON Schema: Define your variables in a player_data_schema.json file automatically generated in the map folder.
Native persistence: Data is stored directly in player.dat via Mixin — zero data loss, even after a crash.
Automatic synchronization: All variables are sent to the client upon connection and with every change (ideal for HUDs).
Developer API: Can be used as a dependency by other mods to inject and manipulate variables programmatically.
Custom types: Create your own complex data types (e.g., Power, Skill, Quest…).
Admin commands: /playerdata get and /playerdata set for operators.
Validation: Min/max for int, null checks, runtime type verification.

For Server Administrators

Installation

Place the .jar file in the mods/ folder of your Fabric 1.20.6 server.
Start the server for the first time—the player_data_schema.json file will be generated in your world folder (next to level.dat).
Modify the JSON as needed, then restart.

JSON Schema Format

{
  "note": {
    "type": "int",
    "defaultValue": 0,
    "maxValue": 5,
    "minValue": 0,
    "null": false
  },
  "hudColor": {
    "type": "string",
    "defaultValue": "light_blue",
    "null": false
  },
  "powers": {
    "type": "Power",
    "array": true,
    "defaultValue": null,
    "null": true
  }
}

Parameter	Description	Required
`type`	`int`, `string`, `boolean`, or a registered custom type	Yes
`defaultValue`	Default value for new players	No
`maxValue`	Maximum value (`int` type only)	No
`minValue`	Minimum value (`int` type only)	No
`null`	Allows `null` (`false` by default)	No
`array`	The variable is an array (`false` by default)	No

Important: If a variable has “null”: false and no defaultValue, an error will be logged at startup.

Commandes

Command	Description	Permission
`/playerdata get <variable> <joueur>`	Displays the current value	OP level 2+
`/playerdata set <variable> <joueur> <valeur>`	Modifies the value (primitive types only)	OP level 2+

Examples :

/playerdata get note Steve
/playerdata set hudColor Steve red
/playerdata set note Steve 3

Developer Guide — Using Custom Player Data as an API

1. Add the dependency

In your build.gradle file, add the JAR as a local dependency (or via a Maven repository if published):

dependencies {
    // add this one
    modImplementation files("libs/custom-player-data-1.0.0.jar")
}

In your fabric.mod.json file, add the following dependency:

{
  "depends": {
    "custom-player-data": ">=1.0.0"
  }
}

2. Create a custom type (optional)

If you need to store complex data, implement ICustomDataType:

package com.myMod.data;

import fr.hdi.api.ICustomDataType;
import net.minecraft.nbt.NbtCompound;

public class Skill implements ICustomDataType {

    private String name = "";
    private int xp = 0;
    private boolean unlocked = false;

    public Skill() {}

    public Skill(String name, int xp, boolean unlocked) {
        this.name = name;
        this.xp = xp;
        this.unlocked = unlocked;
    }

    @Override
    public void writeNbt(NbtCompound nbt) {
        nbt.putString("name", name);
        nbt.putInt("xp", xp);
        nbt.putBoolean("unlocked", unlocked);
    }

    @Override
    public void readNbt(NbtCompound nbt) {
        this.name = nbt.getString("name");
        this.xp = nbt.getInt("xp");
        this.unlocked = nbt.getBoolean("unlocked");
    }

    public String getName() { return name; }
    public int getXp() { return xp; }
    public boolean isUnlocked() { return unlocked; }
    public void setXp(int xp) { this.xp = xp; }
    public void setUnlocked(boolean unlocked) { this.unlocked = unlocked; }

    @Override
    public String toString() {
        return "Skill{" + name + ", xp=" + xp + ", unlocked=" + unlocked + "}";
    }
}

3. Register your types and variables

In your mod's onInitialize() method:

package com.myMod;

import com.myMod.data.Skill;
import fr.hdi.api.TypeRegistry;
import fr.hdi.schema.SchemaManager;
import fr.hdi.schema.VariableDefinition;
import net.fabricmc.api.ModInitializer;

public class myMod implements ModInitializer {

    @Override
    public void onInitialize() {
        // 1. Register custom Type
        TypeRegistry.register("Skill", Skill::new);

        // 2. Register variables schema all possibilties
        SchemaManager.registerVariable(
            VariableDefinition.builder("level", "int")
                .defaultValue(1)
                .minValue(1)
                .maxValue(100)
                .build()
        );

        SchemaManager.registerVariable(
            VariableDefinition.builder("clan", "string")
                .defaultValue("none")
                .build()
        );

        SchemaManager.registerVariable(
            VariableDefinition.builder("hasCompletedTutorial", "boolean")
                .defaultValue(false)
                .build()
        );

        SchemaManager.registerVariable(
            VariableDefinition.builder("skills", "Skill")
                .array(true)
                .nullable(true)
                .defaultNull()
                .build()
        );
    }
}

4. Reading and Writing Player Data

Use PlayerDataStore to access data from anywhere in your server code:

import fr.hdi.api.PlayerDataStore;
import net.minecraft.server.network.ServerPlayerEntity;

// Read classic type
int level = PlayerDataStore.getInt(player, "level");
String clan = PlayerDataStore.getString(player, "clan");
boolean done = PlayerDataStore.getBoolean(player, "hasCompletedTutorial");

// Read with default value
String color = PlayerDataStore.getString(player, "color", "red");

// Read custom type
Skill skill = PlayerDataStore.getCustom(player, "mainSkill", Skill.class);

// List reading
List<Skill> skills = PlayerDataStore.getList(player, "skills", Skill.class);

// Generic reading
Object raw = PlayerDataStore.getData(player, "level");


// set basic variables
PlayerDataStore.setData(player, "level", 42);
PlayerDataStore.setData(player, "clan", "Dragons");
PlayerDataStore.setData(player, "hasCompletedTutorial", true);

// write custom type array
Skill newSkill = new Skill("Archery", 150, true);
List<Skill> skillList = new ArrayList<>();
skillList.add(newSkill);
PlayerDataStore.setData(player, "skills", skillList);

5. Reading data on the client side

Data is automatically synchronized to the client. Use CustomPlayerDataClient:

import fr.hdi.CustomPlayerDataClient;

int level = CustomPlayerDataClient.getClientInt("level");
String color = CustomPlayerDataClient.getClientString("hudColor");
boolean done = CustomPlayerDataClient.getClientBoolean("hasCompletedTutorial");