/* * Copyright 2026 macuguita * * Licensed under the EUPL, Version 1.2 or – as soon they will be approved by * the European Commission - subsequent versions of the EUPL (the "Licence"); * You may not use this work except in compliance with the Licence. * You may obtain a copy of the Licence at: * * https://joinup.ec.europa.eu/software/page/eupl * * Unless required by applicable law or agreed to in writing, software * distributed under the Licence is distributed on an "AS IS" basis, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the Licence for the specific language governing permissions and * limitations under the Licence. */ package com.macuguita.lib.api.attachment; import java.util.Objects; import java.util.function.Supplier; import java.util.function.UnaryOperator; import org.jetbrains.annotations.ApiStatus; import org.jspecify.annotations.Nullable; import net.minecraft.world.entity.Entity; import net.minecraft.world.level.Level; import net.minecraft.world.level.block.entity.BlockEntity; import net.minecraft.world.level.chunk.ChunkAccess; import com.macuguita.lib.impl.platform.CommonAbstraction; /** * Marks all objects on which data can be attached using {@link GuitaAttachmentType}s. * *

Unlike Fabric, the platform's native target interface cannot be injected onto game objects * without mixins, so this is a lightweight wrapper around an {@link Entity}, {@link BlockEntity}, * {@link Level} or {@link ChunkAccess}. Obtain one with the {@code of} factory methods, then read and * write attachments with the same method names Fabric uses. * *

{@code
 * GuitaAttachmentTarget target = GuitaAttachmentTarget.of(player);
 * int mana = target.getAttachedOrCreate(MANA);
 * target.setAttached(MANA, mana + 1);
 * }
* *

Note about {@link BlockEntity} and {@link ChunkAccess} targets: these objects need to be * notified of changes to their state (using {@code setChanged()} and {@code markUnsaved()} * respectively), otherwise the modifications will not take effect properly. As with Fabric, * {@link #setAttached(GuitaAttachmentType, Object)} handles this automatically, but it must be done * manually when the attached data is mutable and mutated in place. * * @see GuitaAttachmentType * @see GuitaAttachmentRegistry */ @ApiStatus.NonExtendable public interface GuitaAttachmentTarget { /** * Wraps the given {@link Entity} as an attachment target. * * @param entity the entity to wrap * @return an attachment target backed by {@code entity} */ static GuitaAttachmentTarget of(Entity entity) { return wrap(entity); } /** * Wraps the given {@link BlockEntity} as an attachment target. * * @param blockEntity the block entity to wrap * @return an attachment target backed by {@code blockEntity} */ static GuitaAttachmentTarget of(BlockEntity blockEntity) { return wrap(blockEntity); } /** * Wraps the given {@link Level} as an attachment target. * * @param level the level to wrap * @return an attachment target backed by {@code level} */ static GuitaAttachmentTarget of(Level level) { return wrap(level); } /** * Wraps the given {@link ChunkAccess} as an attachment target. * * @param chunk the chunk to wrap * @return an attachment target backed by {@code chunk} */ static GuitaAttachmentTarget of(ChunkAccess chunk) { return wrap(chunk); } /** * Gets the data associated with the given {@link GuitaAttachmentType}, or {@code null} if it * doesn't yet exist. * * @param type the attachment type * @param the type of the data * @return the attached data, or {@code null} */ @Nullable A getAttached(GuitaAttachmentType type); /** * Sets the data associated with the given {@link GuitaAttachmentType}. Passing {@code null} * removes the data. * * @param type the attachment type * @param value the new value * @param the type of the data * @return the previous data, or {@code null} */ @Nullable A setAttached(GuitaAttachmentType type, @Nullable A value); /** * Tests whether the given {@link GuitaAttachmentType} has any associated data. This doesn't * create any data, and may return {@code false} even for attachment types with an automatic * initializer. * * @param type the attachment type * @return whether there is associated data */ boolean hasAttached(GuitaAttachmentType type); /** * Gets the data associated with the given {@link GuitaAttachmentType}, throwing a * {@link NullPointerException} if it doesn't yet exist. * * @param type the attachment type * @param the type of the data * @return the attached data */ default A getAttachedOrThrow(GuitaAttachmentType type) { return Objects.requireNonNull(getAttached(type), "No value was attached"); } /** * Gets the data associated with the given {@link GuitaAttachmentType}, or initializes it using * the provided non-{@code null} default value. * * @param type the attachment type * @param defaultValue the fallback default value * @param the type of the data * @return the attached data, initialized if originally absent */ default A getAttachedOrSet(GuitaAttachmentType type, A defaultValue) { Objects.requireNonNull(defaultValue, "default value cannot be null"); A attached = getAttached(type); if (attached != null) { return attached; } setAttached(type, defaultValue); return defaultValue; } /** * Gets the data associated with the given {@link GuitaAttachmentType}, or initializes it using * the non-{@code null} result of the provided {@link Supplier}. * * @param type the attachment type * @param initializer the fallback initializer * @param the type of the data * @return the attached data, initialized if originally absent */ default A getAttachedOrCreate(GuitaAttachmentType type, Supplier initializer) { A attached = getAttached(type); if (attached != null) { return attached; } A initialized = Objects.requireNonNull(initializer.get(), "initializer result cannot be null"); setAttached(type, initialized); return initialized; } /** * Specialization of {@link #getAttachedOrCreate(GuitaAttachmentType, Supplier)}, but * only for attachment types with {@link GuitaAttachmentType#initializer() initializers}. * It will throw an exception if one is not present. * * @param type the attachment type * @param the type of the data * @return the attached data, initialized if originally absent */ default A getAttachedOrCreate(GuitaAttachmentType type) { Supplier init = type.initializer(); if (init == null) { throw new IllegalArgumentException( "Single-argument getAttachedOrCreate is reserved for attachment types with default initializers"); } return getAttachedOrCreate(type, init); } /** * Gets the data associated with the given {@link GuitaAttachmentType}, or returns the provided * non-{@code null} default value if it doesn't exist. Unlike {@link #getAttachedOrCreate}, this * doesn't initialize the attachment with the default value. * * @param type the attachment type * @param defaultValue the non-{@code null} default value to use as fallback * @param the type of the attached data * @return the attached data, or the default value */ default A getAttachedOrElse(GuitaAttachmentType type, A defaultValue) { Objects.requireNonNull(defaultValue, "default value cannot be null"); A attached = getAttached(type); return attached == null ? defaultValue : attached; } /** * Gets the data associated with the given {@link GuitaAttachmentType}, or gets the provided * non-{@code null} default value from the provided non-{@code null} supplier if it doesn't exist. * Unlike {@link #getAttachedOrCreate}, this doesn't initialize the attachment with the default * value. * * @param type the attachment type * @param defaultValue the default value supplier to use as fallback, must not return {@code null} * @param the type of the attached data * @return the attached data, or the default value */ default A getAttachedOrGet(GuitaAttachmentType type, Supplier defaultValue) { Objects.requireNonNull(defaultValue, "default value supplier cannot be null"); A attached = getAttached(type); return attached == null ? Objects.requireNonNull(defaultValue.get(), "default value supplier returned null") : attached; } /** * Removes any data associated with the given {@link GuitaAttachmentType}. Equivalent to calling * {@link #setAttached(GuitaAttachmentType, Object)} with {@code null}. * * @param type the attachment type * @param the type of the data * @return the previous data, or {@code null} */ default @Nullable A removeAttached(GuitaAttachmentType type) { return setAttached(type, null); } /** * Modifies the data associated with the given {@link GuitaAttachmentType}. Functionally the same * as calling {@link #getAttached(GuitaAttachmentType)}, applying the modifier, then calling * {@link #setAttached(GuitaAttachmentType, Object)} with the result. The modifier takes in the * currently attached value, or {@code null} if no attachment is present. * * @param type the attachment type * @param modifier the operation to apply to the current data, or to {@code null} if it doesn't * exist yet * @param the type of the data * @return the previous data, or {@code null} */ default @Nullable A modifyAttached(GuitaAttachmentType type, UnaryOperator<@Nullable A> modifier) { return setAttached(type, modifier.apply(getAttached(type))); } /** * Wraps the given holder, resolving the platform-specific implementation. * * @param holder an {@link Entity}, {@link BlockEntity}, {@link Level} or {@link ChunkAccess} * @return an attachment target backed by {@code holder} * @throws IllegalArgumentException if {@code holder} is not a supported type */ private static GuitaAttachmentTarget wrap(Object holder) { return CommonAbstraction.get().createAttachmentTarget(holder); } }