Something went wrong. Try again.
Library for my mods and adding supporter perks
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277/* * 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. * * <p>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. * * <pre>{@code * GuitaAttachmentTarget target = GuitaAttachmentTarget.of(player); * int mana = target.getAttachedOrCreate(MANA); * target.setAttached(MANA, mana + 1); * }</pre> * * <p>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.NonExtendablepublic 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 <A> the type of the data * @return the attached data, or {@code null} */ <A> @Nullable A getAttached(GuitaAttachmentType<A> 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 <A> the type of the data * @return the previous data, or {@code null} */ <A> @Nullable A setAttached(GuitaAttachmentType<A> 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 <A> the type of the data * @return the attached data */ default <A> A getAttachedOrThrow(GuitaAttachmentType<A> 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 <A> the type of the data * @return the attached data, initialized if originally absent */ default <A> A getAttachedOrSet(GuitaAttachmentType<A> 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 <A> the type of the data * @return the attached data, initialized if originally absent */ default <A> A getAttachedOrCreate(GuitaAttachmentType<A> type, Supplier<A> 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 * <i>only for attachment types with {@link GuitaAttachmentType#initializer() initializers}.</i> * It will throw an exception if one is not present. * * @param type the attachment type * @param <A> the type of the data * @return the attached data, initialized if originally absent */ default <A> A getAttachedOrCreate(GuitaAttachmentType<A> type) { Supplier<A> 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 <A> the type of the attached data * @return the attached data, or the default value */ default <A> A getAttachedOrElse(GuitaAttachmentType<A> 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 <A> the type of the attached data * @return the attached data, or the default value */ default <A> A getAttachedOrGet(GuitaAttachmentType<A> type, Supplier<A> 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 <A> the type of the data * @return the previous data, or {@code null} */ default <A> @Nullable A removeAttached(GuitaAttachmentType<A> 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 <A> the type of the data * @return the previous data, or {@code null} */ default <A> @Nullable A modifyAttached(GuitaAttachmentType<A> 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); }}