Skip to content

Synced Player Data

Gugas749 edited this page Nov 5, 2026 · 1 revision

Synced player data

AbyssSyncedAttachment<T> is a per-player value that is:

  • saved with the player (NeoForge: a data attachment; Forge: the player's persistent NBT under abysscore_attachments),
  • kept on death and End return (copied to the new player object),
  • synced to that player's client, and re-sent on login, respawn and dimension change.

Same API on both loaders. No events to wire and nothing to register on your mod bus.

Register

import com.gugas749.abysscore.api.attachment.AbyssSyncedAttachment;
import com.mojang.serialization.Codec;

public final class MyData {
    // id = mymod:mana, default 0
    public static final AbyssSyncedAttachment<Integer> MANA =
            AbyssSyncedAttachment.register("mymod", "mana", 0, Codec.INT);

    public static final AbyssSyncedAttachment<String> CLASS_NAME =
            AbyssSyncedAttachment.register("mymod", "class", "none", Codec.STRING);

    public static final AbyssSyncedAttachment<Boolean> TUTORIAL_DONE =
            AbyssSyncedAttachment.register("mymod", "tutorial_done", false, Codec.BOOL);

    /** Call from your mod constructor. */
    public static void init() {}
}
  • register(modId, name, default, codec) is the call to use, so ids live in your namespace.
  • register(name, default, codec) registers under abysscore:. It exists for old callers; don't use it in new code.
  • Registering the same id twice throws IllegalStateException.

Structured data: use a record + RecordCodecBuilder

public record ManaData(int current, int max) {
    public static final ManaData DEFAULT = new ManaData(100, 100);

    public static final Codec<ManaData> CODEC = RecordCodecBuilder.create(i -> i.group(
            Codec.INT.fieldOf("current").forGetter(ManaData::current),
            Codec.INT.fieldOf("max").forGetter(ManaData::max)
    ).apply(i, ManaData::new));

    public ManaData withCurrent(int value) {          // "with" = returns a NEW record
        return new ManaData(Math.max(0, Math.min(max, value)), max);
    }
}

public static final AbyssSyncedAttachment<ManaData> MANA =
        AbyssSyncedAttachment.register("mymod", "mana", ManaData.DEFAULT, ManaData.CODEC);

Values must be immutable. If T were a mutable class and you changed a field in place, nothing would be saved properly or sent to the client. Always build a new value and call set(...).

Read and write

// SERVER
ManaData mana = MyData.MANA.get(serverPlayer);                 // the saved value
MyData.MANA.set(serverPlayer, mana.withCurrent(mana.current() - 20));   // save + send to the client

// CLIENT (HUD, screen, client tick...)
ManaData mine = MyData.MANA.get(Minecraft.getInstance().player);  // last value the server sent
ManaData same = MyData.MANA.getClient();                          // same thing, no player needed

Client side, you only know your own values. Only the owning player's client is synced. On the client, get(localPlayer) returns the synced value, and get(anyOtherPlayer) returns the default. To show other players' data (e.g. a mana bar over their heads), send your own packet with sendToTracking.

Values that change every tick

set() sends a packet every time. For values that change every tick, save silently and sync only when needed:

// called every player tick on the server
ManaData m = MyData.MANA.get(player);
ManaData regen = m.withCurrent(m.current() + 1);
if (regen.equals(m)) return;                       // already full: nothing to do

if (player.tickCount % 20 == 0 || regen.current() == regen.max()) {
    MyData.MANA.set(player, regen);                // once per second, or when it hits max
} else {
    MyData.MANA.setSilently(player, regen);        // saved, but no packet
}
Method Side Description
register(modId, name, default, codec) both Create and register. Mod construction time only.
get(Player) both Server: saved value. Client: last synced value for the local player, default for anyone else.
getClient() client Last synced value
set(ServerPlayer, T) server Save + sync
setSilently(ServerPlayer, T) server Save without syncing
sync(ServerPlayer) server Send the saved value now
syncAll(ServerPlayer) (static) server Send every registered attachment to that player
id(), defaultValue() both
all() (static) both Read-only map of every registered attachment
byId(ResourceLocation) (static) both Look one up, or null
onPlayerClone/onLogin/onRespawn/onChangeDimension/onClientLogout — Internal: called by AbyssCore's loader listeners

Low-level helpers

Class Use
AttachmentNbt.encode(codec, value, id) Value → {"v": <tag>} CompoundTag. Errors are logged, not thrown.
AttachmentNbt.decode(codec, tag, fallback, id) The reverse. Returns fallback if missing or unreadable.
AttachmentStorage<T> The interface each loader implements (get/set on a Player). You don't need it.
SyncAttachmentPacket, SyncAttachmentClientHandler Internal sync packet. Never send it yourself.

Clone this wiki locally