Package net.ixdarklord.coolcatcore.api.attachment

Class Attachment<T>

java.lang.Object
net.ixdarklord.coolcatcore.api.attachment.Attachment<T>
Type Parameters:
T - the value's type
public final class Attachment<T> extends Object
A typed piece of data any entity (players included), block entity, item stack, level or the server itself can carry. Attachments come from a mod's AttachmentRegistry, declared once, statically: 

 public static final AttachmentRegistry ATTACHMENTS = AttachmentRegistry.create(MOD_ID);

 // Saved with the player, sent only to that player, kept when they die.
 public static final Attachment<Integer> MADNESS = ATTACHMENTS.builder("madness", Codec.INT, 0)
         .sync(SyncPolicy.SELF)
         .copyOnDeath()
         .build();

 int madness = MADNESS.get(player);
 MADNESS.set(player, madness + 1);
 MADNESS.update(player, m -> Math.max(0, m - 1));
Values should be immutable (numbers, records, immutable lists); a changed value is set(net.minecraft.world.entity.Entity, T) again. Mutable values are allowed on entities, block entities, levels and the server: change them with modify(net.minecraft.world.entity.Entity, java.util.function.Consumer<T>), or make them Trackable. Item stacks only take immutable, persistent values.

A level's values (get(Level)) are saved in its data folder and synced to the players in it; the server's (get(MinecraftServer)) in the server's, synced to every player, whom getGlobal(net.minecraft.world.level.Level) lets read them. For both, SyncPolicy.ALL sends them and SyncPolicy.NONE keeps them on the server. A player's values can be read and written while they're offline too (getOffline(net.minecraft.server.MinecraftServer, java.util.UUID)). 


 TEAM_STAGE.set(server, 3);                          // the whole server's, saved with it
 int stage = TEAM_STAGE.getGlobal(level);             // on either side: the server's, or the client's synced copy
 MADNESS.updateOffline(server, uuid, m -> m + 1);    // a player who isn't online: written to their data file

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    Attachment.Builder<T>
     
    static interface 
    Attachment.Listener<T>
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static @Nullable Attachment<?>
    byId(net.minecraft.resources.ResourceLocation id)
    The attachment with this id, if one was built.
    @Nullable com.mojang.serialization.Codec<T>
    codec()
    The codec values are saved with, or null for a transient attachment.
    boolean
    copyOnDeath()
    Whether a player keeps the value when they die and respawn.
    T
    createDefault()
    A fresh default value.
    void
    fireChanged(AttachmentHolder holder, T oldValue, T newValue)
    For holders: tells the listeners about a change.
    T
    get(net.minecraft.server.MinecraftServer server)
     
    T
    get(net.minecraft.world.entity.Entity entity)
     
    T
    get(net.minecraft.world.item.ItemStack stack)
     
    T
    get(net.minecraft.world.level.block.entity.BlockEntity blockEntity)
     
    T
    get(net.minecraft.world.level.Level level)
     
    T
    getGlobal(net.minecraft.world.level.Level level)
    The server's value as this side knows it: on the server, its own (get(MinecraftServer)); on a client, the copy it was sent (the default if this attachment isn't synced).
    T
    getOffline(net.minecraft.server.MinecraftServer server, UUID player)
    A player's value whether or not they're online: an online player's from their entity, an offline one's from their data file, or the default for a player who has never played here.
    boolean
    has(net.minecraft.server.MinecraftServer server)
     
    boolean
    has(net.minecraft.world.entity.Entity entity)
     
    boolean
    has(net.minecraft.world.item.ItemStack stack)
     
    boolean
    has(net.minecraft.world.level.block.entity.BlockEntity blockEntity)
     
    boolean
    has(net.minecraft.world.level.Level level)
     
    net.minecraft.resources.ResourceLocation
    id()
    modid:name.
    boolean
    isPersistent()
     
    boolean
    isSynced()
     
    boolean
    keepOnDrop()
    Whether a block entity's value travels with its dropped item and comes back when it's placed.
    void
    modify(net.minecraft.server.MinecraftServer server, Consumer<T> mutator)
     
    void
    modify(net.minecraft.world.entity.Entity entity, Consumer<T> mutator)
    Changes a mutable value in place, then saves and syncs it.
    void
    modify(net.minecraft.world.level.block.entity.BlockEntity blockEntity, Consumer<T> mutator)
     
    void
    modify(net.minecraft.world.level.Level level, Consumer<T> mutator)
     
    String
    name()
    The name within its mod.
    Attachment<T>
    onChange(Attachment.Listener<T> listener)
    Calls listener whenever a holder's value changes, on the side it changed: on the server when it's set, on clients when a synced value arrives.
    boolean
    playsSwapAnimation()
    Whether a change to its value on a held item shows the item being put away and taken out again, as vanilla does for most changes to a held stack.
    AttachmentRegistry
    registry()
    The registry of the mod it belongs to; its values are stored under that mod's id.
    void
    reset(net.minecraft.server.MinecraftServer server)
     
    void
    reset(net.minecraft.world.entity.Entity entity)
    Removes the value; the entity reads the default again.
    void
    reset(net.minecraft.world.item.ItemStack stack)
     
    void
    reset(net.minecraft.world.level.block.entity.BlockEntity blockEntity)
     
    void
    reset(net.minecraft.world.level.Level level)
     
    boolean
    resetOffline(net.minecraft.server.MinecraftServer server, UUID player)
    Removes a player's value whether or not they're online (see setOffline(net.minecraft.server.MinecraftServer, java.util.UUID, T)).
    void
    set(net.minecraft.server.MinecraftServer server, T value)
     
    void
    set(net.minecraft.world.entity.Entity entity, T value)
     
    void
    set(net.minecraft.world.item.ItemStack stack, T value)
     
    void
    set(net.minecraft.world.level.block.entity.BlockEntity blockEntity, T value)
     
    void
    set(net.minecraft.world.level.Level level, T value)
     
    boolean
    setOffline(net.minecraft.server.MinecraftServer server, UUID player, T value)
    Sets a player's value whether or not they're online; an offline player's is written to their data file at once (no AttachmentEvents fire for it, and it reaches them when they next join).
    @Nullable net.minecraft.network.codec.StreamCodec<? super net.minecraft.network.RegistryFriendlyByteBuf,T>
    streamCodec()
    The codec values are synced with, or null if they never leave the server.
    SyncPolicy
    syncPolicy()
     
    String
    toString()
     
    T
    update(net.minecraft.server.MinecraftServer server, UnaryOperator<T> function)
     
    T
    update(net.minecraft.world.entity.Entity entity, UnaryOperator<T> function)
    Sets the value to function's result and returns it.
    T
    update(net.minecraft.world.item.ItemStack stack, UnaryOperator<T> function)
     
    T
    update(net.minecraft.world.level.block.entity.BlockEntity blockEntity, UnaryOperator<T> function)
     
    T
    update(net.minecraft.world.level.Level level, UnaryOperator<T> function)
     
    boolean
    updateOffline(net.minecraft.server.MinecraftServer server, UUID player, UnaryOperator<T> function)
    Sets a player's value to function's result, whether or not they're online (see setOffline(net.minecraft.server.MinecraftServer, java.util.UUID, T)).

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Method Details

    • byId

      @Nullable public static @Nullable Attachment<?> byId(net.minecraft.resources.ResourceLocation id)
      The attachment with this id, if one was built.

    • id

      public net.minecraft.resources.ResourceLocation id()
      modid:name.

    • name

      public String name()
      The name within its mod.

    • registry

      public AttachmentRegistry registry()
      The registry of the mod it belongs to; its values are stored under that mod's id.

    • playsSwapAnimation

      public boolean playsSwapAnimation()
      Whether a change to its value on a held item shows the item being put away and taken out again, as vanilla does for most changes to a held stack. Off unless the builder asked for it (Attachment.Builder.swapAnimation()): an attachment's value changing leaves the item where it is in the hand (see HeldItemSwaps).

    • createDefault

      public T createDefault()
      A fresh default value.

    • codec

      @Nullable public @Nullable com.mojang.serialization.Codec<T> codec()
      The codec values are saved with, or null for a transient attachment.

    • streamCodec

      @Nullable public @Nullable net.minecraft.network.codec.StreamCodec<? super net.minecraft.network.RegistryFriendlyByteBuf,T> streamCodec()
      The codec values are synced with, or null if they never leave the server.

    • syncPolicy

      public SyncPolicy syncPolicy()

    • isPersistent

      public boolean isPersistent()

    • isSynced

      public boolean isSynced()

    • copyOnDeath

      public boolean copyOnDeath()
      Whether a player keeps the value when they die and respawn.

    • keepOnDrop

      public boolean keepOnDrop()
      Whether a block entity's value travels with its dropped item and comes back when it's placed.

    • onChange

      public Attachment<T> onChange(Attachment.Listener<T> listener)
      Calls listener whenever a holder's value changes, on the side it changed: on the server when it's set, on clients when a synced value arrives. For modify(net.minecraft.world.entity.Entity, java.util.function.Consumer<T>) and Trackable changes, the old and new values are the same object.

    • fireChanged

      public void fireChanged(AttachmentHolder holder, T oldValue, T newValue)
      For holders: tells the listeners about a change.

    • get

      public T get(net.minecraft.world.entity.Entity entity)

    • set

      public void set(net.minecraft.world.entity.Entity entity, T value)

    • update

      public T update(net.minecraft.world.entity.Entity entity, UnaryOperator<T> function)
      Sets the value to function's result and returns it.

    • modify

      public void modify(net.minecraft.world.entity.Entity entity, Consumer<T> mutator)
      Changes a mutable value in place, then saves and syncs it.

    • has

      public boolean has(net.minecraft.world.entity.Entity entity)

    • reset

      public void reset(net.minecraft.world.entity.Entity entity)
      Removes the value; the entity reads the default again.

    • get

      public T get(net.minecraft.world.level.block.entity.BlockEntity blockEntity)

    • set

      public void set(net.minecraft.world.level.block.entity.BlockEntity blockEntity, T value)

    • update

      public T update(net.minecraft.world.level.block.entity.BlockEntity blockEntity, UnaryOperator<T> function)

    • modify

      public void modify(net.minecraft.world.level.block.entity.BlockEntity blockEntity, Consumer<T> mutator)

    • has

      public boolean has(net.minecraft.world.level.block.entity.BlockEntity blockEntity)

    • reset

      public void reset(net.minecraft.world.level.block.entity.BlockEntity blockEntity)

    • get

      public T get(net.minecraft.world.item.ItemStack stack)

    • set

      public void set(net.minecraft.world.item.ItemStack stack, T value)

    • update

      public T update(net.minecraft.world.item.ItemStack stack, UnaryOperator<T> function)

    • has

      public boolean has(net.minecraft.world.item.ItemStack stack)

    • reset

      public void reset(net.minecraft.world.item.ItemStack stack)

    • get

      public T get(net.minecraft.world.level.Level level)

    • set

      public void set(net.minecraft.world.level.Level level, T value)

    • update

      public T update(net.minecraft.world.level.Level level, UnaryOperator<T> function)

    • modify

      public void modify(net.minecraft.world.level.Level level, Consumer<T> mutator)

    • has

      public boolean has(net.minecraft.world.level.Level level)

    • reset

      public void reset(net.minecraft.world.level.Level level)

    • get

      public T get(net.minecraft.server.MinecraftServer server)

    • set

      public void set(net.minecraft.server.MinecraftServer server, T value)

    • update

      public T update(net.minecraft.server.MinecraftServer server, UnaryOperator<T> function)

    • modify

      public void modify(net.minecraft.server.MinecraftServer server, Consumer<T> mutator)

    • has

      public boolean has(net.minecraft.server.MinecraftServer server)

    • reset

      public void reset(net.minecraft.server.MinecraftServer server)

    • getGlobal

      public T getGlobal(net.minecraft.world.level.Level level)
      The server's value as this side knows it: on the server, its own (get(MinecraftServer)); on a client, the copy it was sent (the default if this attachment isn't synced).
      Parameters:
      level - any level of the side asking

    • getOffline

      public T getOffline(net.minecraft.server.MinecraftServer server, UUID player)
      A player's value whether or not they're online: an online player's from their entity, an offline one's from their data file, or the default for a player who has never played here. Only for saved attachments. On the server thread.

    • setOffline

      public boolean setOffline(net.minecraft.server.MinecraftServer server, UUID player, T value)
      Sets a player's value whether or not they're online; an offline player's is written to their data file at once (no AttachmentEvents fire for it, and it reaches them when they next join). Only for saved attachments. On the server thread.
      Returns:
      false if the player has never played here, or the file couldn't be written

    • updateOffline

      public boolean updateOffline(net.minecraft.server.MinecraftServer server, UUID player, UnaryOperator<T> function)
      Sets a player's value to function's result, whether or not they're online (see setOffline(net.minecraft.server.MinecraftServer, java.util.UUID, T)).

    • resetOffline

      public boolean resetOffline(net.minecraft.server.MinecraftServer server, UUID player)
      Removes a player's value whether or not they're online (see setOffline(net.minecraft.server.MinecraftServer, java.util.UUID, T)).

    • toString

      public String toString()
      Overrides:
      toString in class Object