Expose more data for MusicInstrument

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

@@ -5,10 +5,15 @@
 import io.papermc.paper.registry.RegistryKey;
 import java.util.Collection;
 import java.util.Collections;
-import org.jetbrains.annotations.NotNull;
-import org.jetbrains.annotations.Nullable;
+import java.util.NoSuchElementException;
+import net.kyori.adventure.key.Key;
+import net.kyori.adventure.text.Component;
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
-public abstract class MusicInstrument implements Keyed, net.kyori.adventure.translation.Translatable { // Paper - translation keys
+@NullMarked
+public abstract class MusicInstrument implements Keyed, net.kyori.adventure.translation.Translatable {
 
     // Start generate - MusicInstrument
     // @GeneratedFrom 1.21.5
@@ -33,12 +38,12 @@ public abstract class MusicInstrument implements Keyed, net.kyori.adventure.tran
      * Returns a {@link MusicInstrument} by a {@link NamespacedKey}.
      *
      * @param namespacedKey the key
-     * @return the event or null
+     * @return the music instrument or null
      * @deprecated Use {@link Registry#get(NamespacedKey)} instead.
      */
     @Nullable
     @Deprecated(since = "1.20.1")
-    public static MusicInstrument getByKey(@NotNull NamespacedKey namespacedKey) {
+    public static MusicInstrument getByKey(final NamespacedKey namespacedKey) {
         return Registry.INSTRUMENT.get(namespacedKey);
     }
 
@@ -48,45 +53,74 @@ public static MusicInstrument getByKey(@NotNull NamespacedKey namespacedKey) {
      * @return the memoryKeys
      * @deprecated use {@link Registry#iterator()}.
      */
-    @NotNull
     @Deprecated(since = "1.20.1")
     public static Collection<MusicInstrument> values() {
         return Collections.unmodifiableCollection(Lists.newArrayList(Registry.INSTRUMENT));
     }
 
-    @NotNull
-    private static MusicInstrument getInstrument(@NotNull String key) {
+    /**
+     * Returns a {@link MusicInstrument} by a {@link String} key.
+     *
+     * @param key the key
+     * @return the music instrument
+     * @throws NoSuchElementException if there is no object with the given key
+     */
+    @ApiStatus.Internal
+    private static MusicInstrument getInstrument(final String key) {
         return RegistryAccess.registryAccess().getRegistry(RegistryKey.INSTRUMENT).getOrThrow(NamespacedKey.minecraft(key));
     }
 
-    // Paper start - deprecate getKey
+    /**
+     * Gets for how long the use duration is for the instrument.
+     *
+     * @return the duration.
+     */
+    public abstract float getDuration();
+
+    /**
+     * Gets 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.
+     *
+     * @return the description component.
+     */
+    public abstract Component getDescription();
+
+    /**
+     * Gets the sound for this instrument.
+     *
+     * @return a sound
+     */
+    public abstract Sound getSound();
+
     /**
      * @deprecated use {@link Registry#getKey(Keyed)}, {@link io.papermc.paper.registry.RegistryAccess#getRegistry(io.papermc.paper.registry.RegistryKey)},
      * and {@link io.papermc.paper.registry.RegistryKey#INSTRUMENT}. MusicInstruments can exist without a key.
      */
     @Deprecated(forRemoval = true, since = "1.20.5")
     @Override
-    public abstract @NotNull NamespacedKey getKey();
+    public abstract NamespacedKey getKey();
 
     /**
      * @deprecated use {@link Registry#getKey(Keyed)}, {@link io.papermc.paper.registry.RegistryAccess#getRegistry(io.papermc.paper.registry.RegistryKey)},
      * and {@link io.papermc.paper.registry.RegistryKey#INSTRUMENT}. MusicInstruments can exist without a key.
      */
     @Deprecated(forRemoval = true, since = "1.20.5")
     @Override
-    public [email protected] Key key() {
+    public Key key() {
         return Keyed.super.key();
     }
 
-    // Paper end - deprecate getKey
-
-    // Paper start - mark translation key as deprecated
     /**
      * @deprecated this method assumes that the instrument description
      * always be a translatable component which is not guaranteed.
      */
     @Override
     @Deprecated(forRemoval = true)
-    public abstract @NotNull String translationKey();
-    // Paper end - mark translation key as deprecated
+    public abstract String translationKey();
 }

paper-server/src/main/java/org/bukkit/craftbukkit/CraftMusicInstrument.java

@@ -1,14 +1,16 @@
 package org.bukkit.craftbukkit;
 
 import com.google.common.base.Preconditions;
+import io.papermc.paper.adventure.PaperAdventure;
 import io.papermc.paper.registry.RegistryKey;
 import io.papermc.paper.util.Holderable;
+import net.kyori.adventure.text.Component;
 import net.minecraft.core.Holder;
 import net.minecraft.core.registries.Registries;
 import net.minecraft.world.item.Instrument;
 import org.bukkit.MusicInstrument;
 import org.bukkit.NamespacedKey;
-import org.bukkit.Registry;
+import org.bukkit.Sound;
 import org.jetbrains.annotations.NotNull;
 
 public class CraftMusicInstrument extends MusicInstrument implements io.papermc.paper.util.Holderable<Instrument> {
@@ -26,19 +28,19 @@ public static Instrument bukkitToMinecraft(MusicInstrument bukkit) {
     }
 
     public static Holder<Instrument> bukkitToMinecraftHolder(MusicInstrument bukkit) {
-        return CraftRegistry.bukkitToMinecraftHolder(bukkit, Registries.INSTRUMENT); // Paper - switch to Holder
+        return CraftRegistry.bukkitToMinecraftHolder(bukkit, Registries.INSTRUMENT);
     }
 
-    public static Object bukkitToString(MusicInstrument bukkit) { // Paper - switch to Holder
+    public static Object bukkitToString(MusicInstrument bukkit) {
         Preconditions.checkArgument(bukkit != null);
 
-        return ((CraftMusicInstrument) bukkit).toBukkitSerializationObject(Instrument.DIRECT_CODEC); // Paper - switch to Holder
+        return ((CraftMusicInstrument) bukkit).toBukkitSerializationObject(Instrument.DIRECT_CODEC);
     }
 
-    public static MusicInstrument stringToBukkit(Object string) { // Paper - switch to Holder
+    public static MusicInstrument stringToBukkit(Object string) {
         Preconditions.checkArgument(string != null);
 
-        return io.papermc.paper.util.Holderable.fromBukkitSerializationObject(string, Instrument.CODEC, RegistryKey.INSTRUMENT); // Paper - switch to Holder
+        return io.papermc.paper.util.Holderable.fromBukkitSerializationObject(string, Instrument.CODEC, RegistryKey.INSTRUMENT);
     }
 
     @Override
@@ -63,8 +65,28 @@ public CraftMusicInstrument(Holder<Instrument> holder) {
     }
 
     @Override
-    public Holder<Instrument> getHolder() { // Paper - switch to Holder
-        return this.holder; // Paper - switch to Holder
+    public Holder<Instrument> getHolder() {
+        return this.holder;
+    }
+
+    @Override
+    public float getDuration() {
+        return this.getHandle().useDuration();
+    }
+
+    @Override
+    public float getRange() {
+        return this.getHandle().range();
+    }
+
+    @Override
+    public Component getDescription() {
+        return PaperAdventure.asAdventure(this.getHandle().description());
+    }
+
+    @Override
+    public Sound getSound() {
+        return CraftSound.minecraftHolderToBukkit(this.getHandle().soundEvent());
     }
 
     @NotNull
@@ -76,7 +98,7 @@ public NamespacedKey getKey() {
     @Override
     public @NotNull String translationKey() {
         if (!(this.getHandle().description().getContents() instanceof final net.minecraft.network.chat.contents.TranslatableContents translatableContents)) {
-            throw new UnsupportedOperationException("Description isn't translatable!"); // Paper
+            throw new UnsupportedOperationException("Description isn't translatable!");
         }
         return translatableContents.getKey();
     }

paper-server/src/main/java/org/bukkit/craftbukkit/CraftSound.java

@@ -14,6 +14,10 @@ public static Sound minecraftToBukkit(SoundEvent minecraft) {
         return CraftRegistry.minecraftToBukkit(minecraft, Registries.SOUND_EVENT);
     }
 
+    public static Sound minecraftHolderToBukkit(Holder<SoundEvent> minecraft) {
+        return minecraftToBukkit(minecraft.value());
+    }
+
     public static SoundEvent bukkitToMinecraft(Sound bukkit) {
         return CraftRegistry.bukkitToMinecraft(bukkit);
     }