Paper/patches/api/0401-fix-Instruments.patch

From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
From: Jake Potrebic <jake.m.potrebic@gmail.com>
Date: Fri, 9 Dec 2022 01:34:03 -0800
Subject: [PATCH] fix Instruments

Add missing instrument enums
fix some wrong javadocs

diff --git a/src/main/java/org/bukkit/Instrument.java b/src/main/java/org/bukkit/Instrument.java
index 8f70d86a1d39351424335842c38625d42cfbdfb8..271fb4d41909654b87519edba1c1d4f418cdd3a5 100644
--- a/src/main/java/org/bukkit/Instrument.java
+++ b/src/main/java/org/bukkit/Instrument.java
@@ -8,7 +8,7 @@ import org.jetbrains.annotations.Nullable;
 public enum Instrument {
 
     /**
-     * Piano is the standard instrument for a note block.
+     * Piano (Harp) is the standard instrument for a note block.
      */
     PIANO(0x0),
     /**
@@ -22,7 +22,7 @@ public enum Instrument {
      */
     SNARE_DRUM(0x2),
     /**
-     * Sticks are normally played when a note block is on top of a glass
+     * Sticks (Hat) are normally played when a note block is on top of a glass
      * block.
      */
     STICKS(0x3),
@@ -81,50 +81,48 @@ public enum Instrument {
      */
     @MinecraftExperimental
     @ApiStatus.Experimental
-    ZOMBIE,
+    ZOMBIE(0x10), // Paper
     /**
      * Skeleton is normally played when a Skeleton Head is on top of the note block.
      */
     @MinecraftExperimental
     @ApiStatus.Experimental
-    SKELETON,
+    SKELETON(0x11), // Paper
     /**
      * Creeper is normally played when a Creeper Head is on top of the note block.
      */
     @MinecraftExperimental
     @ApiStatus.Experimental
-    CREEPER,
+    CREEPER(0x12), // Paper
     /**
      * Dragon is normally played when a Dragon Head is on top of the note block.
      */
     @MinecraftExperimental
     @ApiStatus.Experimental
-    DRAGON,
+    DRAGON(0x13), // Paper
     /**
      * Wither Skeleton is normally played when a Wither Skeleton Head is on top of the note block.
      */
     @MinecraftExperimental
     @ApiStatus.Experimental
-    WITHER_SKELETON,
+    WITHER_SKELETON(0x14), // Paper
     /**
      * Piglin is normally played when a Piglin Head is on top of the note block.
      */
     @MinecraftExperimental
     @ApiStatus.Experimental
-    PIGLIN,
+    PIGLIN(0x15), // Paper
     /**
      * Custom Sound is normally played when a Player Head with the required data is on top of the note block.
      */
     @MinecraftExperimental
     @ApiStatus.Experimental
-    CUSTOM_HEAD;
+    CUSTOM_HEAD(0x16); // Paper
 
     private final byte type;
     private static final Map<Byte, Instrument> BY_DATA = Maps.newHashMap();
 
-    private Instrument() {
-        this(-1);
-    }
+    // Paper - remove ctor (the server still uses the byte magic value)
 
     private Instrument(final int type) {
         this.type = (byte) type;
@@ -132,9 +130,8 @@ public enum Instrument {
 
     /**
      * @return The type ID of this instrument.
-     * @deprecated Magic value
      */
-    @Deprecated
+    @org.jetbrains.annotations.ApiStatus.Internal // Paper
     public byte getType() {
         return this.type;
     }
@@ -144,9 +141,8 @@ public enum Instrument {
      *
      * @param type The type ID
      * @return The instrument
-     * @deprecated Magic value
      */
-    @Deprecated
+    @org.jetbrains.annotations.ApiStatus.Internal // Paper
     @Nullable
     public static Instrument getByType(final byte type) {
         return BY_DATA.get(type);
diff --git a/src/main/java/org/bukkit/entity/Player.java b/src/main/java/org/bukkit/entity/Player.java
index a824262598e4a1ad6030e22a77628c43975c031d..eecb88dae2f68322be9add1fda7b50e2b2939f09 100644
--- a/src/main/java/org/bukkit/entity/Player.java
+++ b/src/main/java/org/bukkit/entity/Player.java
@@ -391,9 +391,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
     public void playNote(@NotNull Location loc, byte instrument, byte note);
 
     /**
-     * Play a note for a player at a location. This requires a note block
-     * at the particular location (as far as the client is concerned). This
-     * will not work without a note block. This will not work with cake.
+     * Play a note for a player at a location.
      *
      * @param loc The location of a note block
      * @param instrument The instrument
diff --git a/src/test/java/org/bukkit/InstrumentTest.java b/src/test/java/org/bukkit/InstrumentTest.java
index 14ad060eba6b78c6b7c7deeecc455ea385b92f36..e3d718d75474c5b31c95bd64cb58247ab72364e4 100644
--- a/src/test/java/org/bukkit/InstrumentTest.java
+++ b/src/test/java/org/bukkit/InstrumentTest.java
@@ -8,9 +8,7 @@ public class InstrumentTest {
     @Test
     public void getByType() {
         for (Instrument instrument : Instrument.values()) {
-            if (instrument.getType() < 0) {
-                continue;
-            }
+            // Paper - byte magic values are still used
 
             assertThat(Instrument.getByType(instrument.getType()), is(instrument));
         }