Use ApiStatus.Internal instead of Deprecated (#9042)

Mainly correctly marks a lot of still used "magic values"
as Internal instead of "Deprecated".

patches/api/0172-Fix-Spigot-annotation-mistakes.patch

@@ -6,8 +6,39 @@ Subject: [PATCH] Fix Spigot annotation mistakes
 while some of these may of been true, they are extreme cases and cause
 a ton of noise to plugin developers.
 
+Use ApiStatus.Internal instead of Deprecated for actual internal API
+that continues to have use (internally).
+
 These do not help plugin developers if they bring moise noise than value.
 
+diff --git a/src/main/java/org/bukkit/Art.java b/src/main/java/org/bukkit/Art.java
+index ac420f0059fc50d3e1294f85df7515c9e17ff78f..24daba85ce4129fb0babe67570059ca8119360c0 100644
+--- a/src/main/java/org/bukkit/Art.java
++++ b/src/main/java/org/bukkit/Art.java
+@@ -75,9 +75,9 @@ public enum Art implements Keyed {
+      * Get the ID of this painting.
+      *
+      * @return The ID of this painting
+-     * @deprecated Magic value
++     * @apiNote Internal Use Only
+      */
+-    @Deprecated
++    @org.jetbrains.annotations.ApiStatus.Internal // Paper
+     public int getId() {
+         return id;
+     }
+@@ -93,9 +93,9 @@ public enum Art implements Keyed {
+      *
+      * @param id The ID
+      * @return The painting
+-     * @deprecated Magic value
++     * @apiNote Internal Use Only
+      */
+-    @Deprecated
++    @org.jetbrains.annotations.ApiStatus.Internal // Paper
+     @Nullable
+     public static Art getById(int id) {
+         return BY_ID.get(id);
 diff --git a/src/main/java/org/bukkit/Bukkit.java b/src/main/java/org/bukkit/Bukkit.java
 index 40b4d6ee5ef1f6b88e0b85131be399526488cd9e..20e8bee8a686f8d37d770d8714c5c55af8491584 100644
 --- a/src/main/java/org/bukkit/Bukkit.java
@@ -44,6 +75,170 @@ index 40b4d6ee5ef1f6b88e0b85131be399526488cd9e..20e8bee8a686f8d37d770d8714c5c55a
      public static ScoreboardManager getScoreboardManager() {
          return server.getScoreboardManager();
      }
+diff --git a/src/main/java/org/bukkit/CoalType.java b/src/main/java/org/bukkit/CoalType.java
+index c07499dbdd49d70717dbd674d97b6dbcfd7e9d5b..75e563d2a6d417b95c7f06a0636811aec8259672 100644
+--- a/src/main/java/org/bukkit/CoalType.java
++++ b/src/main/java/org/bukkit/CoalType.java
+@@ -7,6 +7,7 @@ import org.jetbrains.annotations.Nullable;
+ /**
+  * Represents the two types of coal
+  */
++@Deprecated // Paper
+ public enum CoalType {
+     COAL(0x0),
+     CHARCOAL(0x1);
+diff --git a/src/main/java/org/bukkit/CropState.java b/src/main/java/org/bukkit/CropState.java
+index fb4832fb796a38c0f5f51cf80a67259924f2c607..519deeeb86672fd75ae62026f956727d01f78fef 100644
+--- a/src/main/java/org/bukkit/CropState.java
++++ b/src/main/java/org/bukkit/CropState.java
+@@ -7,6 +7,7 @@ import org.jetbrains.annotations.Nullable;
+ /**
+  * Represents the different growth states of crops
+  */
++@Deprecated // Paper
+ public enum CropState {
+ 
+     /**
+diff --git a/src/main/java/org/bukkit/Difficulty.java b/src/main/java/org/bukkit/Difficulty.java
+index 3f6cbefc2b1414ba2dad709e79288013b3ef73be..f35801783538d3377b04131b8bf6effd7eb8e1a5 100644
+--- a/src/main/java/org/bukkit/Difficulty.java
++++ b/src/main/java/org/bukkit/Difficulty.java
+@@ -44,9 +44,9 @@ public enum Difficulty {
+      * Gets the difficulty value associated with this Difficulty.
+      *
+      * @return An integer value of this difficulty
+-     * @deprecated Magic value
++     * @apiNote Internal Use Only
+      */
+-    @Deprecated
++    @org.jetbrains.annotations.ApiStatus.Internal // Paper
+     public int getValue() {
+         return value;
+     }
+@@ -57,9 +57,9 @@ public enum Difficulty {
+      * @param value Value to check
+      * @return Associative {@link Difficulty} with the given value, or null if
+      *     it doesn't exist
+-     * @deprecated Magic value
++     * @apiNote Internal Use Only
+      */
+-    @Deprecated
++    @org.jetbrains.annotations.ApiStatus.Internal // Paper
+     @Nullable
+     public static Difficulty getByValue(final int value) {
+         return BY_ID.get(value);
+diff --git a/src/main/java/org/bukkit/DyeColor.java b/src/main/java/org/bukkit/DyeColor.java
+index bd213cabddd8752e609544f24cfba95405726155..47df858e095c4423c20e49e029d72f0f50d2c924 100644
+--- a/src/main/java/org/bukkit/DyeColor.java
++++ b/src/main/java/org/bukkit/DyeColor.java
+@@ -96,9 +96,9 @@ public enum DyeColor {
+      *
+      * @return A byte containing the wool data value of this color
+      * @see #getDyeData()
+-     * @deprecated Magic value
++     * @apiNote Internal Use Only
+      */
+-    @Deprecated
++    @org.jetbrains.annotations.ApiStatus.Internal // Paper
+     public byte getWoolData() {
+         return woolData;
+     }
+@@ -142,9 +142,9 @@ public enum DyeColor {
+      * @return The {@link DyeColor} representing the given value, or null if
+      *     it doesn't exist
+      * @see #getByDyeData(byte)
+-     * @deprecated Magic value
++     * @apiNote Internal Use Only
+      */
+-    @Deprecated
++    @org.jetbrains.annotations.ApiStatus.Internal // Paper
+     @Nullable
+     public static DyeColor getByWoolData(final byte data) {
+         int i = 0xff & data;
+@@ -202,9 +202,9 @@ public enum DyeColor {
+      *
+      * @param name dye name
+      * @return dye color
+-     * @deprecated legacy use only
++     * @apiNote Internal Use Only
+      */
+-    @Deprecated
++    @org.jetbrains.annotations.ApiStatus.Internal // Paper
+     @NotNull
+     public static DyeColor legacyValueOf(@Nullable String name) {
+         return "SILVER".equals(name) ? DyeColor.LIGHT_GRAY : DyeColor.valueOf(name);
+diff --git a/src/main/java/org/bukkit/Effect.java b/src/main/java/org/bukkit/Effect.java
+index 879d637691683ca862045402f74b751a892bf3ff..611b7df0e31de932f15c2f13bd8ed286e0b3b43f 100644
+--- a/src/main/java/org/bukkit/Effect.java
++++ b/src/main/java/org/bukkit/Effect.java
+@@ -358,9 +358,9 @@ public enum Effect {
+      * Gets the ID for this effect.
+      *
+      * @return ID of this effect
+-     * @deprecated Magic value
++     * @apiNote Internal Use Only
+      */
+-    @Deprecated
++    @org.jetbrains.annotations.ApiStatus.Internal // Paper
+     public int getId() {
+         return this.id;
+     }
+@@ -387,9 +387,9 @@ public enum Effect {
+      *
+      * @param id ID of the Effect to return
+      * @return Effect with the given ID
+-     * @deprecated Magic value
++     * @apiNote Internal Use Only
+      */
+-    @Deprecated
++    @org.jetbrains.annotations.ApiStatus.Internal // Paper
+     @Nullable
+     public static Effect getById(int id) {
+         return BY_ID.get(id);
+diff --git a/src/main/java/org/bukkit/EntityEffect.java b/src/main/java/org/bukkit/EntityEffect.java
+index 1747b912dd08d82757687aaa7614d32d746fd6a1..7b6d9c2bbe1052371fdd4121f88e5009882a3d41 100644
+--- a/src/main/java/org/bukkit/EntityEffect.java
++++ b/src/main/java/org/bukkit/EntityEffect.java
+@@ -227,9 +227,9 @@ public enum EntityEffect {
+      * Gets the data value of this EntityEffect
+      *
+      * @return The data value
+-     * @deprecated Magic value
++     * @apiNote Internal Use Only
+      */
+-    @Deprecated
++    @org.jetbrains.annotations.ApiStatus.Internal // Paper
+     public byte getData() {
+         return data;
+     }
+diff --git a/src/main/java/org/bukkit/GameMode.java b/src/main/java/org/bukkit/GameMode.java
+index 938c3217f92e6d3ef9a637269c469f8359af6347..81e45984a88fc84acd0f76d825abf4ddaed0ac3b 100644
+--- a/src/main/java/org/bukkit/GameMode.java
++++ b/src/main/java/org/bukkit/GameMode.java
+@@ -44,9 +44,9 @@ public enum GameMode {
+      * Gets the mode value associated with this GameMode
+      *
+      * @return An integer value of this gamemode
+-     * @deprecated Magic value
++     * @apiNote Internal Use Only
+      */
+-    @Deprecated
++    @org.jetbrains.annotations.ApiStatus.Internal // Paper
+     public int getValue() {
+         return value;
+     }
+@@ -57,9 +57,9 @@ public enum GameMode {
+      * @param value Value to check
+      * @return Associative {@link GameMode} with the given value, or null if
+      *     it doesn't exist
+-     * @deprecated Magic value
++     * @apiNote Internal Use Only
+      */
+-    @Deprecated
++    @org.jetbrains.annotations.ApiStatus.Internal // Paper
+     @Nullable
+     public static GameMode getByValue(final int value) {
+         return BY_ID.get(value);
 diff --git a/src/main/java/org/bukkit/GrassSpecies.java b/src/main/java/org/bukkit/GrassSpecies.java
 index f9c9ae463aacd593e3aa9caf037ea1e23d56c780..f8ae143acbf586d5279b44f7311ca97f3ae4ead2 100644
 --- a/src/main/java/org/bukkit/GrassSpecies.java
@@ -90,10 +285,21 @@ index 16df0568143a956309e6cab91a0818582fa4ed67..9e80988c71b77bbda1aca27a85953760
          if (this.world == null) {
              return null;
 diff --git a/src/main/java/org/bukkit/Material.java b/src/main/java/org/bukkit/Material.java
-index d56d899ca7737b537ea55c13a384888a873f5da3..cbec3b145a44ceee20823ae0e9c8162b15726189 100644
+index d56d899ca7737b537ea55c13a384888a873f5da3..1f9836477fda507ba33fa8a850fb85ed223c9fc0 100644
 --- a/src/main/java/org/bukkit/Material.java
 +++ b/src/main/java/org/bukkit/Material.java
-@@ -4468,11 +4468,11 @@ public enum Material implements Keyed, Translatable {
+@@ -4459,20 +4459,20 @@ public enum Material implements Keyed, Translatable {
+      * Do not use for any reason.
+      *
+      * @return ID of this material
+-     * @deprecated Magic value
++     * @apiNote Internal Use Only
+      */
+-    @Deprecated
++    @org.jetbrains.annotations.ApiStatus.Internal // Paper
+     public int getId() {
+         Preconditions.checkArgument(legacy, "Cannot get ID of Modern Material");
+         return id;
      }
  
      /**
@@ -155,6 +361,70 @@ index f43209cf7b752c26718c303ca8c3e1c7d9912ad3..f0094e6fb05e526736629ad3181c8d2c
  public enum NetherWartsState {
  
      /**
+diff --git a/src/main/java/org/bukkit/Note.java b/src/main/java/org/bukkit/Note.java
+index fc3da7ce6f7948aeab0962d9472e8f3a126834cf..bd713f9f7d125998d4bc01aaf11d1605ff64a970 100644
+--- a/src/main/java/org/bukkit/Note.java
++++ b/src/main/java/org/bukkit/Note.java
+@@ -39,9 +39,9 @@ public class Note {
+          * Returns the not sharped id of this tone.
+          *
+          * @return the not sharped id of this tone.
+-         * @deprecated Magic value
++         * @apiNote Internal Use Only
+          */
+-        @Deprecated
++        @org.jetbrains.annotations.ApiStatus.Internal // Paper
+         public byte getId() {
+             return getId(false);
+         }
+@@ -53,9 +53,9 @@ public class Note {
+          *
+          * @param sharped Set to true to return the sharped id.
+          * @return the id of this tone.
+-         * @deprecated Magic value
++         * @apiNote Internal Use Only
+          */
+-        @Deprecated
++        @org.jetbrains.annotations.ApiStatus.Internal // Paper
+         public byte getId(boolean sharped) {
+             byte id = (byte) (sharped && sharpable ? this.id + 1 : this.id);
+ 
+@@ -78,9 +78,9 @@ public class Note {
+          * @return if the tone id is the sharped id of the tone.
+          * @throws IllegalArgumentException if neither the tone nor the
+          *     semitone have the id.
+-         * @deprecated Magic value
++         * @apiNote Internal Use Only
+          */
+-        @Deprecated
++        @org.jetbrains.annotations.ApiStatus.Internal // Paper
+         public boolean isSharped(byte id) {
+             if (id == getId(false)) {
+                 return false;
+@@ -97,9 +97,9 @@ public class Note {
+          *
+          * @param id the id of the tone.
+          * @return the tone to id.
+-         * @deprecated Magic value
++         * @apiNote Internal Use Only
+          */
+-        @Deprecated
++        @org.jetbrains.annotations.ApiStatus.Internal // Paper
+         @Nullable
+         public static Tone getById(byte id) {
+             return BY_DATA.get(id);
+@@ -214,9 +214,9 @@ public class Note {
+      * Returns the internal id of this note.
+      *
+      * @return the internal id of this note.
+-     * @deprecated Magic value
++     * @apiNote Internal Use Only
+      */
+-    @Deprecated
++    @org.jetbrains.annotations.ApiStatus.Internal // Paper
+     public byte getId() {
+         return note;
+     }
 diff --git a/src/main/java/org/bukkit/Particle.java b/src/main/java/org/bukkit/Particle.java
 index 81bd12c8addcee754c71e5e030c729c7e096fb4c..6992600d6cff9ed0a30d37ac4dc5dc0e56ecb2c7 100644
 --- a/src/main/java/org/bukkit/Particle.java
@@ -318,7 +588,7 @@ index e455eb21abf121dc6ff10ff8a13dd06f67096a8f..bbc01e7c192ae6689c301670047ff114
          return origin;
      }
 diff --git a/src/main/java/org/bukkit/World.java b/src/main/java/org/bukkit/World.java
-index df511007ca4b3b5df04abfa6b7f1c4de636407fc..dea26b0bd6e1dccb7b043a7395e7958461e270ee 100644
+index df511007ca4b3b5df04abfa6b7f1c4de636407fc..3f50a3c5af674fdb4c5adc64901d305753a0b5e9 100644
 --- a/src/main/java/org/bukkit/World.java
 +++ b/src/main/java/org/bukkit/World.java
 @@ -416,9 +416,8 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
@@ -379,6 +649,30 @@ index df511007ca4b3b5df04abfa6b7f1c4de636407fc..dea26b0bd6e1dccb7b043a7395e79584
      Spigot spigot();
      // Spigot end
  
+@@ -3866,9 +3881,9 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
+          * Gets the dimension ID of this environment
+          *
+          * @return dimension ID
+-         * @deprecated Magic value
++         * @apiNote Internal Use Only
+          */
+-        @Deprecated
++        @org.jetbrains.annotations.ApiStatus.Internal // Paper
+         public int getId() {
+             return id;
+         }
+@@ -3878,9 +3893,9 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
+          *
+          * @param id The ID of the environment
+          * @return The environment
+-         * @deprecated Magic value
++         * @apiNote Internal Use Only
+          */
+-        @Deprecated
++        @org.jetbrains.annotations.ApiStatus.Internal // Paper
+         @Nullable
+         public static Environment getEnvironment(int id) {
+             return lookup.get(id);
 diff --git a/src/main/java/org/bukkit/block/Block.java b/src/main/java/org/bukkit/block/Block.java
 index 78f6cc1a8a8de05aec6f551f8a5f425944f0ffa3..653a83b7ceb5cec1d92aed5250ae50e714fe5f9f 100644
 --- a/src/main/java/org/bukkit/block/Block.java
@@ -430,6 +724,34 @@ index 4bd127b3646307398e0c937c3e36ab671235b72b..f2557a87f468ee20c2d276dbfc0e9a97
      public ItemStack getItem();
  
      /**
+diff --git a/src/main/java/org/bukkit/block/PistonMoveReaction.java b/src/main/java/org/bukkit/block/PistonMoveReaction.java
+index b90f5dc345ad2cdd3ae353dc57f42a14c231d18a..a7b915ded9154d53ac8ca599119c1699cfca2265 100644
+--- a/src/main/java/org/bukkit/block/PistonMoveReaction.java
++++ b/src/main/java/org/bukkit/block/PistonMoveReaction.java
+@@ -48,9 +48,9 @@ public enum PistonMoveReaction {
+ 
+     /**
+      * @return The ID of the move reaction
+-     * @deprecated Magic value
++     * @apiNote Internal Use Only
+      */
+-    @Deprecated
++    @org.jetbrains.annotations.ApiStatus.Internal // Paper
+     public int getId() {
+         return this.id;
+     }
+@@ -58,9 +58,9 @@ public enum PistonMoveReaction {
+     /**
+      * @param id An ID
+      * @return The move reaction with that ID
+-     * @deprecated Magic value
++     * @apiNote Internal Use Only
+      */
+-    @Deprecated
++    @org.jetbrains.annotations.ApiStatus.Internal // Paper
+     @Nullable
+     public static PistonMoveReaction getById(int id) {
+         return byId.get(id);
 diff --git a/src/main/java/org/bukkit/entity/Enderman.java b/src/main/java/org/bukkit/entity/Enderman.java
 index 605af1a9fc48602643aec57dd14e8c4ab657a0bc..b3085c7ff8b3e96083d209f6612c006578773c24 100644
 --- a/src/main/java/org/bukkit/entity/Enderman.java
@@ -454,6 +776,22 @@ index 605af1a9fc48602643aec57dd14e8c4ab657a0bc..b3085c7ff8b3e96083d209f6612c0065
      public void setCarriedMaterial(@NotNull MaterialData material);
  
      /**
+diff --git a/src/main/java/org/bukkit/entity/EntityType.java b/src/main/java/org/bukkit/entity/EntityType.java
+index bb9ae81870a340c00d7480aff5106dc2c44dab8a..2522f7798962695577479a75f3095b72ee76e442 100644
+--- a/src/main/java/org/bukkit/entity/EntityType.java
++++ b/src/main/java/org/bukkit/entity/EntityType.java
+@@ -389,9 +389,9 @@ public enum EntityType implements Keyed, Translatable {
+      *
+      * @param name the entity type's name
+      * @return the matching entity type or null
+-     * @deprecated Magic value
++     * @apiNote Internal Use Only
+      */
+-    @Deprecated
++    @org.jetbrains.annotations.ApiStatus.Internal // Paper
+     @Contract("null -> null")
+     @Nullable
+     public static EntityType fromName(@Nullable String name) {
 diff --git a/src/main/java/org/bukkit/entity/LightningStrike.java b/src/main/java/org/bukkit/entity/LightningStrike.java
 index c49628f2638da68e1ec126e53c8b7c74b0d81b22..8dc433baba7060df5cfe6fc10210a5a27287987d 100644
 --- a/src/main/java/org/bukkit/entity/LightningStrike.java
@@ -543,6 +881,23 @@ index 95c79c5fa0c4e30201f887da6467ce5f81c8a255..7f9c4d4b430a3f0276461346ff2621ba
 +    @Deprecated // Paper
      public MaterialData getDisplayBlock();
  
+     /**
+diff --git a/src/main/java/org/bukkit/entity/Player.java b/src/main/java/org/bukkit/entity/Player.java
+index 9954fc11b2c2fe56c194d7d3ce878a343a9b2429..c3223873d1afe14cdc0a14f97b3aa98d013d6e90 100644
+--- a/src/main/java/org/bukkit/entity/Player.java
++++ b/src/main/java/org/bukkit/entity/Player.java
+@@ -1436,11 +1436,8 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
+ 
+     /**
+      * Forces an update of the player's entire inventory.
+-     *
+-     * @apiNote It should not be necessary for plugins to use this method. If it
+-     * is required for some reason, it is probably a bug.
+      */
+-    @ApiStatus.Internal
++    // @ApiStatus.Internal // Paper - is valid API
+     public void updateInventory();
+ 
      /**
 diff --git a/src/main/java/org/bukkit/entity/Projectile.java b/src/main/java/org/bukkit/entity/Projectile.java
 index 906b33b7569fff5dd78258f9765e879180a52834..06e3ad9cd8f39de0ef6ead794df1492415bc4302 100644
@@ -580,6 +935,32 @@ index 9cb08fe7201a9f91e88c7b1ee22c17889a7bf1c3..c0fcfccdf476106b48e626a099658c04
 -@Deprecated
 +@Deprecated(forRemoval = true) // Paper
  public interface SplashPotion extends ThrownPotion { }
+diff --git a/src/main/java/org/bukkit/entity/TextDisplay.java b/src/main/java/org/bukkit/entity/TextDisplay.java
+index f101ffde9e7b3f6c3ab6f1cffb8d6f4e720634b2..8abc129f5953807e7a451166dabcf3e14e55483f 100644
+--- a/src/main/java/org/bukkit/entity/TextDisplay.java
++++ b/src/main/java/org/bukkit/entity/TextDisplay.java
+@@ -62,19 +62,17 @@ public interface TextDisplay extends Display {
+      * Gets the text background color.
+      *
+      * @return the background color
+-     * @deprecated API subject to change
+      */
+     @Nullable
+-    @Deprecated
++    // @Deprecated // Paper - is stable API
+     Color getBackgroundColor();
+ 
+     /**
+      * Sets the text background color.
+      *
+      * @param color new background color
+-     * @deprecated API subject to change
+      */
+-    @Deprecated
++    // @Deprecated // Paper - is stable API
+     void setBackgroundColor(@Nullable Color color);
+ 
+     /**
 diff --git a/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java b/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java
 index e9a6e5be5f33a342f7e5c496f0f1c64b2f302ace..f0db59a556deaefefbdaca121585c0fd199c13c2 100644
 --- a/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java
@@ -990,9 +1371,21 @@ index f1a48eab1a357ae64545e1f1dc941c383cff8707..466d1bd7089b76f48f953e1a51c611ec
      /**
       * Checks if the inventory contains any ItemStacks with the given
 diff --git a/src/main/java/org/bukkit/inventory/InventoryView.java b/src/main/java/org/bukkit/inventory/InventoryView.java
-index 002acfbdce1db10f7ba1b6a013e678f504ac6e69..aac9180fa3bcbdb0c17dcf96c86647b54ccc28c3 100644
+index 002acfbdce1db10f7ba1b6a013e678f504ac6e69..8d14426eb1ebea27058d5f22ea652f22d00fccb9 100644
 --- a/src/main/java/org/bukkit/inventory/InventoryView.java
 +++ b/src/main/java/org/bukkit/inventory/InventoryView.java
+@@ -126,9 +126,9 @@ public abstract class InventoryView {
+          * Gets the id of this view.
+          *
+          * @return the id of this view
+-         * @deprecated Magic value
++         * @apiNote Internal Use Only
+          */
+-        @Deprecated
++        @org.jetbrains.annotations.ApiStatus.Internal // Paper
+         public int getId() {
+             return id;
+         }
 @@ -210,10 +210,10 @@ public abstract class InventoryView {
      /**
       * Get the item on the cursor of one of the viewing players.
@@ -1286,6 +1679,178 @@ index 32055a8890425e0b819930f3059da5ea9dfca553..26a336dade83baee97d20eb39a058925
      int getMapId();
  
      /**
+diff --git a/src/main/java/org/bukkit/map/MapCanvas.java b/src/main/java/org/bukkit/map/MapCanvas.java
+index 00437719722830c087ff925015086c29bbb04497..ae9bcc8262dbf6eb8673ca82395d09169db38f9d 100644
+--- a/src/main/java/org/bukkit/map/MapCanvas.java
++++ b/src/main/java/org/bukkit/map/MapCanvas.java
+@@ -94,9 +94,9 @@ public interface MapCanvas {
+      * @param x The x coordinate, from 0 to 127.
+      * @param y The y coordinate, from 0 to 127.
+      * @return The color. See {@link MapPalette}.
+-     * @deprecated Magic value, use {@link #getPixelColor(int, int)}
++     * @deprecated use {@link #getPixelColor(int, int)}
+      */
+-    @Deprecated
++    @Deprecated(forRemoval = true, since = "1.20.2") // Paper
+     public byte getPixel(int x, int y);
+ 
+     /**
+@@ -105,9 +105,9 @@ public interface MapCanvas {
+      * @param x The x coordinate, from 0 to 127.
+      * @param y The y coordinate, from 0 to 127.
+      * @return The color. See {@link MapPalette}.
+-     * @deprecated Magic value, use {@link #getBasePixelColor(int, int)}
++     * @deprecated use {@link #getBasePixelColor(int, int)}
+      */
+-    @Deprecated
++    @Deprecated(forRemoval = true, since = "1.20.2") // Paper
+     public byte getBasePixel(int x, int y);
+ 
+     /**
+diff --git a/src/main/java/org/bukkit/map/MapCursor.java b/src/main/java/org/bukkit/map/MapCursor.java
+index 7d4f4970dae6fe4eeea6b6b6810dcecfe20d6e51..599399e4d8ca7c46747439ad2dd0186d0a289a19 100644
+--- a/src/main/java/org/bukkit/map/MapCursor.java
++++ b/src/main/java/org/bukkit/map/MapCursor.java
+@@ -156,9 +156,9 @@ public final class MapCursor {
+      * Get the type of this cursor.
+      *
+      * @return The type (color/style) of the map cursor.
+-     * @deprecated Magic value
++     * @apiNote Internal Use Only
+      */
+-    @Deprecated
++    @org.jetbrains.annotations.ApiStatus.Internal // Paper
+     public byte getRawType() {
+         return type;
+     }
+@@ -215,9 +215,9 @@ public final class MapCursor {
+      * Set the type of this cursor.
+      *
+      * @param type The type (color/style) of the map cursor.
+-     * @deprecated Magic value
++     * @deprecated use {@link #setType(Type)}
+      */
+-    @Deprecated
++    @Deprecated(forRemoval = true, since = "1.20.2") // Paper
+     public void setRawType(byte type) {
+         if (type < 0 || type > 26) {
+             throw new IllegalArgumentException("Type must be in the range 0-26");
+@@ -328,9 +328,9 @@ public final class MapCursor {
+          * Gets the internal value of the cursor.
+          *
+          * @return the value
+-         * @deprecated Magic value
++         * @apiNote Internal Use Only
+          */
+-        @Deprecated
++        @org.jetbrains.annotations.ApiStatus.Internal // Paper
+         public byte getValue() {
+             return value;
+         }
+@@ -340,9 +340,9 @@ public final class MapCursor {
+          *
+          * @param value the value
+          * @return the matching type
+-         * @deprecated Magic value
++         * @apiNote Internal Use Only
+          */
+-        @Deprecated
++        @org.jetbrains.annotations.ApiStatus.Internal // Paper
+         @Nullable
+         public static Type byValue(byte value) {
+             for (Type t : values()) {
+diff --git a/src/main/java/org/bukkit/map/MapPalette.java b/src/main/java/org/bukkit/map/MapPalette.java
+index 3a9aaca2e76411a9c27f9f5e0f22d060d5a66d06..c80faa079eca1564847070f0338fc98024639829 100644
+--- a/src/main/java/org/bukkit/map/MapPalette.java
++++ b/src/main/java/org/bukkit/map/MapPalette.java
+@@ -197,9 +197,9 @@ public final class MapPalette {
+      *
+      * @param image The image to convert.
+      * @return A byte[] containing the pixels of the image.
+-     * @deprecated Magic value
++     * @deprecated use color-related methods
+      */
+-    @Deprecated
++    @Deprecated(forRemoval = true, since = "1.20.2") // Paper
+     @NotNull
+     public static byte[] imageToBytes(@NotNull Image image) {
+         BufferedImage temp = new BufferedImage(image.getWidth(null), image.getHeight(null), BufferedImage.TYPE_INT_ARGB);
+@@ -225,9 +225,9 @@ public final class MapPalette {
+      * @param b The blue component of the color.
+      * @param g The green component of the color.
+      * @return The index in the palette.
+-     * @deprecated Magic value
++     * @deprecated use color-related methods
+      */
+-    @Deprecated
++    @Deprecated(forRemoval = true, since = "1.20.2") // Paper
+     public static byte matchColor(int r, int g, int b) {
+         return matchColor(new Color(r, g, b));
+     }
+@@ -238,9 +238,9 @@ public final class MapPalette {
+      *
+      * @param color The Color to match.
+      * @return The index in the palette.
+-     * @deprecated Magic value
++     * @deprecated use color-related methods
+      */
+-    @Deprecated
++    @Deprecated(forRemoval = true, since = "1.20.2") // Paper
+     public static byte matchColor(@NotNull Color color) {
+         if (color.getAlpha() < 128) return 0;
+ 
+@@ -268,9 +268,9 @@ public final class MapPalette {
+      *
+      * @param index The index in the palette.
+      * @return The Color of the palette entry.
+-     * @deprecated Magic value
++     * @deprecated use color directly
+      */
+-    @Deprecated
++    @Deprecated(forRemoval = true, since = "1.20.2") // Paper
+     @NotNull
+     public static Color getColor(byte index) {
+         // Minecraft has 143 colors, some of which have negative byte representations
+@@ -311,9 +311,9 @@ public final class MapPalette {
+          * @param color The Color to match.
+          * @return The index in the palette.
+          * @throws IllegalStateException if {@link #isCached()} returns false
+-         * @deprecated Magic value
++         * @apiNote Internal Use Only
+          */
+-        @Deprecated
++        @org.jetbrains.annotations.ApiStatus.Internal // Paper
+         byte matchColor(@NotNull Color color);
+     }
+ }
+diff --git a/src/main/java/org/bukkit/map/MapView.java b/src/main/java/org/bukkit/map/MapView.java
+index 9b8b68b66dc15b06800251702c2722623c8462a0..e998c5d871e02564c24260a8205dcfafb6e703d9 100644
+--- a/src/main/java/org/bukkit/map/MapView.java
++++ b/src/main/java/org/bukkit/map/MapView.java
+@@ -32,9 +32,9 @@ public interface MapView {
+          *
+          * @param value The raw scale
+          * @return The enum scale, or null for an invalid input
+-         * @deprecated Magic value
++         * @apiNote Internal Use Only
+          */
+-        @Deprecated
++        @org.jetbrains.annotations.ApiStatus.Internal // Paper
+         @Nullable
+         public static Scale valueOf(byte value) {
+             switch (value) {
+@@ -51,9 +51,9 @@ public interface MapView {
+          * Get the raw value of this scale level.
+          *
+          * @return The scale value
+-         * @deprecated Magic value
++         * @apiNote Internal Use Only
+          */
+-        @Deprecated
++        @org.jetbrains.annotations.ApiStatus.Internal // Paper
+         public byte getValue() {
+             return value;
+         }
 diff --git a/src/main/java/org/bukkit/material/Openable.java b/src/main/java/org/bukkit/material/Openable.java
 index 0ae54f973d11df74abb3105cf9226afb130b4f33..597036bad6bc61b4aa63a61b45e886dd74a0b7f6 100644
 --- a/src/main/java/org/bukkit/material/Openable.java
@@ -1335,6 +1900,34 @@ index 0ea9c6b2420a0f990bd1fdf50fc015e37a7060d8..e99644eae1c662b117aa19060d2484ac
  public enum MushroomBlockTexture {
  
      /**
+diff --git a/src/main/java/org/bukkit/potion/PotionEffectType.java b/src/main/java/org/bukkit/potion/PotionEffectType.java
+index 5f3aa6fd18d57055a6d8494938dff149d51b2803..ceba656b25f74d4bb2eadb9a7eca184b069b4909 100644
+--- a/src/main/java/org/bukkit/potion/PotionEffectType.java
++++ b/src/main/java/org/bukkit/potion/PotionEffectType.java
+@@ -220,9 +220,9 @@ public abstract class PotionEffectType implements Keyed {
+      * Returns the unique ID of this type.
+      *
+      * @return Unique ID
+-     * @deprecated Magic value
++     * @deprecated use {@link #key()}
+      */
+-    @Deprecated
++    @Deprecated(forRemoval = true, since = "1.20.2") // Paper
+     public int getId() {
+         return id;
+     }
+@@ -304,9 +304,9 @@ public abstract class PotionEffectType implements Keyed {
+      *
+      * @param id Unique ID to fetch
+      * @return Resulting type, or null if not found.
+-     * @deprecated Magic value
++     * @apiNote Internal Use Only
+      */
+-    @Deprecated
++    @org.jetbrains.annotations.ApiStatus.Internal // Paper
+     @Nullable
+     public static PotionEffectType getById(int id) {
+         if (id >= byId.length || id < 0)
 diff --git a/src/test/java/org/bukkit/materials/MaterialDataTest.java b/src/test/java/org/bukkit/materials/MaterialDataTest.java
 index 8d78435cc42a9e668b2d4d674b79b4094c3bd1b1..24a8ce4387b897c717b55405f363ffafff45894d 100644
 --- a/src/test/java/org/bukkit/materials/MaterialDataTest.java

patches/api/0189-Add-Player-Client-Options-API.patch

@@ -229,10 +229,10 @@ index 0000000000000000000000000000000000000000..cf67dc7d465223710adbf2b798109f52
 +    }
 +}
 diff --git a/src/main/java/org/bukkit/entity/Player.java b/src/main/java/org/bukkit/entity/Player.java
-index 9954fc11b2c2fe56c194d7d3ce878a343a9b2429..393b3be157d2111d7209b7a94515c93a931a1ec9 100644
+index c3223873d1afe14cdc0a14f97b3aa98d013d6e90..925bdf4cc2191a89ca8f55ca55121fa5d3a556a2 100644
 --- a/src/main/java/org/bukkit/entity/Player.java
 +++ b/src/main/java/org/bukkit/entity/Player.java
-@@ -2874,6 +2874,12 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
+@@ -2871,6 +2871,12 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
       * Reset the cooldown counter to 0, effectively starting the cooldown period.
       */
      void resetCooldown();

patches/api/0206-Brand-support.patch

@@ -5,10 +5,10 @@ Subject: [PATCH] Brand support
 
 
 diff --git a/src/main/java/org/bukkit/entity/Player.java b/src/main/java/org/bukkit/entity/Player.java
-index 393b3be157d2111d7209b7a94515c93a931a1ec9..81e8bfbe4380090830591274025a026de740fd05 100644
+index 925bdf4cc2191a89ca8f55ca55121fa5d3a556a2..b37f84a11e49f0f09371d2baf6ec3eb1c9262068 100644
 --- a/src/main/java/org/bukkit/entity/Player.java
 +++ b/src/main/java/org/bukkit/entity/Player.java
-@@ -2988,6 +2988,16 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
+@@ -2985,6 +2985,16 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
          // Paper end
      }
  

patches/api/0217-Player-elytra-boost-API.patch

@@ -5,10 +5,10 @@ Subject: [PATCH] Player elytra boost API
 
 
 diff --git a/src/main/java/org/bukkit/entity/Player.java b/src/main/java/org/bukkit/entity/Player.java
-index 81e8bfbe4380090830591274025a026de740fd05..36e3f86f463cd7b6bca4c8b63739a06f17d7e28a 100644
+index b37f84a11e49f0f09371d2baf6ec3eb1c9262068..7ccc62f77055a8fc7e4407f70b0ebab956e20570 100644
 --- a/src/main/java/org/bukkit/entity/Player.java
 +++ b/src/main/java/org/bukkit/entity/Player.java
-@@ -2880,6 +2880,24 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
+@@ -2877,6 +2877,24 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
       */
      @NotNull
      <T> T getClientOption(@NotNull com.destroystokyo.paper.ClientOption<T> option);

patches/api/0244-Add-sendOpLevel-API.patch

@@ -5,10 +5,10 @@ Subject: [PATCH] Add sendOpLevel API
 
 
 diff --git a/src/main/java/org/bukkit/entity/Player.java b/src/main/java/org/bukkit/entity/Player.java
-index 36e3f86f463cd7b6bca4c8b63739a06f17d7e28a..a46bc40bf101df46843311684f232b4b5b6f9127 100644
+index 7ccc62f77055a8fc7e4407f70b0ebab956e20570..717b12fceaa918f574d6f15b0f6b2939ce9bd1f9 100644
 --- a/src/main/java/org/bukkit/entity/Player.java
 +++ b/src/main/java/org/bukkit/entity/Player.java
-@@ -2900,6 +2900,19 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
+@@ -2897,6 +2897,19 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      }
      // Paper end
  

patches/api/0369-More-Teleport-API.patch

@@ -165,10 +165,10 @@ index 77e29cada05da8946d718fe331e28e7553922033..5607404fa0132febdbdaad051a4e9426
       * Teleports this entity to the given location. If this entity is riding a
       * vehicle, it will be dismounted prior to teleportation.
 diff --git a/src/main/java/org/bukkit/entity/Player.java b/src/main/java/org/bukkit/entity/Player.java
-index ccc7077f66d96b85478545a89c94b7466c3cdb77..3d64f8c3071495ec95350e09843d8e140b6a9af3 100644
+index 8dc3c5c963e07e1d3819b78b73b39fc082048387..c0fceea5bc007b3f4c93a8fe8cccf4e3cfa88c4f 100644
 --- a/src/main/java/org/bukkit/entity/Player.java
 +++ b/src/main/java/org/bukkit/entity/Player.java
-@@ -3060,6 +3060,49 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
+@@ -3057,6 +3057,49 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      String getClientBrandName();
      // Paper end
  

patches/api/0371-Custom-Chat-Completion-Suggestions-API.patch

@@ -5,10 +5,10 @@ Subject: [PATCH] Custom Chat Completion Suggestions API
 
 
 diff --git a/src/main/java/org/bukkit/entity/Player.java b/src/main/java/org/bukkit/entity/Player.java
-index 3d64f8c3071495ec95350e09843d8e140b6a9af3..58498426c6ec697091a7a8ceeae6b85525ef39b7 100644
+index c0fceea5bc007b3f4c93a8fe8cccf4e3cfa88c4f..cc65c8d4a8e0586d36df630d92a3f904c1169669 100644
 --- a/src/main/java/org/bukkit/entity/Player.java
 +++ b/src/main/java/org/bukkit/entity/Player.java
-@@ -2944,6 +2944,31 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
+@@ -2941,6 +2941,31 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      void sendOpLevel(byte level);
      // Paper end - sendOpLevel API
  

patches/api/0381-Elder-Guardian-appearance-API.patch

@@ -5,10 +5,10 @@ Subject: [PATCH] Elder Guardian appearance API
 
 
 diff --git a/src/main/java/org/bukkit/entity/Player.java b/src/main/java/org/bukkit/entity/Player.java
-index 58498426c6ec697091a7a8ceeae6b85525ef39b7..ef2e523e7571be791e37a66c2f859bd5e04d16ab 100644
+index cc65c8d4a8e0586d36df630d92a3f904c1169669..ae1882f58dcc55c51757fa385effd329d348b896 100644
 --- a/src/main/java/org/bukkit/entity/Player.java
 +++ b/src/main/java/org/bukkit/entity/Player.java
-@@ -3128,6 +3128,24 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
+@@ -3125,6 +3125,24 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      void lookAt(@NotNull org.bukkit.entity.Entity entity, @NotNull io.papermc.paper.entity.LookAnchor playerAnchor, @NotNull io.papermc.paper.entity.LookAnchor entityAnchor);
      // Paper end - Teleport API
  

patches/api/0389-Add-Player-Warden-Warning-API.patch

@@ -5,10 +5,10 @@ Subject: [PATCH] Add Player Warden Warning API
 
 
 diff --git a/src/main/java/org/bukkit/entity/Player.java b/src/main/java/org/bukkit/entity/Player.java
-index ef2e523e7571be791e37a66c2f859bd5e04d16ab..1746e646ccf73efddd62eb7522f2560fdef32c49 100644
+index ae1882f58dcc55c51757fa385effd329d348b896..bd35d2da3ef437e7025ea86265ebcc693399ac83 100644
 --- a/src/main/java/org/bukkit/entity/Player.java
 +++ b/src/main/java/org/bukkit/entity/Player.java
-@@ -3144,6 +3144,59 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
+@@ -3141,6 +3141,59 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
       * @param silent whether sound should be silenced
       */
      void showElderGuardian(boolean silent);

patches/api/0402-Flying-Fall-Damage-API.patch

@@ -5,10 +5,10 @@ Subject: [PATCH] Flying Fall Damage API
 
 
 diff --git a/src/main/java/org/bukkit/entity/Player.java b/src/main/java/org/bukkit/entity/Player.java
-index 2e4b2ad1907a2d5f4462c5fd2d1482f2bb623d3b..4db6e9802105eba76d6f59b74873bea9502d2c7e 100644
+index 03b4f90ba0cdab27b1ce47eef5489e8639f6d960..7df1dd673cd75cb4dc29bbe2c538d0131eeff03e 100644
 --- a/src/main/java/org/bukkit/entity/Player.java
 +++ b/src/main/java/org/bukkit/entity/Player.java
-@@ -1705,6 +1705,23 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
+@@ -1702,6 +1702,23 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
       */
      public void setAllowFlight(boolean flight);
  

patches/api/0428-Add-Listing-API-for-Player.patch

@@ -5,10 +5,10 @@ Subject: [PATCH] Add Listing API for Player
 
 
 diff --git a/src/main/java/org/bukkit/entity/Player.java b/src/main/java/org/bukkit/entity/Player.java
-index 017f6d682181ccba3cb4f826c393f90ee614868f..20fa1024f9ad8f478a347be5c554b5e45b398a1c 100644
+index 0e188288e5ba94b1d17503258c5e1217d08e5549..229bad6cb9433027e06f4247baf7d8c962fdc40b 100644
 --- a/src/main/java/org/bukkit/entity/Player.java
 +++ b/src/main/java/org/bukkit/entity/Player.java
-@@ -1841,6 +1841,32 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
+@@ -1838,6 +1838,32 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      @ApiStatus.Experimental
      public boolean canSee(@NotNull Entity entity);
  

patches/api/0442-Add-player-idle-duration-API.patch

@@ -6,10 +6,10 @@ Subject: [PATCH] Add player idle duration API
 Implements API for getting and resetting a player's idle duration.
 
 diff --git a/src/main/java/org/bukkit/entity/Player.java b/src/main/java/org/bukkit/entity/Player.java
-index 91919b2d06d544be9a09c486791de7dff599f75a..087898a50909a40aabec09f1e52cefed6565ba4c 100644
+index 229bad6cb9433027e06f4247baf7d8c962fdc40b..9240ea09206461d61cc08d4252e8507555bf41cf 100644
 --- a/src/main/java/org/bukkit/entity/Player.java
 +++ b/src/main/java/org/bukkit/entity/Player.java
-@@ -3283,6 +3283,29 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
+@@ -3280,6 +3280,29 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      void increaseWardenWarningLevel();
      // Paper end