Package net.fabricmc.fabric.api.attachment.v1

Interface AttachmentType<A>

Type Parameters:
A - type of the attached data. It is encouraged for this to be an immutable type.
@NonExtendable @Experimental public interface AttachmentType<A>
An attachment allows "attaching" arbitrary data to various game objects (entities, block entities, worlds and chunks at the moment). Use the methods provided in AttachmentRegistry to create and register attachments. Attachments can optionally be made to persist between restarts using a provided Codec.

While the API places no restrictions on the types of data that can be attached, it is generally encouraged to use immutable types. More generally, different attachments must not share mutable state, and it is strongly advised for attachments not to hold internal references to their target. See the following note on entity targets.

Note on Entity and Chunk targets: in several instances, the game needs to copy data from one instance to another. These are player respawning, mob conversion, return from the End, cross-world entity teleportation, and conversion of a ProtoChunk to WorldChunk. By default, attachments are simply copied wholesale, up to copyOnDeath(). Since one instance is discarded, an attachment that keeps a reference to an Entity or ProtoChunk instance can and will break unexpectedly. If, for whatever reason, keeping a reference to the target is absolutely necessary, be sure to implement custom copying logic. For Entity targets, use ServerPlayerEvents.COPY_FROM, ServerEntityWorldChangeEvents.AFTER_ENTITY_CHANGE_WORLD, and ServerLivingEntityEvents.MOB_CONVERSION. For Chunk targets, mixin into WorldChunk(ServerWorld, ProtoChunk, WorldChunk.EntityLoader).

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    copyOnDeath()
     
    Identifier
    identifier()
     
    @Nullable Supplier<A>
    initializer()
    If an object has no value associated to an attachment, this initializer is used to create a non-null starting value.
    default boolean
    isPersistent()
     
    @Nullable com.mojang.serialization.Codec<A>
    persistenceCodec()
    An optional Codec used for reading and writing attachments to NBT for persistence.

  • Method Details

    • identifier

      Identifier identifier()
      Returns:
      the identifier that uniquely identifies this attachment

    • persistenceCodec

      @Nullable @Nullable com.mojang.serialization.Codec<A> persistenceCodec()
      An optional Codec used for reading and writing attachments to NBT for persistence.
      Returns:
      the persistence codec, may be null

    • isPersistent

      default boolean isPersistent()
      Returns:
      whether the attachments persist across server restarts

    • initializer

      @Nullable @Nullable Supplier<A> initializer()
      If an object has no value associated to an attachment, this initializer is used to create a non-null starting value.

      It is encouraged for AttachmentType to be an immutable data type, such as a primitive type or an immutable record.

      Otherwise, one must be very careful, as attachments must not share any mutable state. As an example, for a (mutable) list/array attachment type, the initializer should create a new independent instance each time it is called.

      Returns:
      the initializer for this attachment

    • copyOnDeath

      boolean copyOnDeath()
      Returns:
      whether the attachments should persist after an entity dies, for example when a player respawns or when a mob is converted (e.g. zombie → drowned)