remove api that was scheduled for removal

1 files changed, 1899 insertions, 0 deletions

diff --git a/patches/api/0166-Fix-Spigot-annotation-mistakes.patch b/patches/api/0166-Fix-Spigot-annotation-mistakes.patch
new file mode 100644
index 0000000000..0f7be3c617
--- /dev/null
+++ b/patches/api/0166-Fix-Spigot-annotation-mistakes.patch
@@ -0,0 +1,1899 @@
+From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
+From: Aikar <[email protected]>
+Date: Sun, 24 Mar 2019 18:39:01 -0400
+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 dadff073abb2dec39111e677ec77ffdb2b7ff9a9..042d1d932a33022e4fc873652f70dc6ed342d46a 100644
+--- a/src/main/java/org/bukkit/Art.java
++++ b/src/main/java/org/bukkit/Art.java
+@@ -96,9 +96,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;
+     }
+@@ -114,9 +114,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 fb143a39f81ca7f14688ee3515a06256feac0f80..7b29a19610dbdc99e3662f70a8a291e6203edd1a 100644
+--- a/src/main/java/org/bukkit/Bukkit.java
++++ b/src/main/java/org/bukkit/Bukkit.java
+@@ -880,9 +880,8 @@ public final class Bukkit {
+      *
+      * @param id the id of the map to get
+      * @return a map view if it exists, or null otherwise
+-     * @deprecated Magic value
+      */
+-    @Deprecated
++    //@Deprecated // Paper - Not a magic value
+     @Nullable
+     public static MapView getMap(int id) {
+         return server.getMap(id);
+@@ -961,8 +960,14 @@ public final class Bukkit {
+      * Returns the primary logger associated with this server instance.
+      *
+      * @return Logger associated with this server
++     * @see org.bukkit.plugin.Plugin#getSLF4JLogger()
++     * @apiNote This logger is for the Minecraft server software, not for specific plugins. You should
++     * use a logger for a specific plugin, either via {@link org.bukkit.plugin.Plugin#getSLF4JLogger()}
++     * or {@link org.bukkit.plugin.Plugin#getLogger()} or create a specific logger for a class via slf4j.
++     * That way, log messages contain contextual information about the source of the message.
+      */
+     @NotNull
++    @org.jetbrains.annotations.ApiStatus.Internal // Paper - internalize Bukkit#getLogger
+     public static Logger getLogger() {
+         return server.getLogger();
+     }
+@@ -1359,10 +1364,8 @@ public final class Bukkit {
+      * @param name the name the player to retrieve
+      * @return an offline player
+      * @see #getOfflinePlayer(java.util.UUID)
+-     * @deprecated Persistent storage of users should be by UUID as names are no longer
+-     *             unique past a single session.
+      */
+-    @Deprecated
++    // @Deprecated // Paper
+     @NotNull
+     public static OfflinePlayer getOfflinePlayer(@NotNull String name) {
+         return server.getOfflinePlayer(name);
+@@ -1975,7 +1978,7 @@ public final class Bukkit {
+      *
+      * @return the scoreboard manager or null if no worlds are loaded.
+      */
+-    @Nullable
++    @NotNull // Paper
+     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 0d0777771485a76d960da2f16e963b19d2cf6c2d..fd9cf25f2fdef5ee3b7143f27e5f43dfe3f21a38 100644
+--- a/src/main/java/org/bukkit/Effect.java
++++ b/src/main/java/org/bukkit/Effect.java
+@@ -357,9 +357,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;
+     }
+@@ -386,9 +386,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 9db85b2f6ffd56bbc4db1f75f8769f1c15d5950f..5341957b10cccd7bce5a7595699b1d90412a01d0 100644
+--- a/src/main/java/org/bukkit/EntityEffect.java
++++ b/src/main/java/org/bukkit/EntityEffect.java
+@@ -345,9 +345,9 @@ public enum EntityEffect {
+      * Gets the data value of this EntityEffect, may not be unique.
+      *
+      * @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
++++ b/src/main/java/org/bukkit/GrassSpecies.java
+@@ -6,7 +6,9 @@ import org.jetbrains.annotations.Nullable;
+ 
+ /**
+  * Represents the different types of grass.
++ * @deprecated use {@link org.bukkit.block.data.BlockData}
+  */
++@Deprecated // Paper
+ public enum GrassSpecies {
+ 
+     /**
+diff --git a/src/main/java/org/bukkit/Location.java b/src/main/java/org/bukkit/Location.java
+index c30600666e7b32b8b4ba1e20ede04fd5ebd5a692..eec6c9cd7da6938351905129bb5a66f49a257d01 100644
+--- a/src/main/java/org/bukkit/Location.java
++++ b/src/main/java/org/bukkit/Location.java
+@@ -46,7 +46,7 @@ public class Location implements Cloneable, ConfigurationSerializable, io.paperm
+      * @param y The y-coordinate of this new location
+      * @param z The z-coordinate of this new location
+      */
+-    public Location(@Nullable final World world, final double x, final double y, final double z) {
++    public Location(@UndefinedNullability final World world, final double x, final double y, final double z) { // Paper
+         this(world, x, y, z, 0, 0);
+     }
+ 
+@@ -60,7 +60,7 @@ public class Location implements Cloneable, ConfigurationSerializable, io.paperm
+      * @param yaw The absolute rotation on the x-plane, in degrees
+      * @param pitch The absolute rotation on the y-plane, in degrees
+      */
+-    public Location(@Nullable final World world, final double x, final double y, final double z, final float yaw, final float pitch) {
++    public Location(@UndefinedNullability final World world, final double x, final double y, final double z, final float yaw, final float pitch) { // Paper
+         if (world != null) {
+             this.world = new WeakReference<>(world);
+         }
+@@ -102,7 +102,7 @@ public class Location implements Cloneable, ConfigurationSerializable, io.paperm
+      * @throws IllegalArgumentException when world is unloaded
+      * @see #isWorldLoaded()
+      */
+-    @Nullable
++    @UndefinedNullability // Paper
+     public World getWorld() {
+         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 6ffed5ef4331498ff318ffc5850f8b9a0b85eba7..444406eb7f0c3cd13039bf809254e480ee6fa24f 100644
+--- a/src/main/java/org/bukkit/Material.java
++++ b/src/main/java/org/bukkit/Material.java
+@@ -4681,20 +4681,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
++    @ApiStatus.Internal // Paper
+     public int getId() {
+         Preconditions.checkArgument(legacy, "Cannot get ID of Modern Material");
+         return id;
+     }
+ 
+     /**
+-     * Do not use for any reason.
++     * Checks if this constant is a legacy material.
+      *
+      * @return legacy status
+      */
+-    @Deprecated
++    // @Deprecated // Paper - this is useful, don't deprecate
+     public boolean isLegacy() {
+         return legacy;
+     }
+@@ -4770,8 +4770,10 @@ public enum Material implements Keyed, Translatable {
+      * Gets the MaterialData class associated with this Material
+      *
+      * @return MaterialData associated with this Material
++     * @deprecated use {@link #createBlockData()}
+      */
+     @NotNull
++    @Deprecated // Paper
+     public Class<? extends MaterialData> getData() {
+         Preconditions.checkArgument(legacy, "Cannot get data class of Modern Material");
+         return ctor.getDeclaringClass();
+@@ -5227,7 +5229,11 @@ public enum Material implements Keyed, Translatable {
+      * material.
+      *
+      * @return true if this material can be interacted with.
++     * @deprecated This method is not comprehensive and does not accurately reflect what block types are
++     * interactable. Many "interactions" are defined on the item not block, and many are conditional on some other world state
++     * checks being true.
+      */
++    @Deprecated // Paper
+     public boolean isInteractable() {
+         BlockType type = asBlockType();
+         return type != null && type.isInteractable();
+diff --git a/src/main/java/org/bukkit/NamespacedKey.java b/src/main/java/org/bukkit/NamespacedKey.java
+index 9b61129c3ef83d0bfceba54aba2effa12bc90678..cbdaa121dbc1876d0cd55f4b7b57f283ecaa8f1a 100644
+--- a/src/main/java/org/bukkit/NamespacedKey.java
++++ b/src/main/java/org/bukkit/NamespacedKey.java
+@@ -74,12 +74,14 @@ public final class NamespacedKey implements net.kyori.adventure.key.Key { // Pap
+ 
+     /**
+      * Create a key in a specific namespace.
++     * <p>
++     * For most plugin related code, you should prefer using the
++     * {@link NamespacedKey#NamespacedKey(Plugin, String)} constructor.
+      *
+      * @param namespace namespace
+      * @param key key
+-     * @apiNote should never be used by plugins, for internal use only!!
++     * @see #NamespacedKey(Plugin, String)
+      */
+-    @ApiStatus.Internal
+     public NamespacedKey(@NotNull String namespace, @NotNull String key) {
+         Preconditions.checkArgument(namespace != null && isValidNamespace(namespace), "Invalid namespace. Must be [a-z0-9._-]: %s", namespace);
+         Preconditions.checkArgument(key != null && isValidKey(key), "Invalid key. Must be [a-z0-9/._-]: %s", key);
+diff --git a/src/main/java/org/bukkit/NetherWartsState.java b/src/main/java/org/bukkit/NetherWartsState.java
+index f43209cf7b752c26718c303ca8c3e1c7d9912ad3..f0094e6fb05e526736629ad3181c8d2c16ba6ca4 100644
+--- a/src/main/java/org/bukkit/NetherWartsState.java
++++ b/src/main/java/org/bukkit/NetherWartsState.java
+@@ -1,5 +1,11 @@
+ package org.bukkit;
+ 
++// Paper start
++/**
++ * @deprecated use {@link org.bukkit.block.data.BlockData} and {@link org.bukkit.block.data.Ageable}
++ */
++@Deprecated
++// Paper end
+ public enum NetherWartsState {
+ 
+     /**
+diff --git a/src/main/java/org/bukkit/Note.java b/src/main/java/org/bukkit/Note.java
+index 48aecc9421c500137bbef1dfe3bec8de277c3ff9..aff858346776386f1288b648b221404f7f412399 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);
+@@ -222,9 +222,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/Registry.java b/src/main/java/org/bukkit/Registry.java
+index f1a7f3b3e20963fa9d97bcc0686a35863de2b60f..3effaea369d9c7a6a22979fbfc270f55f9f25cf2 100644
+--- a/src/main/java/org/bukkit/Registry.java
++++ b/src/main/java/org/bukkit/Registry.java
+@@ -220,14 +220,12 @@ public interface Registry<T extends Keyed> extends Iterable<T> {
+      *
+      * @see TrimMaterial
+      */
+-    @ApiStatus.Experimental
+     Registry<TrimMaterial> TRIM_MATERIAL = Bukkit.getRegistry(TrimMaterial.class);
+     /**
+      * Trim patterns.
+      *
+      * @see TrimPattern
+      */
+-    @ApiStatus.Experimental
+     Registry<TrimPattern> TRIM_PATTERN = Bukkit.getRegistry(TrimPattern.class);
+     /**
+      * Damage types.
+@@ -336,8 +334,11 @@ public interface Registry<T extends Keyed> extends Iterable<T> {
+      *
+      * @param input non-null input
+      * @return registered object or null if does not exist
++     * @deprecated this method's behavior is broken and not useful. If you want to get an object
++     * based on its vanilla name, or a key, wrap it in a {@link NamespacedKey} object and use {@link #get(NamespacedKey)}
+      */
+     @Nullable
++    @Deprecated(forRemoval = true) // Paper
+     default T match(@NotNull String input) {
+         Preconditions.checkArgument(input != null, "input must not be null");
+ 
+diff --git a/src/main/java/org/bukkit/SandstoneType.java b/src/main/java/org/bukkit/SandstoneType.java
+index 6277451c3c6c551078c237cd767b6d70c4f585ea..10f5cfb1885833a1d2c1027c03974da45ab28e2f 100644
+--- a/src/main/java/org/bukkit/SandstoneType.java
++++ b/src/main/java/org/bukkit/SandstoneType.java
+@@ -6,7 +6,9 @@ import org.jetbrains.annotations.Nullable;
+ 
+ /**
+  * Represents the three different types of Sandstone
++ * @deprecated use {@link org.bukkit.block.data.BlockData}
+  */
++@Deprecated // Paper
+ public enum SandstoneType {
+     CRACKED(0x0),
+     GLYPHED(0x1),
+diff --git a/src/main/java/org/bukkit/Server.java b/src/main/java/org/bukkit/Server.java
+index c1a1baa2c79ad48b210e770f198ca9a2d7815df4..75b3295a5544626d28c57b317d95db90722de719 100644
+--- a/src/main/java/org/bukkit/Server.java
++++ b/src/main/java/org/bukkit/Server.java
+@@ -741,9 +741,8 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
+      *
+      * @param id the id of the map to get
+      * @return a map view if it exists, or null otherwise
+-     * @deprecated Magic value
+      */
+-    @Deprecated
++    //@Deprecated // Paper - Not a magic value
+     @Nullable
+     public MapView getMap(int id);
+ 
+@@ -810,8 +809,14 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
+      * Returns the primary logger associated with this server instance.
+      *
+      * @return Logger associated with this server
++     * @see org.bukkit.plugin.Plugin#getSLF4JLogger()
++     * @apiNote This logger is for the Minecraft server software, not for specific plugins. You should
++     * use a logger for a specific plugin, either via {@link org.bukkit.plugin.Plugin#getSLF4JLogger()}
++     * or {@link org.bukkit.plugin.Plugin#getLogger()} or create a specific logger for a class via slf4j.
++     * That way, log messages contain contextual information about the source of the message.
+      */
+     @NotNull
++    @org.jetbrains.annotations.ApiStatus.Internal // Paper - internalize Bukkit#getLogger
+     public Logger getLogger();
+ 
+     /**
+@@ -1148,10 +1153,8 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
+      * @param name the name the player to retrieve
+      * @return an offline player
+      * @see #getOfflinePlayer(java.util.UUID)
+-     * @deprecated Persistent storage of users should be by UUID as names are no longer
+-     *             unique past a single session.
+      */
+-    @Deprecated
++    // @Deprecated // Paper
+     @NotNull
+     public OfflinePlayer getOfflinePlayer(@NotNull String name);
+ 
+@@ -1669,7 +1672,7 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
+      *
+      * @return the scoreboard manager or null if no worlds are loaded.
+      */
+-    @Nullable
++    @NotNull // Paper
+     ScoreboardManager getScoreboardManager();
+ 
+     /**
+diff --git a/src/main/java/org/bukkit/UndefinedNullability.java b/src/main/java/org/bukkit/UndefinedNullability.java
+index 4d4265c237179470e1fd017721a8dd595f114013..3babc9df26276300392d3f92ee6e317c33643b0b 100644
+--- a/src/main/java/org/bukkit/UndefinedNullability.java
++++ b/src/main/java/org/bukkit/UndefinedNullability.java
+@@ -14,6 +14,7 @@ import org.jetbrains.annotations.ApiStatus;
+  * suggests a bad API design.
+  */
+ @Retention(RetentionPolicy.CLASS)
[email protected] // Paper
+ @ApiStatus.Internal
+ @Deprecated
+ public @interface UndefinedNullability {
+diff --git a/src/main/java/org/bukkit/Vibration.java b/src/main/java/org/bukkit/Vibration.java
+index e455eb21abf121dc6ff10ff8a13dd06f67096a8f..bbc01e7c192ae6689c301670047ff114306c57cb 100644
+--- a/src/main/java/org/bukkit/Vibration.java
++++ b/src/main/java/org/bukkit/Vibration.java
+@@ -13,6 +13,14 @@ public class Vibration {
+     private final Destination destination;
+     private final int arrivalTime;
+ 
++    // Paper start
++    public Vibration(@NotNull Destination destination, @NotNull int arrivalTime) {
++        this.destination = destination;
++        this.arrivalTime = arrivalTime;
++        this.origin = new Location(null, 0, 0, 0); // Dummy origin because getter expects null
++    }
++
++    @Deprecated(forRemoval = true) // Paper end
+     public Vibration(@NotNull Location origin, @NotNull Destination destination, int arrivalTime) {
+         this.origin = origin;
+         this.destination = destination;
+@@ -22,9 +30,11 @@ public class Vibration {
+     /**
+      * Get the origin of the vibration.
+      *
++     * @deprecated unused as of 1.19
+      * @return origin
+      */
+     @NotNull
++    @Deprecated(forRemoval = true) // Paper
+     public Location getOrigin() {
+         return origin;
+     }
+diff --git a/src/main/java/org/bukkit/World.java b/src/main/java/org/bukkit/World.java
+index fcdc5d83621acff5f9210585455be1ea50abb77c..216995288f6b8b407ef8240411b5ed4713379a7a 100644
+--- a/src/main/java/org/bukkit/World.java
++++ b/src/main/java/org/bukkit/World.java
+@@ -418,9 +418,8 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
+      * @param z Z-coordinate of the chunk
+      * @return Whether the chunk was actually refreshed
+      *
+-     * @deprecated This method is not guaranteed to work suitably across all client implementations.
+      */
+-    @Deprecated
++    //@Deprecated // Paper
+     public boolean refreshChunk(int x, int z);
+ 
+     /**
+@@ -3797,6 +3796,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
+     StructureSearchResult locateNearestStructure(@NotNull Location origin, @NotNull Structure structure, int radius, boolean findUnexplored);
+ 
+     // Spigot start
++    @Deprecated(forRemoval = true) // Paper
+     public class Spigot {
+ 
+         /**
+@@ -3830,7 +3830,11 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
+         }
+     }
+ 
++    /**
++     * @deprecated Unsupported api
++     */
+     @NotNull
++    @Deprecated // Paper
+     Spigot spigot();
+     // Spigot end
+ 
+@@ -4048,9 +4052,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;
+         }
+@@ -4060,9 +4064,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 bb3cf2c5e2acbcd7cf53ad8551a5b11fa6104ada..e4393f2bd71308a58305cb870271d6a647ffcd92 100644
+--- a/src/main/java/org/bukkit/block/Block.java
++++ b/src/main/java/org/bukkit/block/Block.java
+@@ -526,7 +526,7 @@ public interface Block extends Metadatable, Translatable {
+      * @return a list of dropped items for this type of block
+      */
+     @NotNull
+-    Collection<ItemStack> getDrops(@NotNull ItemStack tool, @Nullable Entity entity);
++    Collection<ItemStack> getDrops(@Nullable ItemStack tool, @Nullable Entity entity); // Paper
+ 
+     /**
+      * Returns if the given item is a preferred choice to break this Block.
+diff --git a/src/main/java/org/bukkit/block/BlockState.java b/src/main/java/org/bukkit/block/BlockState.java
+index 3e07fc1bc0e08d0cfd998711c7fd547b2b7b6b73..fd4a9bdcfb6775dfbdb7492e6c9eb90722d2ecdc 100644
+--- a/src/main/java/org/bukkit/block/BlockState.java
++++ b/src/main/java/org/bukkit/block/BlockState.java
+@@ -36,8 +36,10 @@ public interface BlockState extends Metadatable {
+      * Gets the metadata for this block state.
+      *
+      * @return block specific metadata
++     * @deprecated use {@link #getBlockData()}
+      */
+     @NotNull
++    @Deprecated // Paper
+     MaterialData getData();
+ 
+     /**
+@@ -151,7 +153,9 @@ public interface BlockState extends Metadatable {
+      * Sets the metadata for this block state.
+      *
+      * @param data New block specific metadata
++     * @deprecated use {@link #setBlockData(BlockData)}
+      */
++    @Deprecated // Paper
+     void setData(@NotNull MaterialData data);
+ 
+     /**
+diff --git a/src/main/java/org/bukkit/block/BrushableBlock.java b/src/main/java/org/bukkit/block/BrushableBlock.java
+index 4bd127b3646307398e0c937c3e36ab671235b72b..f2557a87f468ee20c2d276dbfc0e9a976656c75c 100644
+--- a/src/main/java/org/bukkit/block/BrushableBlock.java
++++ b/src/main/java/org/bukkit/block/BrushableBlock.java
+@@ -15,7 +15,7 @@ public interface BrushableBlock extends Lootable, TileState {
+      *
+      * @return the item
+      */
+-    @Nullable
++    @org.jetbrains.annotations.NotNull // Paper
+     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/enchantments/Enchantment.java b/src/main/java/org/bukkit/enchantments/Enchantment.java
+index c7a901707048e9dc82b8f17f3285727460173c72..64675a3641acb50676ca0122f8473ce94de8fba7 100644
+--- a/src/main/java/org/bukkit/enchantments/Enchantment.java
++++ b/src/main/java/org/bukkit/enchantments/Enchantment.java
+@@ -269,7 +269,7 @@ public abstract class Enchantment implements Keyed, Translatable {
+      * @deprecated enchantment groupings are now managed by tags, not categories
+      */
+     @NotNull
+-    @Deprecated
++    @Deprecated(forRemoval = true, since = "1.20.5") @org.jetbrains.annotations.Contract("-> fail") // Paper
+     public abstract EnchantmentTarget getItemTarget();
+ 
+     /**
+diff --git a/src/main/java/org/bukkit/entity/Enderman.java b/src/main/java/org/bukkit/entity/Enderman.java
+index 3afe2787de576f7190d87c796bea0ab34dc30248..58191017244f3949f6174fb108e3a245738a53c4 100644
+--- a/src/main/java/org/bukkit/entity/Enderman.java
++++ b/src/main/java/org/bukkit/entity/Enderman.java
+@@ -25,15 +25,19 @@ public interface Enderman extends Monster {
+      * Gets the id and data of the block that the Enderman is carrying.
+      *
+      * @return MaterialData containing the id and data of the block
++     * @deprecated use {@link #getCarriedBlock()}
+      */
+     @NotNull
++    @Deprecated // Paper
+     public MaterialData getCarriedMaterial();
+ 
+     /**
+      * Sets the id and data of the block that the Enderman is carrying.
+      *
+      * @param material data to set the carried block to
++     * @deprecated use {@link #setCarriedBlock(BlockData)}
+      */
++    @Deprecated // Paper
+     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 4047f026ab796eca7ad2d6718e1436f251c08e93..d248069adfc67eb840951f7ab4a1fa5d30214dec 100644
+--- a/src/main/java/org/bukkit/entity/EntityType.java
++++ b/src/main/java/org/bukkit/entity/EntityType.java
+@@ -381,9 +381,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 b27447d7a2833f84cf05946c851f5b6740a578e3..5afeb2f6c82e8f752229462c2d7846f6ae7a4b44 100644
+--- a/src/main/java/org/bukkit/entity/LightningStrike.java
++++ b/src/main/java/org/bukkit/entity/LightningStrike.java
+@@ -84,6 +84,10 @@ public interface LightningStrike extends Entity {
+     public void setCausingPlayer(@Nullable Player player);
+ 
+     // Spigot start
++    /**
++     * @deprecated Unsupported api
++     */
++    @Deprecated // Paper
+     public class Spigot extends Entity.Spigot {
+ 
+         /**
+@@ -98,8 +102,12 @@ public interface LightningStrike extends Entity {
+         }
+     }
+ 
++    /**
++     * @deprecated Unsupported api
++     */
+     @NotNull
+     @Override
++    @Deprecated // Paper
+     Spigot spigot();
+     // Spigot end
+ }
+diff --git a/src/main/java/org/bukkit/entity/LingeringPotion.java b/src/main/java/org/bukkit/entity/LingeringPotion.java
+index bafef53c1d449135f1300c8c8fbb06f482ba67e1..f50aaddf8582be55fd4860ad374d8f2206991897 100644
+--- a/src/main/java/org/bukkit/entity/LingeringPotion.java
++++ b/src/main/java/org/bukkit/entity/LingeringPotion.java
+@@ -3,7 +3,8 @@ package org.bukkit.entity;
+ /**
+  * Represents a thrown lingering potion bottle
+  *
+- * @deprecated lingering status depends on only on the potion item.
++ * @deprecated should not be used for anything, use {@link ThrownPotion} and
++ * set the potion via the methods there.
+  */
+-@Deprecated
++@Deprecated(forRemoval = true) // Paper
+ public interface LingeringPotion extends ThrownPotion { }
+diff --git a/src/main/java/org/bukkit/entity/LivingEntity.java b/src/main/java/org/bukkit/entity/LivingEntity.java
+index b5ea7b60b47f056553a1cec766c57e0f75735633..ec35111df4b38fd55cc34f4baedebcf39c7fc92b 100644
+--- a/src/main/java/org/bukkit/entity/LivingEntity.java
++++ b/src/main/java/org/bukkit/entity/LivingEntity.java
+@@ -716,7 +716,9 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
+      * This may have unexpected results if the entity is not in water.
+      *
+      * @param swimming True if the entity is swimming.
++     * @deprecated This does nothing and is immediately reverted by the server, in the next tick <!-- Paper - future note: should wait a mojang input client/server side -->
+      */
++    @Deprecated // Paper
+     public void setSwimming(boolean swimming);
+ 
+     /**
+@@ -971,7 +973,7 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
+      * @deprecated entity groupings are now managed by tags, not categories
+      */
+     @NotNull
+-    @Deprecated
++    @Deprecated(forRemoval = true, since = "1.20.5") @org.jetbrains.annotations.Contract("-> fail") // Paper
+     public EntityCategory getCategory();
+ 
+     /**
+diff --git a/src/main/java/org/bukkit/entity/Minecart.java b/src/main/java/org/bukkit/entity/Minecart.java
+index 95c79c5fa0c4e30201f887da6467ce5f81c8a255..7f9c4d4b430a3f0276461346ff2621bacf864075 100644
+--- a/src/main/java/org/bukkit/entity/Minecart.java
++++ b/src/main/java/org/bukkit/entity/Minecart.java
+@@ -101,7 +101,9 @@ public interface Minecart extends Vehicle {
+      * Passing a null value will set the minecart to have no display block.
+      *
+      * @param material the material to set as display block.
++     * @deprecated use {@link #setDisplayBlockData(BlockData)}
+      */
++    @Deprecated // Paper
+     public void setDisplayBlock(@Nullable MaterialData material);
+ 
+     /**
+@@ -109,8 +111,10 @@ public interface Minecart extends Vehicle {
+      * This function will return the type AIR if none is set.
+      *
+      * @return the block displayed by this minecart.
++     * @deprecated use {@link #getDisplayBlockData()}
+      */
+     @NotNull
++    @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 dc9829ab0f4efcf9534f1b2d4a2e48ea49e8d372..e65f4f0df2e6832cf089572822c96ecc7a83dab3 100644
+--- a/src/main/java/org/bukkit/entity/Player.java
++++ b/src/main/java/org/bukkit/entity/Player.java
+@@ -1640,11 +1640,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
+--- a/src/main/java/org/bukkit/entity/Projectile.java
++++ b/src/main/java/org/bukkit/entity/Projectile.java
+@@ -29,7 +29,7 @@ public interface Projectile extends Entity {
+      * @return true if it should bounce.
+      * @deprecated does not do anything
+      */
+-    @Deprecated
++    @Deprecated(forRemoval = true)
+     public boolean doesBounce();
+ 
+     /**
+@@ -39,6 +39,6 @@ public interface Projectile extends Entity {
+      * @param doesBounce whether or not it should bounce.
+      * @deprecated does not do anything
+      */
+-    @Deprecated
++    @Deprecated(forRemoval = true)
+     public void setBounce(boolean doesBounce);
+ }
+diff --git a/src/main/java/org/bukkit/entity/SplashPotion.java b/src/main/java/org/bukkit/entity/SplashPotion.java
+index 9cb08fe7201a9f91e88c7b1ee22c17889a7bf1c3..c0fcfccdf476106b48e626a099658c04244ebff8 100644
+--- a/src/main/java/org/bukkit/entity/SplashPotion.java
++++ b/src/main/java/org/bukkit/entity/SplashPotion.java
+@@ -3,7 +3,8 @@ package org.bukkit.entity;
+ /**
+  * Represents a thrown splash potion bottle
+  *
+- * @deprecated splash status depends on only on the potion item.
++ * @deprecated should not be used for anything, use {@link ThrownPotion} and
++ * set the potion via the methods there.
+  */
+-@Deprecated
++@Deprecated(forRemoval = true) // Paper
+ public interface SplashPotion extends ThrownPotion { }
+diff --git a/src/main/java/org/bukkit/entity/memory/MemoryKey.java b/src/main/java/org/bukkit/entity/memory/MemoryKey.java
+index 8f601e85df580ef8106eaff8b9eafb5691a4874b..d615c006c9153fb65024241604b744fbfc383efc 100644
+--- a/src/main/java/org/bukkit/entity/memory/MemoryKey.java
++++ b/src/main/java/org/bukkit/entity/memory/MemoryKey.java
+@@ -69,6 +69,12 @@ public final class MemoryKey<T> implements Keyed {
+     public static final MemoryKey<Location> LIKED_NOTEBLOCK_POSITION = new MemoryKey<>(NamespacedKey.minecraft("liked_noteblock"), Location.class);
+     public static final MemoryKey<Integer> LIKED_NOTEBLOCK_COOLDOWN_TICKS = new MemoryKey<>(NamespacedKey.minecraft("liked_noteblock_cooldown_ticks"), Integer.class);
+     public static final MemoryKey<Integer> ITEM_PICKUP_COOLDOWN_TICKS = new MemoryKey<>(NamespacedKey.minecraft("item_pickup_cooldown_ticks"), Integer.class);
++    /**
++     * @deprecated this constant uses the wrong generic type, the sniffer now stores different positions
++     * from possibly different worlds. Use the relevant methods in {@link org.bukkit.entity.Sniffer} directly
++     * for now.
++     */
++    @Deprecated // Paper
+     public static final MemoryKey<Location> SNIFFER_EXPLORED_POSITIONS = new MemoryKey<>(NamespacedKey.minecraft("sniffer_explored_positions"), Location.class);
+ 
+     /**
+diff --git a/src/main/java/org/bukkit/event/block/BrewingStartEvent.java b/src/main/java/org/bukkit/event/block/BrewingStartEvent.java
+index 9e54ef5b60bf5583c12e1edfa76f19013a5b2a65..37be83184cae203d5e99518b0ff5c708fafb0331 100644
+--- a/src/main/java/org/bukkit/event/block/BrewingStartEvent.java
++++ b/src/main/java/org/bukkit/event/block/BrewingStartEvent.java
+@@ -8,6 +8,7 @@ import org.jetbrains.annotations.NotNull;
+ /**
+  * Called when a brewing stand starts to brew.
+  */
[email protected] // Paper
+ public class BrewingStartEvent extends InventoryBlockStartEvent {
+ 
+     private static final HandlerList handlers = new HandlerList();
+diff --git a/src/main/java/org/bukkit/event/block/CampfireStartEvent.java b/src/main/java/org/bukkit/event/block/CampfireStartEvent.java
+index 53119742beda00a38111063243665bb995ae2188..2d084214e991fecc51f8e18e3d733e43b1dca248 100644
+--- a/src/main/java/org/bukkit/event/block/CampfireStartEvent.java
++++ b/src/main/java/org/bukkit/event/block/CampfireStartEvent.java
+@@ -9,6 +9,7 @@ import org.jetbrains.annotations.NotNull;
+ /**
+  * Called when a Campfire starts to cook.
+  */
[email protected] // Paper
+ public class CampfireStartEvent extends InventoryBlockStartEvent {
+ 
+     private static final HandlerList handlers = new HandlerList();
+diff --git a/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java b/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java
+index f2edd4a9357832e9dec3fb0aafa006335d7b289b..f05ce4fd6c4bbd79edc5f65e7edd1e4a63e93fb8 100644
+--- a/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java
++++ b/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java
+@@ -23,7 +23,7 @@ public class PrepareItemEnchantEvent extends InventoryEvent implements Cancellab
+     private boolean cancelled;
+     private final Player enchanter;
+ 
+-    public PrepareItemEnchantEvent(@NotNull final Player enchanter, @NotNull InventoryView view, @NotNull final Block table, @NotNull final ItemStack item, @NotNull final EnchantmentOffer[] offers, final int bonus) {
++    public PrepareItemEnchantEvent(@NotNull final Player enchanter, @NotNull InventoryView view, @NotNull final Block table, @NotNull final ItemStack item, @org.jetbrains.annotations.Nullable final EnchantmentOffer @NotNull [] offers, final int bonus) { // Paper - offers can contain null values
+         super(view);
+         this.enchanter = enchanter;
+         this.table = table;
+@@ -86,8 +86,7 @@ public class PrepareItemEnchantEvent extends InventoryEvent implements Cancellab
+      *
+      * @return list of available enchantment offers
+      */
+-    @NotNull
+-    public EnchantmentOffer[] getOffers() {
++    public @org.jetbrains.annotations.Nullable EnchantmentOffer @NotNull [] getOffers() { // Paper offers can contain null values
+         return offers;
+     }
+ 
+diff --git a/src/main/java/org/bukkit/event/entity/EntityTargetLivingEntityEvent.java b/src/main/java/org/bukkit/event/entity/EntityTargetLivingEntityEvent.java
+index 090ec6f96ca9b7f760389994da988c44c32b9976..e6b4d4c1722bf4a11744a421d09646b22745b138 100644
+--- a/src/main/java/org/bukkit/event/entity/EntityTargetLivingEntityEvent.java
++++ b/src/main/java/org/bukkit/event/entity/EntityTargetLivingEntityEvent.java
+@@ -10,7 +10,7 @@ import org.jetbrains.annotations.Nullable;
+  * LivingEntity's.
+  */
+ public class EntityTargetLivingEntityEvent extends EntityTargetEvent {
+-    public EntityTargetLivingEntityEvent(@NotNull final Entity entity, @Nullable final LivingEntity target, @Nullable final TargetReason reason) {
++    public EntityTargetLivingEntityEvent(@NotNull final Entity entity, @Nullable final LivingEntity target, @NotNull final TargetReason reason) { // Paper
+         super(entity, target, reason);
+     }
+ 
+diff --git a/src/main/java/org/bukkit/event/entity/EntityToggleSwimEvent.java b/src/main/java/org/bukkit/event/entity/EntityToggleSwimEvent.java
+index e1123295b9511a2c610a1baf7195638f7f3e64c4..273ae8e5da0a858d3b82d1b0f5992318ff49f145 100644
+--- a/src/main/java/org/bukkit/event/entity/EntityToggleSwimEvent.java
++++ b/src/main/java/org/bukkit/event/entity/EntityToggleSwimEvent.java
+@@ -24,6 +24,14 @@ public class EntityToggleSwimEvent extends EntityEvent implements Cancellable {
+         return cancel;
+     }
+ 
++    /**
++     * @deprecated This does nothing, the server and the client doesn't work
++     * correctly when the server try to bypass this. A current workaround
++     * exists. If you want to cancel the switch from the ground state to the
++     * swimming state you need to disable the sprinting flag for the player after
++     * the cancel action.
++     */
++    @Deprecated // Paper
+     @Override
+     public void setCancelled(boolean cancel) {
+         this.cancel = cancel;
+diff --git a/src/main/java/org/bukkit/event/entity/ProjectileHitEvent.java b/src/main/java/org/bukkit/event/entity/ProjectileHitEvent.java
+index 56e6024f1fa64569481543dc076e575bb512eef0..7fccda2a48f7bac7da54862c5cb8f1b484cc9da9 100644
+--- a/src/main/java/org/bukkit/event/entity/ProjectileHitEvent.java
++++ b/src/main/java/org/bukkit/event/entity/ProjectileHitEvent.java
+@@ -19,22 +19,27 @@ public class ProjectileHitEvent extends EntityEvent implements Cancellable {
+     private final BlockFace hitFace;
+     private boolean cancel = false;
+ 
++    @Deprecated @io.papermc.paper.annotation.DoNotUse // Paper
+     public ProjectileHitEvent(@NotNull final Projectile projectile) {
+-        this(projectile, null, null);
++        this(projectile, null, null, null); // Paper
+     }
+ 
++    @Deprecated @io.papermc.paper.annotation.DoNotUse // Paper
+     public ProjectileHitEvent(@NotNull final Projectile projectile, @Nullable Entity hitEntity) {
+-        this(projectile, hitEntity, null);
++        this(projectile, hitEntity, null, null); // Paper
+     }
+ 
++    @Deprecated @io.papermc.paper.annotation.DoNotUse // Paper
+     public ProjectileHitEvent(@NotNull final Projectile projectile, @Nullable Block hitBlock) {
+-        this(projectile, null, hitBlock);
++        this(projectile, null, hitBlock, null); // Paper
+     }
+ 
++    @Deprecated @io.papermc.paper.annotation.DoNotUse // Paper
+     public ProjectileHitEvent(@NotNull final Projectile projectile, @Nullable Entity hitEntity, @Nullable Block hitBlock) {
+         this(projectile, hitEntity, hitBlock, null);
+     }
+ 
++    @org.jetbrains.annotations.ApiStatus.Internal // Paper
+     public ProjectileHitEvent(@NotNull final Projectile projectile, @Nullable Entity hitEntity, @Nullable Block hitBlock, @Nullable BlockFace hitFace) {
+         super(projectile);
+         this.hitEntity = hitEntity;
+diff --git a/src/main/java/org/bukkit/event/entity/SpawnerSpawnEvent.java b/src/main/java/org/bukkit/event/entity/SpawnerSpawnEvent.java
+index 9353f0d09272404f42167ab8b7ad83a03620c436..f3ec8f67328b266defb31a44a36d31401d5e9371 100644
+--- a/src/main/java/org/bukkit/event/entity/SpawnerSpawnEvent.java
++++ b/src/main/java/org/bukkit/event/entity/SpawnerSpawnEvent.java
+@@ -12,12 +12,19 @@ import org.jetbrains.annotations.NotNull;
+ public class SpawnerSpawnEvent extends EntitySpawnEvent {
+     private final CreatureSpawner spawner;
+ 
+-    public SpawnerSpawnEvent(@NotNull final Entity spawnee, @NotNull final CreatureSpawner spawner) {
++    public SpawnerSpawnEvent(@NotNull final Entity spawnee, @org.jetbrains.annotations.Nullable final CreatureSpawner spawner) { // Paper
+         super(spawnee);
+         this.spawner = spawner;
+     }
+ 
+-    @NotNull
++    /**
++     * Gets the spawner tile state, or null
++     * when the entity is spawned from a minecart
++     * spawner.
++     *
++     * @return the spawner tile state
++     */
++    @org.jetbrains.annotations.Nullable // Paper
+     public CreatureSpawner getSpawner() {
+         return spawner;
+     }
+diff --git a/src/main/java/org/bukkit/event/hanging/HangingBreakByEntityEvent.java b/src/main/java/org/bukkit/event/hanging/HangingBreakByEntityEvent.java
+index 68517811f63838bdad41073ee26be82f95042a8e..454885e47611edd707358ddfe0a01b7acf9ad5c8 100644
+--- a/src/main/java/org/bukkit/event/hanging/HangingBreakByEntityEvent.java
++++ b/src/main/java/org/bukkit/event/hanging/HangingBreakByEntityEvent.java
+@@ -11,22 +11,21 @@ import org.jetbrains.annotations.Nullable;
+ public class HangingBreakByEntityEvent extends HangingBreakEvent {
+     private final Entity remover;
+ 
+-    public HangingBreakByEntityEvent(@NotNull final Hanging hanging, @Nullable final Entity remover) {
++    public HangingBreakByEntityEvent(@NotNull final Hanging hanging, @NotNull final Entity remover) { // Paper
+         this(hanging, remover, HangingBreakEvent.RemoveCause.ENTITY);
+     }
+ 
+-    public HangingBreakByEntityEvent(@NotNull final Hanging hanging, @Nullable final Entity remover, @NotNull final HangingBreakEvent.RemoveCause cause) {
++    public HangingBreakByEntityEvent(@NotNull final Hanging hanging, @NotNull final Entity remover, @NotNull final HangingBreakEvent.RemoveCause cause) { // Paper
+         super(hanging, cause);
+         this.remover = remover;
+     }
+ 
+     /**
+      * Gets the entity that removed the hanging entity.
+-     * May be null, for example when broken by an explosion.
+      *
+      * @return the entity that removed the hanging entity
+      */
+-    @Nullable
++    @NotNull // Paper
+     public Entity getRemover() {
+         return remover;
+     }
+diff --git a/src/main/java/org/bukkit/event/inventory/HopperInventorySearchEvent.java b/src/main/java/org/bukkit/event/inventory/HopperInventorySearchEvent.java
+index 80a0a4ad813d6453b30273d25942e6612bb05c1b..18bb808e73c7a78f367ccdb44d5fe12bc54672cb 100644
+--- a/src/main/java/org/bukkit/event/inventory/HopperInventorySearchEvent.java
++++ b/src/main/java/org/bukkit/event/inventory/HopperInventorySearchEvent.java
+@@ -34,7 +34,7 @@ public class HopperInventorySearchEvent extends BlockEvent {
+         DESTINATION;
+     }
+ 
+-    public HopperInventorySearchEvent(@NotNull Inventory inventory, @NotNull ContainerType containerType, @NotNull Block hopper, @NotNull Block searchBlock) {
++    public HopperInventorySearchEvent(@Nullable Inventory inventory, @NotNull ContainerType containerType, @NotNull Block hopper, @NotNull Block searchBlock) { // Paper
+         super(hopper);
+         this.inventory = inventory;
+         this.containerType = containerType;
+diff --git a/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java b/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java
+index f2a2a2ad9930499c5bf624e73571a3294a90db14..c8540a42ab44647fdd112ce4f731f3dc0df552f4 100644
+--- a/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java
++++ b/src/main/java/org/bukkit/event/inventory/InventoryClickEvent.java
+@@ -88,7 +88,7 @@ public class InventoryClickEvent extends InventoryInteractEvent {
+      *
+      * @return the cursor ItemStack
+      */
+-    @Nullable
++    @NotNull // Paper - fix nullability
+     public ItemStack getCursor() {
+         return getView().getCursor();
+     }
+diff --git a/src/main/java/org/bukkit/event/player/PlayerBedLeaveEvent.java b/src/main/java/org/bukkit/event/player/PlayerBedLeaveEvent.java
+index 1cb70b5c8776863f44f1c4cdde152c35cb51edb5..f09b378508fcc6299e7cb40f174028f6f88ba067 100644
+--- a/src/main/java/org/bukkit/event/player/PlayerBedLeaveEvent.java
++++ b/src/main/java/org/bukkit/event/player/PlayerBedLeaveEvent.java
+@@ -43,7 +43,10 @@ public class PlayerBedLeaveEvent extends PlayerEvent implements Cancellable {
+      * {@link Player#setBedSpawnLocation(Location)}.
+      *
+      * @return true if the spawn location will be changed
++     * @deprecated the respawn point is now set when the player enter the bed and
++     * this option doesn't work since MC 1.15.
+      */
++    @Deprecated(forRemoval = true) // Paper - Unused
+     public boolean shouldSetSpawnLocation() {
+         return setBedSpawn;
+     }
+@@ -59,7 +62,10 @@ public class PlayerBedLeaveEvent extends PlayerEvent implements Cancellable {
+      * {@link Player#setBedSpawnLocation(Location)}.
+      *
+      * @param setBedSpawn true to change the new spawn location
++     * @deprecated the respawn point is now set when the player enter the bed and
++     * this option doesn't work since MC 1.15.
+      */
++    @Deprecated(forRemoval = true) // Paper - Unused
+     public void setSpawnLocation(boolean setBedSpawn) {
+         this.setBedSpawn = setBedSpawn;
+     }
+diff --git a/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java b/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java
+index 1b2267f4e8ebded198773ec80e2bff2c861c7084..1a58734d919fae247eeb85dd785fd59990856505 100644
+--- a/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java
++++ b/src/main/java/org/bukkit/event/player/PlayerMoveEvent.java
+@@ -78,7 +78,7 @@ public class PlayerMoveEvent extends PlayerEvent implements Cancellable {
+      *
+      * @return Location the player moved to
+      */
+-    @Nullable
++    @NotNull // Paper
+     public Location getTo() {
+         return to;
+     }
+diff --git a/src/main/java/org/bukkit/event/raid/RaidSpawnWaveEvent.java b/src/main/java/org/bukkit/event/raid/RaidSpawnWaveEvent.java
+index cd58dd7de781823804701fc023706e805c0142a8..1b8bb5241efcf4a90fd098f2000f8394072dca4a 100644
+--- a/src/main/java/org/bukkit/event/raid/RaidSpawnWaveEvent.java
++++ b/src/main/java/org/bukkit/event/raid/RaidSpawnWaveEvent.java
+@@ -19,7 +19,7 @@ public class RaidSpawnWaveEvent extends RaidEvent {
+     private final List<Raider> raiders;
+     private final Raider leader;
+ 
+-    public RaidSpawnWaveEvent(@NotNull Raid raid, @NotNull World world, @Nullable Raider leader, @NotNull List<Raider> raiders) {
++    public RaidSpawnWaveEvent(@NotNull Raid raid, @NotNull World world, @NotNull Raider leader, @NotNull List<Raider> raiders) { // Paper
+         super(raid, world);
+         this.raiders = raiders;
+         this.leader = leader;
+@@ -30,7 +30,7 @@ public class RaidSpawnWaveEvent extends RaidEvent {
+      *
+      * @return {@link Raider}
+      */
+-    @Nullable
++    @NotNull // Paper
+     public Raider getPatrolLeader() {
+         return leader;
+     }
+diff --git a/src/main/java/org/bukkit/event/vehicle/VehicleEntityCollisionEvent.java b/src/main/java/org/bukkit/event/vehicle/VehicleEntityCollisionEvent.java
+index 6bafc62e2235a6b783cbf96f4dabeeaf02bd5178..50c762d777ac90a05772501a28cacff8fd3f5126 100644
+--- a/src/main/java/org/bukkit/event/vehicle/VehicleEntityCollisionEvent.java
++++ b/src/main/java/org/bukkit/event/vehicle/VehicleEntityCollisionEvent.java
+@@ -36,18 +36,22 @@ public class VehicleEntityCollisionEvent extends VehicleCollisionEvent implement
+         this.cancelled = cancel;
+     }
+ 
++    @Deprecated(forRemoval = true) // Paper - Unused
+     public boolean isPickupCancelled() {
+         return cancelledPickup;
+     }
+ 
++    @Deprecated(forRemoval = true) // Paper - Unused
+     public void setPickupCancelled(boolean cancel) {
+         cancelledPickup = cancel;
+     }
+ 
++    @Deprecated(forRemoval = true) // Paper - Unused
+     public boolean isCollisionCancelled() {
+         return cancelledCollision;
+     }
+ 
++    @Deprecated(forRemoval = true) // Paper - Unused
+     public void setCollisionCancelled(boolean cancel) {
+         cancelledCollision = cancel;
+     }
+diff --git a/src/main/java/org/bukkit/generator/ChunkGenerator.java b/src/main/java/org/bukkit/generator/ChunkGenerator.java
+index c0b749a5bbf4980d01fed74768bb61909b579cb9..7e7a53b41013f1bf8956c0e278820f18d77b2f0d 100644
+--- a/src/main/java/org/bukkit/generator/ChunkGenerator.java
++++ b/src/main/java/org/bukkit/generator/ChunkGenerator.java
+@@ -656,7 +656,9 @@ public abstract class ChunkGenerator {
+          * @param y the y location in the chunk from minHeight (inclusive) - maxHeight (exclusive)
+          * @param z the z location in the chunk from 0-15 inclusive
+          * @param material the type to set the block to
++         * @deprecated use {@link #setBlock(int, int, int, BlockData)}
+          */
++        @Deprecated // Paper
+         public void setBlock(int x, int y, int z, @NotNull MaterialData material);
+ 
+         /**
+@@ -700,7 +702,9 @@ public abstract class ChunkGenerator {
+          * @param yMax maximum y location (exclusive) in the chunk to set
+          * @param zMax maximum z location (exclusive) in the chunk to set
+          * @param material the type to set the blocks to
++         * @deprecated use {@link #setRegion(int, int, int, int, int, int, BlockData)}
+          */
++        @Deprecated // Paper
+         public void setRegion(int xMin, int yMin, int zMin, int xMax, int yMax, int zMax, @NotNull MaterialData material);
+ 
+         /**
+@@ -741,8 +745,10 @@ public abstract class ChunkGenerator {
+          * @param y the y location in the chunk from minHeight (inclusive) - maxHeight (exclusive)
+          * @param z the z location in the chunk from 0-15 inclusive
+          * @return the type and data of the block or the MaterialData for air if x, y or z are outside the chunk's bounds
++         * @deprecated use {@link #getBlockData(int, int, int)}
+          */
+         @NotNull
++        @Deprecated // Paper
+         public MaterialData getTypeAndData(int x, int y, int z);
+ 
+         /**
+diff --git a/src/main/java/org/bukkit/inventory/CookingRecipe.java b/src/main/java/org/bukkit/inventory/CookingRecipe.java
+index 571652ba8843a9493f1843523e24145baa958637..f7fa79393aef40027446b78bac8e9490cfafd8bc 100644
+--- a/src/main/java/org/bukkit/inventory/CookingRecipe.java
++++ b/src/main/java/org/bukkit/inventory/CookingRecipe.java
+@@ -68,7 +68,9 @@ public abstract class CookingRecipe<T extends CookingRecipe> implements Recipe,
+      * Get the input material.
+      *
+      * @return The input material.
++     * @deprecated Use {@link #getInputChoice()} instead for more complete data.
+      */
++    @Deprecated // Paper
+     @NotNull
+     public ItemStack getInput() {
+         return this.ingredient.getItemStack();
+diff --git a/src/main/java/org/bukkit/inventory/CraftingInventory.java b/src/main/java/org/bukkit/inventory/CraftingInventory.java
+index df81bac9ecff697f98941e5c8490e10391e90090..a32977ba3ba60a1c9aee6e469d5d6cd1887c55a2 100644
+--- a/src/main/java/org/bukkit/inventory/CraftingInventory.java
++++ b/src/main/java/org/bukkit/inventory/CraftingInventory.java
+@@ -21,8 +21,7 @@ public interface CraftingInventory extends Inventory {
+      *
+      * @return The contents. Individual entries may be null.
+      */
+-    @NotNull
+-    ItemStack[] getMatrix();
++    @Nullable ItemStack @NotNull [] getMatrix(); // Paper - make array elements nullable instead array
+ 
+     /**
+      * Set the item in the result slot of the crafting inventory.
+@@ -38,7 +37,7 @@ public interface CraftingInventory extends Inventory {
+      * @throws IllegalArgumentException if the length of contents is greater
+      *     than the size of the crafting matrix.
+      */
+-    void setMatrix(@NotNull ItemStack[] contents);
++    void setMatrix(@Nullable ItemStack @NotNull [] contents); // Paper - make array elements nullable instead array
+ 
+     /**
+      * Get the current recipe formed on the crafting inventory, if any.
+diff --git a/src/main/java/org/bukkit/inventory/EntityEquipment.java b/src/main/java/org/bukkit/inventory/EntityEquipment.java
+index 2dde946443fee1f6e79b882cbcb448549dc0c99c..127302aa7c22f59438de66fffa0b03ae84a2a8ad 100644
+--- a/src/main/java/org/bukkit/inventory/EntityEquipment.java
++++ b/src/main/java/org/bukkit/inventory/EntityEquipment.java
+@@ -525,6 +525,6 @@ public interface EntityEquipment {
+      *
+      * @return the entity this EntityEquipment belongs to
+      */
+-    @Nullable
++    @NotNull // Paper
+     Entity getHolder();
+ }
+diff --git a/src/main/java/org/bukkit/inventory/FurnaceRecipe.java b/src/main/java/org/bukkit/inventory/FurnaceRecipe.java
+index 1d442dc16cbb0fed21714d47007f3f11e30c57d4..af8f7b88edf0fa790edcf16356a030c4834f531e 100644
+--- a/src/main/java/org/bukkit/inventory/FurnaceRecipe.java
++++ b/src/main/java/org/bukkit/inventory/FurnaceRecipe.java
+@@ -67,8 +67,10 @@ public class FurnaceRecipe extends CookingRecipe<FurnaceRecipe> {
+      *
+      * @param input The input material.
+      * @return The changed recipe, so you can chain calls.
++     * @deprecated use {@link #setInputChoice(RecipeChoice)}
+      */
+     @NotNull
++    @Deprecated
+     public FurnaceRecipe setInput(@NotNull MaterialData input) {
+         return setInput(input.getItemType(), input.getData());
+     }
+diff --git a/src/main/java/org/bukkit/inventory/Inventory.java b/src/main/java/org/bukkit/inventory/Inventory.java
+index f1a48eab1a357ae64545e1f1dc941c383cff8707..466d1bd7089b76f48f953e1a51c611ecd93dcd54 100644
+--- a/src/main/java/org/bukkit/inventory/Inventory.java
++++ b/src/main/java/org/bukkit/inventory/Inventory.java
+@@ -161,8 +161,7 @@ public interface Inventory extends Iterable<ItemStack> {
+      *
+      * @return An array of ItemStacks from the inventory. Individual items may be null.
+      */
+-    @NotNull
+-    public ItemStack[] getContents();
++    public @Nullable ItemStack @NotNull [] getContents(); // Paper - make array elements nullable instead array
+ 
+     /**
+      * Completely replaces the inventory's contents. Removes all existing
+@@ -173,7 +172,7 @@ public interface Inventory extends Iterable<ItemStack> {
+      * @throws IllegalArgumentException If the array has more items than the
+      *     inventory.
+      */
+-    public void setContents(@NotNull ItemStack[] items) throws IllegalArgumentException;
++    public void setContents(@Nullable ItemStack @NotNull [] items) throws IllegalArgumentException; // Paper - make array elements nullable instead array
+ 
+     /**
+      * Return the contents from the section of the inventory where items can
+@@ -186,8 +185,7 @@ public interface Inventory extends Iterable<ItemStack> {
+      *
+      * @return inventory storage contents. Individual items may be null.
+      */
+-    @NotNull
+-    public ItemStack[] getStorageContents();
++    public @Nullable ItemStack @NotNull [] getStorageContents(); // Paper - make array elements nullable instead array
+ 
+     /**
+      * Put the given ItemStacks into the storage slots
+@@ -196,7 +194,7 @@ public interface Inventory extends Iterable<ItemStack> {
+      * @throws IllegalArgumentException If the array has more items than the
+      * inventory.
+      */
+-    public void setStorageContents(@NotNull ItemStack[] items) throws IllegalArgumentException;
++    public void setStorageContents(@Nullable ItemStack @NotNull [] items) throws IllegalArgumentException; // Paper - make array elements nullable instead array
+ 
+     /**
+      * 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..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.
+      *
+-     * @return The item on the player's cursor, or null if they aren't holding
+-     *     one.
++     * @return The item on the player's cursor, or an empty stack
++     * if they aren't holding one.
+      */
+-    @Nullable
++    @NotNull // Paper - fix nullability
+     public final ItemStack getCursor() {
+         return getPlayer().getItemOnCursor();
+     }
+diff --git a/src/main/java/org/bukkit/inventory/ItemFactory.java b/src/main/java/org/bukkit/inventory/ItemFactory.java
+index 3d08beee52f2247db6f6e679206ed6a965fbf9a8..1b4f9b93860e58762ac28715adad5a67298b06d7 100644
+--- a/src/main/java/org/bukkit/inventory/ItemFactory.java
++++ b/src/main/java/org/bukkit/inventory/ItemFactory.java
+@@ -29,7 +29,7 @@ public interface ItemFactory {
+      * @return a new ItemMeta that could be applied to an item stack of the
+      *     specified material
+      */
+-    @Nullable
++    @org.bukkit.UndefinedNullability // Paper
+     ItemMeta getItemMeta(@NotNull final Material material);
+ 
+     /**
+diff --git a/src/main/java/org/bukkit/inventory/ItemStack.java b/src/main/java/org/bukkit/inventory/ItemStack.java
+index d125d29759167996a90b7b69d92d944e80af22ab..d5dd79c98f4d37b09d232214f06ed7dca3a7e6dd 100644
+--- a/src/main/java/org/bukkit/inventory/ItemStack.java
++++ b/src/main/java/org/bukkit/inventory/ItemStack.java
+@@ -10,6 +10,7 @@ import org.bukkit.Material;
+ import org.bukkit.NamespacedKey;
+ import org.bukkit.Registry;
+ import org.bukkit.Translatable;
++import org.bukkit.UndefinedNullability;
+ import org.bukkit.Utility;
+ import org.bukkit.configuration.serialization.ConfigurationSerializable;
+ import org.bukkit.enchantments.Enchantment;
+@@ -179,8 +180,10 @@ public class ItemStack implements Cloneable, ConfigurationSerializable, Translat
+      * Gets the MaterialData for this stack of items
+      *
+      * @return MaterialData for this item
++     * @deprecated cast to {@link org.bukkit.inventory.meta.BlockDataMeta} and use {@link org.bukkit.inventory.meta.BlockDataMeta#getBlockData(Material)}
+      */
+     @Nullable
++    @Deprecated // Paper
+     public MaterialData getData() {
+         Material mat = Bukkit.getUnsafe().toLegacy(getType());
+         if (data == null && mat != null && mat.getData() != null) {
+@@ -194,7 +197,9 @@ public class ItemStack implements Cloneable, ConfigurationSerializable, Translat
+      * Sets the MaterialData for this stack of items
+      *
+      * @param data New MaterialData for this item
++     * @deprecated cast to {@link org.bukkit.inventory.meta.BlockDataMeta} and use {@link org.bukkit.inventory.meta.BlockDataMeta#setBlockData(org.bukkit.block.data.BlockData)}
+      */
++    @Deprecated // Paper
+     public void setData(@Nullable MaterialData data) {
+         if (data == null) {
+             this.data = data;
+@@ -574,7 +579,7 @@ public class ItemStack implements Cloneable, ConfigurationSerializable, Translat
+      *
+      * @return a copy of the current ItemStack's ItemData
+      */
+-    @Nullable
++    @UndefinedNullability // Paper
+     public ItemMeta getItemMeta() {
+         return this.meta == null ? Bukkit.getItemFactory().getItemMeta(this.type) : this.meta.clone();
+     }
+diff --git a/src/main/java/org/bukkit/inventory/PlayerInventory.java b/src/main/java/org/bukkit/inventory/PlayerInventory.java
+index 476fe14faa39f02444cab8ad95d4401033dc6938..2c54660dc1fbc7c1232096797a23cae1262888e9 100644
+--- a/src/main/java/org/bukkit/inventory/PlayerInventory.java
++++ b/src/main/java/org/bukkit/inventory/PlayerInventory.java
+@@ -16,8 +16,7 @@ public interface PlayerInventory extends Inventory {
+      * null and are returned in a fixed order starting from the boots and going
+      * up to the helmet
+      */
+-    @NotNull
+-    public ItemStack[] getArmorContents();
++    public @Nullable ItemStack @NotNull [] getArmorContents(); // Paper - make array elements nullable instead array
+ 
+     /**
+      * Get all additional ItemStacks stored in this inventory.
+@@ -28,8 +27,7 @@ public interface PlayerInventory extends Inventory {
+      *
+      * @return All additional ItemStacks. Individual items can be null.
+      */
+-    @NotNull
+-    public ItemStack[] getExtraContents();
++    public @Nullable ItemStack @NotNull [] getExtraContents(); // Paper - make array elements nullable instead array
+ 
+     /**
+      * Return the ItemStack from the helmet slot
+@@ -106,9 +104,9 @@ public interface PlayerInventory extends Inventory {
+      *
+      * @param slot the slot to get the ItemStack
+      *
+-     * @return the ItemStack in the given slot or null if there is not one
++     * @return the ItemStack in the given slot
+      */
+-    @Nullable
++    @NotNull // Paper
+     public ItemStack getItem(@NotNull EquipmentSlot slot);
+ 
+     /**
+diff --git a/src/main/java/org/bukkit/inventory/ShapedRecipe.java b/src/main/java/org/bukkit/inventory/ShapedRecipe.java
+index 97d5d9c6347bc401e3f4ab7c0ba1391ad5b0449a..da878c6d4928ddbc16b50ace86d992685a2b7873 100644
+--- a/src/main/java/org/bukkit/inventory/ShapedRecipe.java
++++ b/src/main/java/org/bukkit/inventory/ShapedRecipe.java
+@@ -100,8 +100,10 @@ public class ShapedRecipe extends CraftingRecipe {
+      * @param ingredient The ingredient.
+      * @return The changed recipe, so you can chain calls.
+      * @throws IllegalArgumentException if the {@code key} does not appear in the shape.
++     * @deprecated use {@link #setIngredient(char, RecipeChoice)}
+      */
+     @NotNull
++    @Deprecated // Paper
+     public ShapedRecipe setIngredient(char key, @NotNull MaterialData ingredient) {
+         return setIngredient(key, ingredient.getItemType(), ingredient.getData());
+     }
+@@ -179,7 +181,9 @@ public class ShapedRecipe extends CraftingRecipe {
+      * Get a copy of the ingredients map.
+      *
+      * @return The mapping of character to ingredients.
++     * @deprecated Use {@link #getChoiceMap()} instead for more complete data.
+      */
++    @Deprecated // Paper
+     @NotNull
+     public Map<Character, ItemStack> getIngredientMap() {
+         HashMap<Character, ItemStack> result = new HashMap<Character, ItemStack>();
+diff --git a/src/main/java/org/bukkit/inventory/ShapelessRecipe.java b/src/main/java/org/bukkit/inventory/ShapelessRecipe.java
+index b8ac602cd2718d615ec243ce648951a1a46c26ec..beb798482479c58a8628c314b510ab6349576ce8 100644
+--- a/src/main/java/org/bukkit/inventory/ShapelessRecipe.java
++++ b/src/main/java/org/bukkit/inventory/ShapelessRecipe.java
+@@ -43,8 +43,10 @@ public class ShapelessRecipe extends CraftingRecipe {
+      *
+      * @param ingredient The ingredient to add.
+      * @return The changed recipe, so you can chain calls.
++     * @deprecated use {@link #addIngredient(RecipeChoice)}
+      */
+     @NotNull
++    @Deprecated
+     public ShapelessRecipe addIngredient(@NotNull MaterialData ingredient) {
+         return addIngredient(1, ingredient);
+     }
+@@ -80,8 +82,10 @@ public class ShapelessRecipe extends CraftingRecipe {
+      * @param count How many to add (can't be more than 9!)
+      * @param ingredient The ingredient to add.
+      * @return The changed recipe, so you can chain calls.
++     * @deprecated use {@link #addIngredient(int, Material)}
+      */
+     @NotNull
++    @Deprecated // Paper
+     public ShapelessRecipe addIngredient(int count, @NotNull MaterialData ingredient) {
+         return addIngredient(count, ingredient.getItemType(), ingredient.getData());
+     }
+@@ -198,8 +202,10 @@ public class ShapelessRecipe extends CraftingRecipe {
+      *
+      * @param ingredient The ingredient to remove
+      * @return The changed recipe.
++     * @deprecated use {@link #removeIngredient(Material)}
+      */
+     @NotNull
++    @Deprecated // Paper
+     public ShapelessRecipe removeIngredient(@NotNull MaterialData ingredient) {
+         return removeIngredient(ingredient.getItemType(), ingredient.getData());
+     }
+@@ -226,8 +232,10 @@ public class ShapelessRecipe extends CraftingRecipe {
+      * @param count The number of copies to remove.
+      * @param ingredient The ingredient to remove.
+      * @return The changed recipe.
++     * @deprecated use {@link #removeIngredient(int, Material)}
+      */
+     @NotNull
++    @Deprecated // Paper
+     public ShapelessRecipe removeIngredient(int count, @NotNull MaterialData ingredient) {
+         return removeIngredient(count, ingredient.getItemType(), ingredient.getData());
+     }
+@@ -277,7 +285,9 @@ public class ShapelessRecipe extends CraftingRecipe {
+      * Get the list of ingredients used for this recipe.
+      *
+      * @return The input list
++     * @deprecated Use {@link #getChoiceList()} instead for more complete data.
+      */
++    @Deprecated // Paper
+     @NotNull
+     public List<ItemStack> getIngredientList() {
+         ArrayList<ItemStack> result = new ArrayList<ItemStack>(ingredients.size());
+diff --git a/src/main/java/org/bukkit/inventory/StonecuttingRecipe.java b/src/main/java/org/bukkit/inventory/StonecuttingRecipe.java
+index 597a18a767b68b47e81454b7d44613c7178c1366..bc3440eb72127824b3961fbdae583bb61385f65e 100644
+--- a/src/main/java/org/bukkit/inventory/StonecuttingRecipe.java
++++ b/src/main/java/org/bukkit/inventory/StonecuttingRecipe.java
+@@ -57,7 +57,9 @@ public class StonecuttingRecipe implements Recipe, Keyed {
+      * Get the input material.
+      *
+      * @return The input material.
++     * @deprecated Use {@link #getInputChoice()} instead for more complete data.
+      */
++    @Deprecated // Paper
+     @NotNull
+     public ItemStack getInput() {
+         return this.ingredient.getItemStack();
+diff --git a/src/main/java/org/bukkit/inventory/meta/ItemMeta.java b/src/main/java/org/bukkit/inventory/meta/ItemMeta.java
+index 707d6138f4b27370ee68c8396204f89fa0fb65f2..bdb8b666ded9837382093e6353c8d60ed8d77033 100644
+--- a/src/main/java/org/bukkit/inventory/meta/ItemMeta.java
++++ b/src/main/java/org/bukkit/inventory/meta/ItemMeta.java
+@@ -144,6 +144,7 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste
+     /**
+      * Checks for existence of a localized name.
+      *
++     * @deprecated Use {@link ItemMeta#displayName()} and check if it is instanceof a {@link net.kyori.adventure.text.TranslatableComponent}.
+      * @return true if this has a localized name
+      * @deprecated meta no longer exists
+      */
+@@ -156,6 +157,7 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste
+      * Plugins should check that hasLocalizedName() returns <code>true</code>
+      * before calling this method.
+      *
++     * @deprecated Use {@link ItemMeta#displayName()} and cast it to a {@link net.kyori.adventure.text.TranslatableComponent}. No longer used by the client.
+      * @return the localized name that is set
+      * @deprecated meta no longer exists
+      */
+@@ -166,6 +168,7 @@ public interface ItemMeta extends Cloneable, ConfigurationSerializable, Persiste
+     /**
+      * Sets the localized name.
+      *
++     * @deprecated Use {@link ItemMeta#displayName(Component)} with a {@link net.kyori.adventure.text.TranslatableComponent}. No longer used by the client.
+      * @param name the name to set
+      * @deprecated meta no longer exists
+      */
+diff --git a/src/main/java/org/bukkit/inventory/meta/MapMeta.java b/src/main/java/org/bukkit/inventory/meta/MapMeta.java
+index 32055a8890425e0b819930f3059da5ea9dfca553..26a336dade83baee97d20eb39a058925659f5777 100644
+--- a/src/main/java/org/bukkit/inventory/meta/MapMeta.java
++++ b/src/main/java/org/bukkit/inventory/meta/MapMeta.java
+@@ -16,13 +16,8 @@ public interface MapMeta extends ItemMeta {
+      *
+      * @return true if this has a map ID number.
+      * @see #hasMapView()
+-     * @deprecated These methods are poor API: They rely on the caller to pass
+-     * in an only an integer property, and have poorly defined implementation
+-     * behavior if that integer is not a valid map (the current implementation
+-     * for example will generate a new map with a different ID). The xxxMapView
+-     * family of methods should be used instead.
+      */
+-    @Deprecated
++    //@Deprecated // Paper
+     boolean hasMapId();
+ 
+     /**
+@@ -34,13 +29,8 @@ public interface MapMeta extends ItemMeta {
+      *
+      * @return the map ID that is set
+      * @see #getMapView()
+-     * @deprecated These methods are poor API: They rely on the caller to pass
+-     * in an only an integer property, and have poorly defined implementation
+-     * behavior if that integer is not a valid map (the current implementation
+-     * for example will generate a new map with a different ID). The xxxMapView
+-     * family of methods should be used instead.
+      */
+-    @Deprecated
++    //@Deprecated // Paper
+     int getMapId();
+ 
+     /**
+diff --git a/src/main/java/org/bukkit/map/MapCanvas.java b/src/main/java/org/bukkit/map/MapCanvas.java
+index edef478786bb7456af29ca960009873095830050..e8ac449e6280827beb6d2699df75b1d52a922c9b 100644
+--- a/src/main/java/org/bukkit/map/MapCanvas.java
++++ b/src/main/java/org/bukkit/map/MapCanvas.java
+@@ -95,9 +95,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);
+ 
+     /**
+@@ -106,9 +106,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 4e84e3c5d0fa23bbb063d8429c18abcd7ee6b82a..a17b755da4eca0370680a9777ff3c7de422f5079 100644
+--- a/src/main/java/org/bukkit/map/MapCursor.java
++++ b/src/main/java/org/bukkit/map/MapCursor.java
+@@ -158,9 +158,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;
+     }
+@@ -217,9 +217,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 > 34) {
+             throw new IllegalArgumentException("Type must be in the range 0-34");
+@@ -339,9 +339,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;
+         }
+@@ -351,9 +351,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
++++ b/src/main/java/org/bukkit/material/Openable.java
+@@ -1,5 +1,6 @@
+ package org.bukkit.material;
+ 
++@Deprecated // Paper
+ public interface Openable {
+ 
+     /**
+diff --git a/src/main/java/org/bukkit/material/Redstone.java b/src/main/java/org/bukkit/material/Redstone.java
+index 3e46603f8cd38041394e0e1baf788d9009b3ffc7..b15c141f1db07296bb349f11c6f39b0fbe53e7b1 100644
+--- a/src/main/java/org/bukkit/material/Redstone.java
++++ b/src/main/java/org/bukkit/material/Redstone.java
+@@ -3,6 +3,7 @@ package org.bukkit.material;
+ /**
+  * Indicated a Material that may carry or create a Redstone current
+  */
++@Deprecated // Paper
+ public interface Redstone {
+ 
+     /**
+diff --git a/src/main/java/org/bukkit/material/types/MushroomBlockTexture.java b/src/main/java/org/bukkit/material/types/MushroomBlockTexture.java
+index 0ea9c6b2420a0f990bd1fdf50fc015e37a7060d8..e99644eae1c662b117aa19060d2484aca19fe0a4 100644
+--- a/src/main/java/org/bukkit/material/types/MushroomBlockTexture.java
++++ b/src/main/java/org/bukkit/material/types/MushroomBlockTexture.java
+@@ -7,7 +7,9 @@ import org.jetbrains.annotations.Nullable;
+ 
+ /**
+  * Represents the different textured blocks of mushroom.
++ * @deprecated use BlockData
+  */
++@Deprecated // Paper
+ public enum MushroomBlockTexture {
+ 
+     /**
+diff --git a/src/main/java/org/bukkit/potion/PotionEffectType.java b/src/main/java/org/bukkit/potion/PotionEffectType.java
+index 6bbfebab2ee2b59b3f3213789ecb59e2e7f2680a..42d893ce75a75fe46a4e52b17dc405f5b609ab86 100644
+--- a/src/main/java/org/bukkit/potion/PotionEffectType.java
++++ b/src/main/java/org/bukkit/potion/PotionEffectType.java
+@@ -279,9 +279,9 @@ public abstract class PotionEffectType implements Keyed, Translatable {
+      * 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 abstract int getId();
+ 
+     /**
+@@ -317,9 +317,9 @@ public abstract class PotionEffectType implements Keyed, Translatable {
+      *
+      * @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) {
+         PotionEffectType type = ID_MAP.get(id);
+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
++++ b/src/test/java/org/bukkit/materials/MaterialDataTest.java
+@@ -22,6 +22,7 @@ import org.bukkit.material.WoodenStep;
+ import org.bukkit.material.types.MushroomBlockTexture;
+ import org.junit.jupiter.api.Test;
+ 
++@Deprecated // Paper
+ public class MaterialDataTest {
+ 
+     @Test