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

Interface AttachmentTarget

@Experimental @NonExtendable public interface AttachmentTarget
Marks all objects on which data can be attached using AttachmentTypes.

Fabric implements this on Entity, BlockEntity, ServerWorld and Chunk via mixin.

Note about BlockEntity and Chunk targets: these objects need to be notified of changes to their state (using BlockEntity.markDirty() and Chunk.setNeedsSaving(boolean) respectively), otherwise the modifications will not take effect properly. The setAttached(AttachmentType, Object) method handles this automatically, but this needs to be done manually when attached data is mutable, for example: 


 AttachmentType<MutableType> MUTABLE_ATTACHMENT_TYPE = ...;
 BlockEntity be = ...;
 MutableType data = be.getAttachedOrCreate(MUTABLE_ATTACHMENT_TYPE);
 data.mutate();
 be.markDirty(); // Required because we are not using setAttached

Note about BlockEntity targets: by default, many block entities use their NBT to synchronize with the client. That would mean persistent attachments are automatically synced with the client for those block entities. As this is undesirable behavior, the API completely removes attachments from the result of BlockEntity.toInitialChunkDataNbt(), which takes care of all vanilla types. However, modded block entities may be coded differently, so be wary of this when attaching data to modded block entities.

Note about Chunk targets with ChunkStatus.EMPTY: These chunks are not saved unless the generation progresses to at least ChunkStatus.STRUCTURE_STARTS. Therefore, persistent attachments to those chunks may not be saved. The setAttached(AttachmentType, Object) method will log a warning when this is attempted.

  • Field Details

  • Method Details

    • getAttached

      @Nullable default <A> A getAttached(AttachmentType<A> type)
      Gets the data associated with the given AttachmentType, or null if it doesn't yet exist.
      Type Parameters:
      A - the type of the data
      Parameters:
      type - the attachment type
      Returns:
      the attached data

    • getAttachedOrThrow

      default <A> A getAttachedOrThrow(AttachmentType<A> type)
      Gets the data associated with the given AttachmentType, throwing a NullPointerException if it doesn't yet exist.
      Type Parameters:
      A - the type of the data
      Parameters:
      type - the attachment type
      Returns:
      the attached data

    • getAttachedOrSet

      default <A> A getAttachedOrSet(AttachmentType<A> type, A defaultValue)
      Gets the data associated with the given AttachmentType, or initializes it using the provided non-null default value.
      Type Parameters:
      A - the type of the data
      Parameters:
      type - the attachment type
      defaultValue - the fallback default value
      Returns:
      the attached data, initialized if originally absent

    • getAttachedOrCreate

      default <A> A getAttachedOrCreate(AttachmentType<A> type, Supplier<A> initializer)
      Gets the data associated with the given AttachmentType, or initializes it using the non-null result of the provided Supplier.
      Type Parameters:
      A - the type of the data
      Parameters:
      type - the attachment type
      initializer - the fallback initializer
      Returns:
      the attached data, initialized if originally absent

    • getAttachedOrCreate

      default <A> A getAttachedOrCreate(AttachmentType<A> type)
      Specialization of getAttachedOrCreate(AttachmentType, Supplier), but only for attachment types with initializers. It will throw an exception if one is not present.
      Type Parameters:
      A - the type of the data
      Parameters:
      type - the attachment type
      Returns:
      the attached data, initialized if originally absent

    • getAttachedOrElse

      @Contract("_, !null -> !null") default <A> A getAttachedOrElse(AttachmentType<A> type, @Nullable A defaultValue)
      Gets the data associated with the given AttachmentType, or returns the provided default value if it doesn't exist. Unlike getAttachedOrCreate(AttachmentType, Supplier), this doesn't initialize the attachment with the default value.
      Type Parameters:
      A - the type of the attached data
      Parameters:
      type - the attachment type
      defaultValue - the default value to use as fallback
      Returns:
      the attached data, or the default value

    • getAttachedOrGet

      default <A> A getAttachedOrGet(AttachmentType<A> type, Supplier<A> defaultValue)
      Gets the data associated with the given AttachmentType, or gets the provided default value from the provided non-null supplier if it doesn't exist. The supplier may return null. Unlike getAttachedOrCreate(AttachmentType, Supplier), this doesn't initialize the attachment with the default value.
      Type Parameters:
      A - the type of the attached data
      Parameters:
      type - the attachment type
      defaultValue - the default value supplier to use as fallback
      Returns:
      the attached data, or the default value

    • setAttached

      @Nullable default <A> A setAttached(AttachmentType<A> type, @Nullable A value)
      Sets the data associated with the given AttachmentType. Passing null removes the data.
      Type Parameters:
      A - the type of the data
      Parameters:
      type - the attachment type
      value - the new value
      Returns:
      the previous data

    • hasAttached

      default boolean hasAttached(AttachmentType<?> type)
      Tests whether the given AttachmentType has any associated data. This doesn't create any data, and may return false even for attachment types with an automatic initializer.
      Parameters:
      type - the attachment type
      Returns:
      whether there is associated data

    • removeAttached

      @Nullable default <A> A removeAttached(AttachmentType<A> type)
      Removes any data associated with the given AttachmentType. Equivalent to calling setAttached(AttachmentType, Object) with null.
      Type Parameters:
      A - the type of the data
      Parameters:
      type - the attachment type
      Returns:
      the previous data

    • modifyAttached

      @Nullable default <A> A modifyAttached(AttachmentType<A> type, UnaryOperator<A> modifier)
      Modifies the data associated with the given AttachmentType. Functionally the same as calling getAttached(AttachmentType), applying the modifier, then calling setAttached(AttachmentType, Object) with the result. The modifier takes in the currently attached value, or null if no attachment is present.
      Type Parameters:
      A - the type of the data
      Parameters:
      type - the attachment type
      modifier - the operation to apply to the current data, or to null if it doesn't exist yet
      Returns:
      the previous data