Add registry builder for Instrument (#12682)

Co-authored-by: Lulu13022002 <41980282+Lulu13022002@users.noreply.github.com>

paper-api/src/main/java/io/papermc/paper/registry/data/InlinedRegistryBuilderProvider.java

@@ -4,7 +4,7 @@ import io.papermc.paper.registry.RegistryBuilderFactory;
 import java.util.Optional;
 import java.util.ServiceLoader;
 import java.util.function.Consumer;
-import org.bukkit.Art;
+import org.bukkit.MusicInstrument;
 import org.jetbrains.annotations.ApiStatus;
 
 @ApiStatus.Internal
@@ -18,4 +18,5 @@ public interface InlinedRegistryBuilderProvider {
         return Holder.INSTANCE.orElseThrow();
     }
 
+    MusicInstrument createInstrument(Consumer<RegistryBuilderFactory<MusicInstrument, ? extends InstrumentRegistryEntry.Builder>> value);
 }

paper-api/src/main/java/io/papermc/paper/registry/data/InstrumentRegistryEntry.java

@@ -0,0 +1,149 @@
+package io.papermc.paper.registry.data;
+
+import io.papermc.paper.registry.RegistryBuilder;
+import io.papermc.paper.registry.RegistryBuilderFactory;
+import io.papermc.paper.registry.TypedKey;
+import io.papermc.paper.registry.holder.RegistryHolder;
+import net.kyori.adventure.text.Component;
+import org.bukkit.MusicInstrument;
+import org.bukkit.Sound;
+import org.checkerframework.checker.index.qual.Positive;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.Contract;
+import java.util.function.Consumer;
+
+/**
+ * A data-centric version-specific registry entry for the {@link org.bukkit.MusicInstrument} type.
+ */
+@ApiStatus.Experimental
+@ApiStatus.NonExtendable
+public interface InstrumentRegistryEntry {
+
+    /**
+     * Provides the sound event of the instrument.
+     *
+     * @return the sound event.
+     * @see MusicInstrument#getSound()
+     */
+    @Contract(pure = true)
+    RegistryHolder<Sound, SoundEventRegistryEntry> soundEvent();
+
+    /**
+     * Provides the duration of the instrument, which is time to use.
+     *
+     * @return the duration.
+     * @see MusicInstrument#getDuration()
+     */
+    @Contract(pure = true)
+    @Positive float duration();
+
+    /**
+     * Provides the range of the instrument, which is range of the sound.
+     *
+     * @return the range.
+     * @see MusicInstrument#getRange()
+     */
+    @Contract(pure = true)
+    @Positive float range();
+
+    /**
+     * Provides the description of the instrument, which is used in the item tooltip.
+     *
+     * @return the description.
+     * @see MusicInstrument#description()
+     */
+    @Contract(pure = true)
+    Component description();
+
+    /**
+     * A mutable builder for the {@link InstrumentRegistryEntry} plugins may change in applicable registry events.
+     * <p>
+     * The following values are required for each builder:
+     * <ul>
+     *     <li>
+     *         {@link #soundEvent(TypedKey)}, {@link #soundEvent(Consumer)} or {@link #soundEvent(RegistryHolder)}
+     *     </li>
+     *     <li>{@link #duration(float)}</li>
+     *     <li>{@link #range(float)}</li>
+     *     <li>{@link #description(Component)}</li>
+     * </ul>
+     */
+    @ApiStatus.Experimental
+    @ApiStatus.NonExtendable
+    interface Builder extends InstrumentRegistryEntry, RegistryBuilder<MusicInstrument> {
+
+        /**
+         * Sets the sound event for this instrument to a sound event present
+         * in the {@link io.papermc.paper.registry.RegistryKey#SOUND_EVENT} registry.
+         * <p>This will override both {@link #soundEvent(Consumer)} and {@link #soundEvent(RegistryHolder)}</p>
+         *
+         * @param soundEvent the sound event
+         * @return this builder
+         * @see #soundEvent(Consumer)
+         * @see InstrumentRegistryEntry#soundEvent()
+         * @see MusicInstrument#getSound()
+         */
+        @Contract(value = "_ -> this", mutates = "this")
+        Builder soundEvent(TypedKey<Sound> soundEvent);
+
+        /**
+         * Sets the sound event for this instrument to a new sound event.
+         * <p>This will override both {@link #soundEvent(TypedKey)} and {@link #soundEvent(RegistryHolder)}</p>
+         *
+         * @param soundEvent the sound event
+         * @return this builder
+         * @see #soundEvent(TypedKey)
+         * @see InstrumentRegistryEntry#soundEvent()
+         * @see MusicInstrument#getSound()
+         */
+        @Contract(value = "_ -> this", mutates = "this")
+        Builder soundEvent(Consumer<RegistryBuilderFactory<Sound, ? extends SoundEventRegistryEntry.Builder>> soundEvent);
+
+        /**
+         * Sets the sound event for this instrument.
+         * <p>This will override both {@link #soundEvent(Consumer)} and {@link #soundEvent(TypedKey)}</p>
+         *
+         * @param soundEvent the sound event
+         * @return this builder
+         * @see #soundEvent(TypedKey)
+         * @see #soundEvent(Consumer)
+         * @see InstrumentRegistryEntry#soundEvent()
+         * @see MusicInstrument#getSound()
+         */
+        @Contract(value = "_ -> this", mutates = "this")
+        Builder soundEvent(RegistryHolder<Sound, SoundEventRegistryEntry> soundEvent);
+
+        /**
+         * Sets the duration of use for this instrument.
+         *
+         * @param duration the duration (positive)
+         * @return this builder
+         * @see InstrumentRegistryEntry#duration()
+         * @see MusicInstrument#getDuration()
+         */
+        @Contract(value = "_ -> this", mutates = "this")
+        Builder duration(@Positive float duration);
+
+        /**
+         * Sets the range for this instrument.
+         *
+         * @param range the range (positive)
+         * @return this builder
+         * @see InstrumentRegistryEntry#range()
+         * @see MusicInstrument#getRange()
+         */
+        @Contract(value = "_ -> this", mutates = "this")
+        Builder range(@Positive float range);
+
+        /**
+         * Sets the description for this instrument.
+         *
+         * @param description the description
+         * @return this builder
+         * @see InstrumentRegistryEntry#description()
+         * @see MusicInstrument#description()
+         */
+        @Contract(value = "_ -> this", mutates = "this")
+        Builder description(Component description);
+    }
+}

paper-api/src/main/java/io/papermc/paper/registry/event/RegistryEvents.java

@@ -9,6 +9,7 @@ import io.papermc.paper.registry.data.DamageTypeRegistryEntry;
 import io.papermc.paper.registry.data.EnchantmentRegistryEntry;
 import io.papermc.paper.registry.data.FrogVariantRegistryEntry;
 import io.papermc.paper.registry.data.GameEventRegistryEntry;
+import io.papermc.paper.registry.data.InstrumentRegistryEntry;
 import io.papermc.paper.registry.data.JukeboxSongRegistryEntry;
 import io.papermc.paper.registry.data.PaintingVariantRegistryEntry;
 import io.papermc.paper.registry.data.PigVariantRegistryEntry;
@@ -16,6 +17,7 @@ import io.papermc.paper.registry.data.WolfVariantRegistryEntry;
 import org.bukkit.Art;
 import org.bukkit.GameEvent;
 import org.bukkit.JukeboxSong;
+import org.bukkit.MusicInstrument;
 import org.bukkit.block.banner.PatternType;
 import org.bukkit.damage.DamageType;
 import org.bukkit.enchantments.Enchantment;
@@ -43,6 +45,7 @@ public final class RegistryEvents {
     public static final RegistryEventProvider<JukeboxSong, JukeboxSongRegistryEntry.Builder> JUKEBOX_SONG = create(RegistryKey.JUKEBOX_SONG);
     public static final RegistryEventProvider<PatternType, BannerPatternRegistryEntry.Builder> BANNER_PATTERN = create(RegistryKey.BANNER_PATTERN);
     public static final RegistryEventProvider<Art, PaintingVariantRegistryEntry.Builder> PAINTING_VARIANT = create(RegistryKey.PAINTING_VARIANT);
+    public static final RegistryEventProvider<MusicInstrument, InstrumentRegistryEntry.Builder> INSTRUMENT = create(RegistryKey.INSTRUMENT);
     public static final RegistryEventProvider<Cat.Type, CatTypeRegistryEntry.Builder> CAT_VARIANT = create(RegistryKey.CAT_VARIANT);
     public static final RegistryEventProvider<Frog.Variant, FrogVariantRegistryEntry.Builder> FROG_VARIANT = create(RegistryKey.FROG_VARIANT);
     public static final RegistryEventProvider<Chicken.Variant, ChickenVariantRegistryEntry.Builder> CHICKEN_VARIANT = create(RegistryKey.CHICKEN_VARIANT);

paper-api/src/main/java/org/bukkit/MusicInstrument.java

@@ -2,16 +2,32 @@ package org.bukkit;
 
 import com.google.common.collect.Lists;
 import io.papermc.paper.registry.RegistryAccess;
+import io.papermc.paper.registry.RegistryBuilderFactory;
 import io.papermc.paper.registry.RegistryKey;
+import io.papermc.paper.registry.data.InlinedRegistryBuilderProvider;
+import io.papermc.paper.registry.data.InstrumentRegistryEntry;
 import java.util.Collection;
 import java.util.Collections;
+import java.util.function.Consumer;
 import net.kyori.adventure.text.Component;
+import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
 @NullMarked
 public abstract class MusicInstrument implements Keyed, net.kyori.adventure.translation.Translatable {
 
+    /**
+     * Creates an inlined music instrument.
+     *
+     * @param value a consumer for the builder factory
+     * @return the created music instrument
+     */
+    @ApiStatus.Experimental
+    public static MusicInstrument create(final Consumer<RegistryBuilderFactory<MusicInstrument, ? extends InstrumentRegistryEntry.Builder>> value) {
+        return InlinedRegistryBuilderProvider.instance().createInstrument(value);
+    }
+
     // Start generate - MusicInstrument
     // @GeneratedFrom 1.21.7
     public static final MusicInstrument ADMIRE_GOAT_HORN = getInstrument("admire_goat_horn");
@@ -31,12 +47,16 @@ public abstract class MusicInstrument implements Keyed, net.kyori.adventure.tran
     public static final MusicInstrument YEARN_GOAT_HORN = getInstrument("yearn_goat_horn");
     // End generate - MusicInstrument
 
+    private static MusicInstrument getInstrument(final String key) {
+        return RegistryAccess.registryAccess().getRegistry(RegistryKey.INSTRUMENT).getOrThrow(NamespacedKey.minecraft(key));
+    }
+
     /**
      * Returns a {@link MusicInstrument} by a {@link NamespacedKey}.
      *
      * @param namespacedKey the key
      * @return the event or null
-     * @deprecated Use {@link Registry#get(NamespacedKey)} instead.
+     * @deprecated use {@link Registry#get(NamespacedKey)} instead
      */
     @Nullable
     @Deprecated(since = "1.20.1")
@@ -45,38 +65,34 @@ public abstract class MusicInstrument implements Keyed, net.kyori.adventure.tran
     }
 
     /**
-     * Returns all known MusicInstruments.
+     * Returns all known music instruments.
      *
-     * @return the memoryKeys
-     * @deprecated use {@link Registry#iterator()}.
+     * @return the music instruments
+     * @deprecated use {@link Registry#iterator()}
      */
     @Deprecated(since = "1.20.1")
     public static Collection<MusicInstrument> values() {
         return Collections.unmodifiableCollection(Lists.newArrayList(Registry.INSTRUMENT));
     }
 
-    private static MusicInstrument getInstrument(final String key) {
-        return RegistryAccess.registryAccess().getRegistry(RegistryKey.INSTRUMENT).getOrThrow(NamespacedKey.minecraft(key));
-    }
-
     /**
      * Gets the use duration of this music instrument.
      *
-     * @return the duration expressed in seconds.
+     * @return the duration expressed in seconds
      */
     public abstract float getDuration();
 
     /**
      * Gets the range of the sound.
      *
-     * @return the range of the sound.
+     * @return the range of the sound
      */
     public abstract float getRange();
 
     /**
-     * Provides the description of this instrument as displayed to the client.
+     * Gets the description of this instrument as displayed to the client.
      *
-     * @return the description component.
+     * @return the description component
      */
     public abstract Component description();