#1082: Add "since" to Deprecation annotations

By: DerFrZocker <derrieple@gmail.com>

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

@@ -52,7 +52,7 @@ public interface BanEntry<T> {
      * @return the target name or IP address
      * @deprecated See {@link #getBanTarget()}
      */
-    @Deprecated
+    @Deprecated(since = "1.20.1")
     @NotNull
     public String getTarget();
 

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

@@ -23,7 +23,7 @@ public interface BanList<T> {
          *
          * @deprecated deprecated in favor of {@link #PROFILE}
          */
-        @Deprecated
+        @Deprecated(since = "1.20.1")
         NAME,
         /**
          * Banned IP addresses
@@ -43,7 +43,7 @@ public interface BanList<T> {
      * @return the corresponding entry, or null if none found
      * @deprecated see {@link #getBanEntry(Object)}
      */
-    @Deprecated
+    @Deprecated(since = "1.20.1")
     @Nullable
     public BanEntry<T> getBanEntry(@NotNull String target);
 
@@ -69,7 +69,7 @@ public interface BanList<T> {
      *     (updated) previous ban
      * @deprecated see {@link #addBan(Object, String, Date, String)}
      */
-    @Deprecated
+    @Deprecated(since = "1.20.1")
     @Nullable
     public BanEntry<T> addBan(@NotNull String target, @Nullable String reason, @Nullable Date expires, @Nullable String source);
 
@@ -124,7 +124,7 @@ public interface BanList<T> {
      * @return an immutable set containing every entry tracked by this list
      * @deprecated This return a generic class, prefer use {@link #getEntries()}
      */
-    @Deprecated
+    @Deprecated(since = "1.20.1")
     @NotNull
     public Set<BanEntry> getBanEntries();
 
@@ -155,7 +155,7 @@ public interface BanList<T> {
      *     active ban status, false otherwise
      * @deprecated see {@link #isBanned(Object)}
      */
-    @Deprecated
+    @Deprecated(since = "1.20.1")
     public boolean isBanned(@NotNull String target);
 
     /**
@@ -174,6 +174,6 @@ public interface BanList<T> {
      *
      * @deprecated see {@link #pardon(Object)}
      */
-    @Deprecated
+    @Deprecated(since = "1.20.1")
     public void pardon(@NotNull String target);
 }

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

@@ -481,7 +481,7 @@ public final class Bukkit {
      * @return the default ticks per animal spawns value
      * @deprecated Deprecated in favor of {@link #getTicksPerSpawns(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public static int getTicksPerAnimalSpawns() {
         return server.getTicksPerAnimalSpawns();
     }
@@ -506,7 +506,7 @@ public final class Bukkit {
      * @return the default ticks per monsters spawn value
      * @deprecated Deprecated in favor of {@link #getTicksPerSpawns(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public static int getTicksPerMonsterSpawns() {
         return server.getTicksPerMonsterSpawns();
     }
@@ -530,7 +530,7 @@ public final class Bukkit {
      * @return the default ticks per water mobs spawn value
      * @deprecated Deprecated in favor of {@link #getTicksPerSpawns(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public static int getTicksPerWaterSpawns() {
         return server.getTicksPerWaterSpawns();
     }
@@ -554,7 +554,7 @@ public final class Bukkit {
      * @return the default ticks per ambient mobs spawn value
      * @deprecated Deprecated in favor of {@link #getTicksPerSpawns(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public static int getTicksPerAmbientSpawns() {
         return server.getTicksPerAmbientSpawns();
     }
@@ -578,7 +578,7 @@ public final class Bukkit {
      * @return the default ticks per water ambient mobs spawn value
      * @deprecated Deprecated in favor of {@link #getTicksPerSpawns(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public static int getTicksPerWaterAmbientSpawns() {
         return server.getTicksPerAmbientSpawns();
     }
@@ -602,7 +602,7 @@ public final class Bukkit {
      * @return the default ticks per water underground creature spawn value
      * @deprecated Deprecated in favor of {@link #getTicksPerSpawns(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public static int getTicksPerWaterUndergroundCreatureSpawns() {
         return server.getTicksPerWaterUndergroundCreatureSpawns();
     }
@@ -803,7 +803,7 @@ public final class Bukkit {
      * @return a map view if it exists, or null otherwise
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     @Nullable
     public static MapView getMap(int id) {
         return server.getMap(id);
@@ -1158,7 +1158,7 @@ public final class Bukkit {
      * @return true if the server should send a preview, false otherwise
      * @deprecated chat previews have been removed
      */
-    @Deprecated
+    @Deprecated(since = "1.19.3")
     public static boolean shouldSendChatPreviews() {
         return server.shouldSendChatPreviews();
     }
@@ -1255,7 +1255,7 @@ public final class Bukkit {
      * @deprecated Persistent storage of users should be by UUID as names are no longer
      *             unique past a single session.
      */
-    @Deprecated
+    @Deprecated(since = "1.7.5")
     @NotNull
     public static OfflinePlayer getOfflinePlayer(@NotNull String name) {
         return server.getOfflinePlayer(name);
@@ -1332,7 +1332,7 @@ public final class Bukkit {
      *
      * @deprecated see {@link #banIP(InetAddress)}
      */
-    @Deprecated
+    @Deprecated(since = "1.20.1")
     public static void banIP(@NotNull String address) {
         server.banIP(address);
     }
@@ -1344,7 +1344,7 @@ public final class Bukkit {
      *
      * @deprecated see {@link #unbanIP(InetAddress)}
      */
-    @Deprecated
+    @Deprecated(since = "1.20.1")
     public static void unbanIP(@NotNull String address) {
         server.unbanIP(address);
     }
@@ -1585,7 +1585,7 @@ public final class Bukkit {
      * @return the monster spawn limit
      * @deprecated Deprecated in favor of {@link #getSpawnLimit(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public static int getMonsterSpawnLimit() {
         return server.getMonsterSpawnLimit();
     }
@@ -1597,7 +1597,7 @@ public final class Bukkit {
      * @return the animal spawn limit
      * @deprecated Deprecated in favor of {@link #getSpawnLimit(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public static int getAnimalSpawnLimit() {
         return server.getAnimalSpawnLimit();
     }
@@ -1609,7 +1609,7 @@ public final class Bukkit {
      * @return the water animal spawn limit
      * @deprecated Deprecated in favor of {@link #getSpawnLimit(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public static int getWaterAnimalSpawnLimit() {
         return server.getWaterAnimalSpawnLimit();
     }
@@ -1621,7 +1621,7 @@ public final class Bukkit {
      * @return the water ambient spawn limit
      * @deprecated Deprecated in favor of {@link #getSpawnLimit(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public static int getWaterAmbientSpawnLimit() {
         return server.getAmbientSpawnLimit();
     }
@@ -1633,7 +1633,7 @@ public final class Bukkit {
      * @return the water underground creature limit
      * @deprecated Deprecated in favor of {@link #getSpawnLimit(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public static int getWaterUndergroundCreatureSpawnLimit() {
         return server.getWaterUndergroundCreatureSpawnLimit();
     }
@@ -1645,7 +1645,7 @@ public final class Bukkit {
      * @return the ambient spawn limit
      * @deprecated Deprecated in favor of {@link #getSpawnLimit(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public static int getAmbientSpawnLimit() {
         return server.getAmbientSpawnLimit();
     }
@@ -2170,7 +2170,7 @@ public final class Bukkit {
      * @return the unsafe values instance
      * @see UnsafeValues
      */
-    @Deprecated
+    @Deprecated(since = "1.7.2")
     @NotNull
     public static UnsafeValues getUnsafe() {
         return server.getUnsafe();

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

@@ -65,7 +65,7 @@ public interface ChunkSnapshot {
      * @return 0-15
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     int getData(int x, int y, int z);
 
     /**
@@ -107,7 +107,7 @@ public interface ChunkSnapshot {
      * @deprecated biomes are now 3-dimensional
      */
     @NotNull
-    @Deprecated
+    @Deprecated(since = "1.15")
     Biome getBiome(int x, int z);
 
     /**
@@ -129,7 +129,7 @@ public interface ChunkSnapshot {
      * @return temperature at given coordinate
      * @deprecated biomes are now 3-dimensional
      */
-    @Deprecated
+    @Deprecated(since = "1.15")
     double getRawBiomeTemperature(int x, int z);
 
     /**

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

@@ -24,7 +24,7 @@ public enum CoalType {
      * @return A byte containing the data value of this coal type
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     public byte getData() {
         return data;
     }
@@ -37,7 +37,7 @@ public enum CoalType {
      *     it doesn't exist
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     @Nullable
     public static CoalType getByData(final byte data) {
         return BY_DATA.get(data);

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

@@ -55,7 +55,7 @@ public enum CropState {
      * @return A byte containing the data value of this growth state
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     public byte getData() {
         return data;
     }
@@ -68,7 +68,7 @@ public enum CropState {
      *     it doesn't exist
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     @Nullable
     public static CropState getByData(final byte data) {
         return BY_DATA.get(data);

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

@@ -46,7 +46,7 @@ public enum Difficulty {
      * @return An integer value of this difficulty
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     public int getValue() {
         return value;
     }
@@ -59,7 +59,7 @@ public enum Difficulty {
      *     it doesn't exist
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     @Nullable
     public static Difficulty getByValue(final int value) {
         return BY_ID.get(value);

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

@@ -98,7 +98,7 @@ public enum DyeColor {
      * @see #getDyeData()
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     public byte getWoolData() {
         return woolData;
     }
@@ -110,7 +110,7 @@ public enum DyeColor {
      * @see #getWoolData()
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     public byte getDyeData() {
         return dyeData;
     }
@@ -144,7 +144,7 @@ public enum DyeColor {
      * @see #getByDyeData(byte)
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     @Nullable
     public static DyeColor getByWoolData(final byte data) {
         int i = 0xff & data;
@@ -163,7 +163,7 @@ public enum DyeColor {
      * @see #getByWoolData(byte)
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     @Nullable
     public static DyeColor getByDyeData(final byte data) {
         int i = 0xff & data;
@@ -204,7 +204,7 @@ public enum DyeColor {
      * @return dye color
      * @deprecated legacy use only
      */
-    @Deprecated
+    @Deprecated(since = "1.13")
     @NotNull
     public static DyeColor legacyValueOf(@Nullable String name) {
         return "SILVER".equals(name) ? DyeColor.LIGHT_GRAY : DyeColor.valueOf(name);

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

@@ -27,70 +27,70 @@ public enum Effect {
      * @deprecated no longer exists
      * @see Sound#BLOCK_WOODEN_DOOR_OPEN
      */
-    @Deprecated
+    @Deprecated(since = "1.19.3")
     DOOR_TOGGLE(1006, Type.SOUND),
     /**
      * Sound of a door opening.
      * @deprecated no longer exists
      * @see Sound#BLOCK_IRON_DOOR_OPEN
      */
-    @Deprecated
+    @Deprecated(since = "1.19.3")
     IRON_DOOR_TOGGLE(1005, Type.SOUND),
     /**
      * Sound of a trapdoor opening.
      * @deprecated no longer exists
      * @see Sound#BLOCK_WOODEN_TRAPDOOR_OPEN
      */
-    @Deprecated
+    @Deprecated(since = "1.19.3")
     TRAPDOOR_TOGGLE(1007, Type.SOUND),
     /**
      * Sound of a door opening.
      * @deprecated no longer exists
      * @see Sound#BLOCK_IRON_TRAPDOOR_OPEN
      */
-    @Deprecated
+    @Deprecated(since = "1.19.3")
     IRON_TRAPDOOR_TOGGLE(1037, Type.SOUND),
     /**
      * Sound of a door opening.
      * @deprecated no longer exists
      * @see Sound#BLOCK_FENCE_GATE_OPEN
      */
-    @Deprecated
+    @Deprecated(since = "1.19.3")
     FENCE_GATE_TOGGLE(1008, Type.SOUND),
     /**
      * Sound of a door closing.
      * @deprecated no longer exists
      * @see Sound#BLOCK_WOODEN_DOOR_CLOSE
      */
-    @Deprecated
+    @Deprecated(since = "1.19.3")
     DOOR_CLOSE(1012, Type.SOUND),
     /**
      * Sound of a door closing.
      * @deprecated no longer exists
      * @see Sound#BLOCK_IRON_DOOR_CLOSE
      */
-    @Deprecated
+    @Deprecated(since = "1.19.3")
     IRON_DOOR_CLOSE(1011, Type.SOUND),
     /**
      * Sound of a trapdoor closing.
      * @deprecated no longer exists
      * @see Sound#BLOCK_WOODEN_TRAPDOOR_CLOSE
      */
-    @Deprecated
+    @Deprecated(since = "1.19.3")
     TRAPDOOR_CLOSE(1013, Type.SOUND),
     /**
      * Sound of a door closing.
      * @deprecated no longer exists
      * @see Sound#BLOCK_IRON_TRAPDOOR_CLOSE
      */
-    @Deprecated
+    @Deprecated(since = "1.19.3")
     IRON_TRAPDOOR_CLOSE(1036, Type.SOUND),
     /**
      * Sound of a door closing.
      * @deprecated no longer exists
      * @see Sound#BLOCK_FENCE_GATE_CLOSE
      */
-    @Deprecated
+    @Deprecated(since = "1.19.3")
     FENCE_GATE_CLOSE(1014, Type.SOUND),
     /**
      * Sound of fire being extinguished.
@@ -359,7 +359,7 @@ public enum Effect {
      * @return ID of this effect
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     public int getId() {
         return this.id;
     }
@@ -388,7 +388,7 @@ public enum Effect {
      * @return Effect with the given ID
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     @Nullable
     public static Effect getById(int id) {
         return BY_ID.get(id);

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

@@ -57,7 +57,7 @@ public enum EntityEffect {
      *
      * @deprecated Use {@link LivingEntity#playHurtAnimation(float)}
      */
-    @Deprecated
+    @Deprecated(since = "1.20.1")
     HURT(2, LivingEntity.class),
     /**
      * When a mob dies.
@@ -69,7 +69,7 @@ public enum EntityEffect {
      * @see #SNOWBALL_BREAK
      * @see #ENTITY_DEATH
      */
-    @Deprecated
+    @Deprecated(since = "1.12.2")
     DEATH(3, Entity.class),
     /**
      * Spawns the egg breaking particles
@@ -132,7 +132,7 @@ public enum EntityEffect {
      * @see #SHEEP_EAT_GRASS
      * @see #TNT_MINECART_IGNITE
      */
-    @Deprecated
+    @Deprecated(since = "1.12.2")
     SHEEP_EAT(10, Entity.class),
     /**
      * Plays the sheep eating grass animation
@@ -347,7 +347,7 @@ public enum EntityEffect {
      * @return The data value
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     public byte getData() {
         return data;
     }

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

@@ -18,7 +18,7 @@ public interface FeatureFlag extends Keyed {
      *
      * @deprecated not available since 1.21.2
      */
-    @Deprecated
+    @Deprecated(since = "1.21.2")
     public static final FeatureFlag BUNDLE = Bukkit.getUnsafe().getFeatureFlag(NamespacedKey.minecraft("bundle"));
 
     /**
@@ -26,7 +26,7 @@ public interface FeatureFlag extends Keyed {
      *
      * @deprecated not available since 1.20
      */
-    @Deprecated
+    @Deprecated(since = "1.20.2")
     public static final FeatureFlag UPDATE_1_20 = Bukkit.getUnsafe().getFeatureFlag(NamespacedKey.minecraft("update_1_20"));
 
     public static final FeatureFlag TRADE_REBALANCE = Bukkit.getUnsafe().getFeatureFlag(NamespacedKey.minecraft("trade_rebalance"));
@@ -36,7 +36,7 @@ public interface FeatureFlag extends Keyed {
      *
      * @deprecated not available since 1.21
      */
-    @Deprecated
+    @Deprecated(since = "1.21")
     public static final FeatureFlag UPDATE_121 = Bukkit.getUnsafe().getFeatureFlag(NamespacedKey.minecraft("update_1_21"));
 
     public static final FeatureFlag WINTER_DROP = Bukkit.getUnsafe().getFeatureFlag(NamespacedKey.minecraft("winter_drop"));

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

@@ -20,41 +20,41 @@ public abstract class GameEvent implements Keyed {
     public static final GameEvent BLOCK_DETACH = getEvent("block_detach");
     public static final GameEvent BLOCK_OPEN = getEvent("block_open");
     public static final GameEvent BLOCK_PLACE = getEvent("block_place");
-    @Deprecated
+    @Deprecated(since = "1.19")
     public static final GameEvent BLOCK_PRESS = getEvent("block_activate");
-    @Deprecated
+    @Deprecated(since = "1.19")
     public static final GameEvent BLOCK_SWITCH = getEvent("block_activate");
-    @Deprecated
+    @Deprecated(since = "1.19")
     public static final GameEvent BLOCK_UNPRESS = getEvent("block_deactivate");
-    @Deprecated
+    @Deprecated(since = "1.19")
     public static final GameEvent BLOCK_UNSWITCH = getEvent("block_deactivate");
     public static final GameEvent CONTAINER_CLOSE = getEvent("container_close");
     public static final GameEvent CONTAINER_OPEN = getEvent("container_open");
-    @Deprecated
+    @Deprecated(since = "1.20")
     public static final GameEvent DISPENSE_FAIL = getEvent("block_activate");
     public static final GameEvent DRINK = getEvent("drink");
-    @Deprecated
+    @Deprecated(since = "1.19")
     public static final GameEvent DRINKING_FINISH = getEvent("drink");
     public static final GameEvent EAT = getEvent("eat");
-    @Deprecated
+    @Deprecated(since = "1.19")
     public static final GameEvent ELYTRA_FREE_FALL = getEvent("elytra_glide");
     public static final GameEvent ELYTRA_GLIDE = getEvent("elytra_glide");
     public static final GameEvent ENTITY_DAMAGE = getEvent("entity_damage");
-    @Deprecated
+    @Deprecated(since = "1.19")
     public static final GameEvent ENTITY_DAMAGED = getEvent("entity_damage");
     public static final GameEvent ENTITY_DIE = getEvent("entity_die");
     public static final GameEvent ENTITY_DISMOUNT = getEvent("entity_dismount");
-    @Deprecated
+    @Deprecated(since = "1.19")
     public static final GameEvent ENTITY_DYING = getEvent("entity_die");
     public static final GameEvent ENTITY_INTERACT = getEvent("entity_interact");
     public static final GameEvent ENTITY_MOUNT = getEvent("entity_mount");
-    @Deprecated
+    @Deprecated(since = "1.19")
     public static final GameEvent ENTITY_KILLED = getEvent("entity_die");
     public static final GameEvent ENTITY_PLACE = getEvent("entity_place");
     public static final GameEvent ENTITY_ACTION = getEvent("entity_action");
-    @Deprecated
+    @Deprecated(since = "1.20.2")
     public static final GameEvent ENTITY_ROAR = getEvent("entity_action");
-    @Deprecated
+    @Deprecated(since = "1.20.2")
     public static final GameEvent ENTITY_SHAKE = getEvent("entity_action");
     public static final GameEvent EQUIP = getEvent("equip");
     public static final GameEvent EXPLODE = getEvent("explode");
@@ -68,33 +68,33 @@ public abstract class GameEvent implements Keyed {
     public static final GameEvent JUKEBOX_PLAY = getEvent("jukebox_play");
     public static final GameEvent JUKEBOX_STOP_PLAY = getEvent("jukebox_stop_play");
     public static final GameEvent LIGHTNING_STRIKE = getEvent("lightning_strike");
-    @Deprecated
+    @Deprecated(since = "1.19")
     public static final GameEvent MOB_INTERACT = getEvent("entity_interact");
     public static final GameEvent NOTE_BLOCK_PLAY = getEvent("note_block_play");
-    @Deprecated
+    @Deprecated(since = "1.20")
     public static final GameEvent PISTON_CONTRACT = getEvent("block_deactivate");
-    @Deprecated
+    @Deprecated(since = "1.20")
     public static final GameEvent PISTON_EXTEND = getEvent("block_activate");
     public static final GameEvent PRIME_FUSE = getEvent("prime_fuse");
     public static final GameEvent PROJECTILE_LAND = getEvent("projectile_land");
     public static final GameEvent PROJECTILE_SHOOT = getEvent("projectile_shoot");
-    @Deprecated
+    @Deprecated(since = "1.19")
     public static final GameEvent RAVAGER_ROAR = getEvent("entity_action");
-    @Deprecated
+    @Deprecated(since = "1.19")
     public static final GameEvent RING_BELL = getEvent("block_change");
     public static final GameEvent SCULK_SENSOR_TENDRILS_CLICKING = getEvent("sculk_sensor_tendrils_clicking");
     public static final GameEvent SHEAR = getEvent("shear");
     public static final GameEvent SHRIEK = getEvent("shriek");
-    @Deprecated
+    @Deprecated(since = "1.19")
     public static final GameEvent SHULKER_CLOSE = getEvent("container_close");
-    @Deprecated
+    @Deprecated(since = "1.19")
     public static final GameEvent SHULKER_OPEN = getEvent("container_open");
     public static final GameEvent SPLASH = getEvent("splash");
     public static final GameEvent STEP = getEvent("step");
     public static final GameEvent SWIM = getEvent("swim");
     public static final GameEvent TELEPORT = getEvent("teleport");
     public static final GameEvent UNEQUIP = getEvent("unequip");
-    @Deprecated
+    @Deprecated(since = "1.19")
     public static final GameEvent WOLF_SHAKING = getEvent("entity_action");
     public static final GameEvent RESONATE_1 = getEvent("resonate_1");
     public static final GameEvent RESONATE_2 = getEvent("resonate_2");
@@ -120,7 +120,7 @@ public abstract class GameEvent implements Keyed {
      * @deprecated Use {@link Registry#get(NamespacedKey)} instead.
      */
     @Nullable
-    @Deprecated
+    @Deprecated(since = "1.20.1")
     public static GameEvent getByKey(@NotNull NamespacedKey namespacedKey) {
         return Registry.GAME_EVENT.get(namespacedKey);
     }
@@ -132,7 +132,7 @@ public abstract class GameEvent implements Keyed {
      * @deprecated use {@link Registry#iterator()}.
      */
     @NotNull
-    @Deprecated
+    @Deprecated(since = "1.20.1")
     public static Collection<GameEvent> values() {
         return Collections.unmodifiableCollection(Lists.newArrayList(Registry.GAME_EVENT));
     }

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

@@ -46,7 +46,7 @@ public enum GameMode {
      * @return An integer value of this gamemode
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     public int getValue() {
         return value;
     }
@@ -59,7 +59,7 @@ public enum GameMode {
      *     it doesn't exist
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     @Nullable
     public static GameMode getByValue(final int value) {
         return BY_ID.get(value);

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

@@ -35,7 +35,7 @@ public enum GrassSpecies {
      * @return A byte containing the data value of this grass species
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     public byte getData() {
         return data;
     }
@@ -48,7 +48,7 @@ public enum GrassSpecies {
      *     if it doesn't exist
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     @Nullable
     public static GrassSpecies getByData(final byte data) {
         return BY_DATA.get(data);

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

@@ -132,7 +132,7 @@ public enum Instrument {
      * @return The type ID of this instrument.
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     public byte getType() {
         return this.type;
     }
@@ -144,7 +144,7 @@ public enum Instrument {
      * @return The instrument
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     @Nullable
     public static Instrument getByType(final byte type) {
         return BY_DATA.get(type);

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

@@ -25,7 +25,7 @@ public abstract class MusicInstrument implements Keyed {
      * @deprecated Use {@link Registry#get(NamespacedKey)} instead.
      */
     @Nullable
-    @Deprecated
+    @Deprecated(since = "1.20.1")
     public static MusicInstrument getByKey(@NotNull NamespacedKey namespacedKey) {
         return Registry.INSTRUMENT.get(namespacedKey);
     }
@@ -37,7 +37,7 @@ public abstract class MusicInstrument implements Keyed {
      * @deprecated use {@link Registry#iterator()}.
      */
     @NotNull
-    @Deprecated
+    @Deprecated(since = "1.20.1")
     public static Collection<MusicInstrument> values() {
         return Collections.unmodifiableCollection(Lists.newArrayList(Registry.INSTRUMENT));
     }

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

@@ -161,7 +161,7 @@ public final class NamespacedKey {
      */
     @ApiStatus.Internal
     @NotNull
-    @Deprecated
+    @Deprecated(since = "1.20.5")
     public static NamespacedKey randomKey() {
         return new NamespacedKey(BUKKIT, UUID.randomUUID().toString());
     }

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

@@ -41,7 +41,7 @@ public class Note {
          * @return the not sharped id of this tone.
          * @deprecated Magic value
          */
-        @Deprecated
+        @Deprecated(since = "1.6.2")
         public byte getId() {
             return getId(false);
         }
@@ -55,7 +55,7 @@ public class Note {
          * @return the id of this tone.
          * @deprecated Magic value
          */
-        @Deprecated
+        @Deprecated(since = "1.6.2")
         public byte getId(boolean sharped) {
             byte id = (byte) (sharped && sharpable ? this.id + 1 : this.id);
 
@@ -80,7 +80,7 @@ public class Note {
          *     semitone have the id.
          * @deprecated Magic value
          */
-        @Deprecated
+        @Deprecated(since = "1.6.2")
         public boolean isSharped(byte id) {
             if (id == getId(false)) {
                 return false;
@@ -99,7 +99,7 @@ public class Note {
          * @return the tone to id.
          * @deprecated Magic value
          */
-        @Deprecated
+        @Deprecated(since = "1.6.2")
         @Nullable
         public static Tone getById(byte id) {
             return BY_DATA.get(id);
@@ -224,7 +224,7 @@ public class Note {
      * @return the internal id of this note.
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     public byte getId() {
         return note;
     }

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

@@ -177,7 +177,7 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
      * respawn anchors.
      */
     @Nullable
-    @Deprecated
+    @Deprecated(since = "1.20.4")
     public Location getBedSpawnLocation();
 
     /**

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

@@ -25,7 +25,7 @@ public enum SandstoneType {
      * @return A byte containing the data value of this sandstone type
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     public byte getData() {
         return data;
     }
@@ -38,7 +38,7 @@ public enum SandstoneType {
      *     if it doesn't exist
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     @Nullable
     public static SandstoneType getByData(final byte data) {
         return BY_DATA.get(data);

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

@@ -406,7 +406,7 @@ public interface Server extends PluginMessageRecipient {
      * @return the default ticks per animal spawns value
      * @deprecated Deprecated in favor of {@link #getTicksPerSpawns(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public int getTicksPerAnimalSpawns();
 
     /**
@@ -429,7 +429,7 @@ public interface Server extends PluginMessageRecipient {
      * @return the default ticks per monsters spawn value
      * @deprecated Deprecated in favor of {@link #getTicksPerSpawns(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public int getTicksPerMonsterSpawns();
 
     /**
@@ -451,7 +451,7 @@ public interface Server extends PluginMessageRecipient {
      * @return the default ticks per water mobs spawn value
      * @deprecated Deprecated in favor of {@link #getTicksPerSpawns(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public int getTicksPerWaterSpawns();
 
     /**
@@ -473,7 +473,7 @@ public interface Server extends PluginMessageRecipient {
      * @return the default ticks per water ambient mobs spawn value
      * @deprecated Deprecated in favor of {@link #getTicksPerSpawns(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public int getTicksPerWaterAmbientSpawns();
 
     /**
@@ -495,7 +495,7 @@ public interface Server extends PluginMessageRecipient {
      * @return the default ticks per water underground creature spawn value
      * @deprecated Deprecated in favor of {@link #getTicksPerSpawns(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public int getTicksPerWaterUndergroundCreatureSpawns();
 
     /**
@@ -517,7 +517,7 @@ public interface Server extends PluginMessageRecipient {
      * @return the default ticks per ambient mobs spawn value
      * @deprecated Deprecated in favor of {@link #getTicksPerSpawns(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public int getTicksPerAmbientSpawns();
 
     /**
@@ -689,7 +689,7 @@ public interface Server extends PluginMessageRecipient {
      * @return a map view if it exists, or null otherwise
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     @Nullable
     public MapView getMap(int id);
 
@@ -993,7 +993,7 @@ public interface Server extends PluginMessageRecipient {
      * @return true if the server should send a preview, false otherwise
      * @deprecated chat previews have been removed
      */
-    @Deprecated
+    @Deprecated(since = "1.19.3")
     public boolean shouldSendChatPreviews();
 
     /**
@@ -1072,7 +1072,7 @@ public interface Server extends PluginMessageRecipient {
      * @deprecated Persistent storage of users should be by UUID as names are no longer
      *             unique past a single session.
      */
-    @Deprecated
+    @Deprecated(since = "1.7.5")
     @NotNull
     public OfflinePlayer getOfflinePlayer(@NotNull String name);
 
@@ -1137,7 +1137,7 @@ public interface Server extends PluginMessageRecipient {
      *
      * @deprecated see {@link #banIP(InetAddress)}
      */
-    @Deprecated
+    @Deprecated(since = "1.20.1")
     public void banIP(@NotNull String address);
 
     /**
@@ -1147,7 +1147,7 @@ public interface Server extends PluginMessageRecipient {
      *
      * @deprecated see {@link #unbanIP(InetAddress)}
      */
-    @Deprecated
+    @Deprecated(since = "1.20.1")
     public void unbanIP(@NotNull String address);
 
     /**
@@ -1350,7 +1350,7 @@ public interface Server extends PluginMessageRecipient {
      * @return the monster spawn limit
      * @deprecated Deprecated in favor of {@link #getSpawnLimit(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     int getMonsterSpawnLimit();
 
     /**
@@ -1360,7 +1360,7 @@ public interface Server extends PluginMessageRecipient {
      * @return the animal spawn limit
      * @deprecated Deprecated in favor of {@link #getSpawnLimit(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     int getAnimalSpawnLimit();
 
     /**
@@ -1370,7 +1370,7 @@ public interface Server extends PluginMessageRecipient {
      * @return the water animal spawn limit
      * @deprecated Deprecated in favor of {@link #getSpawnLimit(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     int getWaterAnimalSpawnLimit();
 
     /**
@@ -1380,7 +1380,7 @@ public interface Server extends PluginMessageRecipient {
      * @return the water ambient spawn limit
      * @deprecated Deprecated in favor of {@link #getSpawnLimit(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     int getWaterAmbientSpawnLimit();
 
     /**
@@ -1389,7 +1389,7 @@ public interface Server extends PluginMessageRecipient {
      * @return the water underground creature limit
      * @deprecated Deprecated in favor of {@link #getSpawnLimit(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     int getWaterUndergroundCreatureSpawnLimit();
 
     /**
@@ -1399,7 +1399,7 @@ public interface Server extends PluginMessageRecipient {
      * @return the ambient spawn limit
      * @deprecated Deprecated in favor of {@link #getSpawnLimit(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     int getAmbientSpawnLimit();
 
     /**
@@ -1849,7 +1849,7 @@ public interface Server extends PluginMessageRecipient {
      * @return the unsafe values instance
      * @see UnsafeValues
      */
-    @Deprecated
+    @Deprecated(since = "1.7.2")
     @NotNull
     UnsafeValues getUnsafe();
 }

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

@@ -4,7 +4,7 @@ package org.bukkit;
  * Represents the different types of skulls.
  * @deprecated check {@link Material} instead
  */
-@Deprecated
+@Deprecated(since = "1.13")
 public enum SkullType {
     SKELETON,
     WITHER,

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

@@ -23,7 +23,7 @@ import org.jetbrains.annotations.Nullable;
  * {@link org.bukkit.generator.structure.StructureType} instead.
  */
 // Order is retrieved from WorldGenFactory
-@Deprecated
+@Deprecated(since = "1.19")
 public final class StructureType implements Keyed {
 
     private static final Map<String, StructureType> structureTypeMap = new HashMap<>();

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

@@ -52,7 +52,7 @@ public interface Tag<T extends Keyed> extends Keyed {
     /**
      * @deprecated {@link #WOOL_CARPETS}.
      */
-    @Deprecated
+    @Deprecated(since = "1.19")
     Tag<Material> CARPETS = WOOL_CARPETS;
     /**
      * Vanilla block tag representing all wooden doors.
@@ -828,7 +828,7 @@ public interface Tag<T extends Keyed> extends Keyed {
      *
      * @deprecated use {@link #ITEMS_PIGLIN_FOOD}
      */
-    @Deprecated
+    @Deprecated(since = "1.20.5")
     Tag<Material> PIGLIN_FOOD = ITEMS_PIGLIN_FOOD;
     /**
      * Vanilla item tag representing all fox food.
@@ -839,7 +839,7 @@ public interface Tag<T extends Keyed> extends Keyed {
      *
      * @deprecated use {@link #ITEMS_FOX_FOOD}
      */
-    @Deprecated
+    @Deprecated(since = "1.20.5")
     Tag<Material> FOX_FOOD = ITEMS_FOX_FOOD;
     /**
      * Vanilla item tag representing all cow food.
@@ -1137,7 +1137,7 @@ public interface Tag<T extends Keyed> extends Keyed {
      * this constant now acts as a reference to {@link #ITEMS_BREAKS_DECORATED_POTS} which largely shares
      * the same contents of the old "minecraft:tools" tag.
      */
-    @Deprecated(forRemoval = true)
+    @Deprecated(since = "1.20.6", forRemoval = true)
     Tag<Material> ITEMS_TOOLS = ITEMS_BREAKS_DECORATED_POTS;
     /**
      * Vanilla item tag representing all seeds plantable by villagers.
@@ -1253,7 +1253,7 @@ public interface Tag<T extends Keyed> extends Keyed {
      *
      * @deprecated use {@link #ITEMS_AXOLOTL_FOOD}
      */
-    @Deprecated
+    @Deprecated(since = "1.20.5")
     Tag<Material> AXOLOTL_TEMPT_ITEMS = ITEMS_AXOLOTL_FOOD;
     /**
      * Vanilla item tag representing all items which are preferred for
@@ -1340,7 +1340,7 @@ public interface Tag<T extends Keyed> extends Keyed {
      * Vanilla tag representing entities which deflect arrows.
      * @deprecated use {@link #ENTITY_TYPES_DEFLECTS_PROJECTILES}
      */
-    @Deprecated
+    @Deprecated(since = "1.20.5")
     Tag<EntityType> ENTITY_TYPES_DEFLECTS_ARROWS = ENTITY_TYPES_DEFLECTS_PROJECTILES;
     /**
      * Vanilla tag representing entities which can turn in boats.

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

@@ -9,7 +9,7 @@ import org.jetbrains.annotations.Nullable;
  *
  * @deprecated Deprecated, see usage methods for replacement(s)
  */
-@Deprecated
+@Deprecated(since = "1.19")
 public enum TreeSpecies {
 
     /**
@@ -51,7 +51,7 @@ public enum TreeSpecies {
      * @return A byte containing the data value of this tree species
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     public byte getData() {
         return data;
     }
@@ -64,7 +64,7 @@ public enum TreeSpecies {
      *     if it doesn't exist
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     @Nullable
     public static TreeSpecies getByData(final byte data) {
         return BY_DATA.get(data);

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

@@ -15,7 +15,7 @@ import org.jetbrains.annotations.ApiStatus;
  */
 @Retention(RetentionPolicy.CLASS)
 @ApiStatus.Internal
-@Deprecated
+@Deprecated(since = "1.13.2")
 public @interface UndefinedNullability {
 
     /**

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

@@ -29,7 +29,7 @@ import org.jetbrains.annotations.Nullable;
  * may be poorly named, throw exceptions, have misleading parameters, or any
  * other bad programming practice.
  */
-@Deprecated
+@Deprecated(since = "1.7.2")
 public interface UnsafeValues {
 
     Material toLegacy(Material material);

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

@@ -209,7 +209,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      *     As of the current Minecraft version chunks are now strictly managed and
      *     will not be loaded for more than 1 tick unless they are in use.
      */
-    @Deprecated
+    @Deprecated(since = "1.14")
     public boolean isChunkInUse(int x, int z);
 
     /**
@@ -299,7 +299,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * chunk as before as terrain decoration may be spread across chunks. Use of
      * this method should be avoided as it is known to produce buggy results.
      */
-    @Deprecated
+    @Deprecated(since = "1.13")
     public boolean regenerateChunk(int x, int z);
 
     /**
@@ -311,7 +311,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      *
      * @deprecated This method is not guaranteed to work suitably across all client implementations.
      */
-    @Deprecated
+    @Deprecated(since = "1.8")
     public boolean refreshChunk(int x, int z);
 
     /**
@@ -563,7 +563,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @see #generateTree(org.bukkit.Location, java.util.Random, org.bukkit.TreeType, java.util.function.Consumer)
      * @deprecated this method does not handle tile entities (bee nests)
      */
-    @Deprecated
+    @Deprecated(since = "1.17.1")
     public boolean generateTree(@NotNull Location loc, @NotNull TreeType type, @NotNull BlockChangeDelegate delegate);
 
     /**
@@ -609,7 +609,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @return A List of all Entities currently residing in this world that
      *     match the given class/interface
      */
-    @Deprecated
+    @Deprecated(since = "1.1")
     @NotNull
     public <T extends Entity> Collection<T> getEntitiesByClass(@NotNull Class<T>... classes);
 
@@ -1314,7 +1314,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      *     Material} are null or {@link Material} is not a block
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.7.5")
     @NotNull
     public FallingBlock spawnFallingBlock(@NotNull Location location, @NotNull Material material, byte data) throws IllegalArgumentException;
 
@@ -1413,7 +1413,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @deprecated biomes are now 3-dimensional
      */
     @NotNull
-    @Deprecated
+    @Deprecated(since = "1.15")
     Biome getBiome(int x, int z);
 
     /**
@@ -1424,7 +1424,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @param bio new Biome type for this block
      * @deprecated biomes are now 3-dimensional
      */
-    @Deprecated
+    @Deprecated(since = "1.15")
     void setBiome(int x, int z, @NotNull Biome bio);
 
     /**
@@ -1441,7 +1441,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @return Temperature of the requested block
      * @deprecated biomes are now 3-dimensional
      */
-    @Deprecated
+    @Deprecated(since = "1.15")
     public double getTemperature(int x, int z);
 
     /**
@@ -1471,7 +1471,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @return Humidity of the requested block
      * @deprecated biomes are now 3-dimensional
      */
-    @Deprecated
+    @Deprecated(since = "1.15")
     public double getHumidity(int x, int z);
 
     /**
@@ -1585,7 +1585,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @return true if the world's spawn area will be kept loaded into memory.
      * @deprecated use {@link GameRule#SPAWN_CHUNK_RADIUS} for finer control
      */
-    @Deprecated
+    @Deprecated(since = "1.20.5")
     public boolean getKeepSpawnInMemory();
 
     /**
@@ -1596,7 +1596,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      *     loaded into memory.
      * @deprecated use {@link GameRule#SPAWN_CHUNK_RADIUS} for finer control
      */
-    @Deprecated
+    @Deprecated(since = "1.20.5")
     public void setKeepSpawnInMemory(boolean keepLoaded);
 
     /**
@@ -1660,7 +1660,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * this method to always return the correct value.
      */
     @Nullable
-    @Deprecated
+    @Deprecated(since = "1.16.1")
     public WorldType getWorldType();
 
     /**
@@ -1713,7 +1713,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @return The world's ticks per animal spawns value
      * @deprecated Deprecated in favor of {@link #getTicksPerSpawns(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public long getTicksPerAnimalSpawns();
 
     /**
@@ -1742,7 +1742,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      *     to set the world to
      * @deprecated Deprecated in favor of {@link #setTicksPerSpawns(SpawnCategory, int)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public void setTicksPerAnimalSpawns(int ticksPerAnimalSpawns);
 
     /**
@@ -1770,7 +1770,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @return The world's ticks per monster spawns value
      * @deprecated Deprecated in favor of {@link #getTicksPerSpawns(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public long getTicksPerMonsterSpawns();
 
     /**
@@ -1799,7 +1799,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      *     want to set the world to
      * @deprecated Deprecated in favor of {@link #setTicksPerSpawns(SpawnCategory, int)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public void setTicksPerMonsterSpawns(int ticksPerMonsterSpawns);
 
     /**
@@ -1825,7 +1825,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @return The world's ticks per water mob spawns value
      * @deprecated Deprecated in favor of {@link #getTicksPerSpawns(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public long getTicksPerWaterSpawns();
 
     /**
@@ -1852,7 +1852,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      *     want to set the world to
      * @deprecated Deprecated in favor of {@link #setTicksPerSpawns(SpawnCategory, int)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public void setTicksPerWaterSpawns(int ticksPerWaterSpawns);
 
     /**
@@ -1874,7 +1874,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @return the default ticks per water ambient mobs spawn value
      * @deprecated Deprecated in favor of {@link #getTicksPerSpawns(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public long getTicksPerWaterAmbientSpawns();
 
     /**
@@ -1901,7 +1901,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      *     want to set the world to
      * @deprecated Deprecated in favor of {@link #setTicksPerSpawns(SpawnCategory, int)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public void setTicksPerWaterAmbientSpawns(int ticksPerAmbientSpawns);
 
     /**
@@ -1923,7 +1923,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @return the default ticks per water underground creature spawn value
      * @deprecated Deprecated in favor of {@link #getTicksPerSpawns(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public long getTicksPerWaterUndergroundCreatureSpawns();
 
     /**
@@ -1950,7 +1950,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      *     want to set the world to
      * @deprecated Deprecated in favor of {@link #setTicksPerSpawns(SpawnCategory, int)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public void setTicksPerWaterUndergroundCreatureSpawns(int ticksPerWaterUndergroundCreatureSpawns);
 
     /**
@@ -1976,7 +1976,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @return the default ticks per ambient mobs spawn value
      * @deprecated Deprecated in favor of {@link #getTicksPerSpawns(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public long getTicksPerAmbientSpawns();
 
     /**
@@ -2003,7 +2003,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      *     want to set the world to
      * @deprecated Deprecated in favor of {@link #setTicksPerSpawns(SpawnCategory, int)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public void setTicksPerAmbientSpawns(int ticksPerAmbientSpawns);
 
     /**
@@ -2064,7 +2064,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @return The monster spawn limit
      * @deprecated Deprecated in favor of {@link #getSpawnLimit(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     int getMonsterSpawnLimit();
 
     /**
@@ -2077,7 +2077,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @param limit the new mob limit
      * @deprecated Deprecated in favor of {@link #setSpawnLimit(SpawnCategory, int)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     void setMonsterSpawnLimit(int limit);
 
     /**
@@ -2087,7 +2087,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @return The animal spawn limit
      * @deprecated Deprecated in favor of {@link #getSpawnLimit(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     int getAnimalSpawnLimit();
 
     /**
@@ -2100,7 +2100,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @param limit the new mob limit
      * @deprecated Deprecated in favor of {@link #getSpawnLimit(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     void setAnimalSpawnLimit(int limit);
 
     /**
@@ -2110,7 +2110,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @return The water animal spawn limit
      * @deprecated Deprecated in favor of {@link #getSpawnLimit(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     int getWaterAnimalSpawnLimit();
 
     /**
@@ -2123,7 +2123,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @param limit the new mob limit
      * @deprecated Deprecated in favor of {@link #setSpawnLimit(SpawnCategory, int)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     void setWaterAnimalSpawnLimit(int limit);
 
     /**
@@ -2133,7 +2133,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @return The water underground creature spawn limit
      * @deprecated Deprecated in favor of {@link #getSpawnLimit(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     int getWaterUndergroundCreatureSpawnLimit();
 
     /**
@@ -2146,7 +2146,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @param limit the new mob limit
      * @deprecated Deprecated in favor of {@link #setSpawnLimit(SpawnCategory, int)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     void setWaterUndergroundCreatureSpawnLimit(int limit);
 
     /**
@@ -2156,7 +2156,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @return the water ambient spawn limit
      * @deprecated Deprecated in favor of {@link #getSpawnLimit(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     int getWaterAmbientSpawnLimit();
 
     /**
@@ -2169,7 +2169,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @param limit the new mob limit
      * @deprecated Deprecated in favor of {@link #setSpawnLimit(SpawnCategory, int)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     void setWaterAmbientSpawnLimit(int limit);
 
     /**
@@ -2179,7 +2179,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @return The ambient spawn limit
      * @deprecated Deprecated in favor of {@link #getSpawnLimit(SpawnCategory)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     int getAmbientSpawnLimit();
 
     /**
@@ -2192,7 +2192,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @param limit the new mob limit
      * @deprecated Deprecated in favor of {@link #setSpawnLimit(SpawnCategory, int)}
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     void setAmbientSpawnLimit(int limit);
 
     /**
@@ -2413,7 +2413,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @return String value of rule
      * @deprecated use {@link #getGameRuleValue(GameRule)} instead
      */
-    @Deprecated
+    @Deprecated(since = "1.13")
     @Contract("null -> null; !null -> !null")
     @Nullable
     public String getGameRuleValue(@Nullable String rule);
@@ -2431,7 +2431,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @return True if rule was set
      * @deprecated use {@link #setGameRule(GameRule, Object)} instead.
      */
-    @Deprecated
+    @Deprecated(since = "1.13")
     public boolean setGameRuleValue(@NotNull String rule, @NotNull String value);
 
     /**
@@ -2759,7 +2759,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * instead.
      */
     @Nullable
-    @Deprecated
+    @Deprecated(since = "1.19")
     public Location locateNearestStructure(@NotNull Location origin, @NotNull org.bukkit.StructureType structureType, int radius, boolean findUnexplored);
 
     /**
@@ -2984,7 +2984,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
          * @return dimension ID
          * @deprecated Magic value
          */
-        @Deprecated
+        @Deprecated(since = "1.6.2")
         public int getId() {
             return id;
         }
@@ -2996,7 +2996,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
          * @return The environment
          * @deprecated Magic value
          */
-        @Deprecated
+        @Deprecated(since = "1.6.2")
         @Nullable
         public static Environment getEnvironment(int id) {
             return lookup.get(id);

paper-api/src/main/java/org/bukkit/attribute/AttributeModifier.java

@@ -123,7 +123,7 @@ public class AttributeModifier implements ConfigurationSerializable, Keyed {
      * @deprecated use {@link #getSlotGroup()}
      */
     @Nullable
-    @Deprecated
+    @Deprecated(since = "1.20.5")
     public EquipmentSlot getSlot() {
         return slot == EquipmentSlotGroup.ANY ? null : slot.getExample();
     }

paper-api/src/main/java/org/bukkit/block/Bed.java

@@ -6,5 +6,5 @@ import org.bukkit.material.Colorable;
  * Represents a captured state of a bed.
  * @deprecated does not provide useful information beyond the material itself
  */
-@Deprecated
+@Deprecated(since = "1.13")
 public interface Bed extends TileState, Colorable { }

paper-api/src/main/java/org/bukkit/block/Block.java

@@ -40,7 +40,7 @@ public interface Block extends Metadatable, Translatable {
      * @return block specific metadata
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     byte getData();
 
     /**

paper-api/src/main/java/org/bukkit/block/BlockState.java

@@ -221,14 +221,14 @@ public interface BlockState extends Metadatable {
      * @return The data as a raw byte.
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     public byte getRawData();
 
     /**
      * @param data The new data value for the block.
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     public void setRawData(byte data);
 
     /**

paper-api/src/main/java/org/bukkit/block/BlockType.java

@@ -3634,6 +3634,6 @@ public interface BlockType extends Keyed, Translatable {
      * @deprecated only for internal use
      */
     @Nullable
-    @Deprecated
+    @Deprecated(since = "1.20.6")
     Material asMaterial();
 }

paper-api/src/main/java/org/bukkit/block/CreatureSpawner.java

@@ -15,7 +15,7 @@ public interface CreatureSpawner extends TileState, Spawner {
      * @deprecated magic value, use
      * {@link #setSpawnedType(org.bukkit.entity.EntityType)}.
      */
-    @Deprecated
+    @Deprecated(since = "1.11.2")
     public void setCreatureTypeByName(@Nullable String creatureType);
 
     /**
@@ -24,7 +24,7 @@ public interface CreatureSpawner extends TileState, Spawner {
      * @return The creature type's name if is set.
      * @deprecated magic value, use {@link #getSpawnedType()}.
      */
-    @Deprecated
+    @Deprecated(since = "1.11.2")
     @Nullable
     public String getCreatureTypeName();
 }

paper-api/src/main/java/org/bukkit/block/DecoratedPot.java

@@ -51,7 +51,7 @@ public interface DecoratedPot extends TileState, BlockInventoryHolder {
      * @return the sherds
      * @deprecated in favor of {@link #getSherds()}
      */
-    @Deprecated
+    @Deprecated(since = "1.20.1")
     @NotNull
     public List<Material> getShards();
 

paper-api/src/main/java/org/bukkit/block/Lockable.java

@@ -26,7 +26,7 @@ public interface Lockable {
      * @deprecated locks are not necessarily pure strings
      */
     @NotNull
-    @Deprecated
+    @Deprecated(since = "1.21.2")
     String getLock();
 
     /**
@@ -36,7 +36,7 @@ public interface Lockable {
      * @param key the key required to access the container.
      * @deprecated locks are not necessarily pure strings
      */
-    @Deprecated
+    @Deprecated(since = "1.21.2")
     void setLock(@Nullable String key);
 
     /**

paper-api/src/main/java/org/bukkit/block/PistonMoveReaction.java

@@ -50,7 +50,7 @@ public enum PistonMoveReaction {
      * @return The ID of the move reaction
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     public int getId() {
         return this.id;
     }
@@ -60,7 +60,7 @@ public enum PistonMoveReaction {
      * @return The move reaction with that ID
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     @Nullable
     public static PistonMoveReaction getById(int id) {
         return byId.get(id);

paper-api/src/main/java/org/bukkit/block/Sign.java

@@ -19,7 +19,7 @@ public interface Sign extends TileState, Colorable {
      * @return Array of Strings containing each line of text
      * @deprecated  A sign may have multiple writable sides now. Use {@link Sign#getSide(Side)} and {@link SignSide#getLines()}.
      */
-    @Deprecated
+    @Deprecated(since = "1.20")
     @NotNull
     public String[] getLines();
 
@@ -33,7 +33,7 @@ public interface Sign extends TileState, Colorable {
      * @throws IndexOutOfBoundsException Thrown when the line does not exist
      * @deprecated A sign may have multiple writable sides now. Use {@link #getSide(Side)} and {@link SignSide#getLine(int)}.
      */
-    @Deprecated
+    @Deprecated(since = "1.20")
     @NotNull
     public String getLine(int index) throws IndexOutOfBoundsException;
 
@@ -48,7 +48,7 @@ public interface Sign extends TileState, Colorable {
      * @throws IndexOutOfBoundsException If the index is out of the range 0..3
      * @deprecated A sign may have multiple writable sides now. Use {@link #getSide(Side)} and {@link SignSide#setLine(int, String)}.
      */
-    @Deprecated
+    @Deprecated(since = "1.20")
     public void setLine(int index, @NotNull String line) throws IndexOutOfBoundsException;
 
     /**
@@ -57,7 +57,7 @@ public interface Sign extends TileState, Colorable {
      * @return if this sign is currently editable
      * @deprecated use {@link #isWaxed()} instead
      */
-    @Deprecated
+    @Deprecated(since = "1.20.1")
     public boolean isEditable();
 
     /**
@@ -66,7 +66,7 @@ public interface Sign extends TileState, Colorable {
      * @param editable if this sign is currently editable
      * @deprecated use {@link #setWaxed(boolean)} instead
      */
-    @Deprecated
+    @Deprecated(since = "1.20.1")
     public void setEditable(boolean editable);
 
     /**
@@ -91,7 +91,7 @@ public interface Sign extends TileState, Colorable {
      * @return if this sign has glowing text
      * @deprecated A sign may have multiple writable sides now. Use {@link #getSide(Side)} and {@link SignSide#isGlowingText()}.
      */
-    @Deprecated
+    @Deprecated(since = "1.20")
     public boolean isGlowingText();
 
     /**
@@ -100,7 +100,7 @@ public interface Sign extends TileState, Colorable {
      * @param glowing if this sign has glowing text
      * @deprecated A sign may have multiple writable sides now. Use {@link #getSide(Side)} and {@link SignSide#setGlowingText(boolean)}.
      */
-    @Deprecated
+    @Deprecated(since = "1.20")
     public void setGlowingText(boolean glowing);
 
     /**
@@ -110,7 +110,7 @@ public interface Sign extends TileState, Colorable {
      */
     @NotNull
     @Override
-    @Deprecated
+    @Deprecated(since = "1.20")
     public DyeColor getColor();
 
     /**
@@ -119,7 +119,7 @@ public interface Sign extends TileState, Colorable {
      * @deprecated A sign may have multiple writable sides now. Use {@link #getSide(Side)} and {@link SignSide#setColor(org.bukkit.DyeColor)}.
      */
     @Override
-    @Deprecated
+    @Deprecated(since = "1.20")
     public void setColor(@NotNull DyeColor color);
 
     /**

paper-api/src/main/java/org/bukkit/block/Skull.java

@@ -28,7 +28,7 @@ public interface Skull extends TileState {
      * @return the owner of the skull or null if the skull does not have an owner
      * @deprecated See {@link #getOwningPlayer()}.
      */
-    @Deprecated
+    @Deprecated(since = "1.9.4")
     @Nullable
     public String getOwner();
 
@@ -42,7 +42,7 @@ public interface Skull extends TileState {
      * @return true if the owner was successfully set
      * @deprecated see {@link #setOwningPlayer(org.bukkit.OfflinePlayer)}.
      */
-    @Deprecated
+    @Deprecated(since = "1.94")
     @Contract("null -> false")
     public boolean setOwner(@Nullable String name);
 
@@ -115,7 +115,7 @@ public interface Skull extends TileState {
      * @return the rotation of the skull
      * @deprecated use {@link BlockData}
      */
-    @Deprecated
+    @Deprecated(since = "1.13")
     @NotNull
     public BlockFace getRotation();
 
@@ -126,7 +126,7 @@ public interface Skull extends TileState {
      * @param rotation the rotation of the skull
      * @deprecated use {@link BlockData}
      */
-    @Deprecated
+    @Deprecated(since = "1.13")
     public void setRotation(@NotNull BlockFace rotation);
 
     /**
@@ -135,7 +135,7 @@ public interface Skull extends TileState {
      * @return the type of skull
      * @deprecated check {@link Material} instead
      */
-    @Deprecated
+    @Deprecated(since = "1.13")
     @NotNull
     public SkullType getSkullType();
 
@@ -145,7 +145,7 @@ public interface Skull extends TileState {
      * @param skullType the type of skull
      * @deprecated check {@link Material} instead
      */
-    @Deprecated
+    @Deprecated(since = "1.13")
     @Contract("_ -> fail")
     public void setSkullType(SkullType skullType);
 }

paper-api/src/main/java/org/bukkit/block/SuspiciousSand.java

@@ -5,6 +5,6 @@ package org.bukkit.block;
  *
  * @see BrushableBlock
  */
-@Deprecated
+@Deprecated(since = "1.20")
 public interface SuspiciousSand extends BrushableBlock {
 }

paper-api/src/main/java/org/bukkit/block/banner/PatternType.java

@@ -69,7 +69,7 @@ public interface PatternType extends OldEnum<PatternType>, Keyed {
      * @deprecated magic value
      */
     @NotNull
-    @Deprecated(forRemoval = true)
+    @Deprecated(since = "1.20.4", forRemoval = true)
     public String getIdentifier();
 
     /**
@@ -83,7 +83,7 @@ public interface PatternType extends OldEnum<PatternType>, Keyed {
      */
     @Contract("null -> null")
     @Nullable
-    @Deprecated(forRemoval = true)
+    @Deprecated(since = "1.20.4", forRemoval = true)
     public static PatternType getByIdentifier(@Nullable String identifier) {
         if (identifier == null) {
             return null;

paper-api/src/main/java/org/bukkit/block/data/type/Switch.java

@@ -14,7 +14,7 @@ public interface Switch extends Directional, FaceAttachable, Powerable {
      * @deprecated use {@link #getAttachedFace()}
      */
     @NotNull
-    @Deprecated
+    @Deprecated(since = "1.15.2")
     Face getFace();
 
     /**
@@ -23,7 +23,7 @@ public interface Switch extends Directional, FaceAttachable, Powerable {
      * @param face the new 'face' value
      * @deprecated use {@link #getAttachedFace()}
      */
-    @Deprecated
+    @Deprecated(since = "1.15.2")
     void setFace(@NotNull Face face);
 
     /**
@@ -31,7 +31,7 @@ public interface Switch extends Directional, FaceAttachable, Powerable {
      *
      * @deprecated use {@link AttachedFace}
      */
-    @Deprecated
+    @Deprecated(since = "1.15.2")
     public enum Face {
         /**
          * The switch is mounted to the floor and pointing upwards.

paper-api/src/main/java/org/bukkit/block/data/type/Vault.java

@@ -24,7 +24,7 @@ public interface Vault extends Directional {
      * @return the 'vault_state' value
      * @deprecated see {@link #getVaultState()}
      */
-    @Deprecated(forRemoval = true)
+    @Deprecated(since = "1.21.3", forRemoval = true)
     @NotNull
     State getTrialSpawnerState();
 
@@ -41,7 +41,7 @@ public interface Vault extends Directional {
      * @param state the new 'vault_state' value
      * @deprecated see {@link #setVaultState(State)}
      */
-    @Deprecated(forRemoval = true)
+    @Deprecated(since = "1.21.3", forRemoval = true)
     void setTrialSpawnerState(@NotNull State state);
 
     /**

paper-api/src/main/java/org/bukkit/boss/BossBar.java

@@ -137,13 +137,13 @@ public interface BossBar {
      * Shows the previously hidden boss bar to all attached players
      * @deprecated {@link #setVisible(boolean)}
      */
-    @Deprecated
+    @Deprecated(since = "1.9")
     void show();
 
     /**
      * Hides this boss bar from all attached players
      * @deprecated {@link #setVisible(boolean)}
      */
-    @Deprecated
+    @Deprecated(since = "1.9")
     void hide();
 }

paper-api/src/main/java/org/bukkit/command/Command.java

@@ -321,7 +321,7 @@ public abstract class Command {
      * consoles or when this command is executed with
      * {@link Bukkit#dispatchCommand(CommandSender, String)}.
      */
-    @Deprecated
+    @Deprecated(since = "1.20.4")
     @Nullable
     public String getPermissionMessage() {
         return permissionMessage;
@@ -392,7 +392,7 @@ public abstract class Command {
      * consoles or when this command is executed with
      * {@link Bukkit#dispatchCommand(CommandSender, String)}.
      */
-    @Deprecated
+    @Deprecated(since = "1.20.4")
     @NotNull
     public Command setPermissionMessage(@Nullable String permissionMessage) {
         this.permissionMessage = permissionMessage;

paper-api/src/main/java/org/bukkit/configuration/file/FileConfiguration.java

@@ -209,7 +209,7 @@ public abstract class FileConfiguration extends MemoryConfiguration {
      * {@link FileConfigurationOptions#getHeader()} instead.
      */
     @NotNull
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     protected String buildHeader() {
         return "";
     }

paper-api/src/main/java/org/bukkit/configuration/file/FileConfigurationOptions.java

@@ -67,7 +67,7 @@ public class FileConfigurationOptions extends MemoryConfigurationOptions {
      * @deprecated use getHeader() instead.
      */
     @NotNull
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public String header() {
         StringBuilder stringHeader = new StringBuilder();
         for (String line : header) {
@@ -105,7 +105,7 @@ public class FileConfigurationOptions extends MemoryConfigurationOptions {
      * @deprecated use setHeader() instead
      */
     @NotNull
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public FileConfigurationOptions header(@Nullable String value) {
         this.header = (value == null) ? Collections.emptyList() : Collections.unmodifiableList(Arrays.asList(value.split("\\n")));
         return this;
@@ -183,7 +183,7 @@ public class FileConfigurationOptions extends MemoryConfigurationOptions {
      *
      * @deprecated Call {@link #parseComments()} instead.
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public boolean copyHeader() {
         return parseComments;
     }
@@ -195,7 +195,7 @@ public class FileConfigurationOptions extends MemoryConfigurationOptions {
      * @deprecated Call {@link #parseComments(boolean)} instead.
      */
     @NotNull
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public FileConfigurationOptions copyHeader(boolean value) {
         parseComments = value;
         return this;

paper-api/src/main/java/org/bukkit/configuration/file/YamlConfiguration.java

@@ -42,12 +42,12 @@ public class YamlConfiguration extends FileConfiguration {
     /**
      * @deprecated unused, not intended to be API
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     protected static final String COMMENT_PREFIX = "# ";
     /**
      * @deprecated unused, not intended to be API
      */
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     protected static final String BLANK_CONFIG = "{}\n";
     private final DumperOptions yamlDumperOptions;
     private final LoaderOptions yamlLoaderOptions;

paper-api/src/main/java/org/bukkit/configuration/file/YamlConfigurationOptions.java

@@ -46,7 +46,7 @@ public class YamlConfigurationOptions extends FileConfigurationOptions {
 
     @NotNull
     @Override
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public YamlConfigurationOptions header(@Nullable String value) {
         super.header(value);
         return this;
@@ -68,7 +68,7 @@ public class YamlConfigurationOptions extends FileConfigurationOptions {
 
     @NotNull
     @Override
-    @Deprecated
+    @Deprecated(since = "1.18.1")
     public YamlConfigurationOptions copyHeader(boolean value) {
         super.copyHeader(value);
         return this;

paper-api/src/main/java/org/bukkit/configuration/file/YamlConstructor.java

@@ -17,7 +17,7 @@ public class YamlConstructor extends SafeConstructor {
     /**
      * @deprecated options required
      */
-    @Deprecated
+    @Deprecated(since = "1.19.4")
     public YamlConstructor() {
         this(new LoaderOptions());
     }

paper-api/src/main/java/org/bukkit/configuration/file/YamlRepresenter.java

@@ -15,7 +15,7 @@ public class YamlRepresenter extends Representer {
     /**
      * @deprecated options required
      */
-    @Deprecated
+    @Deprecated(since = "1.19.4")
     public YamlRepresenter() {
         this(new DumperOptions());
     }

paper-api/src/main/java/org/bukkit/enchantments/Enchantment.java

@@ -239,7 +239,7 @@ public abstract class Enchantment implements Keyed, Translatable {
      * @deprecated enchantments are badly named, use {@link #getKey()}.
      */
     @NotNull
-    @Deprecated
+    @Deprecated(since = "1.13")
     public abstract String getName();
 
     /**
@@ -263,7 +263,7 @@ public abstract class Enchantment implements Keyed, Translatable {
      * @deprecated enchantment groupings are now managed by tags, not categories
      */
     @NotNull
-    @Deprecated
+    @Deprecated(since = "1.20.5")
     public abstract EnchantmentTarget getItemTarget();
 
     /**
@@ -275,7 +275,7 @@ public abstract class Enchantment implements Keyed, Translatable {
      * @return true if the enchantment is a treasure enchantment
      * @deprecated enchantment types are now managed by tags
      */
-    @Deprecated
+    @Deprecated(since = "1.21")
     public abstract boolean isTreasure();
 
     /**
@@ -288,7 +288,7 @@ public abstract class Enchantment implements Keyed, Translatable {
      * only for {@link Enchantment#BINDING_CURSE} and
      * {@link Enchantment#VANISHING_CURSE}.
      */
-    @Deprecated
+    @Deprecated(since = "1.13")
     public abstract boolean isCursed();
 
     /**
@@ -320,7 +320,7 @@ public abstract class Enchantment implements Keyed, Translatable {
      */
     @Contract("null -> null")
     @Nullable
-    @Deprecated
+    @Deprecated(since = "1.20.3")
     public static Enchantment getByKey(@Nullable NamespacedKey key) {
         if (key == null) {
             return null;
@@ -335,7 +335,7 @@ public abstract class Enchantment implements Keyed, Translatable {
      * @return Resulting Enchantment, or null if not found
      * @deprecated enchantments are badly named, use {@link #getByKey(org.bukkit.NamespacedKey)}.
      */
-    @Deprecated
+    @Deprecated(since = "1.13")
     @Contract("null -> null")
     @Nullable
     public static Enchantment getByName(@Nullable String name) {
@@ -353,7 +353,7 @@ public abstract class Enchantment implements Keyed, Translatable {
      * @deprecated use {@link Registry#iterator() Registry.ENCHANTMENT.iterator()}
      */
     @NotNull
-    @Deprecated
+    @Deprecated(since = "1.20.3")
     public static Enchantment[] values() {
         return Lists.newArrayList(Registry.ENCHANTMENT).toArray(new Enchantment[0]);
     }

paper-api/src/main/java/org/bukkit/enchantments/EnchantmentTarget.java

@@ -13,7 +13,7 @@ public enum EnchantmentTarget {
      *
      * @deprecated this target no longer exists in Vanilla
      */
-    @Deprecated
+    @Deprecated(since = "1.16.1")
     ALL {
         @Override
         public boolean includes(@NotNull Material item) {

paper-api/src/main/java/org/bukkit/enchantments/EnchantmentWrapper.java

@@ -6,7 +6,7 @@ import org.jetbrains.annotations.NotNull;
  * A simple wrapper for ease of selecting {@link Enchantment}s
  * @deprecated only for backwards compatibility, EnchantmentWrapper is no longer used.
  */
-@Deprecated
+@Deprecated(since = "1.20.3")
 public abstract class EnchantmentWrapper extends Enchantment {
     protected EnchantmentWrapper() {
     }

paper-api/src/main/java/org/bukkit/entity/AbstractArrow.java

@@ -20,7 +20,7 @@ public interface AbstractArrow extends Projectile {
      * @see #getWeapon()
      * @deprecated a function of the firing weapon
      */
-    @Deprecated
+    @Deprecated(since = "1.21")
     public int getKnockbackStrength();
 
     /**
@@ -30,7 +30,7 @@ public interface AbstractArrow extends Projectile {
      * @see #setWeapon(org.bukkit.inventory.ItemStack)
      * @deprecated a function of the firing weapon
      */
-    @Deprecated
+    @Deprecated(since = "1.21")
     public void setKnockbackStrength(int knockbackStrength);
 
     /**
@@ -132,7 +132,7 @@ public interface AbstractArrow extends Projectile {
      * @see #setWeapon(org.bukkit.inventory.ItemStack)
      * @deprecated a function of the firing weapon instead
      */
-    @Deprecated
+    @Deprecated(since = "1.21")
     public void setShotFromCrossbow(boolean shotFromCrossbow);
 
     /**

paper-api/src/main/java/org/bukkit/entity/AbstractHorse.java

@@ -20,7 +20,7 @@ public interface AbstractHorse extends Vehicle, InventoryHolder, Tameable {
      * @return a {@link Horse.Variant} representing the horse's variant
      * @deprecated different variants are different classes
      */
-    @Deprecated
+    @Deprecated(since = "1.11")
     @NotNull
     public Horse.Variant getVariant();
 
@@ -28,7 +28,7 @@ public interface AbstractHorse extends Vehicle, InventoryHolder, Tameable {
      * @param variant variant
      * @deprecated you are required to spawn a different entity
      */
-    @Deprecated
+    @Deprecated(since = "1.11")
     @Contract("_ -> fail")
     public void setVariant(Horse.Variant variant);
 

paper-api/src/main/java/org/bukkit/entity/AbstractSkeleton.java

@@ -21,7 +21,7 @@ public interface AbstractSkeleton extends Monster {
      * @return Current type
      * @deprecated should check what class instance this is.
      */
-    @Deprecated
+    @Deprecated(since = "1.17")
     @NotNull
     public Skeleton.SkeletonType getSkeletonType();
 
@@ -29,7 +29,7 @@ public interface AbstractSkeleton extends Monster {
      * @param type type
      * @deprecated Must spawn a new subtype variant
      */
-    @Deprecated
+    @Deprecated(since = "1.17")
     @Contract("_ -> fail")
     public void setSkeletonType(Skeleton.SkeletonType type);
 }

paper-api/src/main/java/org/bukkit/entity/Ageable.java

@@ -25,7 +25,7 @@ public interface Ageable extends Creature {
      * @param lock new lock
      * @deprecated see {@link Breedable#setAgeLock(boolean)}
      */
-    @Deprecated
+    @Deprecated(since = "1.16.2")
     public void setAgeLock(boolean lock);
 
     /**
@@ -34,7 +34,7 @@ public interface Ageable extends Creature {
      * @return the current agelock
      * @deprecated see {@link Breedable#getAgeLock()}
      */
-    @Deprecated
+    @Deprecated(since = "1.16.2")
     public boolean getAgeLock();
 
     /**
@@ -60,7 +60,7 @@ public interface Ageable extends Creature {
      * @return the ability to breed of the animal
      * @deprecated see {@link Breedable#canBreed()}
      */
-    @Deprecated
+    @Deprecated(since = "1.16.2")
     public boolean canBreed();
 
     /**
@@ -70,6 +70,6 @@ public interface Ageable extends Creature {
      * @param breed breedability of the animal
      * @deprecated see {@link Breedable#setBreed(boolean)}
      */
-    @Deprecated
+    @Deprecated(since = "1.16.2")
     public void setBreed(boolean breed);
 }

paper-api/src/main/java/org/bukkit/entity/AreaEffectCloud.java

@@ -152,7 +152,7 @@ public interface AreaEffectCloud extends Entity {
      * @param data PotionData to set the base potion state to
      * @deprecated Upgraded / extended potions are now their own {@link PotionType} use {@link #setBasePotionType} instead.
      */
-    @Deprecated
+    @Deprecated(since = "1.20.6")
     void setBasePotionData(@Nullable PotionData data);
 
     /**
@@ -162,7 +162,7 @@ public interface AreaEffectCloud extends Entity {
      * @deprecated Upgraded / extended potions are now their own {@link PotionType} use {@link #getBasePotionType()} instead.
      */
     @Nullable
-    @Deprecated
+    @Deprecated(since = "1.20.6")
     PotionData getBasePotionData();
 
     /**

paper-api/src/main/java/org/bukkit/entity/ArmorStand.java

@@ -17,7 +17,7 @@ public interface ArmorStand extends LivingEntity {
      * @deprecated prefer {@link EntityEquipment#getItemInHand()}
      */
     @NotNull
-    @Deprecated
+    @Deprecated(since = "1.15.2")
     ItemStack getItemInHand();
 
     /**
@@ -28,7 +28,7 @@ public interface ArmorStand extends LivingEntity {
      * @deprecated prefer
      * {@link EntityEquipment#setItemInHand(org.bukkit.inventory.ItemStack)}
      */
-    @Deprecated
+    @Deprecated(since = "1.15.2")
     void setItemInHand(@Nullable ItemStack item);
 
     /**
@@ -39,7 +39,7 @@ public interface ArmorStand extends LivingEntity {
      * @deprecated prefer {@link EntityEquipment#getBoots()}
      */
     @NotNull
-    @Deprecated
+    @Deprecated(since = "1.15.2")
     ItemStack getBoots();
 
     /**
@@ -50,7 +50,7 @@ public interface ArmorStand extends LivingEntity {
      * @deprecated prefer
      * {@link EntityEquipment#setBoots(org.bukkit.inventory.ItemStack)}
      */
-    @Deprecated
+    @Deprecated(since = "1.15.2")
     void setBoots(@Nullable ItemStack item);
 
     /**
@@ -61,7 +61,7 @@ public interface ArmorStand extends LivingEntity {
      * @deprecated prefer {@link EntityEquipment#getLeggings()}
      */
     @NotNull
-    @Deprecated
+    @Deprecated(since = "1.15.2")
     ItemStack getLeggings();
 
     /**
@@ -72,7 +72,7 @@ public interface ArmorStand extends LivingEntity {
      * @deprecated prefer
      * {@link EntityEquipment#setLeggings(org.bukkit.inventory.ItemStack)}
      */
-    @Deprecated
+    @Deprecated(since = "1.15.2")
     void setLeggings(@Nullable ItemStack item);
 
     /**
@@ -83,7 +83,7 @@ public interface ArmorStand extends LivingEntity {
      * @deprecated prefer {@link EntityEquipment#getChestplate()}
      */
     @NotNull
-    @Deprecated
+    @Deprecated(since = "1.15.2")
     ItemStack getChestplate();
 
     /**
@@ -94,7 +94,7 @@ public interface ArmorStand extends LivingEntity {
      * @deprecated prefer
      * {@link EntityEquipment#setChestplate(org.bukkit.inventory.ItemStack)}
      */
-    @Deprecated
+    @Deprecated(since = "1.15.2")
     void setChestplate(@Nullable ItemStack item);
 
     /**
@@ -105,7 +105,7 @@ public interface ArmorStand extends LivingEntity {
      * @deprecated prefer {@link EntityEquipment#getHelmet()}
      */
     @NotNull
-    @Deprecated
+    @Deprecated(since = "1.15.2")
     ItemStack getHelmet();
 
     /**
@@ -116,7 +116,7 @@ public interface ArmorStand extends LivingEntity {
      * @deprecated prefer
      * {@link EntityEquipment#setHelmet(org.bukkit.inventory.ItemStack)}
      */
-    @Deprecated
+    @Deprecated(since = "1.15.2")
     void setHelmet(@Nullable ItemStack item);
 
     /**

paper-api/src/main/java/org/bukkit/entity/Arrow.java

@@ -17,7 +17,7 @@ public interface Arrow extends AbstractArrow {
      * @param data PotionData to set the base potion state to
      * @deprecated Upgraded / extended potions are now their own {@link PotionType} use {@link #setBasePotionType} instead.
      */
-    @Deprecated
+    @Deprecated(since = "1.20.6")
     void setBasePotionData(@Nullable PotionData data);
 
     /**
@@ -27,7 +27,7 @@ public interface Arrow extends AbstractArrow {
      * @deprecated Upgraded / extended potions are now their own {@link PotionType} use {@link #getBasePotionType()} instead.
      */
     @Nullable
-    @Deprecated
+    @Deprecated(since = "1.20.6")
     PotionData getBasePotionData();
 
     /**

paper-api/src/main/java/org/bukkit/entity/Boat.java

@@ -15,7 +15,7 @@ public interface Boat extends Vehicle {
      * @return the wood type
      * @deprecated deprecated in favor of {@link #getBoatType()}
      */
-    @Deprecated
+    @Deprecated(since = "1.19")
     @NotNull
     TreeSpecies getWoodType();
 
@@ -25,7 +25,7 @@ public interface Boat extends Vehicle {
      * @param species the new wood type
      * @deprecated deprecated in favor of {@link #setBoatType(Type)}
      */
-    @Deprecated
+    @Deprecated(since = "1.19")
     void setWoodType(@NotNull TreeSpecies species);
 
     /**
@@ -34,7 +34,7 @@ public interface Boat extends Vehicle {
      * @return the boat type
      * @deprecated different boats types are now different entity types
      */
-    @Deprecated
+    @Deprecated(since = "1.21.2")
     @NotNull
     Type getBoatType();
 
@@ -44,7 +44,7 @@ public interface Boat extends Vehicle {
      * @param type the new type
      * @deprecated different boats types are now different entity types
      */
-    @Deprecated
+    @Deprecated(since = "1.21.2")
     void setBoatType(@NotNull Type type);
 
     /**
@@ -54,7 +54,7 @@ public interface Boat extends Vehicle {
      * @return The max speed.
      * @deprecated boats are complex and many of these methods do not work correctly across multiple versions.
      */
-    @Deprecated
+    @Deprecated(since = "1.9")
     public double getMaxSpeed();
 
     /**
@@ -63,7 +63,7 @@ public interface Boat extends Vehicle {
      * @param speed The max speed.
      * @deprecated boats are complex and many of these methods do not work correctly across multiple versions.
      */
-    @Deprecated
+    @Deprecated(since = "1.9")
     public void setMaxSpeed(double speed);
 
     /**
@@ -73,7 +73,7 @@ public interface Boat extends Vehicle {
      * @return The rate of deceleration
      * @deprecated boats are complex and many of these methods do not work correctly across multiple versions.
      */
-    @Deprecated
+    @Deprecated(since = "1.9")
     public double getOccupiedDeceleration();
 
     /**
@@ -84,7 +84,7 @@ public interface Boat extends Vehicle {
      * @param rate deceleration rate
      * @deprecated boats are complex and many of these methods do not work correctly across multiple versions.
      */
-    @Deprecated
+    @Deprecated(since = "1.9")
     public void setOccupiedDeceleration(double rate);
 
     /**
@@ -95,7 +95,7 @@ public interface Boat extends Vehicle {
      * @return The rate of deceleration
      * @deprecated boats are complex and many of these methods do not work correctly across multiple versions.
      */
-    @Deprecated
+    @Deprecated(since = "1.9")
     public double getUnoccupiedDeceleration();
 
     /**
@@ -107,7 +107,7 @@ public interface Boat extends Vehicle {
      * @param rate deceleration rate
      * @deprecated boats are complex and many of these methods do not work correctly across multiple versions.
      */
-    @Deprecated
+    @Deprecated(since = "1.9")
     public void setUnoccupiedDeceleration(double rate);
 
     /**
@@ -116,7 +116,7 @@ public interface Boat extends Vehicle {
      * @return whether boats can work on land
      * @deprecated boats are complex and many of these methods do not work correctly across multiple versions.
      */
-    @Deprecated
+    @Deprecated(since = "1.9")
     public boolean getWorkOnLand();
 
     /**
@@ -125,7 +125,7 @@ public interface Boat extends Vehicle {
      * @param workOnLand whether boats can work on land
      * @deprecated boats are complex and many of these methods do not work correctly across multiple versions.
      */
-    @Deprecated
+    @Deprecated(since = "1.9")
     public void setWorkOnLand(boolean workOnLand);
 
     /**
@@ -140,7 +140,7 @@ public interface Boat extends Vehicle {
      * Represents the type of boats.
      * @deprecated different boats types are now different entity types
      */
-    @Deprecated
+    @Deprecated(since = "1.21.2")
     public enum Type {
         OAK(Material.OAK_PLANKS),
         SPRUCE(Material.SPRUCE_PLANKS),

paper-api/src/main/java/org/bukkit/entity/Damageable.java

@@ -79,7 +79,7 @@ public interface Damageable extends Entity {
      * @return Maximum health
      * @deprecated use {@link Attribute#MAX_HEALTH}.
      */
-    @Deprecated
+    @Deprecated(since = "1.11")
     double getMaxHealth();
 
     /**
@@ -94,13 +94,13 @@ public interface Damageable extends Entity {
      * @param health amount of health to set the maximum to
      * @deprecated use {@link Attribute#MAX_HEALTH}.
      */
-    @Deprecated
+    @Deprecated(since = "1.11")
     void setMaxHealth(double health);
 
     /**
      * Resets the max health to the original amount.
      * @deprecated use {@link Attribute#MAX_HEALTH}.
      */
-    @Deprecated
+    @Deprecated(since = "1.11")
     void resetMaxHealth();
 }

paper-api/src/main/java/org/bukkit/entity/Endermite.java

@@ -10,7 +10,7 @@ public interface Endermite extends Monster {
      * @return player spawned status
      * @deprecated this functionality no longer exists
      */
-    @Deprecated
+    @Deprecated(since = "1.17")
     boolean isPlayerSpawned();
 
     /**
@@ -21,6 +21,6 @@ public interface Endermite extends Monster {
      * @param playerSpawned player spawned status
      * @deprecated this functionality no longer exists
      */
-    @Deprecated
+    @Deprecated(since = "1.17")
     void setPlayerSpawned(boolean playerSpawned);
 }

paper-api/src/main/java/org/bukkit/entity/Entity.java

@@ -321,7 +321,7 @@ public interface Entity extends Metadatable, CommandSender, Nameable, Persistent
      * @deprecated entities may have multiple passengers, use
      * {@link #getPassengers()}
      */
-    @Deprecated
+    @Deprecated(since = "1.11.2")
     @Nullable
     public Entity getPassenger();
 
@@ -333,7 +333,7 @@ public interface Entity extends Metadatable, CommandSender, Nameable, Persistent
      * @deprecated entities may have multiple passengers, use
      * {@link #addPassenger(org.bukkit.entity.Entity)}
      */
-    @Deprecated
+    @Deprecated(since = "1.11.2")
     public boolean setPassenger(@NotNull Entity passenger);
 
     /**
@@ -397,7 +397,7 @@ public interface Entity extends Metadatable, CommandSender, Nameable, Persistent
      * @param event a {@link EntityDamageEvent}
      * @deprecated method is for internal use only and will be removed
      */
-    @Deprecated(forRemoval = true)
+    @Deprecated(since = "1.20.4", forRemoval = true)
     public void setLastDamageCause(@Nullable EntityDamageEvent event);
 
     /**

paper-api/src/main/java/org/bukkit/entity/EntityType.java

@@ -393,7 +393,7 @@ public enum EntityType implements Keyed, Translatable {
      * @return the entity type's name
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     @Nullable
     public String getName() {
         return name;
@@ -418,7 +418,7 @@ public enum EntityType implements Keyed, Translatable {
      * @return the raw type id
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     public short getTypeId() {
         return typeId;
     }
@@ -430,7 +430,7 @@ public enum EntityType implements Keyed, Translatable {
      * @return the matching entity type or null
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     @Contract("null -> null")
     @Nullable
     public static EntityType fromName(@Nullable String name) {
@@ -447,7 +447,7 @@ public enum EntityType implements Keyed, Translatable {
      * @return the matching entity type or null
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     @Nullable
     public static EntityType fromId(int id) {
         if (id > Short.MAX_VALUE) {

paper-api/src/main/java/org/bukkit/entity/Evoker.java

@@ -14,7 +14,7 @@ public interface Evoker extends Spellcaster {
      * @deprecated future versions of Minecraft have additional spell casting
      * entities.
      */
-    @Deprecated
+    @Deprecated(since = "1.11.2")
     public enum Spell {
 
         /**
@@ -51,7 +51,7 @@ public interface Evoker extends Spellcaster {
      * entities.
      *
      */
-    @Deprecated
+    @Deprecated(since = "1.11.2")
     @NotNull
     Spell getCurrentSpell();
 
@@ -62,6 +62,6 @@ public interface Evoker extends Spellcaster {
      * @deprecated future versions of Minecraft have additional spell casting
      * entities.
      */
-    @Deprecated
+    @Deprecated(since = "1.11.2")
     void setCurrentSpell(@Nullable Spell spell);
 }

paper-api/src/main/java/org/bukkit/entity/FallingBlock.java

@@ -15,7 +15,7 @@ public interface FallingBlock extends Entity {
      * @return Material of the block
      * @deprecated use {@link #getBlockData()}
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     @NotNull
     Material getMaterial();
 

paper-api/src/main/java/org/bukkit/entity/FishHook.java

@@ -208,7 +208,7 @@ public interface FishHook extends Projectile {
      * @return chance the bite chance
      * @deprecated has no effect in newer Minecraft versions
      */
-    @Deprecated
+    @Deprecated(since = "1.9.2")
     public double getBiteChance();
 
     /**
@@ -222,7 +222,7 @@ public interface FishHook extends Projectile {
      *     and 1
      * @deprecated has no effect in newer Minecraft versions
      */
-    @Deprecated
+    @Deprecated(since = "1.9.2")
     public void setBiteChance(double chance) throws IllegalArgumentException;
 
     /**

paper-api/src/main/java/org/bukkit/entity/Guardian.java

@@ -63,14 +63,14 @@ public interface Guardian extends Monster {
      * @return true if the Guardian is an Elder Guardian, false if not
      * @deprecated should check if instance of {@link ElderGuardian}.
      */
-    @Deprecated
+    @Deprecated(since = "1.10.2")
     public boolean isElder();
 
     /**
      * @param shouldBeElder shouldBeElder
      * @deprecated Must spawn a new {@link ElderGuardian}.
      */
-    @Deprecated
+    @Deprecated(since = "1.10.2")
     public void setElder(boolean shouldBeElder);
 
     /**

paper-api/src/main/java/org/bukkit/entity/Horse.java

@@ -11,7 +11,7 @@ public interface Horse extends AbstractHorse {
     /**
      * @deprecated different variants are differing classes
      */
-    @Deprecated
+    @Deprecated(since = "1.11")
     public enum Variant {
         /**
          * A normal horse
@@ -154,14 +154,14 @@ public interface Horse extends AbstractHorse {
      * @return carrying chest status
      * @deprecated see {@link ChestedHorse}
      */
-    @Deprecated
+    @Deprecated(since = "1.11")
     public boolean isCarryingChest();
 
     /**
      * @param chest chest
      * @deprecated see {@link ChestedHorse}
      */
-    @Deprecated
+    @Deprecated(since = "1.11")
     public void setCarryingChest(boolean chest);
 
     @NotNull

paper-api/src/main/java/org/bukkit/entity/HumanEntity.java

@@ -189,7 +189,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * @deprecated Humans may now dual wield in their off hand, use explicit
      * methods in {@link PlayerInventory}.
      */
-    @Deprecated
+    @Deprecated(since = "1.9")
     @NotNull
     public ItemStack getItemInHand();
 
@@ -201,7 +201,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * @deprecated Humans may now dual wield in their off hand, use explicit
      * methods in {@link PlayerInventory}.
      */
-    @Deprecated
+    @Deprecated(since = "1.9")
     public void setItemInHand(@Nullable ItemStack item);
 
     /**
@@ -461,7 +461,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * @deprecated There are currently no well defined semantics regarding
      * serialized entities in Bukkit. Use with care.
      */
-    @Deprecated
+    @Deprecated(since = "1.12")
     @Nullable
     public Entity getShoulderEntityLeft();
 
@@ -479,7 +479,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * @deprecated There are currently no well defined semantics regarding
      * serialized entities in Bukkit. Use with care.
      */
-    @Deprecated
+    @Deprecated(since = "1.12")
     public void setShoulderEntityLeft(@Nullable Entity entity);
 
     /**
@@ -493,7 +493,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * @deprecated There are currently no well defined semantics regarding
      * serialized entities in Bukkit. Use with care.
      */
-    @Deprecated
+    @Deprecated(since = "1.12")
     @Nullable
     public Entity getShoulderEntityRight();
 
@@ -511,7 +511,7 @@ public interface HumanEntity extends LivingEntity, AnimalTamer, InventoryHolder
      * @deprecated There are currently no well defined semantics regarding
      * serialized entities in Bukkit. Use with care.
      */
-    @Deprecated
+    @Deprecated(since = "1.12")
     public void setShoulderEntityRight(@Nullable Entity entity);
 
     /**

paper-api/src/main/java/org/bukkit/entity/LingeringPotion.java

@@ -5,5 +5,5 @@ package org.bukkit.entity;
  *
  * @deprecated lingering status depends on only on the potion item.
  */
-@Deprecated
+@Deprecated(since = "1.20.5")
 public interface LingeringPotion extends ThrownPotion { }

paper-api/src/main/java/org/bukkit/entity/LivingEntity.java

@@ -353,7 +353,7 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
      * @deprecated no need to force since multiple effects of the same type are
      * now supported.
      */
-    @Deprecated
+    @Deprecated(since = "1.15.2")
     public boolean addPotionEffect(@NotNull PotionEffect effect, boolean force);
 
     /**
@@ -771,7 +771,7 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
      * @deprecated entity groupings are now managed by tags, not categories
      */
     @NotNull
-    @Deprecated
+    @Deprecated(since = "1.20.5")
     public EntityCategory getCategory();
 
     /**

paper-api/src/main/java/org/bukkit/entity/Ocelot.java

@@ -30,7 +30,7 @@ public interface Ocelot extends Animals {
      * @deprecated Cats are now a separate entity.
      */
     @NotNull
-    @Deprecated
+    @Deprecated(since = "1.19.4")
     public Type getCatType();
 
     /**
@@ -39,7 +39,7 @@ public interface Ocelot extends Animals {
      * @param type New type of this cat.
      * @deprecated Cats are now a separate entity.
      */
-    @Deprecated
+    @Deprecated(since = "1.19.4")
     public void setCatType(@NotNull Type type);
 
     /**
@@ -47,7 +47,7 @@ public interface Ocelot extends Animals {
      *
      * @deprecated Cats are now a separate entity.
      */
-    @Deprecated
+    @Deprecated(since = "1.14")
     public enum Type {
         WILD_OCELOT(0),
         BLACK_CAT(1),
@@ -73,7 +73,7 @@ public interface Ocelot extends Animals {
          * @return Type ID.
          * @deprecated Magic value
          */
-        @Deprecated
+        @Deprecated(since = "1.6.2")
         public int getId() {
             return id;
         }
@@ -85,7 +85,7 @@ public interface Ocelot extends Animals {
          * @return Resulting type, or null if not found.
          * @deprecated Magic value
          */
-        @Deprecated
+        @Deprecated(since = "1.6.2")
         @Nullable
         public static Type getType(int id) {
             return (id >= types.length) ? null : types[id];

paper-api/src/main/java/org/bukkit/entity/PiglinAbstract.java

@@ -55,7 +55,7 @@ public interface PiglinAbstract extends Monster, Ageable {
      * @return Whether the piglin is a baby
      * @deprecated see {@link Ageable#isAdult()}
      */
-    @Deprecated
+    @Deprecated(since = "1.16.2")
     public boolean isBaby();
 
     /**
@@ -64,6 +64,6 @@ public interface PiglinAbstract extends Monster, Ageable {
      * @param flag Whether the piglin is a baby
      * @deprecated see {@link Ageable#setBaby()} and {@link Ageable#setAdult()}
      */
-    @Deprecated
+    @Deprecated(since = "1.16.2")
     public void setBaby(boolean flag);
 }

paper-api/src/main/java/org/bukkit/entity/Player.java

@@ -360,7 +360,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * context/time which it is accessed
      */
     @Override
-    @Deprecated
+    @Deprecated(since = "1.16.1")
     public boolean isOnGround();
 
     /**
@@ -437,7 +437,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      */
     @Nullable
     @Override
-    @Deprecated
+    @Deprecated(since = "1.20.4")
     public Location getBedSpawnLocation();
 
     /**
@@ -459,7 +459,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @deprecated Misleading name. This method sets the player's respawn
      * location more generally and is not limited to beds.
      */
-    @Deprecated
+    @Deprecated(since = "1.20.4")
     public void setBedSpawnLocation(@Nullable Location location);
 
     /**
@@ -480,7 +480,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @deprecated Misleading name. This method sets the player's respawn
      * location more generally and is not limited to beds.
      */
-    @Deprecated
+    @Deprecated(since = "1.20.4")
     public void setBedSpawnLocation(@Nullable Location location, boolean force);
 
     /**
@@ -525,7 +525,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param note The note ID.
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     public void playNote(@NotNull Location loc, byte instrument, byte note);
 
     /**
@@ -756,7 +756,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param data a data bit needed for some effects
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     public void playEffect(@NotNull Location loc, @NotNull Effect effect, int data);
 
     /**
@@ -802,7 +802,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param data The block data
      * @deprecated Magic value
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     public void sendBlockChange(@NotNull Location loc, @NotNull Material material, byte data);
 
     /**
@@ -856,7 +856,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @deprecated suppressLightUpdates is not functional in versions greater
      * than 1.19.4
      */
-    @Deprecated
+    @Deprecated(since = "1.20")
     public void sendBlockChanges(@NotNull Collection<BlockState> blocks, boolean suppressLightUpdates);
 
     /**
@@ -1316,7 +1316,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param player Player to hide
      * @deprecated see {@link #hidePlayer(Plugin, Player)}
      */
-    @Deprecated
+    @Deprecated(since = "1.12.2")
     public void hidePlayer(@NotNull Player player);
 
     /**
@@ -1333,7 +1333,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param player Player to show
      * @deprecated see {@link #showPlayer(Plugin, Player)}
      */
-    @Deprecated
+    @Deprecated(since = "1.12.2")
     public void showPlayer(@NotNull Player player);
 
     /**
@@ -1463,7 +1463,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @deprecated Minecraft no longer uses textures packs. Instead you
      *     should use {@link #setResourcePack(String)}.
      */
-    @Deprecated
+    @Deprecated(since = "1.7.2")
     public void setTexturePack(@NotNull String url);
 
     /**
@@ -1918,7 +1918,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @param subtitle Subtitle text
      * @deprecated API behavior subject to change
      */
-    @Deprecated
+    @Deprecated(since = "1.8.7")
     public void sendTitle(@Nullable String title, @Nullable String subtitle);
 
     /**

paper-api/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(since = "1.20.2")
     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(since = "1.20.2")
     public void setBounce(boolean doesBounce);
 }

paper-api/src/main/java/org/bukkit/entity/Skeleton.java

@@ -48,7 +48,7 @@ public interface Skeleton extends AbstractSkeleton {
      * @deprecated classes are different types. This interface only remains in
      *     the Skeleton interface to preserve backwards compatibility.
      */
-    @Deprecated
+    @Deprecated(since = "1.11")
     public enum SkeletonType {
 
         /**

paper-api/src/main/java/org/bukkit/entity/SplashPotion.java

@@ -5,5 +5,5 @@ package org.bukkit.entity;
  *
  * @deprecated splash status depends on only on the potion item.
  */
-@Deprecated
+@Deprecated(since = "1.14")
 public interface SplashPotion extends ThrownPotion { }

paper-api/src/main/java/org/bukkit/entity/TippedArrow.java

@@ -4,5 +4,5 @@ package org.bukkit.entity;
  * @deprecated tipped status depends only on base potion type not being
  * UNCRAFTABLE and effects being empty.
  */
-@Deprecated
+@Deprecated(since = "1.14")
 public interface TippedArrow extends Arrow { }

paper-api/src/main/java/org/bukkit/entity/Zoglin.java

@@ -11,7 +11,7 @@ public interface Zoglin extends Monster, Ageable {
      * @return Whether the zoglin is a baby
      * @deprecated see {@link Ageable#isAdult()}
      */
-    @Deprecated
+    @Deprecated(since = "1.6.2")
     public boolean isBaby();
 
     /**
@@ -20,6 +20,6 @@ public interface Zoglin extends Monster, Ageable {
      * @param flag Whether the zoglin is a baby
      * @deprecated see {@link Ageable#setBaby()} and {@link Ageable#setAdult()}
      */
-    @Deprecated
+    @Deprecated(since = "1.16.2")
     public void setBaby(boolean flag);
 }

paper-api/src/main/java/org/bukkit/entity/Zombie.java

@@ -14,7 +14,7 @@ public interface Zombie extends Monster, Ageable {
      * @return Whether the zombie is a baby
      * @deprecated see {@link Ageable#isAdult()}
      */
-    @Deprecated
+    @Deprecated(since = "1.16.2")
     public boolean isBaby();
 
     /**
@@ -23,7 +23,7 @@ public interface Zombie extends Monster, Ageable {
      * @param flag Whether the zombie is a baby
      * @deprecated see {@link Ageable#setBaby()} and {@link Ageable#setAdult()}
      */
-    @Deprecated
+    @Deprecated(since = "1.16.2")
     public void setBaby(boolean flag);
 
     /**
@@ -32,14 +32,14 @@ public interface Zombie extends Monster, Ageable {
      * @return Whether the zombie is a villager
      * @deprecated check if instanceof {@link ZombieVillager}.
      */
-    @Deprecated
+    @Deprecated(since = "1.10.2")
     public boolean isVillager();
 
     /**
      * @param flag flag
      * @deprecated must spawn {@link ZombieVillager}.
      */
-    @Deprecated
+    @Deprecated(since = "1.9")
     @Contract("_ -> fail")
     public void setVillager(boolean flag);
 
@@ -47,7 +47,7 @@ public interface Zombie extends Monster, Ageable {
      * @param profession profession
      * @see ZombieVillager#getVillagerProfession()
      */
-    @Deprecated
+    @Deprecated(since = "1.10.2")
     @Contract("_ -> fail")
     public void setVillagerProfession(Villager.Profession profession);
 
@@ -55,7 +55,7 @@ public interface Zombie extends Monster, Ageable {
      * @return profession
      * @see ZombieVillager#getVillagerProfession()
      */
-    @Deprecated
+    @Deprecated(since = "1.10.2")
     @Nullable
     @Contract("-> null")
     public Villager.Profession getVillagerProfession();

paper-api/src/main/java/org/bukkit/event/block/BlockBurnEvent.java

@@ -17,7 +17,7 @@ public class BlockBurnEvent extends BlockEvent implements Cancellable {
     private boolean cancelled;
     private final Block ignitingBlock;
 
-    @Deprecated
+    @Deprecated(since = "1.11.2")
     public BlockBurnEvent(@NotNull final Block block) {
         this(block, null);
     }

paper-api/src/main/java/org/bukkit/event/block/BlockCanBuildEvent.java

@@ -26,7 +26,7 @@ public class BlockCanBuildEvent extends BlockEvent {
     protected BlockData blockData;
     private final Player player;
 
-    @Deprecated
+    @Deprecated(since = "1.13.2")
     public BlockCanBuildEvent(@NotNull final Block block, @NotNull final BlockData type, final boolean canBuild) {
         this(block, null, type, canBuild);
     }

paper-api/src/main/java/org/bukkit/event/block/BlockPistonExtendEvent.java

@@ -16,7 +16,7 @@ public class BlockPistonExtendEvent extends BlockPistonEvent {
     private final int length;
     private List<Block> blocks;
 
-    @Deprecated
+    @Deprecated(since = "1.8")
     public BlockPistonExtendEvent(@NotNull final Block block, final int length, @NotNull final BlockFace direction) {
         super(block, direction);
 
@@ -37,7 +37,7 @@ public class BlockPistonExtendEvent extends BlockPistonEvent {
      * @deprecated slime blocks make the value of this method
      *          inaccurate due to blocks being pushed at the side
      */
-    @Deprecated
+    @Deprecated(since = "1.8")
     public int getLength() {
         return this.length;
     }

paper-api/src/main/java/org/bukkit/event/block/BlockPistonRetractEvent.java

@@ -26,7 +26,7 @@ public class BlockPistonRetractEvent extends BlockPistonEvent {
      *
      * @return The possible location of the possibly moving block.
      */
-    @Deprecated
+    @Deprecated(since = "1.8")
     @NotNull
     public Location getRetractLocation() {
         return getBlock().getRelative(getDirection(), 2).getLocation();

paper-api/src/main/java/org/bukkit/event/block/BlockPlaceEvent.java

@@ -24,7 +24,7 @@ public class BlockPlaceEvent extends BlockEvent implements Cancellable {
     protected Player player;
     protected EquipmentSlot hand;
 
-    @Deprecated
+    @Deprecated(since = "1.9")
     public BlockPlaceEvent(@NotNull final Block placedBlock, @NotNull final BlockState replacedBlockState, @NotNull final Block placedAgainst, @NotNull final ItemStack itemInHand, @NotNull final Player thePlayer, final boolean canBuild) {
         this(placedBlock, replacedBlockState, placedAgainst, itemInHand, thePlayer, canBuild, EquipmentSlot.HAND);
     }

paper-api/src/main/java/org/bukkit/event/block/CauldronLevelChangeEvent.java

@@ -60,7 +60,7 @@ public class CauldronLevelChangeEvent extends BlockEvent implements Cancellable
      * @see #getBlock()
      * @deprecated not all cauldron contents are Levelled
      */
-    @Deprecated
+    @Deprecated(since = "1.17")
     public int getOldLevel() {
         BlockData oldBlock = getBlock().getBlockData();
         return (oldBlock instanceof Levelled) ? ((Levelled) oldBlock).getLevel() : ((oldBlock.getMaterial() == Material.CAULDRON) ? 0 : 3);
@@ -73,7 +73,7 @@ public class CauldronLevelChangeEvent extends BlockEvent implements Cancellable
      * @see #getNewState()
      * @deprecated not all cauldron contents are Levelled
      */
-    @Deprecated
+    @Deprecated(since = "1.17")
     public int getNewLevel() {
         BlockData newBlock = newState.getBlockData();
         return (newBlock instanceof Levelled) ? ((Levelled) newBlock).getLevel() : ((newBlock.getMaterial() == Material.CAULDRON) ? 0 : 3);
@@ -86,7 +86,7 @@ public class CauldronLevelChangeEvent extends BlockEvent implements Cancellable
      * @see #getNewState()
      * @deprecated not all cauldron contents are Levelled
      */
-    @Deprecated
+    @Deprecated(since = "1.17")
     public void setNewLevel(int newLevel) {
         Preconditions.checkArgument(0 <= newLevel && newLevel <= 3, "Cauldron level out of bounds 0 <= %s <= 3", newLevel);
         if (newLevel == 0) {

paper-api/src/main/java/org/bukkit/event/block/NotePlayEvent.java

@@ -60,7 +60,7 @@ public class NotePlayEvent extends BlockEvent implements Cancellable {
      * @param instrument the Instrument. Has no effect if null.
      * @deprecated no effect on newer Minecraft versions
      */
-    @Deprecated
+    @Deprecated(since = "1.13")
     public void setInstrument(@NotNull Instrument instrument) {
         if (instrument != null) {
             this.instrument = instrument;
@@ -73,7 +73,7 @@ public class NotePlayEvent extends BlockEvent implements Cancellable {
      * @param note the Note. Has no effect if null.
      * @deprecated no effect on newer Minecraft versions
      */
-    @Deprecated
+    @Deprecated(since = "1.13")
     public void setNote(@NotNull Note note) {
         if (note != null) {
             this.note = note;

paper-api/src/main/java/org/bukkit/event/block/SignChangeEvent.java

@@ -20,7 +20,7 @@ public class SignChangeEvent extends BlockEvent implements Cancellable {
     private final String[] lines;
     private final Side side;
 
-    @Deprecated
+    @Deprecated(since = "1.19.4")
     public SignChangeEvent(@NotNull final Block theBlock, @NotNull final Player thePlayer, @NotNull final String[] theLines) {
         this(theBlock, thePlayer, theLines, Side.FRONT);
     }

paper-api/src/main/java/org/bukkit/event/enchantment/PrepareItemEnchantEvent.java

@@ -69,7 +69,7 @@ public class PrepareItemEnchantEvent extends InventoryEvent implements Cancellab
      * @deprecated Use {@link #getOffers()} instead of this method
      */
     @NotNull
-    @Deprecated
+    @Deprecated(since = "1.20.5")
     public int[] getExpLevelCostsOffered() {
         int[] levelOffers = new int[offers.length];
         for (int i = 0; i < offers.length; i++) {

paper-api/src/main/java/org/bukkit/event/entity/CreatureSpawnEvent.java

@@ -57,7 +57,7 @@ public class CreatureSpawnEvent extends EntitySpawnEvent {
          * {@link ChunkLoadEvent#isNewChunk()} and {@link Chunk#getEntities()}
          * for similar effect.
          */
-        @Deprecated
+        @Deprecated(since = "1.14")
         CHUNK_GEN,
         /**
          * When a creature spawns from a spawner

paper-api/src/main/java/org/bukkit/event/entity/EntityCombustByBlockEvent.java

@@ -11,7 +11,7 @@ import org.jetbrains.annotations.Nullable;
 public class EntityCombustByBlockEvent extends EntityCombustEvent {
     private final Block combuster;
 
-    @Deprecated
+    @Deprecated(since = "1.21")
     public EntityCombustByBlockEvent(@Nullable final Block combuster, @NotNull final Entity combustee, final int duration) {
         this(combuster, combustee, (float) duration);
     }

paper-api/src/main/java/org/bukkit/event/entity/EntityCombustByEntityEvent.java

@@ -9,7 +9,7 @@ import org.jetbrains.annotations.NotNull;
 public class EntityCombustByEntityEvent extends EntityCombustEvent {
     private final Entity combuster;
 
-    @Deprecated
+    @Deprecated(since = "1.21")
     public EntityCombustByEntityEvent(@NotNull final Entity combuster, @NotNull final Entity combustee, final int duration) {
         this(combuster, combustee, (float) duration);
     }

paper-api/src/main/java/org/bukkit/event/entity/EntityCombustEvent.java

@@ -15,7 +15,7 @@ public class EntityCombustEvent extends EntityEvent implements Cancellable {
     private float duration;
     private boolean cancel;
 
-    @Deprecated
+    @Deprecated(since = "1.21")
     public EntityCombustEvent(@NotNull final Entity combustee, final int duration) {
         this(combustee, (float) duration);
     }
@@ -66,7 +66,7 @@ public class EntityCombustEvent extends EntityEvent implements Cancellable {
      * @see #setDuration(float)
      * @deprecated duration is now a float
      */
-    @Deprecated(forRemoval = true)
+    @Deprecated(since = "1.21", forRemoval = true)
     public void setDuration(int duration) {
         this.duration = duration;
     }

paper-api/src/main/java/org/bukkit/event/entity/EntityCreatePortalEvent.java

@@ -14,7 +14,7 @@ import org.jetbrains.annotations.NotNull;
  *
  * @deprecated Use {@link PortalCreateEvent}
  */
-@Deprecated
+@Deprecated(since = "1.14.1")
 public class EntityCreatePortalEvent extends EntityEvent implements Cancellable {
     private static final HandlerList handlers = new HandlerList();
     private final List<BlockState> blocks;

paper-api/src/main/java/org/bukkit/event/entity/EntityDamageByBlockEvent.java

@@ -17,7 +17,7 @@ public class EntityDamageByBlockEvent extends EntityDamageEvent {
     private final Block damager;
     private final BlockState damagerState;
 
-    @Deprecated(forRemoval = true)
+    @Deprecated(since = "1.20.4", forRemoval = true)
     public EntityDamageByBlockEvent(@Nullable final Block damager, @NotNull final Entity damagee, @NotNull final DamageCause cause, final double damage) {
         this(damager, (damager != null) ? damager.getState() : null, damagee, cause, (damager != null) ? DamageSource.builder(DamageType.GENERIC).withDamageLocation(damager.getLocation()).build() : DamageSource.builder(DamageType.GENERIC).build(), damage);
     }
@@ -28,7 +28,7 @@ public class EntityDamageByBlockEvent extends EntityDamageEvent {
         this.damagerState = damagerState;
     }
 
-    @Deprecated(forRemoval = true)
+    @Deprecated(since = "1.20.4", forRemoval = true)
     public EntityDamageByBlockEvent(@Nullable final Block damager, @NotNull final Entity damagee, @NotNull final DamageCause cause, @NotNull final Map<DamageModifier, Double> modifiers, @NotNull final Map<DamageModifier, ? extends Function<? super Double, Double>> modifierFunctions) {
         this(damager, (damager != null) ? damager.getState() : null, damagee, cause, (damager != null) ? DamageSource.builder(DamageType.GENERIC).withDamageLocation(damager.getLocation()).build() : DamageSource.builder(DamageType.GENERIC).build(), modifiers, modifierFunctions);
     }

paper-api/src/main/java/org/bukkit/event/entity/EntityDamageByEntityEvent.java

@@ -13,7 +13,7 @@ import org.jetbrains.annotations.NotNull;
 public class EntityDamageByEntityEvent extends EntityDamageEvent {
     private final Entity damager;
 
-    @Deprecated(forRemoval = true)
+    @Deprecated(since = "1.20.4", forRemoval = true)
     public EntityDamageByEntityEvent(@NotNull final Entity damager, @NotNull final Entity damagee, @NotNull final DamageCause cause, final double damage) {
         this(damager, damagee, cause, DamageSource.builder(DamageType.GENERIC).withCausingEntity(damager).withDirectEntity(damager).build(), damage);
     }
@@ -23,7 +23,7 @@ public class EntityDamageByEntityEvent extends EntityDamageEvent {
         this.damager = damager;
     }
 
-    @Deprecated(forRemoval = true)
+    @Deprecated(since = "1.20.4", forRemoval = true)
     public EntityDamageByEntityEvent(@NotNull final Entity damager, @NotNull final Entity damagee, @NotNull final DamageCause cause, @NotNull final Map<DamageModifier, Double> modifiers, @NotNull final Map<DamageModifier, ? extends Function<? super Double, Double>> modifierFunctions) {
         this(damager, damagee, cause, DamageSource.builder(DamageType.GENERIC).withCausingEntity(damager).withDirectEntity(damager).build(), modifiers, modifierFunctions);
     }