CraftBlock - fix applyBoneMeal false result (#12407)

* Update adventure to 4.19.0

The update only includes a new configuration for MiniMessage,
specifically one to prevent it from emitting virtual components.
As virtual components break the generated component tree, items quickly
become unstackable with items generated before adventure 4.18.

Plugin developers may construct their own mini message instance which
will emit virtual components if they so choose.

* Bump to adventure 4.20.0

.editorconfig

@@ -1,32 +1,32 @@
 [*]
-charset=utf-8
-end_of_line=lf
-insert_final_newline=true
-indent_style=space
-indent_size=4
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 4
 ij_any_block_comment_add_space = false
 ij_any_block_comment_at_first_column = false
 ij_any_line_comment_at_first_column = false
 ij_any_line_comment_add_space = true
 
 [*.tiny]
-indent_style=tab
+indent_style = tab
 
 [*.bat]
-end_of_line=crlf
+end_of_line = crlf
 
 [*.yml]
-indent_size=2
+indent_size = 2
 
 [*.patch]
-trim_trailing_whitespace=false
+trim_trailing_whitespace = false
 
 [*.java]
 ij_continuation_indent_size = 4
 ij_java_class_count_to_use_import_on_demand = 999999
 ij_java_insert_inner_class_imports = false
 ij_java_names_count_to_use_import_on_demand = 999999
-ij_java_imports_layout = *,|,$*
+ij_java_imports_layout = *, |, $*
 ij_java_generate_final_locals = true
 ij_java_generate_final_parameters = true
 ij_java_method_parameters_new_line_after_left_paren = true
@@ -40,5 +40,5 @@ ij_java_use_fq_class_names = true
 [paper-server/src/minecraft/resources/data/**/*.json]
 indent_size = 2
 
-[paper-api-generator/generated/**/*.java]
-ij_java_imports_layout = $*,|,*
+[paper-api/src/generated/java/**/*.java]
+ij_java_imports_layout = $*, |, *

CONTRIBUTING.md

@@ -208,7 +208,8 @@ required.
   with `// Paper end - <COMMIT DESCRIPTION>`.
 - One-line changes should have `// Paper - <COMMIT DESCRIPTION>` at the end of the line.
 
-> [!NOTE] These comments are incredibly important to be able to keep track of changes
+> [!NOTE]
+> These comments are incredibly important to be able to keep track of changes
 > across files and to remember what they are for, even a decade into the future.
 
 Here's an example of how to mark changes by Paper:
@@ -263,6 +264,40 @@ are assumed to be non-null by default. For less obvious placing such as on gener
 **For other classes**: Keep using both `@Nullable` and `@NotNull` from `org.jetbrains.annotations`. These
 will be replaced later.
 
+### API checks
+
+When performing API-related checks where an exception needs to be thrown under specific conditions, you should use the `Preconditions` class.
+
+#### Checking Method Arguments
+To validate method arguments, use `Preconditions#checkArgument`. This will throw an `IllegalArgumentException` if the condition is not met.
+> Don't use Preconditions#checkNotNull, as it throws a NullPointerException, which makes it harder to determine whether the error was caused by an internal issue or invalid arguments.
+
+ex:
+```java
+@Override
+public void sendMessage(Player player, Component message) {
+    Preconditions.checkArgument(player != null, "player cannot be null");
+    Preconditions.checkArgument(player.isOnline(), "player %s must be online", player.getName());
+    Preconditions.checkArgument(message != null, "message cannot be null");
+    // rest of code
+}
+```
+
+#### Checking Object State
+To validate the state of an object inside a method, use `Preconditions#checkState`. This will throw an `IllegalStateException` if the condition is not met.
+ex:
+```java
+private Player player;
+
+@Override
+public void sendMessage(Component message) {
+    Preconditions.checkArgument(message != null, "message cannot be null");
+    Preconditions.checkState(this.player != null, "player cannot be null");
+    Preconditions.checkState(this.player.isOnline(), "player %s must be online", this.player.getName());
+    // rest of code
+}
+```
+
 ## Access Transformers
 Sometimes, Vanilla code already contains a field, method, or type you want to access
 but the visibility is too low (e.g. a private field in an entity class). Paper can use access transformers

build-data/mappings-patch.tiny

@@ -1,4 +1,4 @@
-tiny	2	0	spigot	mojang+yarn
+tiny	2	0	spigot	mojang
 
 # Originally DistanceManager, which also implements DistanceManager, so clashes since the implemented class
 # is imported and not fully qualified. Easiest fix is to just change the name

build-data/paper.at

@@ -186,6 +186,7 @@ public net.minecraft.world.entity.Entity getEncodeId()Ljava/lang/String;
 public net.minecraft.world.entity.Entity getFireImmuneTicks()I
 public net.minecraft.world.entity.Entity getSharedFlag(I)Z
 public net.minecraft.world.entity.Entity hasVisualFire
+public net.minecraft.world.entity.Entity isAffectedByBlocks()Z
 public net.minecraft.world.entity.Entity isInBubbleColumn()Z
 public net.minecraft.world.entity.Entity isInRain()Z
 public net.minecraft.world.entity.Entity isInvulnerableToBase(Lnet/minecraft/world/damagesource/DamageSource;)Z
@@ -196,6 +197,7 @@ public net.minecraft.world.entity.Entity random
 public net.minecraft.world.entity.Entity setLevel(Lnet/minecraft/world/level/Level;)V
 public net.minecraft.world.entity.Entity setRot(FF)V
 public net.minecraft.world.entity.Entity setSharedFlag(IZ)V
+public net.minecraft.world.entity.Entity teleportPassengers()V
 public net.minecraft.world.entity.Entity unsetRemoved()V
 public net.minecraft.world.entity.Entity wasTouchingWater
 public net.minecraft.world.entity.ExperienceOrb count
@@ -490,6 +492,7 @@ public net.minecraft.world.inventory.BrewingStandMenu brewingStandData
 public net.minecraft.world.inventory.CraftingMenu access
 public net.minecraft.world.inventory.DispenserMenu dispenser
 public net.minecraft.world.inventory.HorseInventoryMenu SLOT_BODY_ARMOR
+public net.minecraft.world.inventory.HorseInventoryMenu horse
 public net.minecraft.world.inventory.MerchantContainer selectionHint
 public net.minecraft.world.inventory.Slot slot
 public net.minecraft.world.item.AdventureModePredicate predicates
@@ -503,6 +506,7 @@ public net.minecraft.world.item.ItemStackLinkedSet TYPE_AND_TAG
 public net.minecraft.world.item.JukeboxSongPlayer song
 public net.minecraft.world.item.MapItem createNewSavedData(Lnet/minecraft/world/level/Level;IIIZZLnet/minecraft/resources/ResourceKey;)Lnet/minecraft/world/level/saveddata/maps/MapId;
 public net.minecraft.world.item.StandingAndWallBlockItem wallBlock
+public net.minecraft.world.item.component.BundleContents$Mutable getMaxAmountToAdd(Lnet/minecraft/world/item/ItemStack;)I
 public net.minecraft.world.item.component.ItemContainerContents MAX_SIZE
 public net.minecraft.world.item.component.ItemContainerContents items
 public net.minecraft.world.item.context.UseOnContext <init>(Lnet/minecraft/world/level/Level;Lnet/minecraft/world/entity/player/Player;Lnet/minecraft/world/InteractionHand;Lnet/minecraft/world/item/ItemStack;Lnet/minecraft/world/phys/BlockHitResult;)V
@@ -602,6 +606,7 @@ public net.minecraft.world.level.block.entity.SculkSensorBlockEntity lastVibrati
 public net.minecraft.world.level.block.entity.SculkShriekerBlockEntity warningLevel
 public net.minecraft.world.level.block.entity.ShulkerBoxBlockEntity openCount
 public net.minecraft.world.level.block.entity.SignBlockEntity playerWhoMayEdit
+public net.minecraft.world.level.block.entity.SkullBlockEntity customName
 public net.minecraft.world.level.block.entity.SkullBlockEntity noteBlockSound
 public net.minecraft.world.level.block.entity.SkullBlockEntity owner
 public net.minecraft.world.level.block.entity.StructureBlockEntity author
@@ -622,9 +627,16 @@ public net.minecraft.world.level.block.entity.TheEndGatewayBlockEntity exitPorta
 public net.minecraft.world.level.block.entity.TrialSpawnerBlockEntity trialSpawner
 public net.minecraft.world.level.block.entity.trialspawner.TrialSpawner isOminous
 public net.minecraft.world.level.block.entity.trialspawner.TrialSpawner stateAccessor
+public net.minecraft.world.level.block.entity.trialspawner.TrialSpawnerData cooldownEndsAt
 public net.minecraft.world.level.block.entity.trialspawner.TrialSpawnerData currentMobs
 public net.minecraft.world.level.block.entity.trialspawner.TrialSpawnerData detectedPlayers
+public net.minecraft.world.level.block.entity.trialspawner.TrialSpawnerData nextMobSpawnsAt
 public net.minecraft.world.level.block.entity.trialspawner.TrialSpawnerData nextSpawnData
+public net.minecraft.world.level.block.entity.vault.VaultBlockEntity serverData
+public net.minecraft.world.level.block.entity.vault.VaultServerData getRewardedPlayers()Ljava/util/Set;
+public net.minecraft.world.level.block.entity.vault.VaultServerData pauseStateUpdatingUntil(J)V
+public net.minecraft.world.level.block.entity.vault.VaultServerData stateUpdatingResumesAt()J
+public net.minecraft.world.level.block.entity.vault.VaultSharedData getConnectedPlayers()Ljava/util/Set;
 public net.minecraft.world.level.block.state.BlockBehaviour getMenuProvider(Lnet/minecraft/world/level/block/state/BlockState;Lnet/minecraft/world/level/Level;Lnet/minecraft/core/BlockPos;)Lnet/minecraft/world/MenuProvider;
 public net.minecraft.world.level.block.state.BlockBehaviour hasCollision
 public net.minecraft.world.level.block.state.BlockBehaviour$BlockStateBase destroySpeed
@@ -723,6 +735,7 @@ public-f net.minecraft.world.item.trading.MerchantOffer rewardExp
 public-f net.minecraft.world.item.trading.MerchantOffer xp
 public-f net.minecraft.world.level.LevelSettings hardcore
 public-f net.minecraft.world.level.LevelSettings levelName
+public-f net.minecraft.world.level.block.ChestBlock MENU_PROVIDER_COMBINER
 public-f net.minecraft.world.level.block.entity.BannerBlockEntity baseColor
 public-f net.minecraft.world.level.block.entity.trialspawner.TrialSpawner normalConfig
 public-f net.minecraft.world.level.block.entity.trialspawner.TrialSpawner ominousConfig

build-data/reobf-mappings-patch.tiny

@@ -10,7 +10,7 @@
 # a significant amount of time for us to track down every possible issue, so this file will likely be around and in
 # use - at least in some capacity - for a long time.
 
-tiny	2	0	mojang+yarn	spigot
+tiny	2	0	mojang	spigot
 
 # CraftBukkit changes type
 c	net/minecraft/server/level/ServerLevel	net/minecraft/server/level/WorldServer

build.gradle.kts

@@ -12,7 +12,7 @@ import java.nio.file.Path
 import kotlin.random.Random
 
 plugins {
-    id("io.papermc.paperweight.core") version "2.0.0-beta.8" apply false
+    id("io.papermc.paperweight.core") version "2.0.0-beta.14" apply false
 }
 
 subprojects {
@@ -38,6 +38,7 @@ subprojects {
         options.encoding = Charsets.UTF_8.name()
         options.release = 21
         options.isFork = true
+        options.compilerArgs.addAll(listOf("-Xlint:-deprecation", "-Xlint:-removal"))
     }
     tasks.withType<Javadoc> {
         options.encoding = Charsets.UTF_8.name()

paper-api-generator/build.gradle.kts

@@ -25,7 +25,7 @@ tasks.register<JavaExec>("generate") {
     dependsOn(tasks.check)
     mainClass.set("io.papermc.generator.Main")
     classpath(sourceSets.main.map { it.runtimeClasspath })
-    args(projectDir.toPath().resolve("generated").toString())
+    args(rootProject.layout.projectDirectory.dir("paper-api/src/generated/java").asFile.absolutePath)
     javaLauncher = javaToolchains.defaultJavaLauncher(project)
 }
 

paper-api-generator/src/main/java/io/papermc/generator/types/GeneratedKeyType.java

@@ -101,7 +101,6 @@ public class GeneratedKeyType<T, A> extends SimpleGenerator {
             .addCode("return $T.create($T.$L, $N);", TypedKey.class, RegistryKey.class, requireNonNull(REGISTRY_KEY_FIELD_NAMES.get(this.apiRegistryKey), "Missing field for " + this.apiRegistryKey), keyParam)
             .returns(returnType);
         if (this.publicCreateKeyMethod) {
-            create.addAnnotation(EXPERIMENTAL_API_ANNOTATION); // TODO remove once not experimental
             create.addJavadoc(CREATE_JAVADOC, this.apiType, this.registryKey.location().toString());
         }
         return create;
@@ -157,8 +156,6 @@ public class GeneratedKeyType<T, A> extends SimpleGenerator {
         if (allExperimental) {
             typeBuilder.addAnnotations(experimentalAnnotations(null)); // Update for Experimental API
             createMethod.addAnnotations(experimentalAnnotations(null)); // Update for Experimental API
-        } else {
-            typeBuilder.addAnnotation(EXPERIMENTAL_API_ANNOTATION); // TODO experimental API
         }
         return typeBuilder.addMethod(createMethod.build()).build();
     }

paper-api/build.gradle.kts

@@ -11,7 +11,7 @@ java {
 
 val annotationsVersion = "26.0.1"
 val bungeeCordChatVersion = "1.20-R0.2"
-val adventureVersion = "4.18.0"
+val adventureVersion = "4.20.0"
 val slf4jVersion = "2.0.9"
 val log4jVersion = "2.17.1"
 
@@ -93,7 +93,7 @@ dependencies {
     testRuntimeOnly("org.junit.platform:junit-platform-launcher")
 }
 
-val generatedApiPath: java.nio.file.Path = rootProject.projectDir.toPath().resolve("paper-api-generator/generated")
+val generatedApiPath: java.nio.file.Path = layout.projectDirectory.dir("src/generated/java").asFile.toPath()
 idea {
     module {
         generatedSourceDirs.add(generatedApiPath.toFile())
@@ -176,7 +176,7 @@ tasks.withType<Javadoc> {
         "https://guava.dev/releases/33.3.1-jre/api/docs/",
         "https://javadoc.io/doc/org.yaml/snakeyaml/2.2/",
         "https://javadoc.io/doc/org.jetbrains/annotations/$annotationsVersion/",
-        "https://javadoc.io/doc/org.joml/joml/1.10.8/index.html",
+        "https://javadoc.io/doc/org.joml/joml/1.10.8/",
         "https://www.javadoc.io/doc/com.google.code.gson/gson/2.11.0",
         "https://jspecify.dev/docs/api/",
         "https://jd.advntr.dev/api/$adventureVersion/",

paper-api/src/generated/java/io/papermc/paper/registry/keys/AttributeKeys.java

@@ -7,7 +7,6 @@ import io.papermc.paper.registry.RegistryKey;
 import io.papermc.paper.registry.TypedKey;
 import net.kyori.adventure.key.Key;
 import org.bukkit.attribute.Attribute;
-import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
 
 /**
@@ -25,7 +24,6 @@ import org.jspecify.annotations.NullMarked;
 })
 @GeneratedFrom("1.21.4")
 @NullMarked
-@ApiStatus.Experimental
 public final class AttributeKeys {
     /**
      * {@code minecraft:armor}

paper-api/src/generated/java/io/papermc/paper/registry/keys/BannerPatternKeys.java

@@ -7,7 +7,6 @@ import io.papermc.paper.registry.RegistryKey;
 import io.papermc.paper.registry.TypedKey;
 import net.kyori.adventure.key.Key;
 import org.bukkit.block.banner.PatternType;
-import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
 
 /**
@@ -25,7 +24,6 @@ import org.jspecify.annotations.NullMarked;
 })
 @GeneratedFrom("1.21.4")
 @NullMarked
-@ApiStatus.Experimental
 public final class BannerPatternKeys {
     /**
      * {@code minecraft:base}
@@ -337,7 +335,6 @@ public final class BannerPatternKeys {
      * @param key the value's key in the registry
      * @return a new typed key
      */
-    @ApiStatus.Experimental
     public static TypedKey<PatternType> create(final Key key) {
         return TypedKey.create(RegistryKey.BANNER_PATTERN, key);
     }

paper-api/src/generated/java/io/papermc/paper/registry/keys/BiomeKeys.java

@@ -7,7 +7,6 @@ import io.papermc.paper.registry.RegistryKey;
 import io.papermc.paper.registry.TypedKey;
 import net.kyori.adventure.key.Key;
 import org.bukkit.block.Biome;
-import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
 
 /**
@@ -25,7 +24,6 @@ import org.jspecify.annotations.NullMarked;
 })
 @GeneratedFrom("1.21.4")
 @NullMarked
-@ApiStatus.Experimental
 public final class BiomeKeys {
     /**
      * {@code minecraft:badlands}
@@ -491,7 +489,6 @@ public final class BiomeKeys {
      * @param key the value's key in the registry
      * @return a new typed key
      */
-    @ApiStatus.Experimental
     public static TypedKey<Biome> create(final Key key) {
         return TypedKey.create(RegistryKey.BIOME, key);
     }

paper-api/src/generated/java/io/papermc/paper/registry/keys/BlockTypeKeys.java

@@ -7,7 +7,6 @@ import io.papermc.paper.registry.RegistryKey;
 import io.papermc.paper.registry.TypedKey;
 import net.kyori.adventure.key.Key;
 import org.bukkit.block.BlockType;
-import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
 
 /**
@@ -25,7 +24,6 @@ import org.jspecify.annotations.NullMarked;
 })
 @GeneratedFrom("1.21.4")
 @NullMarked
-@ApiStatus.Experimental
 public final class BlockTypeKeys {
     /**
      * {@code minecraft:acacia_button}

paper-api/src/generated/java/io/papermc/paper/registry/keys/CatVariantKeys.java

@@ -7,7 +7,6 @@ import io.papermc.paper.registry.RegistryKey;
 import io.papermc.paper.registry.TypedKey;
 import net.kyori.adventure.key.Key;
 import org.bukkit.entity.Cat;
-import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
 
 /**
@@ -25,7 +24,6 @@ import org.jspecify.annotations.NullMarked;
 })
 @GeneratedFrom("1.21.4")
 @NullMarked
-@ApiStatus.Experimental
 public final class CatVariantKeys {
     /**
      * {@code minecraft:all_black}

paper-api/src/generated/java/io/papermc/paper/registry/keys/DamageTypeKeys.java

@@ -7,7 +7,6 @@ import io.papermc.paper.registry.RegistryKey;
 import io.papermc.paper.registry.TypedKey;
 import net.kyori.adventure.key.Key;
 import org.bukkit.damage.DamageType;
-import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
 
 /**
@@ -25,7 +24,6 @@ import org.jspecify.annotations.NullMarked;
 })
 @GeneratedFrom("1.21.4")
 @NullMarked
-@ApiStatus.Experimental
 public final class DamageTypeKeys {
     /**
      * {@code minecraft:arrow}
@@ -379,7 +377,6 @@ public final class DamageTypeKeys {
      * @param key the value's key in the registry
      * @return a new typed key
      */
-    @ApiStatus.Experimental
     public static TypedKey<DamageType> create(final Key key) {
         return TypedKey.create(RegistryKey.DAMAGE_TYPE, key);
     }

paper-api/src/generated/java/io/papermc/paper/registry/keys/EnchantmentKeys.java

@@ -7,7 +7,6 @@ import io.papermc.paper.registry.RegistryKey;
 import io.papermc.paper.registry.TypedKey;
 import net.kyori.adventure.key.Key;
 import org.bukkit.enchantments.Enchantment;
-import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
 
 /**
@@ -25,7 +24,6 @@ import org.jspecify.annotations.NullMarked;
 })
 @GeneratedFrom("1.21.4")
 @NullMarked
-@ApiStatus.Experimental
 public final class EnchantmentKeys {
     /**
      * {@code minecraft:aqua_affinity}
@@ -330,7 +328,6 @@ public final class EnchantmentKeys {
      * @param key the value's key in the registry
      * @return a new typed key
      */
-    @ApiStatus.Experimental
     public static TypedKey<Enchantment> create(final Key key) {
         return TypedKey.create(RegistryKey.ENCHANTMENT, key);
     }

paper-api/src/generated/java/io/papermc/paper/registry/keys/FluidKeys.java

@@ -7,7 +7,6 @@ import io.papermc.paper.registry.RegistryKey;
 import io.papermc.paper.registry.TypedKey;
 import net.kyori.adventure.key.Key;
 import org.bukkit.Fluid;
-import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
 
 /**
@@ -25,7 +24,6 @@ import org.jspecify.annotations.NullMarked;
 })
 @GeneratedFrom("1.21.4")
 @NullMarked
-@ApiStatus.Experimental
 public final class FluidKeys {
     /**
      * {@code minecraft:empty}

paper-api/src/generated/java/io/papermc/paper/registry/keys/FrogVariantKeys.java

@@ -7,7 +7,6 @@ import io.papermc.paper.registry.RegistryKey;
 import io.papermc.paper.registry.TypedKey;
 import net.kyori.adventure.key.Key;
 import org.bukkit.entity.Frog;
-import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
 
 /**
@@ -25,7 +24,6 @@ import org.jspecify.annotations.NullMarked;
 })
 @GeneratedFrom("1.21.4")
 @NullMarked
-@ApiStatus.Experimental
 public final class FrogVariantKeys {
     /**
      * {@code minecraft:cold}

paper-api/src/generated/java/io/papermc/paper/registry/keys/GameEventKeys.java

@@ -7,7 +7,6 @@ import io.papermc.paper.registry.RegistryKey;
 import io.papermc.paper.registry.TypedKey;
 import net.kyori.adventure.key.Key;
 import org.bukkit.GameEvent;
-import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
 
 /**
@@ -25,7 +24,6 @@ import org.jspecify.annotations.NullMarked;
 })
 @GeneratedFrom("1.21.4")
 @NullMarked
-@ApiStatus.Experimental
 public final class GameEventKeys {
     /**
      * {@code minecraft:block_activate}
@@ -456,7 +454,6 @@ public final class GameEventKeys {
      * @param key the value's key in the registry
      * @return a new typed key
      */
-    @ApiStatus.Experimental
     public static TypedKey<GameEvent> create(final Key key) {
         return TypedKey.create(RegistryKey.GAME_EVENT, key);
     }

paper-api/src/generated/java/io/papermc/paper/registry/keys/InstrumentKeys.java

@@ -7,7 +7,6 @@ import io.papermc.paper.registry.RegistryKey;
 import io.papermc.paper.registry.TypedKey;
 import net.kyori.adventure.key.Key;
 import org.bukkit.MusicInstrument;
-import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
 
 /**
@@ -25,7 +24,6 @@ import org.jspecify.annotations.NullMarked;
 })
 @GeneratedFrom("1.21.4")
 @NullMarked
-@ApiStatus.Experimental
 public final class InstrumentKeys {
     /**
      * {@code minecraft:admire_goat_horn}
@@ -92,7 +90,6 @@ public final class InstrumentKeys {
      * @param key the value's key in the registry
      * @return a new typed key
      */
-    @ApiStatus.Experimental
     public static TypedKey<MusicInstrument> create(final Key key) {
         return TypedKey.create(RegistryKey.INSTRUMENT, key);
     }

paper-api/src/generated/java/io/papermc/paper/registry/keys/ItemTypeKeys.java

@@ -7,7 +7,6 @@ import io.papermc.paper.registry.RegistryKey;
 import io.papermc.paper.registry.TypedKey;
 import net.kyori.adventure.key.Key;
 import org.bukkit.inventory.ItemType;
-import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
 
 /**
@@ -25,7 +24,6 @@ import org.jspecify.annotations.NullMarked;
 })
 @GeneratedFrom("1.21.4")
 @NullMarked
-@ApiStatus.Experimental
 public final class ItemTypeKeys {
     /**
      * {@code minecraft:acacia_boat}

paper-api/src/generated/java/io/papermc/paper/registry/keys/JukeboxSongKeys.java

@@ -7,7 +7,6 @@ import io.papermc.paper.registry.RegistryKey;
 import io.papermc.paper.registry.TypedKey;
 import net.kyori.adventure.key.Key;
 import org.bukkit.JukeboxSong;
-import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
 
 /**
@@ -25,7 +24,6 @@ import org.jspecify.annotations.NullMarked;
 })
 @GeneratedFrom("1.21.4")
 @NullMarked
-@ApiStatus.Experimental
 public final class JukeboxSongKeys {
     /**
      * {@code minecraft:11}
@@ -169,7 +167,6 @@ public final class JukeboxSongKeys {
      * @param key the value's key in the registry
      * @return a new typed key
      */
-    @ApiStatus.Experimental
     public static TypedKey<JukeboxSong> create(final Key key) {
         return TypedKey.create(RegistryKey.JUKEBOX_SONG, key);
     }

paper-api/src/generated/java/io/papermc/paper/registry/keys/MapDecorationTypeKeys.java

@@ -7,7 +7,6 @@ import io.papermc.paper.registry.RegistryKey;
 import io.papermc.paper.registry.TypedKey;
 import net.kyori.adventure.key.Key;
 import org.bukkit.map.MapCursor;
-import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
 
 /**
@@ -25,7 +24,6 @@ import org.jspecify.annotations.NullMarked;
 })
 @GeneratedFrom("1.21.4")
 @NullMarked
-@ApiStatus.Experimental
 public final class MapDecorationTypeKeys {
     /**
      * {@code minecraft:banner_black}

paper-api/src/generated/java/io/papermc/paper/registry/keys/MenuTypeKeys.java

@@ -7,7 +7,6 @@ import io.papermc.paper.registry.RegistryKey;
 import io.papermc.paper.registry.TypedKey;
 import net.kyori.adventure.key.Key;
 import org.bukkit.inventory.MenuType;
-import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
 
 /**
@@ -25,7 +24,6 @@ import org.jspecify.annotations.NullMarked;
 })
 @GeneratedFrom("1.21.4")
 @NullMarked
-@ApiStatus.Experimental
 public final class MenuTypeKeys {
     /**
      * {@code minecraft:anvil}

paper-api/src/generated/java/io/papermc/paper/registry/keys/MobEffectKeys.java

@@ -7,7 +7,6 @@ import io.papermc.paper.registry.RegistryKey;
 import io.papermc.paper.registry.TypedKey;
 import net.kyori.adventure.key.Key;
 import org.bukkit.potion.PotionEffectType;
-import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
 
 /**
@@ -25,7 +24,6 @@ import org.jspecify.annotations.NullMarked;
 })
 @GeneratedFrom("1.21.4")
 @NullMarked
-@ApiStatus.Experimental
 public final class MobEffectKeys {
     /**
      * {@code minecraft:absorption}

paper-api/src/generated/java/io/papermc/paper/registry/keys/PaintingVariantKeys.java

@@ -7,7 +7,6 @@ import io.papermc.paper.registry.RegistryKey;
 import io.papermc.paper.registry.TypedKey;
 import net.kyori.adventure.key.Key;
 import org.bukkit.Art;
-import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
 
 /**
@@ -25,7 +24,6 @@ import org.jspecify.annotations.NullMarked;
 })
 @GeneratedFrom("1.21.4")
 @NullMarked
-@ApiStatus.Experimental
 public final class PaintingVariantKeys {
     /**
      * {@code minecraft:alban}
@@ -386,7 +384,6 @@ public final class PaintingVariantKeys {
      * @param key the value's key in the registry
      * @return a new typed key
      */
-    @ApiStatus.Experimental
     public static TypedKey<Art> create(final Key key) {
         return TypedKey.create(RegistryKey.PAINTING_VARIANT, key);
     }

paper-api/src/generated/java/io/papermc/paper/registry/keys/SoundEventKeys.java

@@ -7,7 +7,6 @@ import io.papermc.paper.registry.RegistryKey;
 import io.papermc.paper.registry.TypedKey;
 import net.kyori.adventure.key.Key;
 import org.bukkit.Sound;
-import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
 
 /**
@@ -25,7 +24,6 @@ import org.jspecify.annotations.NullMarked;
 })
 @GeneratedFrom("1.21.4")
 @NullMarked
-@ApiStatus.Experimental
 public final class SoundEventKeys {
     /**
      * {@code minecraft:ambient.basalt_deltas.additions}

paper-api/src/generated/java/io/papermc/paper/registry/keys/StructureKeys.java

@@ -7,7 +7,6 @@ import io.papermc.paper.registry.RegistryKey;
 import io.papermc.paper.registry.TypedKey;
 import net.kyori.adventure.key.Key;
 import org.bukkit.generator.structure.Structure;
-import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
 
 /**
@@ -25,7 +24,6 @@ import org.jspecify.annotations.NullMarked;
 })
 @GeneratedFrom("1.21.4")
 @NullMarked
-@ApiStatus.Experimental
 public final class StructureKeys {
     /**
      * {@code minecraft:ancient_city}
@@ -274,7 +272,6 @@ public final class StructureKeys {
      * @param key the value's key in the registry
      * @return a new typed key
      */
-    @ApiStatus.Experimental
     public static TypedKey<Structure> create(final Key key) {
         return TypedKey.create(RegistryKey.STRUCTURE, key);
     }

paper-api/src/generated/java/io/papermc/paper/registry/keys/StructureTypeKeys.java

@@ -7,7 +7,6 @@ import io.papermc.paper.registry.RegistryKey;
 import io.papermc.paper.registry.TypedKey;
 import net.kyori.adventure.key.Key;
 import org.bukkit.generator.structure.StructureType;
-import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
 
 /**
@@ -25,7 +24,6 @@ import org.jspecify.annotations.NullMarked;
 })
 @GeneratedFrom("1.21.4")
 @NullMarked
-@ApiStatus.Experimental
 public final class StructureTypeKeys {
     /**
      * {@code minecraft:buried_treasure}

paper-api/src/generated/java/io/papermc/paper/registry/keys/TrimMaterialKeys.java

@@ -7,7 +7,6 @@ import io.papermc.paper.registry.RegistryKey;
 import io.papermc.paper.registry.TypedKey;
 import net.kyori.adventure.key.Key;
 import org.bukkit.inventory.meta.trim.TrimMaterial;
-import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
 
 /**
@@ -25,7 +24,6 @@ import org.jspecify.annotations.NullMarked;
 })
 @GeneratedFrom("1.21.4")
 @NullMarked
-@ApiStatus.Experimental
 public final class TrimMaterialKeys {
     /**
      * {@code minecraft:amethyst}
@@ -113,7 +111,6 @@ public final class TrimMaterialKeys {
      * @param key the value's key in the registry
      * @return a new typed key
      */
-    @ApiStatus.Experimental
     public static TypedKey<TrimMaterial> create(final Key key) {
         return TypedKey.create(RegistryKey.TRIM_MATERIAL, key);
     }

paper-api/src/generated/java/io/papermc/paper/registry/keys/TrimPatternKeys.java

@@ -7,7 +7,6 @@ import io.papermc.paper.registry.RegistryKey;
 import io.papermc.paper.registry.TypedKey;
 import net.kyori.adventure.key.Key;
 import org.bukkit.inventory.meta.trim.TrimPattern;
-import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
 
 /**
@@ -25,7 +24,6 @@ import org.jspecify.annotations.NullMarked;
 })
 @GeneratedFrom("1.21.4")
 @NullMarked
-@ApiStatus.Experimental
 public final class TrimPatternKeys {
     /**
      * {@code minecraft:bolt}
@@ -162,7 +160,6 @@ public final class TrimPatternKeys {
      * @param key the value's key in the registry
      * @return a new typed key
      */
-    @ApiStatus.Experimental
     public static TypedKey<TrimPattern> create(final Key key) {
         return TypedKey.create(RegistryKey.TRIM_PATTERN, key);
     }

paper-api/src/generated/java/io/papermc/paper/registry/keys/VillagerProfessionKeys.java

@@ -7,7 +7,6 @@ import io.papermc.paper.registry.RegistryKey;
 import io.papermc.paper.registry.TypedKey;
 import net.kyori.adventure.key.Key;
 import org.bukkit.entity.Villager;
-import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
 
 /**
@@ -25,7 +24,6 @@ import org.jspecify.annotations.NullMarked;
 })
 @GeneratedFrom("1.21.4")
 @NullMarked
-@ApiStatus.Experimental
 public final class VillagerProfessionKeys {
     /**
      * {@code minecraft:armorer}

paper-api/src/generated/java/io/papermc/paper/registry/keys/VillagerTypeKeys.java

@@ -7,7 +7,6 @@ import io.papermc.paper.registry.RegistryKey;
 import io.papermc.paper.registry.TypedKey;
 import net.kyori.adventure.key.Key;
 import org.bukkit.entity.Villager;
-import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
 
 /**
@@ -25,7 +24,6 @@ import org.jspecify.annotations.NullMarked;
 })
 @GeneratedFrom("1.21.4")
 @NullMarked
-@ApiStatus.Experimental
 public final class VillagerTypeKeys {
     /**
      * {@code minecraft:desert}

paper-api/src/generated/java/io/papermc/paper/registry/keys/WolfVariantKeys.java

@@ -7,7 +7,6 @@ import io.papermc.paper.registry.RegistryKey;
 import io.papermc.paper.registry.TypedKey;
 import net.kyori.adventure.key.Key;
 import org.bukkit.entity.Wolf;
-import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
 
 /**
@@ -25,7 +24,6 @@ import org.jspecify.annotations.NullMarked;
 })
 @GeneratedFrom("1.21.4")
 @NullMarked
-@ApiStatus.Experimental
 public final class WolfVariantKeys {
     /**
      * {@code minecraft:ashen}
@@ -99,7 +97,6 @@ public final class WolfVariantKeys {
      * @param key the value's key in the registry
      * @return a new typed key
      */
-    @ApiStatus.Experimental
     public static TypedKey<Wolf.Variant> create(final Key key) {
         return TypedKey.create(RegistryKey.WOLF_VARIANT, key);
     }

paper-api/src/main/java/com/destroystokyo/paper/NamespacedTag.java

@@ -5,6 +5,7 @@ import java.util.Locale;
 import java.util.UUID;
 import java.util.regex.Pattern;
 import org.bukkit.plugin.Plugin;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 
 /**
@@ -126,6 +127,7 @@ public final class NamespacedTag implements com.destroystokyo.paper.Namespaced {
      * @deprecated should never be used by plugins, for internal use only!!
      */
     @Deprecated
+    @ApiStatus.Internal
     public static NamespacedTag randomKey() {
         return new NamespacedTag(BUKKIT, UUID.randomUUID().toString());
     }

paper-api/src/main/java/com/destroystokyo/paper/event/entity/SkeletonHorseTrapEvent.java

@@ -1,6 +1,5 @@
 package com.destroystokyo.paper.event.entity;
 
-import com.google.common.collect.ImmutableList;
 import java.util.List;
 import org.bukkit.entity.HumanEntity;
 import org.bukkit.entity.SkeletonHorse;
@@ -21,12 +20,6 @@ public class SkeletonHorseTrapEvent extends EntityEvent implements Cancellable {
     private final List<HumanEntity> eligibleHumans;
     private boolean cancelled;
 
-    @Deprecated
-    @ApiStatus.Internal
-    public SkeletonHorseTrapEvent(final SkeletonHorse horse) {
-        this(horse, ImmutableList.of());
-    }
-
     @ApiStatus.Internal
     public SkeletonHorseTrapEvent(final SkeletonHorse horse, final List<HumanEntity> eligibleHumans) {
         super(horse);

paper-api/src/main/java/com/destroystokyo/paper/event/player/IllegalPacketEvent.java

@@ -10,7 +10,7 @@ import org.jetbrains.annotations.Nullable;
 /**
  * @deprecated Not used
  */
-@Deprecated(since = "1.16.4")
+@Deprecated(since = "1.16.4", forRemoval = true)
 public class IllegalPacketEvent extends PlayerEvent {
 
     private static final HandlerList HANDLER_LIST = new HandlerList();

paper-api/src/main/java/com/destroystokyo/paper/event/player/PlayerArmorChangeEvent.java

@@ -5,6 +5,7 @@ import org.bukkit.Material;
 import org.bukkit.entity.Player;
 import org.bukkit.event.HandlerList;
 import org.bukkit.event.player.PlayerEvent;
+import org.bukkit.inventory.EquipmentSlot;
 import org.bukkit.inventory.ItemStack;
 import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
@@ -16,8 +17,10 @@ import static org.bukkit.Material.*;
  * Called when the player themselves change their armor items
  * <p>
  * Not currently called for environmental factors though it <strong>MAY BE IN THE FUTURE</strong>
+ * @apiNote Use {@link io.papermc.paper.event.entity.EntityEquipmentChangedEvent} for all entity equipment changes
  */
 @NullMarked
+@ApiStatus.Obsolete(since = "1.21.4")
 public class PlayerArmorChangeEvent extends PlayerEvent {
 
     private static final HandlerList HANDLER_LIST = new HandlerList();
@@ -38,11 +41,27 @@ public class PlayerArmorChangeEvent extends PlayerEvent {
      * Gets the type of slot being altered.
      *
      * @return type of slot being altered
+     * @deprecated {@link SlotType} does not accurately represent what item types are valid in each slot. Use {@link #getSlot()} instead.
      */
+    @Deprecated(since = "1.21.4")
     public SlotType getSlotType() {
         return this.slotType;
     }
 
+    /**
+     * Gets the slot being altered.
+     *
+     * @return slot being altered
+     */
+    public EquipmentSlot getSlot() {
+        return switch (this.slotType) {
+            case HEAD -> EquipmentSlot.HEAD;
+            case CHEST -> EquipmentSlot.CHEST;
+            case LEGS -> EquipmentSlot.LEGS;
+            case FEET -> EquipmentSlot.FEET;
+        };
+    }
+
     /**
      * Gets the existing item that's being replaced
      *
@@ -70,6 +89,10 @@ public class PlayerArmorChangeEvent extends PlayerEvent {
         return HANDLER_LIST;
     }
 
+    /**
+     * @deprecated {@link SlotType} does not accurately represent what item types are valid in each slot.
+     */
+    @Deprecated(since = "1.21.4")
     public enum SlotType {
         HEAD(NETHERITE_HELMET, DIAMOND_HELMET, GOLDEN_HELMET, IRON_HELMET, CHAINMAIL_HELMET, LEATHER_HELMET, CARVED_PUMPKIN, PLAYER_HEAD, SKELETON_SKULL, ZOMBIE_HEAD, CREEPER_HEAD, WITHER_SKELETON_SKULL, TURTLE_HELMET, DRAGON_HEAD, PIGLIN_HEAD),
         CHEST(NETHERITE_CHESTPLATE, DIAMOND_CHESTPLATE, GOLDEN_CHESTPLATE, IRON_CHESTPLATE, CHAINMAIL_CHESTPLATE, LEATHER_CHESTPLATE, ELYTRA),

paper-api/src/main/java/com/destroystokyo/paper/event/player/PlayerClientOptionsChangeEvent.java

@@ -30,20 +30,6 @@ public class PlayerClientOptionsChangeEvent extends PlayerEvent {
     private final boolean textFilteringEnabled;
     private final ParticleVisibility particleVisibility;
 
-    @Deprecated
-    public PlayerClientOptionsChangeEvent(final Player player, final String locale, final int viewDistance, final ChatVisibility chatVisibility, final boolean chatColors, final SkinParts skinParts, final MainHand mainHand) {
-        super(player);
-        this.locale = locale;
-        this.viewDistance = viewDistance;
-        this.chatVisibility = chatVisibility;
-        this.chatColors = chatColors;
-        this.skinparts = skinParts;
-        this.mainHand = mainHand;
-        this.allowsServerListings = false;
-        this.textFilteringEnabled = false;
-        this.particleVisibility = ParticleVisibility.ALL;
-    }
-
     @ApiStatus.Internal
     public PlayerClientOptionsChangeEvent(final Player player, final Map<ClientOption<?>, ?> options) {
         super(player);

paper-api/src/main/java/com/destroystokyo/paper/event/player/PlayerUseUnknownEntityEvent.java

@@ -11,7 +11,7 @@ import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
 /**
- * Represents an event that is called when a player right-clicks an unknown entity.
+ * Represents an event that is called when a player clicks an unknown entity.
  * Useful for plugins dealing with virtual entities (entities that aren't actually spawned on the server).
  * <br>
  * This event may be called multiple times per interaction with different interaction hands

paper-api/src/main/java/com/destroystokyo/paper/event/profile/ProfileWhitelistVerifyEvent.java

@@ -50,12 +50,6 @@ public class ProfileWhitelistVerifyEvent extends Event {
     private boolean whitelisted;
     private @Nullable Component kickMessage;
 
-    @Deprecated
-    @ApiStatus.Internal
-    public ProfileWhitelistVerifyEvent(final PlayerProfile profile, final boolean whitelistEnabled, final boolean whitelisted, final boolean isOp, final @Nullable String kickMessage) {
-        this(profile, whitelistEnabled, whitelisted, isOp, kickMessage == null ? null : LegacyComponentSerializer.legacySection().deserialize(kickMessage));
-    }
-
     @ApiStatus.Internal
     public ProfileWhitelistVerifyEvent(final PlayerProfile profile, final boolean whitelistEnabled, final boolean whitelisted, final boolean isOp, final @Nullable Component kickMessage) {
         this.profile = profile;

paper-api/src/main/java/com/destroystokyo/paper/event/server/PaperServerListPingEvent.java

@@ -55,18 +55,6 @@ public class PaperServerListPingEvent extends ServerListPingEvent implements Can
     private boolean originalPlayerCount = true;
     private Object[] players;
 
-    @Deprecated
-    @ApiStatus.Internal
-    public PaperServerListPingEvent(@NotNull StatusClient client, @NotNull String motd, int numPlayers, int maxPlayers,
-            @NotNull String version, int protocolVersion, @Nullable CachedServerIcon favicon) {
-        super("", client.getAddress().getAddress(), motd, numPlayers, maxPlayers);
-        this.client = client;
-        this.numPlayers = numPlayers;
-        this.version = version;
-        this.protocolVersion = protocolVersion;
-        setServerIcon(favicon);
-    }
-
     @ApiStatus.Internal
     public PaperServerListPingEvent(@NotNull StatusClient client, @NotNull net.kyori.adventure.text.Component motd, int numPlayers, int maxPlayers,
                                     @NotNull String version, int protocolVersion, @Nullable CachedServerIcon favicon) {

paper-api/src/main/java/io/papermc/paper/command/brigadier/CommandRegistrationFlag.java

@@ -10,5 +10,10 @@ import org.jetbrains.annotations.ApiStatus;
  */
 @ApiStatus.Internal
 public enum CommandRegistrationFlag {
+
+    /**
+     * @deprecated This is the default behavior now.
+     */
+    @Deprecated(since = "1.21.4")
     FLATTEN_ALIASES
 }

paper-api/src/main/java/io/papermc/paper/command/brigadier/CommandSourceStack.java

@@ -1,5 +1,7 @@
 package io.papermc.paper.command.brigadier;
 
+import com.mojang.brigadier.RedirectModifier;
+import com.mojang.brigadier.tree.CommandNode;
 import org.bukkit.Location;
 import org.bukkit.command.CommandSender;
 import org.bukkit.entity.Entity;
@@ -48,4 +50,24 @@ public interface CommandSourceStack {
      * @return entity that executes this command
      */
     @Nullable Entity getExecutor();
+
+    /**
+     * Creates a new CommandSourceStack object with a different location for redirecting commands to other nodes.
+     *
+     * @param location The location to create a new CommandSourceStack object with
+     * @return The newly created CommandSourceStack
+     * @see #getLocation()
+     * @see com.mojang.brigadier.builder.ArgumentBuilder#fork(CommandNode, RedirectModifier)
+     */
+    CommandSourceStack withLocation(Location location);
+
+    /**
+     * Creates a new CommandSourceStack object with a different executor for redirecting commands to other nodes.
+     *
+     * @param executor The executing entity to create a new CommandSourceStack object with
+     * @return The newly created CommandSourceStack
+     * @see #getExecutor()
+     * @see com.mojang.brigadier.builder.ArgumentBuilder#fork(CommandNode, RedirectModifier)
+     */
+    CommandSourceStack withExecutor(Entity executor);
 }

paper-api/src/main/java/io/papermc/paper/command/brigadier/Commands.java

@@ -113,6 +113,7 @@ public interface Commands extends Registrar {
      * <p>Commands have certain overriding behavior:
      * <ul>
      *   <li>Aliases will not override already existing commands (excluding namespaced ones)</li>
+     *   <li>Aliases are <b>not</b> Brigadier redirects, they just copy the command to a different label</li>
      *   <li>The main command/namespaced label will override already existing commands</li>
      * </ul>
      *
@@ -129,6 +130,7 @@ public interface Commands extends Registrar {
      * <p>Commands have certain overriding behavior:
      * <ul>
      *   <li>Aliases will not override already existing commands (excluding namespaced ones)</li>
+     *   <li>Aliases are <b>not</b> Brigadier redirects, they just copy the command to a different label</li>
      *   <li>The main command/namespaced label will override already existing commands</li>
      * </ul>
      *
@@ -146,6 +148,7 @@ public interface Commands extends Registrar {
      * <p>Commands have certain overriding behavior:
      * <ul>
      *   <li>Aliases will not override already existing commands (excluding namespaced ones)</li>
+     *   <li>Aliases are <b>not</b> Brigadier redirects, they just copy the command to a different label</li>
      *   <li>The main command/namespaced label will override already existing commands</li>
      * </ul>
      *
@@ -163,6 +166,7 @@ public interface Commands extends Registrar {
      * <p>Commands have certain overriding behavior:
      * <ul>
      *   <li>Aliases will not override already existing commands (excluding namespaced ones)</li>
+     *   <li>Aliases are <b>not</b> Brigadier redirects, they just copy the command to a different label</li>
      *   <li>The main command/namespaced label will override already existing commands</li>
      * </ul>
      *
@@ -179,6 +183,7 @@ public interface Commands extends Registrar {
      * <p>Commands have certain overriding behavior:
      * <ul>
      *   <li>Aliases will not override already existing commands (excluding namespaced ones)</li>
+     *   <li>Aliases are <b>not</b> Brigadier redirects, they just copy the command to a different label</li>
      *   <li>The main command/namespaced label will override already existing commands</li>
      * </ul>
      *

paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/ArgumentTypes.java

@@ -7,6 +7,7 @@ import io.papermc.paper.command.brigadier.argument.range.IntegerRangeProvider;
 import io.papermc.paper.command.brigadier.argument.resolvers.BlockPositionResolver;
 import io.papermc.paper.command.brigadier.argument.resolvers.FinePositionResolver;
 import io.papermc.paper.command.brigadier.argument.resolvers.PlayerProfileListResolver;
+import io.papermc.paper.command.brigadier.argument.resolvers.RotationResolver;
 import io.papermc.paper.command.brigadier.argument.resolvers.selector.EntitySelectorArgumentResolver;
 import io.papermc.paper.command.brigadier.argument.resolvers.selector.PlayerSelectorArgumentResolver;
 import io.papermc.paper.entity.LookAnchor;
@@ -123,6 +124,15 @@ public final class ArgumentTypes {
         return provider().finePosition(centerIntegers);
     }
 
+    /**
+     * A rotation argument.
+     *
+     * @return rotation argument
+     */
+    public static ArgumentType<RotationResolver> rotation() {
+        return provider().rotation();
+    }
+
     /**
      * A blockstate argument which will provide rich parsing for specifying
      * the specific block variant and then the block entity NBT if applicable.

paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/VanillaArgumentProvider.java

@@ -7,6 +7,7 @@ import io.papermc.paper.command.brigadier.argument.range.IntegerRangeProvider;
 import io.papermc.paper.command.brigadier.argument.resolvers.BlockPositionResolver;
 import io.papermc.paper.command.brigadier.argument.resolvers.FinePositionResolver;
 import io.papermc.paper.command.brigadier.argument.resolvers.PlayerProfileListResolver;
+import io.papermc.paper.command.brigadier.argument.resolvers.RotationResolver;
 import io.papermc.paper.command.brigadier.argument.resolvers.selector.EntitySelectorArgumentResolver;
 import io.papermc.paper.command.brigadier.argument.resolvers.selector.PlayerSelectorArgumentResolver;
 import io.papermc.paper.entity.LookAnchor;
@@ -57,6 +58,8 @@ interface VanillaArgumentProvider {
 
     ArgumentType<FinePositionResolver> finePosition(boolean centerIntegers);
 
+    ArgumentType<RotationResolver> rotation();
+
     ArgumentType<BlockState> blockState();
 
     ArgumentType<ItemStack> itemStack();

paper-api/src/main/java/io/papermc/paper/command/brigadier/argument/resolvers/RotationResolver.java

@@ -0,0 +1,16 @@
+package io.papermc.paper.command.brigadier.argument.resolvers;
+
+import io.papermc.paper.command.brigadier.CommandSourceStack;
+import io.papermc.paper.math.Rotation;
+import org.jetbrains.annotations.ApiStatus;
+
+/**
+ * An {@link ArgumentResolver} that's capable of resolving
+ * a rotation argument value using a {@link CommandSourceStack}.
+ *
+ * @see io.papermc.paper.command.brigadier.argument.ArgumentTypes#rotation()
+ */
+@ApiStatus.Experimental
+@ApiStatus.NonExtendable
+public interface RotationResolver extends ArgumentResolver<Rotation> {
+}

paper-api/src/main/java/io/papermc/paper/datacomponent/item/DamageResistant.java

@@ -21,9 +21,9 @@ public interface DamageResistant {
     }
 
     /**
-     * The types that this damage type is invincible tp.
+     * The types that this damage type is invincible to.
      *
-     * @return item
+     * @return the key of the tag holding the respective damage types.
      */
     @Contract(value = "-> new", pure = true)
     TagKey<DamageType> types();

paper-api/src/main/java/io/papermc/paper/datacomponent/item/consumable/ConsumeEffect.java

@@ -21,7 +21,7 @@ public interface ConsumeEffect {
      * Creates a consume effect that randomly teleports the entity on consumption.
      *
      * @param diameter diameter of random teleportation
-     * @return the effect
+     * @return the effect instance
      */
     @Contract(value = "_ -> new", pure = true)
     static TeleportRandomly teleportRandomlyEffect(final float diameter) {
@@ -29,21 +29,21 @@ public interface ConsumeEffect {
     }
 
     /**
-     * Creates a consume effect that gives status effects on consumption.
+     * Creates a consume effect that removes status effects on consumption.
      *
-     * @param key the sound effect to play
-     * @return the effect
+     * @param effects the potion effects to remove
+     * @return the effect instance
      */
     @Contract(value = "_ -> new", pure = true)
-    static RemoveStatusEffects removeEffects(final RegistryKeySet<PotionEffectType> key) {
-        return ConsumableTypesBridge.bridge().removeStatusEffects(key);
+    static RemoveStatusEffects removeEffects(final RegistryKeySet<PotionEffectType> effects) {
+        return ConsumableTypesBridge.bridge().removeStatusEffects(effects);
     }
 
     /**
      * Creates a consume effect that plays a sound on consumption.
      *
-     * @param key the sound effect to play
-     * @return the effect
+     * @param key the key sound effect to play
+     * @return the effect instance
      */
     @Contract(value = "_ -> new", pure = true)
     static PlaySound playSoundConsumeEffect(final Key key) {
@@ -53,7 +53,7 @@ public interface ConsumeEffect {
     /**
      * Creates a consume effect that clears all status effects.
      *
-     * @return effect instance
+     * @return the effect instance
      */
     @Contract(value = "-> new", pure = true)
     static ClearAllStatusEffects clearAllStatusEffects() {
@@ -61,17 +61,20 @@ public interface ConsumeEffect {
     }
 
     /**
-     * Creates a consume effect that gives status effects on consumption.
+     * Creates a consume effect that gives potion effects on consumption.
      *
      * @param effects     the potion effects to apply
-     * @param probability the probability of these effects being applied, between 0 and 1 inclusive.
-     * @return the effect
+     * @param probability the probability of these effects being applied, between 0 and 1 inclusive
+     * @return the effect instance
      */
     @Contract(value = "_, _ -> new", pure = true)
     static ApplyStatusEffects applyStatusEffects(final List<PotionEffect> effects, final float probability) {
         return ConsumableTypesBridge.bridge().applyStatusEffects(effects, probability);
     }
 
+    /**
+     * Represents a consumable effect that randomly teleports the entity on consumption.
+     */
     @ApiStatus.Experimental
     @ApiStatus.NonExtendable
     interface TeleportRandomly extends ConsumeEffect {
@@ -85,14 +88,14 @@ public interface ConsumeEffect {
     }
 
     /**
-     * Represents a consumable effect that removes status effects on consumption
+     * Represents a consumable effect that removes status effects on consumption.
      */
     @ApiStatus.Experimental
     @ApiStatus.NonExtendable
     interface RemoveStatusEffects extends ConsumeEffect {
 
         /**
-         * Potion effects to remove
+         * Potion effects to remove.
          *
          * @return effects
          */
@@ -107,7 +110,7 @@ public interface ConsumeEffect {
     interface PlaySound extends ConsumeEffect {
 
         /**
-         * Sound effect to play in the world
+         * Sound effect to play in the world.
          *
          * @return sound effect
          */
@@ -124,16 +127,16 @@ public interface ConsumeEffect {
     }
 
     /**
-     * Represents a consumable effect that applies effects based on a probability on consumption.
+     * Represents a consumable effect that applies potion effects based on a probability on consumption.
      */
     @ApiStatus.Experimental
     @ApiStatus.NonExtendable
     interface ApplyStatusEffects extends ConsumeEffect {
 
         /**
-         * Effect instances to grant
+         * Potion effect instances to grant.
          *
-         * @return effect
+         * @return potion effects
          */
         List<PotionEffect> effects();
 

paper-api/src/main/java/io/papermc/paper/datapack/DatapackRegistrar.java

@@ -19,11 +19,13 @@ import org.jspecify.annotations.Nullable;
  * is called anytime the game tries to discover datapacks at any of the
  * configured locations. This means that if a datapack should stay available to the server,
  * it must always be discovered whenever this event fires.
- * <p>An example of a plugin loading a datapack from within it's own jar is below</p>
+ * <p>
+ * An example of a plugin loading a datapack from within its own jar is below,
+ * assuming the datapack is included under {@code resources/pack} folder:
  * <pre>{@code
  * public class YourPluginBootstrap implements PluginBootstrap {
  *     @Override
- *     public void bootstrap(BoostrapContext context) {
+ *     public void bootstrap(BootstrapContext context) {
  *         final LifecycleEventManager<BootstrapContext> manager = context.getLifecycleManager();
  *         manager.registerEventHandler(LifecycleEvents.DATAPACK_DISCOVERY, event -> {
  *             DatapackRegistrar registrar = event.registrar();
@@ -39,6 +41,7 @@ import org.jspecify.annotations.Nullable;
  *     }
  * }
  * }</pre>
+ *
  * @see io.papermc.paper.plugin.lifecycle.event.types.LifecycleEvents#DATAPACK_DISCOVERY
  */
 @ApiStatus.NonExtendable

paper-api/src/main/java/io/papermc/paper/entity/PlayerGiveResult.java

@@ -0,0 +1,39 @@
+package io.papermc.paper.entity;
+
+import java.util.Collection;
+import org.bukkit.entity.Item;
+import org.bukkit.inventory.ItemStack;
+import org.jetbrains.annotations.Unmodifiable;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * A result type used by {@link org.bukkit.entity.Player#give(ItemStack...)} and its overloads.
+ */
+@NullMarked
+public interface PlayerGiveResult {
+
+    /**
+     * A collection of itemstacks that were not added to the player's inventory as they did not fit.
+     * The collection is derived from the collections of items to add by creating copies of each stack that was not
+     * fully added to the inventory and assigning the non-added count as their amount.
+     * <p>
+     * Itemstacks found here *may* also be found as item entities in the {@link #drops()} collection, as the
+     * give logic may have dropped them.
+     *
+     * @return the unmodifiable collection of itemstacks that are leftover as they could not be added. Each element is a
+     * copy of the input stack they are derived from.
+     */
+    @Unmodifiable
+    Collection<ItemStack> leftovers();
+
+    /**
+     * A collection of item entities dropped as a result of this call to {@link org.bukkit.entity.Player#give(ItemStack...)}.
+     * The item entities contained here are not guaranteed to match the {@link #leftovers()} as plugins may cancel the
+     * spawning of item entities.
+     *
+     * @return the unmodifiable collection of dropped item entities.
+     */
+    @Unmodifiable
+    Collection<Item> drops();
+
+}

paper-api/src/main/java/io/papermc/paper/event/block/PlayerShearBlockEvent.java

@@ -12,10 +12,10 @@ import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
 
 /**
- * Called when a player uses sheers on a block.
+ * Called when a player uses shears on a block.
  * <p>
- * This event is <b>not</b> called when breaking blocks with shears but instead only when a
- * player uses the sheer item on a block to garner drops from said block and/or change its state.
+ * This event is <b>not</b> called when a player breaks blocks with shears, but rather when a
+ * player uses the shears on a block to collect drops from it and/or modify its state.
  * <p>
  * Examples include shearing a pumpkin to turn it into a carved pumpkin or shearing a beehive to get honeycomb.
  */

paper-api/src/main/java/io/papermc/paper/event/entity/EntityAttemptSmashAttackEvent.java

@@ -0,0 +1,103 @@
+package io.papermc.paper.event.entity;
+
+import org.bukkit.entity.LivingEntity;
+import org.bukkit.event.HandlerList;
+import org.bukkit.event.entity.EntityEvent;
+import org.bukkit.inventory.ItemStack;
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Called when an entity attempts to perform a smash attack.
+ */
+@NullMarked
+public class EntityAttemptSmashAttackEvent extends EntityEvent {
+
+    private static final HandlerList HANDLER_LIST = new HandlerList();
+
+    private final LivingEntity target;
+    private final ItemStack weapon;
+    private final boolean originalResult;
+    private Result result = Result.DEFAULT;
+
+    @ApiStatus.Internal
+    public EntityAttemptSmashAttackEvent(
+        final LivingEntity attacker,
+        final LivingEntity target,
+        final ItemStack weapon,
+        final boolean originalResult
+    ) {
+        super(attacker);
+        this.target = target;
+        this.weapon = weapon;
+        this.originalResult = originalResult;
+    }
+
+    /**
+     * Yields the target of the attempted smash attack.
+     *
+     * @return the target entity
+     */
+    public LivingEntity getTarget() {
+        return target;
+    }
+
+    /**
+     * Yields a copy of the itemstack used in the smash attack attempt.
+     *
+     * @return the itemstack
+     */
+    public ItemStack getWeapon() {
+        return weapon.clone();
+    }
+
+    /**
+     * Yields the original result the server computed.
+     *
+     * @return {@code true} if this attempt would have been successful by vanilla's logic, {@code false} otherwise.
+     */
+    public boolean getOriginalResult() {
+        return originalResult;
+    }
+
+    /**
+     * Yields the effective result of this event.
+     * The result may take one of three values:
+     *
+     * <ul>
+     *     <li>{@link Result#ALLOW}: The attempt will succeed.</li>
+     *     <li>{@link Result#DENY}: The attempt will fail.</li>
+     *     <li>{@link Result#DEFAULT}: The attempt will succeed if {@link #getOriginalResult()} is {@code true} and fail otherwise.</li>
+     * </ul>
+     *
+     * @return the result.
+     */
+    public Result getResult() {
+        return this.result;
+    }
+
+    /**
+     * Configures a new result for this event.
+     * The passes result may take one of three values:
+     *
+     * <ul>
+     *     <li>{@link Result#ALLOW}: The attempt will succeed.</li>
+     *     <li>{@link Result#DENY}: The attempt will fail.</li>
+     *     <li>{@link Result#DEFAULT}: The attempt will succeed if {@link #getOriginalResult()} is {@code true} and fail otherwise.</li>
+     * </ul>
+     *
+     * @param result the new result of the event.
+     */
+    public void setResult(final Result result) {
+        this.result = result;
+    }
+
+    @Override
+    public HandlerList getHandlers() {
+        return HANDLER_LIST;
+    }
+
+    public static HandlerList getHandlerList() {
+        return HANDLER_LIST;
+    }
+}

paper-api/src/main/java/io/papermc/paper/event/entity/EntityEffectTickEvent.java

@@ -0,0 +1,75 @@
+package io.papermc.paper.event.entity;
+
+import org.bukkit.entity.LivingEntity;
+import org.bukkit.event.Cancellable;
+import org.bukkit.event.HandlerList;
+import org.bukkit.event.entity.EntityEvent;
+import org.bukkit.potion.PotionEffectType;
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * An event that is triggered when an entity receives a potion effect instantly
+ * or when the potion effect is applied on each tick (e.g. every 25 ticks for Poison level 1).
+ * <p>
+ * For example, this event may be called when an entity regenerates health
+ * or takes poison damage as a result of a potion effect.
+ */
+@NullMarked
+public class EntityEffectTickEvent extends EntityEvent implements Cancellable {
+
+    private static final HandlerList HANDLER_LIST = new HandlerList();
+
+    private final PotionEffectType type;
+    private final int amplifier;
+    private boolean cancelled;
+
+    @ApiStatus.Internal
+    public EntityEffectTickEvent(final LivingEntity entity, final PotionEffectType type, final int amplifier) {
+        super(entity);
+        this.type = type;
+        this.amplifier = amplifier;
+    }
+
+    @Override
+    public LivingEntity getEntity() {
+        return (LivingEntity) super.getEntity();
+    }
+
+    /**
+     * Gets the type of the potion effect associated with this event.
+     *
+     * @return the {@link PotionEffectType} of the effect
+     */
+    public PotionEffectType getType() {
+        return type;
+    }
+
+    /**
+     * Gets the amplifier level of the potion effect associated with this event.
+     *
+     * @return the amplifier level of the potion effect
+     */
+    public int getAmplifier() {
+        return amplifier;
+    }
+
+    @Override
+    public boolean isCancelled() {
+        return this.cancelled;
+    }
+
+    @Override
+    public void setCancelled(final boolean cancel) {
+        this.cancelled = cancel;
+    }
+
+    @Override
+    public HandlerList getHandlers() {
+        return HANDLER_LIST;
+    }
+
+    public static HandlerList getHandlerList() {
+        return HANDLER_LIST;
+    }
+}

paper-api/src/main/java/io/papermc/paper/event/entity/EntityEquipmentChangedEvent.java

@@ -0,0 +1,89 @@
+package io.papermc.paper.event.entity;
+
+import java.util.Collections;
+import java.util.Map;
+import org.bukkit.entity.LivingEntity;
+import org.bukkit.event.HandlerList;
+import org.bukkit.event.entity.EntityEvent;
+import org.bukkit.inventory.EquipmentSlot;
+import org.bukkit.inventory.ItemStack;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.Contract;
+import org.jetbrains.annotations.Unmodifiable;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Called whenever a change to an entity's equipment has been detected. This event is called after effects from
+ * attribute modifiers and enchantments have been updated.
+ * <p>
+ * Examples of actions that can trigger this event:
+ * <ul>
+ *     <li>An entity being added to a world.</li>
+ *     <li>A player logging in.</li>
+ *     <li>The durability of an equipment item changing.</li>
+ *     <li>A dispenser equipping an item onto an entity.</li>
+ *     <li>An entity picking up an armor or weapon item from the ground.</li>
+ *     <li>A player changing their equipped armor.</li>
+ *     <li>A player changes their currently held item.</li>
+ * </ul>
+ */
+@NullMarked
+public class EntityEquipmentChangedEvent extends EntityEvent {
+
+    private static final HandlerList HANDLER_LIST = new HandlerList();
+
+    private final Map<EquipmentSlot, EquipmentChange> equipmentChanges;
+
+    @ApiStatus.Internal
+    public EntityEquipmentChangedEvent(final LivingEntity entity, final Map<EquipmentSlot, EquipmentChange> equipmentChanges) {
+        super(entity);
+
+        this.equipmentChanges = equipmentChanges;
+    }
+
+    @Override
+    public LivingEntity getEntity() {
+        return (LivingEntity) this.entity;
+    }
+
+    /**
+     * Gets a map of changed slots to their respective equipment changes.
+     *
+     * @return the equipment changes map
+     */
+    public @Unmodifiable Map<EquipmentSlot, EquipmentChange> getEquipmentChanges() {
+        return Collections.unmodifiableMap(this.equipmentChanges);
+    }
+
+    @Override
+    public HandlerList getHandlers() {
+        return HANDLER_LIST;
+    }
+
+    public static HandlerList getHandlerList() {
+        return HANDLER_LIST;
+    }
+
+    /**
+     * Represents a change in equipment for a single equipment slot.
+     */
+    @ApiStatus.NonExtendable
+    public interface EquipmentChange {
+
+        /**
+         * Gets the existing item that is being replaced.
+         *
+         * @return the existing item
+         */
+        @Contract(pure = true, value = "-> new")
+        ItemStack oldItem();
+
+        /**
+         * Gets the new item that is replacing the existing item.
+         *
+         * @return the new item
+         */
+        @Contract(pure = true, value = "-> new")
+        ItemStack newItem();
+    }
+}

paper-api/src/main/java/io/papermc/paper/event/packet/ClientTickEndEvent.java

@@ -0,0 +1,29 @@
+package io.papermc.paper.event.packet;
+
+import org.bukkit.entity.Player;
+import org.bukkit.event.HandlerList;
+import org.bukkit.event.player.PlayerEvent;
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Called when a {@code minecraft:client_tick_end} packet is received by the server.
+ */
+@NullMarked
+public class ClientTickEndEvent extends PlayerEvent {
+    private static final HandlerList HANDLER_LIST = new HandlerList();
+
+    @ApiStatus.Internal
+    public ClientTickEndEvent(final Player player) {
+        super(player);
+    }
+
+    @Override
+    public HandlerList getHandlers() {
+        return HANDLER_LIST;
+    }
+
+    public static HandlerList getHandlerList() {
+        return HANDLER_LIST;
+    }
+}

paper-api/src/main/java/io/papermc/paper/event/player/PlayerClientLoadedWorldEvent.java

@@ -0,0 +1,46 @@
+package io.papermc.paper.event.player;
+
+import org.bukkit.entity.Player;
+import org.bukkit.event.HandlerList;
+import org.bukkit.event.player.PlayerEvent;
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Called when a player is marked as loaded.
+ * <p>
+ * This either happens when the player notifies the server after loading the world (closing the downloading terrain screen)
+ * or when the player has not done so for 60 ticks after joining the server or respawning.
+ */
+@NullMarked
+public class PlayerClientLoadedWorldEvent extends PlayerEvent {
+
+    private static final HandlerList HANDLER_LIST = new HandlerList();
+
+    private final boolean timeout;
+
+    @ApiStatus.Internal
+    public PlayerClientLoadedWorldEvent(final Player who, final boolean timeout) {
+        super(who);
+        this.timeout = timeout;
+    }
+
+    /**
+     * True if the event was triggered because the server has not been notified by the player
+     * for 60 ticks after the player joined the server or respawned.
+     *
+     * @return true if the event was triggered because of a timeout
+     */
+    public boolean isTimeout() {
+        return timeout;
+    }
+
+    @Override
+    public HandlerList getHandlers() {
+        return HANDLER_LIST;
+    }
+
+    public static HandlerList getHandlerList() {
+        return HANDLER_LIST;
+    }
+}

paper-api/src/main/java/io/papermc/paper/math/Rotation.java

@@ -0,0 +1,34 @@
+package io.papermc.paper.math;
+
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Represents a rotation with specified pitch and yaw values.
+ */
+@NullMarked
+public interface Rotation {
+    /**
+     * Creates a new rotation with the specified yaw and pitch values.
+     *
+     * @param yaw   the yaw component of the rotation, measured in degrees
+     * @param pitch the pitch component of the rotation, measured in degrees
+     * @return a new {@code Rotation} instance with the specified yaw and pitch
+     */
+    static Rotation rotation(float yaw, float pitch) {
+        return new RotationImpl(yaw, pitch);
+    }
+
+    /**
+     * Retrieves the pitch component of the rotation, measured in degrees.
+     *
+     * @return the pitch value in degrees
+     */
+    float pitch();
+
+    /**
+     * Retrieves the yaw component of the rotation, measured in degrees.
+     *
+     * @return the yaw value in degrees
+     */
+    float yaw();
+}

paper-api/src/main/java/io/papermc/paper/math/RotationImpl.java

@@ -0,0 +1,4 @@
+package io.papermc.paper.math;
+
+record RotationImpl(float yaw, float pitch) implements Rotation {
+}

paper-api/src/main/java/io/papermc/paper/raytracing/PositionedRayTraceConfigurationBuilder.java

@@ -0,0 +1,112 @@
+package io.papermc.paper.raytracing;
+
+import java.util.function.Predicate;
+import org.bukkit.FluidCollisionMode;
+import org.bukkit.Location;
+import org.bukkit.block.Block;
+import org.bukkit.entity.Entity;
+import org.bukkit.util.Vector;
+import org.checkerframework.checker.index.qual.NonNegative;
+import org.jetbrains.annotations.Contract;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * A builder for configuring a raytrace with a starting location
+ * and direction.
+ */
+@NullMarked
+public interface PositionedRayTraceConfigurationBuilder {
+
+    /**
+     * Sets the starting location.
+     *
+     * @param start the new starting location
+     * @return a reference to this object
+     */
+    @Contract(value = "_ -> this", mutates = "this")
+    PositionedRayTraceConfigurationBuilder start(Location start);
+
+    /**
+     * Sets the direction.
+     *
+     * @param direction the new direction
+     * @return a reference to this object
+     */
+    @Contract(value = "_ -> this", mutates = "this")
+    PositionedRayTraceConfigurationBuilder direction(Vector direction);
+
+    /**
+     * Sets the maximum distance.
+     *
+     * @param maxDistance the new maxDistance
+     * @return a reference to this object
+     */
+    @Contract(value = "_ -> this", mutates = "this")
+    PositionedRayTraceConfigurationBuilder maxDistance(@NonNegative double maxDistance);
+
+    /**
+     * Sets the FluidCollisionMode when looking for block collisions.
+     * <p>
+     * If collisions with passable blocks are ignored, fluid collisions are
+     * ignored as well regardless of the fluid collision mode.
+     *
+     * @param fluidCollisionMode the new FluidCollisionMode
+     * @return a reference to this object
+     */
+    @Contract(value = "_ -> this", mutates = "this")
+    PositionedRayTraceConfigurationBuilder fluidCollisionMode(FluidCollisionMode fluidCollisionMode);
+
+    /**
+     * Sets whether the raytrace should ignore passable blocks when looking for
+     * block collisions.
+     * <p>
+     * If collisions with passable blocks are ignored, fluid collisions are
+     * ignored as well regardless of the fluid collision mode.
+     * <p>
+     * Portal blocks are only considered passable if the ray starts within them.
+     * Apart from that collisions with portal blocks will be considered even if
+     * collisions with passable blocks are otherwise ignored.
+     *
+     * @param ignorePassableBlocks if the raytrace should ignore passable blocks
+     * @return a reference to this object
+     */
+    @Contract(value = "_ -> this", mutates = "this")
+    PositionedRayTraceConfigurationBuilder ignorePassableBlocks(boolean ignorePassableBlocks);
+
+    /**
+     * Sets the size of the raytrace when looking for entity collisions.
+     *
+     * @param raySize the new raytrace size
+     * @return a reference to this object
+     */
+    @Contract(value = "_ -> this", mutates = "this")
+    PositionedRayTraceConfigurationBuilder raySize(@NonNegative double raySize);
+
+    /**
+     * Sets the current entity filter when looking for entity collisions.
+     *
+     * @param entityFilter predicate for entities the ray can potentially collide with
+     * @return a reference to this object
+     */
+    @Contract(value = "_ -> this", mutates = "this")
+    PositionedRayTraceConfigurationBuilder entityFilter(Predicate<? super Entity> entityFilter);
+
+    /**
+     * Sets the current block filter when looking for block collisions.
+     *
+     * @param blockFilter predicate for blocks the ray can potentially collide with
+     * @return a reference to this object
+     */
+    @Contract(value = "_ -> this", mutates = "this")
+    PositionedRayTraceConfigurationBuilder blockFilter(Predicate<? super Block> blockFilter);
+
+    /**
+     * Sets the targets for the rayTrace.
+     *
+     * @param first the first target
+     * @param others the other targets
+     * @return a reference to this object
+     */
+    @Contract(value = "_, _ -> this", mutates = "this")
+    PositionedRayTraceConfigurationBuilder targets(RayTraceTarget first, RayTraceTarget... others);
+}

paper-api/src/main/java/io/papermc/paper/raytracing/RayTraceTarget.java

@@ -0,0 +1,9 @@
+package io.papermc.paper.raytracing;
+
+/**
+ * List of Targets a builder can target.
+ */
+public enum RayTraceTarget {
+    ENTITY,
+    BLOCK
+}

paper-api/src/main/java/io/papermc/paper/registry/RegistryKey.java

@@ -1,6 +1,7 @@
 package io.papermc.paper.registry;
 
 import io.papermc.paper.datacomponent.DataComponentType;
+import io.papermc.paper.registry.tag.TagKey;
 import net.kyori.adventure.key.Key;
 import net.kyori.adventure.key.KeyPattern;
 import net.kyori.adventure.key.Keyed;
@@ -78,7 +79,7 @@ public sealed interface RegistryKey<T> extends Keyed permits RegistryKeyImpl {
     RegistryKey<BlockType> BLOCK = create("block");
     /**
      * @apiNote use preferably only in the context of registry entries.
-     * @see io.papermc.paper.registry.data
+     * @see io.papermc.paper.registry.keys.ItemTypeKeys
      */
     @ApiStatus.Experimental // Paper - already required for registry builders
     RegistryKey<ItemType> ITEM = create("item");
@@ -209,7 +210,6 @@ public sealed interface RegistryKey<T> extends Keyed permits RegistryKeyImpl {
      * @param key the key of the typed key.
      * @return the constructed typed key.
      */
-    @ApiStatus.Experimental
     default TypedKey<T> typedKey(final Key key) {
         return TypedKey.create(this, key);
     }
@@ -220,8 +220,29 @@ public sealed interface RegistryKey<T> extends Keyed permits RegistryKeyImpl {
      * @param key the string representation of the key that will be passed to {@link Key#key(String)}.
      * @return the constructed typed key.
      */
-    @ApiStatus.Experimental
-    default TypedKey<T> typedKey(final @KeyPattern String key) {
+    default TypedKey<T> typedKey(@KeyPattern final String key) {
         return TypedKey.create(this, key);
     }
+
+    /**
+     * Constructs a new {@link TagKey} for this registry given the tag key's key.
+     *
+     * @param key the key of the typed key.
+     * @return the constructed tag key.
+     */
+    @ApiStatus.Experimental
+    default TagKey<T> tagKey(final Key key) {
+        return TagKey.create(this, key);
+    }
+
+    /**
+     * Constructs a new {@link TagKey} for this registry given the tag key's key.
+     *
+     * @param key the string representation of the key that will be passed to {@link Key#key(String)}.
+     * @return the constructed tag key.
+     */
+    @ApiStatus.Experimental
+    default TagKey<T> tagKey(@KeyPattern final String key) {
+        return TagKey.create(this, key);
+    }
 }

paper-api/src/main/java/io/papermc/paper/registry/TypedKey.java

@@ -11,7 +11,6 @@ import org.jspecify.annotations.NullMarked;
  *
  * @param <T> the value type for the registry
  */
-@ApiStatus.Experimental
 @NullMarked
 public sealed interface TypedKey<T> extends Key permits TypedKeyImpl {
 
@@ -39,7 +38,6 @@ public sealed interface TypedKey<T> extends Key permits TypedKeyImpl {
      * @param <T> value type
      * @return a new key for the value key and registry key
      */
-    @ApiStatus.Experimental
     static <T> TypedKey<T> create(final RegistryKey<T> registryKey, final Key key) {
         return new TypedKeyImpl<>(key, registryKey);
     }
@@ -53,8 +51,7 @@ public sealed interface TypedKey<T> extends Key permits TypedKeyImpl {
      * @return a new key for the value key and registry key
      * @see Key#key(String)
      */
-    @ApiStatus.Experimental
-    static <T> TypedKey<T> create(final RegistryKey<T> registryKey, final @KeyPattern String key) {
+    static <T> TypedKey<T> create(final RegistryKey<T> registryKey, @KeyPattern final String key) {
         return create(registryKey, Key.key(key));
     }
 }

paper-api/src/main/java/io/papermc/paper/registry/tag/TagKey.java

@@ -1,7 +1,9 @@
 package io.papermc.paper.registry.tag;
 
 import io.papermc.paper.registry.RegistryKey;
+import io.papermc.paper.registry.TypedKey;
 import net.kyori.adventure.key.Key;
+import net.kyori.adventure.key.KeyPattern;
 import net.kyori.adventure.key.Keyed;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.Contract;
@@ -15,15 +17,29 @@ public sealed interface TagKey<T> extends Keyed permits TagKeyImpl {
      * Creates a new tag key for a registry.
      *
      * @param registryKey the registry for the tag
-     * @param key the specific key for the tag
+     * @param key         the specific key for the tag
+     * @param <T>         the registry value type
      * @return a new tag key
-     * @param <T> the registry value type
      */
     @Contract(value = "_, _ -> new", pure = true)
     static <T> TagKey<T> create(final RegistryKey<T> registryKey, final Key key) {
         return new TagKeyImpl<>(registryKey, key);
     }
 
+    /**
+     * Creates a new tag key for a registry.
+     *
+     * @param registryKey the registry for the tag
+     * @param key         the string version of a {@link Key} that will be passed to {@link Key#key(String)} for parsing.
+     * @param <T>         the registry value type
+     * @return a new tag key
+     * @see Key#key(String)
+     */
+    @ApiStatus.Experimental
+    static <T> TagKey<T> create(final RegistryKey<T> registryKey, @KeyPattern final String key) {
+        return create(registryKey, Key.key(key));
+    }
+
     /**
      * Get the registry key for this tag key.
      *

paper-api/src/main/java/io/papermc/paper/tag/PostFlattenTagRegistrar.java

@@ -19,18 +19,20 @@ import org.jspecify.annotations.NullMarked;
  * tags only point to individual entries and not other nested tags.
  * <p>
  * An example of a custom enchant being registered to the vanilla
- * {@code #minecraft:in_enchanting_table} tag.
+ * {@code #minecraft:in_enchanting_table} tag:
  * <pre>{@code
  * class YourBootstrapClass implements PluginBootstrap {
  *
+ *     public static final TypedKey<Enchantment> CUSTOM_POINTY_ENCHANT = EnchantmentKeys.create(Key.key("papermc:pointy"));
+ *
  *     @Override
  *     public void bootstrap(BootstrapContext context) {
- *         LifecycleEventManager<BootstrapContext> manager = context.getLifecycleManager();
+ *         final LifecycleEventManager<BootstrapContext> manager = context.getLifecycleManager();
  *         manager.registerEventHandler(LifecycleEvents.TAGS.postFlatten(RegistryKey.ENCHANTMENT), event -> {
  *             final PostFlattenTagRegistrar<Enchantment> registrar = event.registrar();
  *             registrar.addToTag(
  *                 EnchantmentTagKeys.IN_ENCHANTING_TABLE,
- *                 Set.of(CUSTOM_ENCHANT)
+ *                 Set.of(CUSTOM_POINTY_ENCHANT)
  *             );
  *         });
  *     }

paper-api/src/main/java/io/papermc/paper/tag/PreFlattenTagRegistrar.java

@@ -22,9 +22,11 @@ import org.jspecify.annotations.NullMarked;
  * <pre>{@code
  * class YourBootstrapClass implements PluginBootstrap {
  *
+ *     public static final TagKey<ItemType> AXE_PICKAXE = ItemTypeTagKeys.create(Key.key("papermc:axe_pickaxe"));
+ *
  *     @Override
  *     public void bootstrap(BootstrapContext context) {
- *         LifecycleEventManager<BootstrapContext> manager = context.getLifecycleManager();
+ *         final LifecycleEventManager<BootstrapContext> manager = context.getLifecycleManager();
  *         manager.registerEventHandler(LifecycleEvents.TAGS.preFlatten(RegistryKey.ITEM), event -> {
  *             final PreFlattenTagRegistrar<ItemType> registrar = event.registrar();
  *             registrar.setTag(AXE_PICKAXE, Set.of(

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

@@ -2,12 +2,13 @@ package org.bukkit;
 
 import com.google.common.base.Preconditions;
 import com.google.common.collect.Lists;
+import io.papermc.paper.registry.RegistryAccess;
 import io.papermc.paper.registry.RegistryBuilderFactory;
+import io.papermc.paper.registry.RegistryKey;
 import io.papermc.paper.registry.data.InlinedRegistryBuilderProvider;
 import io.papermc.paper.registry.data.PaintingVariantRegistryEntry;
 import java.util.Locale;
 import java.util.function.Consumer;
-import org.bukkit.packs.DataPack;
 import org.bukkit.util.OldEnum;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
@@ -18,8 +19,8 @@ import org.jetbrains.annotations.Nullable;
  * <p>
  * The arts listed in this interface are present in the default server
  * or can be enabled via a {@link FeatureFlag}.
- * There may be additional arts present in the server, for example from a {@link DataPack}
- * which can be accessed via {@link Registry#ART}.
+ * There may be additional arts present in the server, for example from a {@link io.papermc.paper.datapack.Datapack}
+ * which can be accessed via {@link RegistryAccess#registryAccess()} and {@link RegistryKey#PAINTING_VARIANT}.
  */
 public interface Art extends OldEnum<Art>, Keyed {
 
@@ -87,7 +88,7 @@ public interface Art extends OldEnum<Art>, Keyed {
 
     @NotNull
     private static Art getArt(@NotNull String key) {
-        return Registry.ART.getOrThrow(NamespacedKey.minecraft(key));
+        return RegistryAccess.registryAccess().getRegistry(RegistryKey.PAINTING_VARIANT).getOrThrow(NamespacedKey.minecraft(key));
     }
 
     /**
@@ -108,9 +109,9 @@ public interface Art extends OldEnum<Art>, Keyed {
      * Get the ID of this painting.
      *
      * @return The ID of this painting
-     * @deprecated Magic value
+     * @deprecated Magic value that is based on inconsistent, data-driven registry
      */
-    @Deprecated(since = "1.6.2")
+    @Deprecated(since = "1.6.2", forRemoval = true)
     int getId();
 
     // Paper start - deprecate getKey
@@ -161,9 +162,9 @@ public interface Art extends OldEnum<Art>, Keyed {
      *
      * @param id The ID
      * @return The painting
-     * @deprecated Magic value
+     * @deprecated Magic value that is based on inconsistent, data-driven registry
      */
-    @Deprecated(since = "1.6.2")
+    @Deprecated(since = "1.6.2", forRemoval = true)
     @Nullable
     static Art getById(int id) {
         for (Art art : Registry.ART) {
@@ -189,7 +190,7 @@ public interface Art extends OldEnum<Art>, Keyed {
     static Art getByName(@NotNull String name) {
         Preconditions.checkArgument(name != null, "Name cannot be null");
 
-        return Bukkit.getUnsafe().get(Registry.ART, NamespacedKey.fromString(name.toLowerCase(Locale.ROOT)));
+        return Bukkit.getUnsafe().get(RegistryKey.PAINTING_VARIANT, NamespacedKey.fromString(name.toLowerCase(Locale.ROOT)));
     }
 
     /**
@@ -200,7 +201,7 @@ public interface Art extends OldEnum<Art>, Keyed {
     @NotNull
     @Deprecated(since = "1.21.3", forRemoval = true) @org.jetbrains.annotations.ApiStatus.ScheduledForRemoval(inVersion = "1.22") // Paper - will be removed via asm-utils
     static Art valueOf(@NotNull String name) {
-        Art art = Bukkit.getUnsafe().get(Registry.ART, NamespacedKey.fromString(name.toLowerCase(Locale.ROOT)));
+        Art art = Bukkit.getUnsafe().get(RegistryKey.PAINTING_VARIANT, NamespacedKey.fromString(name.toLowerCase(Locale.ROOT)));
         Preconditions.checkArgument(art != null, "No art found with the name %s", name);
         return art;
     }

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

@@ -40,6 +40,7 @@ import org.bukkit.inventory.InventoryHolder;
 import org.bukkit.inventory.ItemCraftResult;
 import org.bukkit.inventory.ItemFactory;
 import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.MenuType;
 import org.bukkit.inventory.Merchant;
 import org.bukkit.inventory.Recipe;
 import org.bukkit.inventory.meta.ItemMeta;
@@ -929,7 +930,6 @@ public final class Bukkit {
      * @param id the id of the map to get
      * @return a map view if it exists, or null otherwise
      */
-    // @Deprecated(since = "1.6.2") // Paper - Not a magic value
     @Nullable
     public static MapView getMap(int id) {
         return server.getMap(id);
@@ -1116,20 +1116,24 @@ public final class Bukkit {
 
     /**
      * Adds a recipe to the crafting manager.
+     * Recipes added with this method won't be sent to the client automatically.
+     * <p>
+     * Players still have to discover recipes via {@link Player#discoverRecipe(NamespacedKey)}
+     * before seeing them in their recipe book.
      *
      * @param recipe the recipe to add
-     * @return true if the recipe was added, false if it wasn't for some
-     *     reason
+     * @return true if the recipe was added, false if it wasn't for some reason
+     * @see #addRecipe(Recipe, boolean)
      */
     @Contract("null -> false")
     public static boolean addRecipe(@Nullable Recipe recipe) {
         return server.addRecipe(recipe);
     }
 
-    // Paper start - method to send recipes immediately
     /**
      * Adds a recipe to the crafting manager.
      *
+     * @apiNote resendRecipes is ignored at the moment for stability reasons, recipes will always be updated
      * @param recipe the recipe to add
      * @param resendRecipes true to update the client with the full set of recipes
      * @return true if the recipe was added, false if it wasn't for some reason
@@ -1138,7 +1142,6 @@ public final class Bukkit {
     public static boolean addRecipe(@Nullable Recipe recipe, boolean resendRecipes) {
         return server.addRecipe(recipe, resendRecipes);
     }
-    // Paper end - method to send recipes immediately
 
     /**
      * Get a list of all recipes for a given item. The stack size is ignored
@@ -1372,7 +1375,11 @@ public final class Bukkit {
      * Sets the radius, in blocks, around each worlds spawn point to protect.
      *
      * @param value new spawn radius, or 0 if none
+     * @deprecated has not functioned for a long time as the spawn radius is defined by the server.properties file.
+     * There is no API replacement for this method. It is generally recommended to implement "protection"-like behaviour
+     * via events or third-party plugin APIs.
      */
+    @Deprecated(since = "1.21.4", forRemoval = true)
     public static void setSpawnRadius(int value) {
         server.setSpawnRadius(value);
     }
@@ -1384,7 +1391,7 @@ public final class Bukkit {
      * @return true if the server should send a preview, false otherwise
      * @deprecated chat previews have been removed
      */
-    @Deprecated(since = "1.19.3")
+    @Deprecated(since = "1.19.3", forRemoval = true)
     public static boolean shouldSendChatPreviews() {
         return server.shouldSendChatPreviews();
     }
@@ -1507,7 +1514,6 @@ public final class Bukkit {
      * @return an offline player
      * @see #getOfflinePlayer(java.util.UUID)
      */
-    // @Deprecated(since = "1.7.5") // Paper
     @NotNull
     public static OfflinePlayer getOfflinePlayer(@NotNull String name) {
         return server.getOfflinePlayer(name);
@@ -1925,7 +1931,10 @@ public final class Bukkit {
      * @param title the title of the corresponding merchant inventory, displayed
      * when the merchant inventory is viewed
      * @return a new merchant
+     * @deprecated The title parameter is no-longer needed when used with
+     * {@link MenuType#MERCHANT} and {@link MenuType.Typed#builder()}.
      */
+    @Deprecated(since = "1.21.4")
     public static @NotNull Merchant createMerchant(net.kyori.adventure.text.@Nullable Component title) {
         return server.createMerchant(title);
     }
@@ -1936,7 +1945,8 @@ public final class Bukkit {
      * @param title the title of the corresponding merchant inventory, displayed
      * when the merchant inventory is viewed
      * @return a new merchant
-     * @deprecated in favour of {@link #createMerchant(net.kyori.adventure.text.Component)}
+     * @deprecated in favour of {@link #createMerchant(net.kyori.adventure.text.Component)}. The title parameter is
+     * no-longer needed when used with {@link MenuType#MERCHANT} and {@link MenuType.Typed#builder()}
      */
     @NotNull
     @Deprecated // Paper
@@ -1944,6 +1954,16 @@ public final class Bukkit {
         return server.createMerchant(title);
     }
 
+    /**
+     * Creates an empty merchant.
+     *
+     * @return a new merchant
+     */
+    @NotNull
+    public static Merchant createMerchant() {
+        return server.createMerchant();
+    }
+
     /**
      * Gets the amount of consecutive neighbor updates before skipping
      * additional ones.
@@ -2961,8 +2981,19 @@ public final class Bukkit {
     }
     // Paper end - Folia region threading API
 
+    /**
+     * @deprecated All methods on this class have been deprecated, see the individual methods for replacements.
+     */
+    @Deprecated(since = "1.21.4", forRemoval = true)
     @NotNull
     public static Server.Spigot spigot() {
         return server.spigot();
     }
+
+    /**
+     * Restarts the server. If the server administrator has not configured restarting, the server will stop.
+     */
+    public static void restart() {
+        server.restart();
+    }
 }

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

@@ -65,7 +65,7 @@ public interface ChunkSnapshot {
      * @return 0-15
      * @deprecated Magic value
      */
-    @Deprecated(since = "1.6.2")
+    @Deprecated(since = "1.6.2", forRemoval = true)
     int getData(int x, int y, int z);
 
     /**

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(since = "1.19.3")
+    @Deprecated(since = "1.19.3", forRemoval = true)
     DOOR_TOGGLE(1006, Type.SOUND),
     /**
      * Sound of a door opening.
      * @deprecated no longer exists
      * @see Sound#BLOCK_IRON_DOOR_OPEN
      */
-    @Deprecated(since = "1.19.3")
+    @Deprecated(since = "1.19.3", forRemoval = true)
     IRON_DOOR_TOGGLE(1005, Type.SOUND),
     /**
      * Sound of a trapdoor opening.
      * @deprecated no longer exists
      * @see Sound#BLOCK_WOODEN_TRAPDOOR_OPEN
      */
-    @Deprecated(since = "1.19.3")
+    @Deprecated(since = "1.19.3", forRemoval = true)
     TRAPDOOR_TOGGLE(1007, Type.SOUND),
     /**
      * Sound of a door opening.
      * @deprecated no longer exists
      * @see Sound#BLOCK_IRON_TRAPDOOR_OPEN
      */
-    @Deprecated(since = "1.19.3")
+    @Deprecated(since = "1.19.3", forRemoval = true)
     IRON_TRAPDOOR_TOGGLE(1037, Type.SOUND),
     /**
      * Sound of a door opening.
      * @deprecated no longer exists
      * @see Sound#BLOCK_FENCE_GATE_OPEN
      */
-    @Deprecated(since = "1.19.3")
+    @Deprecated(since = "1.19.3", forRemoval = true)
     FENCE_GATE_TOGGLE(1008, Type.SOUND),
     /**
      * Sound of a door closing.
      * @deprecated no longer exists
      * @see Sound#BLOCK_WOODEN_DOOR_CLOSE
      */
-    @Deprecated(since = "1.19.3")
+    @Deprecated(since = "1.19.3", forRemoval = true)
     DOOR_CLOSE(1012, Type.SOUND),
     /**
      * Sound of a door closing.
      * @deprecated no longer exists
      * @see Sound#BLOCK_IRON_DOOR_CLOSE
      */
-    @Deprecated(since = "1.19.3")
+    @Deprecated(since = "1.19.3", forRemoval = true)
     IRON_DOOR_CLOSE(1011, Type.SOUND),
     /**
      * Sound of a trapdoor closing.
      * @deprecated no longer exists
      * @see Sound#BLOCK_WOODEN_TRAPDOOR_CLOSE
      */
-    @Deprecated(since = "1.19.3")
+    @Deprecated(since = "1.19.3", forRemoval = true)
     TRAPDOOR_CLOSE(1013, Type.SOUND),
     /**
      * Sound of a door closing.
      * @deprecated no longer exists
      * @see Sound#BLOCK_IRON_TRAPDOOR_CLOSE
      */
-    @Deprecated(since = "1.19.3")
+    @Deprecated(since = "1.19.3", forRemoval = true)
     IRON_TRAPDOOR_CLOSE(1036, Type.SOUND),
     /**
      * Sound of a door closing.
      * @deprecated no longer exists
      * @see Sound#BLOCK_FENCE_GATE_CLOSE
      */
-    @Deprecated(since = "1.19.3")
+    @Deprecated(since = "1.19.3", forRemoval = true)
     FENCE_GATE_CLOSE(1014, Type.SOUND),
     /**
      * Sound of fire being extinguished.

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

@@ -1,9 +1,14 @@
 package org.bukkit;
 
 import com.google.common.base.Preconditions;
-import org.bukkit.entity.Ageable;
+import io.papermc.paper.datacomponent.DataComponentTypes;
+import org.bukkit.entity.Allay;
+import org.bukkit.entity.Animals;
+import org.bukkit.entity.Armadillo;
 import org.bukkit.entity.ArmorStand;
+import org.bukkit.entity.Arrow;
 import org.bukkit.entity.Cat;
+import org.bukkit.entity.Creaking;
 import org.bukkit.entity.Dolphin;
 import org.bukkit.entity.Egg;
 import org.bukkit.entity.Entity;
@@ -15,6 +20,8 @@ import org.bukkit.entity.Guardian;
 import org.bukkit.entity.Hoglin;
 import org.bukkit.entity.IronGolem;
 import org.bukkit.entity.LivingEntity;
+import org.bukkit.entity.Mob;
+import org.bukkit.entity.Ocelot;
 import org.bukkit.entity.Player;
 import org.bukkit.entity.Rabbit;
 import org.bukkit.entity.Ravager;
@@ -23,7 +30,6 @@ import org.bukkit.entity.Sniffer;
 import org.bukkit.entity.Snowball;
 import org.bukkit.entity.Squid;
 import org.bukkit.entity.Tameable;
-import org.bukkit.entity.TippedArrow;
 import org.bukkit.entity.Villager;
 import org.bukkit.entity.Warden;
 import org.bukkit.entity.Witch;
@@ -32,32 +38,34 @@ import org.bukkit.entity.Zoglin;
 import org.bukkit.entity.ZombieVillager;
 import org.bukkit.entity.minecart.ExplosiveMinecart;
 import org.bukkit.entity.minecart.SpawnerMinecart;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
+import java.util.Set;
 
 /**
- * A list of all Effects that can happen to entities.
+ * A list of all effects that can happen to entities.
  */
 public enum EntityEffect {
 
     /**
-     * Colored particles from a tipped arrow.
+     * Colored particles from an arrow.
      */
-    ARROW_PARTICLES(0, TippedArrow.class),
+    ARROW_PARTICLES(0, Arrow.class),
     /**
      * Rabbit jumping.
      */
     RABBIT_JUMP(1, Rabbit.class),
     /**
-     * Resets a spawner minecart's delay to 200. Does not effect actual spawning
-     * delay, only the speed at which the entity in the spawner spins
+     * Resets a spawner minecart's delay to 200. Does not affect actual spawning
+     * delay, only the speed at which the entity in the spawner spins.
      */
     RESET_SPAWNER_MINECART_DELAY(1, SpawnerMinecart.class),
     /**
      * When mobs get hurt.
      *
-     * @deprecated Use {@link LivingEntity#playHurtAnimation(float)}
+     * @deprecated use {@link LivingEntity#playHurtAnimation(float)}
      */
-    @Deprecated(since = "1.20.1")
+    @Deprecated(since = "1.20.1", forRemoval = true)
     HURT(2, LivingEntity.class),
     /**
      * When a mob dies.
@@ -65,58 +73,97 @@ public enum EntityEffect {
      * <b>This will cause client-glitches!</b>
      *
      * @deprecated split into individual effects
-     * @see #EGG_BREAK
-     * @see #SNOWBALL_BREAK
+     * @see #PROJECTILE_CRACK
      * @see #ENTITY_DEATH
      */
-    @Deprecated(since = "1.12.2")
+    @Deprecated(since = "1.12.2", forRemoval = true)
     DEATH(3, Entity.class),
     /**
-     * Spawns the egg breaking particles
+     * Spawns the egg breaking particles.
+     *
+     * @deprecated use {@link #PROJECTILE_CRACK}
      */
+    @Deprecated(since = "1.21.4", forRemoval = true)
     EGG_BREAK(3, Egg.class),
     /**
-     * Spawns the snowball breaking particles
+     * Spawns the snowball breaking particles.
+     *
+     * @deprecated use {@link #PROJECTILE_CRACK}
      */
+    @Deprecated(since = "1.21.4", forRemoval = true)
     SNOWBALL_BREAK(3, Snowball.class),
     /**
-     * Plays the entity death sound and animation
+     * Shows the crack particles when a projectile
+     * hits something.
+     */
+    PROJECTILE_CRACK(3, Egg.class, Snowball.class),
+    /**
+     * Plays the entity death sound and animation.
      * <p>
      * <b>This will cause client-glitches!</b>
      */
     ENTITY_DEATH(3, LivingEntity.class),
     /**
-     * Plays the fang attack animation
+     * Plays the evoker's fang attack animation.
+     *
+     * @deprecated use {@link #ENTITY_ATTACK}
      */
+    @Deprecated(since = "1.21.4", forRemoval = true)
     FANG_ATTACK(4, EvokerFangs.class),
     /**
-     * Plays the hoglin attack animation
+     * Plays the hoglin attack animation.
+     *
+     * @deprecated use {@link #ENTITY_ATTACK}
      */
+    @Deprecated(since = "1.21.4", forRemoval = true)
     HOGLIN_ATTACK(4, Hoglin.class),
     /**
-     * Plays the iron golem attack animation
+     * Plays the iron golem attack animation.
+     *
+     * @deprecated use {@link #ENTITY_ATTACK}
      */
+    @Deprecated(since = "1.21.4", forRemoval = true)
     IRON_GOLEN_ATTACK(4, IronGolem.class),
     /**
-     * Plays the ravager attack animation
+     * Plays the ravager attack animation.
+     *
+     * @deprecated use {@link #ENTITY_ATTACK}
      */
+    @Deprecated(since = "1.21.4", forRemoval = true)
     RAVAGER_ATTACK(4, Ravager.class),
     /**
-     * Plays the warden attack animation
+     * Plays the warden attack animation.
+     *
+     * @deprecated use {@link #ENTITY_ATTACK}
      */
+    @Deprecated(since = "1.21.4", forRemoval = true)
     WARDEN_ATTACK(4, Warden.class),
     /**
-     * Plays the zoglin attack animation
+     * Plays the zoglin attack animation.
+     *
+     * @deprecated use {@link #ENTITY_ATTACK}
      */
+    @Deprecated(since = "1.21.4", forRemoval = true)
     ZOGLIN_ATTACK(4, Zoglin.class),
+    /**
+     * Plays an attack animation for the respective entities.
+     */
+    ENTITY_ATTACK(4, EvokerFangs.class, Hoglin.class, IronGolem.class, Ravager.class, Warden.class, Zoglin.class, Creaking.class),
     // 5 - unused
     /**
      * The smoke when taming an entity fails.
+     *
      * @deprecated use {@link EntityEffect#TAMING_FAILED}
      */
-    @Deprecated(since = "1.21") // Paper
+    @Deprecated(since = "1.21", forRemoval = true)
     WOLF_SMOKE(6, Tameable.class),
-    // Paper start - rename "wolf" effects
+    /**
+     * The hearts when taming an entity succeeds.
+     *
+     * @deprecated use {@link EntityEffect#TAMING_SUCCEEDED}
+     */
+    @Deprecated(since = "1.21", forRemoval = true)
+    WOLF_HEARTS(7, Tameable.class),
     /**
      * The smoke when taming an entity fails.
      */
@@ -125,20 +172,13 @@ public enum EntityEffect {
      * The hearts when taming an entity succeeds.
      */
     TAMING_SUCCEEDED(7, Tameable.class),
-    // Paper end - rename "wolf" effects
-    /**
-     * The hearts when taming an entity succeeds.
-     * @deprecated use {@link EntityEffect#TAMING_SUCCEEDED}
-     */
-    @Deprecated(since = "1.21") // Paper
-    WOLF_HEARTS(7, Tameable.class),
     /**
      * When a wolf shakes (after being wet).
      *
      * @see EntityEffect#WOLF_SHAKE_STOP
      */
     WOLF_SHAKE(8, Wolf.class),
-    // 9 - unused
+    // 9 - internal
     /**
      * When an entity eats a LONG_GRASS block.
      *
@@ -146,10 +186,10 @@ public enum EntityEffect {
      * @see #SHEEP_EAT_GRASS
      * @see #TNT_MINECART_IGNITE
      */
-    @Deprecated(since = "1.12.2")
+    @Deprecated(since = "1.12.2", forRemoval = true)
     SHEEP_EAT(10, Entity.class),
     /**
-     * Plays the sheep eating grass animation
+     * Plays the sheep eating grass animation.
      */
     SHEEP_EAT_GRASS(10, Sheep.class),
     /**
@@ -179,7 +219,8 @@ public enum EntityEffect {
      */
     WITCH_MAGIC(15, Witch.class),
     /**
-     * When a zombie transforms into a villager by shaking violently.
+     * Plays the sound when a zombie villager is
+     * cured.
      */
     ZOMBIE_TRANSFORM(16, ZombieVillager.class),
     /**
@@ -187,9 +228,10 @@ public enum EntityEffect {
      */
     FIREWORK_EXPLODE(17, Firework.class),
     /**
-     * Hearts from a breeding entity.
+     * Hearts from a breeding entity
+     * or when an Allay duplicates.
      */
-    LOVE_HEARTS(18, Ageable.class),
+    LOVE_HEARTS(18, Animals.class, Allay.class),
     /**
      * Resets squid rotation.
      */
@@ -197,7 +239,7 @@ public enum EntityEffect {
     /**
      * Silverfish entering block, spawner spawning.
      */
-    ENTITY_POOF(20, LivingEntity.class),
+    ENTITY_POOF(20, Mob.class),
     /**
      * Guardian plays the attack sound effect.
      */
@@ -218,9 +260,10 @@ public enum EntityEffect {
     ARMOR_STAND_HIT(32, ArmorStand.class),
     /**
      * Entity hurt by thorns attack.
+     *
      * @deprecated in favor of {@link LivingEntity#playHurtAnimation(float)} or {@link Entity#broadcastHurtAnimation(java.util.Collection)}
      */
-    @Deprecated(since = "1.19.4", forRemoval = true) // Paper
+    @Deprecated(since = "1.19.4", forRemoval = true)
     THORNS_HURT(33, LivingEntity.class),
     /**
      * Iron golem puts away rose.
@@ -228,16 +271,27 @@ public enum EntityEffect {
     IRON_GOLEM_SHEATH(34, IronGolem.class),
     /**
      * Totem prevents entity death.
+     *
+     * @deprecated see {@link #PROTECTED_FROM_DEATH}
      */
+    @Deprecated(since = "1.21.2", forRemoval = true)
     TOTEM_RESURRECT(35, LivingEntity.class),
+    /**
+     * Item with {@link DataComponentTypes#DEATH_PROTECTION} prevents entity death.
+     * For player, the item selected will be shown for a moment on the screen, if the
+     * item is not found a totem will appear.
+     */
+    PROTECTED_FROM_DEATH(35, Entity.class),
     /**
      * Entity hurt due to drowning damage.
+     *
      * @deprecated in favor of {@link LivingEntity#playHurtAnimation(float)} or {@link Entity#broadcastHurtAnimation(java.util.Collection)}
      */
     @Deprecated(since = "1.19.4", forRemoval = true)
     HURT_DROWN(36, LivingEntity.class),
     /**
      * Entity hurt due to explosion damage.
+     *
      * @deprecated in favor of {@link LivingEntity#playHurtAnimation(float)} or {@link Entity#broadcastHurtAnimation(java.util.Collection)}
      */
     @Deprecated(since = "1.19.4", forRemoval = true)
@@ -252,66 +306,94 @@ public enum EntityEffect {
     RAVAGER_STUNNED(39, Ravager.class),
     /**
      * Cat taming failed.
+     *
+     * @deprecated use {@link #TRUSTING_FAILED}
      */
+    @Deprecated(since = "1.14", forRemoval = true)
     CAT_TAME_FAIL(40, Cat.class),
     /**
      * Cat taming succeeded.
+     *
+     * @deprecated use {@link #TRUSTING_SUCCEEDED}
      */
+    @Deprecated(since = "1.14", forRemoval = true)
     CAT_TAME_SUCCESS(41, Cat.class),
+    /**
+     * Ocelot trusting failed.
+     */
+    TRUSTING_FAILED(40, Ocelot.class),
+    /**
+     * Ocelot trusting succeeded.
+     */
+    TRUSTING_SUCCEEDED(41, Ocelot.class),
     /**
      * Villager splashes particles during a raid.
      */
     VILLAGER_SPLASH(42, Villager.class),
     /**
      * Player's bad omen effect removed to start or increase raid difficult.
+     *
      * @deprecated raid system was overhauled in 1.20.5
      */
     @Deprecated(since = "1.20.5", forRemoval = true)
     PLAYER_BAD_OMEN_RAID(43, Player.class),
     /**
      * Entity hurt due to berry bush. Prickly!
+     *
      * @deprecated in favor of {@link LivingEntity#playHurtAnimation(float)} or {@link Entity#broadcastHurtAnimation(java.util.Collection)}
      */
     @Deprecated(since = "1.19.4", forRemoval = true)
     HURT_BERRY_BUSH(44, LivingEntity.class),
     /**
-     * Fox chews the food in its mouth
+     * Fox chews the food in its mouth.
      */
     FOX_CHEW(45, Fox.class),
     /**
-     * Entity teleported as a result of chorus fruit or as an enderman
+     * Entity teleported as a result of chorus fruit or as an enderman.
      */
     TELEPORT_ENDER(46, LivingEntity.class),
     /**
-     * Entity breaks item in main hand
+     * Entity breaks item in main hand.
+     *
+     * @see org.bukkit.inventory.EquipmentSlot#HAND
      */
     BREAK_EQUIPMENT_MAIN_HAND(47, LivingEntity.class),
     /**
-     * Entity breaks item in off hand
+     * Entity breaks item in off hand.
+     *
+     * @see org.bukkit.inventory.EquipmentSlot#OFF_HAND
      */
     BREAK_EQUIPMENT_OFF_HAND(48, LivingEntity.class),
     /**
-     * Entity breaks item in helmet slot
+     * Entity breaks item in helmet slot.
+     *
+     * @see org.bukkit.inventory.EquipmentSlot#HEAD
      */
     BREAK_EQUIPMENT_HELMET(49, LivingEntity.class),
     /**
-     * Entity breaks item in chestplate slot
+     * Entity breaks item in chestplate slot.
+     *
+     * @see org.bukkit.inventory.EquipmentSlot#CHEST
      */
     BREAK_EQUIPMENT_CHESTPLATE(50, LivingEntity.class),
     /**
-     * Entity breaks item in legging slot
+     * Entity breaks item in legging slot.
+     *
+     * @see org.bukkit.inventory.EquipmentSlot#LEGS
      */
     BREAK_EQUIPMENT_LEGGINGS(51, LivingEntity.class),
     /**
-     * Entity breaks item in boot slot
+     * Entity breaks item in boot slot.
+     *
+     * @see org.bukkit.inventory.EquipmentSlot#FEET
      */
     BREAK_EQUIPMENT_BOOTS(52, LivingEntity.class),
     /**
-     * Spawns honey block slide particles at the entity's feet
+     * Spawns honey block slide particles at the entity's feet.
      */
     HONEY_BLOCK_SLIDE_PARTICLES(53, Entity.class),
     /**
-     * Spawns honey block fall particles at the entity's feet
+     * Spawns honey block fall particles at the entity's feet.
      */
     HONEY_BLOCK_FALL_PARTICLES(54, LivingEntity.class),
     /**
@@ -319,110 +401,136 @@ public enum EntityEffect {
      */
     SWAP_HAND_ITEMS(55, LivingEntity.class),
     /**
-     * Stops a wolf that is currently shaking
+     * Stops a wolf that is currently shaking.
      *
      * @see EntityEffect#WOLF_SHAKE
      */
     WOLF_SHAKE_STOP(56, Wolf.class),
     // 57 - unused
     /**
-     * Goat lowers its head for ramming
+     * Goat lowers its head for ramming.
      *
      * @see #GOAT_RAISE_HEAD
      */
     GOAT_LOWER_HEAD(58, Goat.class),
     /**
-     * Goat raises its head
+     * Goat raises its head.
      *
      * @see #GOAT_LOWER_HEAD
      */
     GOAT_RAISE_HEAD(59, Goat.class),
     /**
-     * Spawns death smoke particles
+     * Spawns death smoke particles.
      */
     SPAWN_DEATH_SMOKE(60, LivingEntity.class),
     /**
-     * Warden shakes its tendrils
+     * Warden shakes its tendrils.
      */
     WARDEN_TENDRIL_SHAKE(61, Warden.class),
     /**
-     * Warden performs sonic attack animation <br>
-     * Does not play the sound or fire the beam
+     * Warden performs sonic attack animation.
+     * <br>
+     * Does not play the sound or fire the beam.
      */
     WARDEN_SONIC_ATTACK(62, Warden.class),
     /**
-     * Plays sniffer digging sound <br>
+     * Plays sniffer digging sound.
+     * <br>
      * Sniffer must have a target and be in {@link Sniffer.State#SEARCHING} or
-     * {@link Sniffer.State#DIGGING}
+     * {@link Sniffer.State#DIGGING}.
      */
     SNIFFER_DIG(63, Sniffer.class),
-    // Paper start - add missing EntityEffect
     /**
      * Armadillo peeks out of its shell
      */
-    ARMADILLO_PEEK(64, org.bukkit.entity.Armadillo.class),
+    ARMADILLO_PEEK(64, Armadillo.class),
     /**
-     * {@link org.bukkit.inventory.EquipmentSlot#BODY} armor piece breaks
+     * {@link org.bukkit.inventory.EquipmentSlot#BODY} armor piece breaks.
+     *
+     * @deprecated use {@link #BREAK_EQUIPMENT_BODY}
      */
+    @Deprecated(since = "1.21.4", forRemoval = true)
     BODY_BREAK(65, LivingEntity.class),
+    /**
+     * Entity breaks item in body slot.
+     *
+     * @see org.bukkit.inventory.EquipmentSlot#BODY
+     */
+    BREAK_EQUIPMENT_BODY(65, LivingEntity.class),
     /**
      * A creaking transient shaking when being hit.
      * Does not apply to plain creaking entities as they are not invulnerable like the transient ones spawned by the
      * creaking heart.
      */
-    SHAKE(66, org.bukkit.entity.Creaking.class);
-    // Paper end - add missing EntityEffect
+    SHAKE(66, Creaking.class);
 
     private final byte data;
-    private final Class<? extends Entity> applicable;
+    private final Set<Class<? extends Entity>> applicableClasses;
 
-    EntityEffect(final int data, /*@NotNull*/ Class<? extends Entity> clazz) {
+    EntityEffect(int data, Class<? extends Entity>... applicableClasses) {
+        Preconditions.checkState(applicableClasses.length > 0, "Unknown applicable classes");
         this.data = (byte) data;
-        this.applicable = clazz;
+        this.applicableClasses = Set.of(applicableClasses);
     }
 
     /**
-     * Gets the data value of this EntityEffect, may not be unique.
+     * Gets the data value of this entity effect, may not be unique.
      *
-     * @return The data value
-     * @apiNote Internal Use Only
+     * @return the data value
      */
-    @org.jetbrains.annotations.ApiStatus.Internal // Paper
+    @ApiStatus.Internal
     public byte getData() {
-        return data;
+        return this.data;
     }
 
     /**
-     * Gets entity superclass which this affect is applicable to.
+     * Gets entity superclass which this entity effect is applicable to.
      *
      * @return applicable class
+     * @deprecated an entity effect can apply to multiple superclasses, see {@link #getApplicableClasses()}
      */
     @NotNull
+    @Deprecated(since = "1.21.4")
     public Class<? extends Entity> getApplicable() {
-        return applicable;
+        return this.applicableClasses.iterator().next();
     }
 
     /**
-     * Checks if this effect is applicable to the given entity.
+     * Gets the entity superclasses which this entity effect is applicable to.
+     *
+     * @return the applicable classes
+     */
+    @NotNull
+    public Set<Class<? extends Entity>> getApplicableClasses() {
+        return this.applicableClasses;
+    }
+
+    /**
+     * Checks if this entity effect is applicable to the given entity.
      *
      * @param entity the entity to check
-     * @return true if applicable
+     * @return {@code true} if applicable
      */
     public boolean isApplicableTo(@NotNull Entity entity) {
         Preconditions.checkArgument(entity != null, "Entity cannot be null");
 
-        return isApplicableTo(entity.getClass());
+        return this.isApplicableTo(entity.getClass());
     }
 
     /**
-     * Checks if this effect is applicable to the given entity class.
+     * Checks if this entity effect is applicable to the given entity class.
      *
      * @param clazz the entity class to check
-     * @return true if applicable
+     * @return {@code true} if applicable
      */
     public boolean isApplicableTo(@NotNull Class<? extends Entity> clazz) {
         Preconditions.checkArgument(clazz != null, "Class cannot be null");
 
-        return applicable.isAssignableFrom(clazz);
+        for (Class<? extends Entity> applicableClass : this.applicableClasses) {
+            if (applicableClass.isAssignableFrom(clazz)) {
+                return true;
+            }
+        }
+        return false;
     }
 }

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

@@ -2,6 +2,7 @@ package org.bukkit;
 
 import com.google.common.base.Preconditions;
 import com.google.common.collect.Lists;
+import io.papermc.paper.registry.RegistryKey;
 import java.util.Locale;
 import org.bukkit.util.OldEnum;
 import org.jetbrains.annotations.NotNull;
@@ -45,7 +46,7 @@ public interface Fluid extends OldEnum<Fluid>, Keyed {
     @NotNull
     @Deprecated(since = "1.21.3", forRemoval = true) @org.jetbrains.annotations.ApiStatus.ScheduledForRemoval(inVersion = "1.22") // Paper - will be removed via asm-utils
     static Fluid valueOf(@NotNull String name) {
-        Fluid fluid = Bukkit.getUnsafe().get(Registry.FLUID, NamespacedKey.fromString(name.toLowerCase(Locale.ROOT)));
+        Fluid fluid = Bukkit.getUnsafe().get(RegistryKey.FLUID, NamespacedKey.fromString(name.toLowerCase(Locale.ROOT)));
         Preconditions.checkArgument(fluid != null, "No fluid found with the name %s", name);
         return fluid;
     }

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

@@ -1,5 +1,7 @@
 package org.bukkit;
 
+import io.papermc.paper.registry.RegistryAccess;
+import io.papermc.paper.registry.RegistryKey;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 
@@ -31,7 +33,7 @@ public interface JukeboxSong extends Keyed, Translatable {
 
     @NotNull
     private static JukeboxSong get(@NotNull String key) {
-        return Registry.JUKEBOX_SONG.getOrThrow(NamespacedKey.minecraft(key));
+        return RegistryAccess.registryAccess().getRegistry(RegistryKey.JUKEBOX_SONG).getOrThrow(NamespacedKey.minecraft(key));
     }
 
     // Paper start - adventure

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

@@ -3,24 +3,22 @@ package org.bukkit;
 import com.google.common.base.Preconditions;
 import java.lang.ref.Reference;
 import java.lang.ref.WeakReference;
-import com.google.common.base.Preconditions; // Paper
+import java.util.Collection;
 import java.util.HashMap;
 import java.util.Map;
+import java.util.function.Predicate;
+import io.papermc.paper.math.FinePosition;
+import io.papermc.paper.math.Rotation;
 import org.bukkit.block.Block;
 import org.bukkit.configuration.serialization.ConfigurationSerializable;
-import org.bukkit.entity.Entity; // Paper
-import org.bukkit.util.NumberConversions;
-import org.bukkit.util.Vector;
-import org.jetbrains.annotations.NotNull;
-import org.jetbrains.annotations.Nullable;
-
-// Paper start
-import java.util.Collection;
-import java.util.function.Predicate;
 import org.bukkit.entity.Entity;
 import org.bukkit.entity.LivingEntity;
 import org.bukkit.entity.Player;
-// Paper end
+import org.bukkit.util.NumberConversions;
+import org.bukkit.util.Vector;
+import org.jetbrains.annotations.Contract;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 /**
  * Represents a 3-dimensional position in a world.
@@ -30,7 +28,7 @@ import org.bukkit.entity.Player;
  * magnitude than 360 are valid, but may be normalized to any other equivalent
  * representation by the implementation.
  */
-public class Location implements Cloneable, ConfigurationSerializable, io.papermc.paper.math.FinePosition { // Paper
+public class Location implements Cloneable, ConfigurationSerializable, io.papermc.paper.math.FinePosition {
     private Reference<World> world;
     private double x;
     private double y;
@@ -46,7 +44,7 @@ public class Location implements Cloneable, ConfigurationSerializable, io.paperm
      * @param y The y-coordinate of this new location
      * @param z The z-coordinate of this new location
      */
-    public Location(@UndefinedNullability final World world, final double x, final double y, final double z) { // Paper
+    public Location(@UndefinedNullability final World world, final double x, final double y, final double z) {
         this(world, x, y, z, 0, 0);
     }
 
@@ -60,7 +58,7 @@ public class Location implements Cloneable, ConfigurationSerializable, io.paperm
      * @param yaw The absolute rotation on the x-plane, in degrees
      * @param pitch The absolute rotation on the y-plane, in degrees
      */
-    public Location(@UndefinedNullability final World world, final double x, final double y, final double z, final float yaw, final float pitch) { // Paper
+    public Location(@UndefinedNullability final World world, final double x, final double y, final double z, final float yaw, final float pitch) {
         if (world != null) {
             this.world = new WeakReference<>(world);
         }
@@ -102,7 +100,7 @@ public class Location implements Cloneable, ConfigurationSerializable, io.paperm
      * @throws IllegalArgumentException when world is unloaded
      * @see #isWorldLoaded()
      */
-    @UndefinedNullability // Paper
+    @UndefinedNullability
     public World getWorld() {
         if (this.world == null) {
             return null;
@@ -398,6 +396,35 @@ public class Location implements Cloneable, ConfigurationSerializable, io.paperm
         return this;
     }
 
+    /**
+     * Adds rotation in the form of yaw and patch to this location. Not world-aware.
+     *
+     * @param yaw   yaw, measured in degrees.
+     * @param pitch pitch, measured in degrees.
+     * @return the same location
+     * @see Vector
+     */
+    @NotNull
+    @Contract(value = "_,_ -> this", mutates = "this")
+    public Location addRotation(final float yaw, final float pitch) {
+        this.yaw += yaw;
+        this.pitch += pitch;
+        return this;
+    }
+
+    /**
+     * Adds rotation to this location. Not world-aware.
+     *
+     * @param rotation the rotation to add.
+     * @return the same location
+     * @see Vector
+     */
+    @NotNull
+    @Contract(value = "_ -> this", mutates = "this")
+    public Location addRotation(@NotNull Rotation rotation) {
+        return addRotation(rotation.yaw(), rotation.pitch());
+    }
+
     /**
      * Subtracts the location by another.
      *
@@ -451,6 +478,35 @@ public class Location implements Cloneable, ConfigurationSerializable, io.paperm
         return this;
     }
 
+    /**
+     * Subtracts rotation in the form of yaw and patch from this location.
+     *
+     * @param yaw   yaw, measured in degrees.
+     * @param pitch pitch, measured in degrees.
+     * @return the same location
+     * @see Vector
+     */
+    @NotNull
+    @Contract(value = "_,_ -> this", mutates = "this")
+    public Location subtractRotation(final float yaw, final float pitch) {
+        this.yaw -= yaw;
+        this.pitch -= pitch;
+        return this;
+    }
+
+    /**
+     * Subtracts rotation from this location.
+     *
+     * @param rotation the rotation to subtract.
+     * @return the same location
+     * @see Vector
+     */
+    @NotNull
+    @Contract(value = "_ -> this", mutates = "this")
+    public Location subtractRotation(@NotNull Rotation rotation) {
+        return subtractRotation(rotation.yaw(), rotation.pitch());
+    }
+
     /**
      * Gets the magnitude of the location, defined as sqrt(x^2+y^2+z^2). The
      * value of this method is not cached and uses a costly square-root
@@ -543,9 +599,10 @@ public class Location implements Cloneable, ConfigurationSerializable, io.paperm
         return this;
     }
 
-    public boolean isChunkLoaded() { return this.getWorld().isChunkLoaded(locToBlock(x) >> 4, locToBlock(z) >> 4); } // Paper
+    public boolean isChunkLoaded() {
+        return this.getWorld().isChunkLoaded(locToBlock(x) >> 4, locToBlock(z) >> 4);
+    }
 
-    // Paper start - isGenerated API
     /**
      * Checks if a {@link Chunk} has been generated at this location.
      *
@@ -556,9 +613,6 @@ public class Location implements Cloneable, ConfigurationSerializable, io.paperm
         Preconditions.checkNotNull(world, "Location has no world!");
         return world.isChunkGenerated(locToBlock(x) >> 4, locToBlock(z) >> 4);
     }
-    // Paper end - isGenerated API
-
-    // Paper start - expand location manipulation API
 
     /**
      * Sets the position of this Location and returns itself
@@ -578,6 +632,37 @@ public class Location implements Cloneable, ConfigurationSerializable, io.paperm
         return this;
     }
 
+    /**
+     * Sets the rotation of this location and returns itself.
+     * <p>
+     * This mutates this object, clone first.
+     *
+     * @param yaw   yaw, measured in degrees.
+     * @param pitch pitch, measured in degrees.
+     * @return self (not cloned)
+     */
+    @NotNull
+    @Contract(value = "_,_ -> this", mutates = "this")
+    public Location setRotation(final float yaw, final float pitch) {
+        this.yaw = yaw;
+        this.pitch = pitch;
+        return this;
+    }
+
+    /**
+     * Sets the rotation of this location and returns itself.
+     * <p>
+     * This mutates this object, clone first.
+     *
+     * @param rotation the new rotation.
+     * @return self (not cloned)
+     */
+    @NotNull
+    @Contract(value = "_ -> this", mutates = "this")
+    public Location setRotation(@NotNull Rotation rotation) {
+        return setRotation(rotation.yaw(), rotation.pitch());
+    }
+
     /**
      * Takes the x/y/z from base and adds the specified x/y/z to it and returns self
      * <p>
@@ -609,9 +694,7 @@ public class Location implements Cloneable, ConfigurationSerializable, io.paperm
     public Location subtract(@NotNull Location base, double x, double y, double z) {
         return this.set(base.x - x, base.y - y, base.z - z);
     }
-    // Paper end - expand location manipulation API
 
-    // Paper start - expand Location API
     /**
      * @return A new location where X/Y/Z are on the Block location (integer value of X/Y/Z)
      */
@@ -624,7 +707,6 @@ public class Location implements Cloneable, ConfigurationSerializable, io.paperm
         return blockLoc;
     }
 
-    // Paper start
     /**
      * @return The block key for this location's block location.
      * @see Block#getBlockKey(int, int, int)
@@ -634,7 +716,6 @@ public class Location implements Cloneable, ConfigurationSerializable, io.paperm
     public long toBlockKey() {
         return Block.getBlockKey(getBlockX(), getBlockY(), getBlockZ());
     }
-    // Paper end
 
     /**
      * @return A new location where X/Y/Z are the center of the block
@@ -647,9 +728,7 @@ public class Location implements Cloneable, ConfigurationSerializable, io.paperm
         centerLoc.setZ(getBlockZ() + 0.5);
         return centerLoc;
     }
-    // Paper end - expand Location API
 
-    // Paper start - Add heightmap api
     /**
      * Returns a copy of this location except with y = getWorld().getHighestBlockYAt(this.getBlockX(), this.getBlockZ())
      * @return A copy of this location except with y = getWorld().getHighestBlockYAt(this.getBlockX(), this.getBlockZ())
@@ -671,9 +750,7 @@ public class Location implements Cloneable, ConfigurationSerializable, io.paperm
         ret.setY(this.getWorld().getHighestBlockYAt(this, heightMap));
         return ret;
     }
-    // Paper end - Add heightmap api
 
-    // Paper start - Expand Explosions API
     /**
      * Creates explosion at this location with given power
      * <p>
@@ -754,9 +831,7 @@ public class Location implements Cloneable, ConfigurationSerializable, io.paperm
     public boolean createExplosion(@Nullable Entity source, float power, boolean setFire, boolean breakBlocks) {
         return this.getWorld().createExplosion(source, this, power, setFire, breakBlocks);
     }
-    // Paper end - Expand Explosions API
 
-    // Paper start - additional getNearbyEntities API
     /**
      * Returns a list of entities within a bounding box centered around a Location.
      * <p>
@@ -979,7 +1054,6 @@ public class Location implements Cloneable, ConfigurationSerializable, io.paperm
         }
         return world.getNearbyEntitiesByType(clazz, this, xRadius, yRadius, zRadius, predicate);
     }
-    // Paper end - additional getNearbyEntities API
 
     @Override
     public boolean equals(Object obj) {
@@ -1155,7 +1229,6 @@ public class Location implements Cloneable, ConfigurationSerializable, io.paperm
         return pitch;
     }
 
-    // Paper - add Position
     @Override
     public double x() {
         return this.getX();
@@ -1173,12 +1246,11 @@ public class Location implements Cloneable, ConfigurationSerializable, io.paperm
 
     @Override
     public boolean isFinite() {
-        return io.papermc.paper.math.FinePosition.super.isFinite() && Float.isFinite(this.getYaw()) && Float.isFinite(this.getPitch());
+        return FinePosition.super.isFinite() && Float.isFinite(this.getYaw()) && Float.isFinite(this.getPitch());
     }
 
     @Override
     public @NotNull Location toLocation(@NotNull World world) {
         return new Location(world, this.x(), this.y(), this.z(), this.getYaw(), this.getPitch());
     }
-    // Paper end
 }

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

@@ -1,6 +1,8 @@
 package org.bukkit;
 
 import com.google.common.collect.Lists;
+import io.papermc.paper.registry.RegistryAccess;
+import io.papermc.paper.registry.RegistryKey;
 import java.util.Collection;
 import java.util.Collections;
 import org.jetbrains.annotations.NotNull;
@@ -44,7 +46,7 @@ public abstract class MusicInstrument implements Keyed, net.kyori.adventure.tran
 
     @NotNull
     private static MusicInstrument getInstrument(@NotNull String key) {
-        return Registry.INSTRUMENT.getOrThrow(NamespacedKey.minecraft(key));
+        return RegistryAccess.registryAccess().getRegistry(RegistryKey.INSTRUMENT).getOrThrow(NamespacedKey.minecraft(key));
     }
 
     // Paper start - deprecate getKey

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

@@ -83,14 +83,12 @@ public final class NamespacedKey implements net.kyori.adventure.key.Key, com.des
      * @see #NamespacedKey(Plugin, String)
      */
     public NamespacedKey(@NotNull String namespace, @NotNull String key) {
-        Preconditions.checkArgument(namespace != null && isValidNamespace(namespace), "Invalid namespace. Must be [a-z0-9._-]: %s", namespace);
-        Preconditions.checkArgument(key != null && isValidKey(key), "Invalid key. Must be [a-z0-9/._-]: %s", key);
-
+        Preconditions.checkArgument(namespace != null, "Namespace cannot be null");
+        Preconditions.checkArgument(key != null, "Key cannot be null");
         this.namespace = namespace;
         this.key = key;
 
-        String string = toString();
-        Preconditions.checkArgument(string.length() <= Short.MAX_VALUE, "NamespacedKey must be less than 32768 characters", string); // Paper - Fix improper length validation
+        this.validate();
     }
 
     /**
@@ -108,16 +106,17 @@ public final class NamespacedKey implements net.kyori.adventure.key.Key, com.des
     public NamespacedKey(@NotNull Plugin plugin, @NotNull String key) {
         Preconditions.checkArgument(plugin != null, "Plugin cannot be null");
         Preconditions.checkArgument(key != null, "Key cannot be null");
-
         this.namespace = plugin.getName().toLowerCase(Locale.ROOT);
         this.key = key.toLowerCase(Locale.ROOT);
 
         // Check validity after normalization
+        this.validate();
+    }
+
+    private void validate() {
+        Preconditions.checkArgument(this.namespace.length() + 1 + this.key.length() <= Short.MAX_VALUE, "NamespacedKey must be less than 32768 characters");
         Preconditions.checkArgument(isValidNamespace(this.namespace), "Invalid namespace. Must be [a-z0-9._-]: %s", this.namespace);
         Preconditions.checkArgument(isValidKey(this.key), "Invalid key. Must be [a-z0-9/._-]: %s", this.key);
-
-        String string = toString();
-        Preconditions.checkArgument(string.length() <= Short.MAX_VALUE, "NamespacedKey must be less than 32768 characters", string); // Paper - Fix improper length validation
     }
 
     @NotNull

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

@@ -11,14 +11,15 @@ import org.bukkit.entity.EntityType;
 import org.bukkit.entity.Player;
 import org.bukkit.permissions.ServerOperator;
 import org.bukkit.profile.PlayerProfile;
-import org.jetbrains.annotations.NotNull;
-import org.jetbrains.annotations.Nullable;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 /**
  * Represents a reference to a player identity and the data belonging to a
  * player that is stored on the disk and can, thus, be retrieved without the
  * player needing to be online.
  */
+@NullMarked
 public interface OfflinePlayer extends ServerOperator, AnimalTamer, ConfigurationSerializable, io.papermc.paper.persistence.PersistentDataViewHolder { // Paper - Add Offline PDC API
 
     /**
@@ -62,7 +63,6 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
      * @return Player UUID
      */
     @Override
-    @NotNull
     public UUID getUniqueId();
 
     /**
@@ -74,7 +74,6 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
      *
      * @return the player's profile
      */
-    @NotNull
     com.destroystokyo.paper.profile.PlayerProfile getPlayerProfile(); // Paper
 
     /**
@@ -91,7 +90,6 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
      * @return Ban Entry
      * @deprecated use {@link #ban(String, Date, String)}
      */
-    @NotNull
     @Deprecated(since = "1.20.4")
     public default BanEntry banPlayer(@Nullable String reason) {
         return banPlayer(reason, null, null);
@@ -104,7 +102,6 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
      * @return Ban Entry
      * @deprecated use {@link #ban(String, Date, String)}
      */
-    @NotNull
     @Deprecated(since = "1.20.4")
     public default BanEntry banPlayer(@Nullable String reason, @Nullable String source) {
         return banPlayer(reason, null, source);
@@ -117,9 +114,8 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
      * @return Ban Entry
      * @deprecated use {@link #ban(String, Date, String)}
      */
-    @NotNull
     @Deprecated(since = "1.20.4")
-    public default BanEntry banPlayer(@Nullable String reason, @Nullable java.util.Date expires) {
+    public default BanEntry banPlayer(@Nullable String reason, java.util.@Nullable Date expires) {
         return banPlayer(reason, expires, null);
     }
 
@@ -131,18 +127,16 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
      * @return Ban Entry
      * @deprecated use {@link #ban(String, Date, String)}
      */
-    @NotNull
     @Deprecated(since = "1.20.4")
-    public default BanEntry banPlayer(@Nullable String reason, @Nullable java.util.Date expires, @Nullable String source) {
+    public default BanEntry banPlayer(@Nullable String reason, java.util.@Nullable Date expires, @Nullable String source) {
         return banPlayer(reason, expires, source, true);
     }
 
     /**
      * @deprecated use {@link #ban(String, Date, String)}
      */
-    @NotNull
     @Deprecated(since = "1.20.4")
-    public default BanEntry banPlayer(@Nullable String reason, @Nullable java.util.Date expires, @Nullable String source, boolean kickIfOnline) {
+    public default BanEntry banPlayer(@Nullable String reason, java.util.@Nullable Date expires, @Nullable String source, boolean kickIfOnline) {
         BanEntry banEntry = Bukkit.getServer().getBanList(BanList.Type.NAME).addBan(getName(), reason, expires, source);
         if (kickIfOnline && isOnline()) {
             getPlayer().kickPlayer(reason);
@@ -309,7 +303,7 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
      * @throws IllegalArgumentException if the statistic requires an
      *     additional parameter
      */
-    public void incrementStatistic(@NotNull Statistic statistic) throws IllegalArgumentException;
+    public void incrementStatistic(Statistic statistic) throws IllegalArgumentException;
 
     /**
      * Decrements the given statistic for this player.
@@ -322,7 +316,7 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
      * @throws IllegalArgumentException if the statistic requires an
      *     additional parameter
      */
-    public void decrementStatistic(@NotNull Statistic statistic) throws IllegalArgumentException;
+    public void decrementStatistic(Statistic statistic) throws IllegalArgumentException;
 
     /**
      * Increments the given statistic for this player.
@@ -334,7 +328,7 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
      * @throws IllegalArgumentException if the statistic requires an
      *     additional parameter
      */
-    public void incrementStatistic(@NotNull Statistic statistic, int amount) throws IllegalArgumentException;
+    public void incrementStatistic(Statistic statistic, int amount) throws IllegalArgumentException;
 
     /**
      * Decrements the given statistic for this player.
@@ -346,7 +340,7 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
      * @throws IllegalArgumentException if the statistic requires an
      *     additional parameter
      */
-    public void decrementStatistic(@NotNull Statistic statistic, int amount) throws IllegalArgumentException;
+    public void decrementStatistic(Statistic statistic, int amount) throws IllegalArgumentException;
 
     /**
      * Sets the given statistic for this player.
@@ -358,7 +352,7 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
      * @throws IllegalArgumentException if the statistic requires an
      *     additional parameter
      */
-    public void setStatistic(@NotNull Statistic statistic, int newValue) throws IllegalArgumentException;
+    public void setStatistic(Statistic statistic, int newValue) throws IllegalArgumentException;
 
     /**
      * Gets the value of the given statistic for this player.
@@ -369,7 +363,7 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
      * @throws IllegalArgumentException if the statistic requires an
      *     additional parameter
      */
-    public int getStatistic(@NotNull Statistic statistic) throws IllegalArgumentException;
+    public int getStatistic(Statistic statistic) throws IllegalArgumentException;
 
     /**
      * Increments the given statistic for this player for the given material.
@@ -384,7 +378,7 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
      * @throws IllegalArgumentException if the given parameter is not valid
      *     for the statistic
      */
-    public void incrementStatistic(@NotNull Statistic statistic, @NotNull Material material) throws IllegalArgumentException;
+    public void incrementStatistic(Statistic statistic, Material material) throws IllegalArgumentException;
 
     /**
      * Decrements the given statistic for this player for the given material.
@@ -399,7 +393,7 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
      * @throws IllegalArgumentException if the given parameter is not valid
      *     for the statistic
      */
-    public void decrementStatistic(@NotNull Statistic statistic, @NotNull Material material) throws IllegalArgumentException;
+    public void decrementStatistic(Statistic statistic, Material material) throws IllegalArgumentException;
 
     /**
      * Gets the value of the given statistic for this player.
@@ -412,7 +406,7 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
      * @throws IllegalArgumentException if the given parameter is not valid
      *     for the statistic
      */
-    public int getStatistic(@NotNull Statistic statistic, @NotNull Material material) throws IllegalArgumentException;
+    public int getStatistic(Statistic statistic, Material material) throws IllegalArgumentException;
 
     /**
      * Increments the given statistic for this player for the given material.
@@ -426,7 +420,7 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
      * @throws IllegalArgumentException if the given parameter is not valid
      *     for the statistic
      */
-    public void incrementStatistic(@NotNull Statistic statistic, @NotNull Material material, int amount) throws IllegalArgumentException;
+    public void incrementStatistic(Statistic statistic, Material material, int amount) throws IllegalArgumentException;
 
     /**
      * Decrements the given statistic for this player for the given material.
@@ -440,7 +434,7 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
      * @throws IllegalArgumentException if the given parameter is not valid
      *     for the statistic
      */
-    public void decrementStatistic(@NotNull Statistic statistic, @NotNull Material material, int amount) throws IllegalArgumentException;
+    public void decrementStatistic(Statistic statistic, Material material, int amount) throws IllegalArgumentException;
 
     /**
      * Sets the given statistic for this player for the given material.
@@ -454,7 +448,7 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
      * @throws IllegalArgumentException if the given parameter is not valid
      *     for the statistic
      */
-    public void setStatistic(@NotNull Statistic statistic, @NotNull Material material, int newValue) throws IllegalArgumentException;
+    public void setStatistic(Statistic statistic, Material material, int newValue) throws IllegalArgumentException;
 
     /**
      * Increments the given statistic for this player for the given entity.
@@ -469,7 +463,7 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
      * @throws IllegalArgumentException if the given parameter is not valid
      *     for the statistic
      */
-    public void incrementStatistic(@NotNull Statistic statistic, @NotNull EntityType entityType) throws IllegalArgumentException;
+    public void incrementStatistic(Statistic statistic, EntityType entityType) throws IllegalArgumentException;
 
     /**
      * Decrements the given statistic for this player for the given entity.
@@ -484,7 +478,7 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
      * @throws IllegalArgumentException if the given parameter is not valid
      *     for the statistic
      */
-    public void decrementStatistic(@NotNull Statistic statistic, @NotNull EntityType entityType) throws IllegalArgumentException;
+    public void decrementStatistic(Statistic statistic, EntityType entityType) throws IllegalArgumentException;
 
     /**
      * Gets the value of the given statistic for this player.
@@ -497,7 +491,7 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
      * @throws IllegalArgumentException if the given parameter is not valid
      *     for the statistic
      */
-    public int getStatistic(@NotNull Statistic statistic, @NotNull EntityType entityType) throws IllegalArgumentException;
+    public int getStatistic(Statistic statistic, EntityType entityType) throws IllegalArgumentException;
 
     /**
      * Increments the given statistic for this player for the given entity.
@@ -511,7 +505,7 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
      * @throws IllegalArgumentException if the given parameter is not valid
      *     for the statistic
      */
-    public void incrementStatistic(@NotNull Statistic statistic, @NotNull EntityType entityType, int amount) throws IllegalArgumentException;
+    public void incrementStatistic(Statistic statistic, EntityType entityType, int amount) throws IllegalArgumentException;
 
     /**
      * Decrements the given statistic for this player for the given entity.
@@ -525,7 +519,7 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
      * @throws IllegalArgumentException if the given parameter is not valid
      *     for the statistic
      */
-    public void decrementStatistic(@NotNull Statistic statistic, @NotNull EntityType entityType, int amount);
+    public void decrementStatistic(Statistic statistic, EntityType entityType, int amount);
 
     /**
      * Sets the given statistic for this player for the given entity.
@@ -539,7 +533,7 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
      * @throws IllegalArgumentException if the given parameter is not valid
      *     for the statistic
      */
-    public void setStatistic(@NotNull Statistic statistic, @NotNull EntityType entityType, int newValue);
+    public void setStatistic(Statistic statistic, EntityType entityType, int newValue);
 
     /**
      * Gets the player's last death location.
@@ -571,6 +565,6 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio
      * @see io.papermc.paper.persistence.PersistentDataViewHolder#getPersistentDataContainer()
      */
     @Override
-    io.papermc.paper.persistence.@NotNull PersistentDataContainerView getPersistentDataContainer();
+    io.papermc.paper.persistence.PersistentDataContainerView getPersistentDataContainer();
     // Paper end - add pdc to offline player
 }

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

@@ -146,12 +146,10 @@ public enum Particle implements Keyed {
     /**
      * Uses {@link BlockData} as DataType
      */
-    @ApiStatus.Experimental
     BLOCK_CRUMBLE("block_crumble", BlockData.class),
     /**
      * Uses {@link Trail} as DataType
      */
-    @ApiStatus.Experimental
     TRAIL("trail", Trail.class),
     OMINOUS_SPAWNING("ominous_spawning"),
     RAID_OMEN("raid_omen"),
@@ -276,7 +274,6 @@ public enum Particle implements Keyed {
     /**
      * Options which can be applied to trail particles - a location, color and duration.
      */
-    @ApiStatus.Experimental
     public static class Trail {
 
         private final Location target;

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

@@ -3,6 +3,7 @@ package org.bukkit;
 import com.google.common.base.Preconditions;
 import com.google.common.base.Predicates;
 import com.google.common.collect.ImmutableMap;
+import com.google.common.collect.Iterables;
 import io.papermc.paper.datacomponent.DataComponentType;
 import io.papermc.paper.registry.RegistryAccess;
 import io.papermc.paper.registry.RegistryKey;
@@ -63,7 +64,7 @@ public interface Registry<T extends Keyed> extends Iterable<T> {
     @SuppressWarnings("removal")
     @Deprecated(forRemoval = true, since = "1.21.4")
     private static <A extends Keyed> Registry<A> legacyRegistryFor(final Class<A> clazz) {
-        return Objects.requireNonNull(RegistryAccess.registryAccess().getRegistry(clazz), "No registry present for " + clazz.getSimpleName() + ". This is a bug.");
+        return Objects.requireNonNull(RegistryAccess.registryAccess().getRegistry(clazz), () -> "No registry present for " + clazz.getSimpleName() + ". This is a bug.");
     }
 
     /**
@@ -271,7 +272,6 @@ public interface Registry<T extends Keyed> extends Iterable<T> {
      * @see JukeboxSong
      * @deprecated use {@link RegistryAccess#getRegistry(RegistryKey)} with {@link RegistryKey#JUKEBOX_SONG}
      */
-    @ApiStatus.Experimental
     @Deprecated(since = "1.21")
     Registry<JukeboxSong> JUKEBOX_SONG = legacyRegistryFor(JukeboxSong.class);
     /**
@@ -298,6 +298,11 @@ public interface Registry<T extends Keyed> extends Iterable<T> {
             return MemoryKey.values().iterator();
         }
 
+        @Override
+        public int size() {
+            return MemoryKey.values().size();
+        }
+
         @Override
         public @Nullable MemoryKey get(final NamespacedKey key) {
             return MemoryKey.getByKey(key);
@@ -537,6 +542,13 @@ public interface Registry<T extends Keyed> extends Iterable<T> {
         return (namespacedKey != null) ? this.get(namespacedKey) : null;
     }
 
+    /**
+     * Gets the size of the registry.
+     *
+     * @return the size of the registry
+     */
+    int size();
+
     @ApiStatus.Internal
     class SimpleRegistry<T extends Enum<T> & Keyed> extends NotARegistry<T> { // Paper - remove final
 
@@ -565,6 +577,11 @@ public interface Registry<T extends Keyed> extends Iterable<T> {
             return this.map.get(key);
         }
 
+        @Override
+        public int size() {
+            return map.size();
+        }
+
         @Override
         public Iterator<T> iterator() {
             return this.map.values().iterator();
@@ -585,6 +602,11 @@ public interface Registry<T extends Keyed> extends Iterable<T> {
             return StreamSupport.stream(this.spliterator(), false);
         }
 
+        @Override
+        public int size() {
+            return Iterables.size(this);
+        }
+
         @Override
         public NamespacedKey getKey(final A value) {
             return value.getKey();

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

@@ -14,6 +14,9 @@ import java.util.Set;
 import java.util.UUID;
 import java.util.function.Consumer;
 import java.util.logging.Logger;
+import net.kyori.adventure.text.Component;
+import net.kyori.adventure.text.minimessage.MiniMessage;
+import net.kyori.adventure.text.minimessage.tag.resolver.TagResolver;
 import org.bukkit.Warning.WarningState;
 import org.bukkit.advancement.Advancement;
 import org.bukkit.block.data.BlockData;
@@ -40,6 +43,7 @@ import org.bukkit.inventory.InventoryHolder;
 import org.bukkit.inventory.ItemCraftResult;
 import org.bukkit.inventory.ItemFactory;
 import org.bukkit.inventory.ItemStack;
+import org.bukkit.inventory.MenuType;
 import org.bukkit.inventory.Merchant;
 import org.bukkit.inventory.Recipe;
 import org.bukkit.inventory.meta.ItemMeta;
@@ -409,6 +413,40 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
     }
     // Paper end
 
+    /**
+     * Sends a message with the MiniMessage format to the server.
+     * <p>
+     * See <a href="https://docs.advntr.dev/minimessage/">MiniMessage docs</a>
+     * for more information on the format.
+     *
+     * @param message MiniMessage content
+     */
+    default void sendRichMessage(final @NotNull String message) {
+        this.sendMessage(MiniMessage.miniMessage().deserialize(message, this));
+    }
+
+    /**
+     * Sends a message with the MiniMessage format to the server.
+     * <p>
+     * See <a href="https://docs.advntr.dev/minimessage/">MiniMessage docs</a> and <a href="https://docs.advntr.dev/minimessage/dynamic-replacements">MiniMessage Placeholders docs</a>
+     * for more information on the format.
+     *
+     * @param message MiniMessage content
+     * @param resolvers resolvers to use
+     */
+    default void sendRichMessage(final @NotNull String message, final @NotNull TagResolver... resolvers) {
+        this.sendMessage(MiniMessage.miniMessage().deserialize(message, this, resolvers));
+    }
+
+    /**
+     * Sends a plain message to the server.
+     *
+     * @param message plain message
+     */
+    default void sendPlainMessage(final @NotNull String message) {
+        this.sendMessage(Component.text(message));
+    }
+
     /**
      * Gets the name of the update folder. The update folder is used to safely
      * update plugins at the right moment on a plugin load.
@@ -950,26 +988,24 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
     public boolean dispatchCommand(@NotNull CommandSender sender, @NotNull String commandLine) throws CommandException;
 
     /**
-     * Adds a recipe to the crafting manager. Recipes added with
-     * this method won't be sent to the client automatically. Use
-     * {@link #updateRecipes()} or {@link #updateResources()} to
-     * update clients to new recipes added.
+     * Adds a recipe to the crafting manager.
+     * Recipes added with this method won't be sent to the client automatically.
      * <p>
-     * Player's still have to discover recipes via {@link Player#discoverRecipe(NamespacedKey)}
+     * Players still have to discover recipes via {@link Player#discoverRecipe(NamespacedKey)}
      * before seeing them in their recipe book.
      *
      * @param recipe the recipe to add
-     * @return true if the recipe was added, false if it wasn't for some
-     *     reason
+     * @return true if the recipe was added, false if it wasn't for some reason
      * @see #addRecipe(Recipe, boolean)
      */
     @Contract("null -> false")
-    public boolean addRecipe(@Nullable Recipe recipe);
+    boolean addRecipe(@Nullable Recipe recipe);
 
     // Paper start - method to send recipes immediately
     /**
      * Adds a recipe to the crafting manager.
      *
+     * @apiNote resendRecipes is ignored for now for stability reasons, recipes will always be updated
      * @param recipe the recipe to add
      * @param resendRecipes true to update the client with the full set of recipes
      * @return true if the recipe was added, false if it wasn't for some reason
@@ -1181,7 +1217,11 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
      * Sets the radius, in blocks, around each worlds spawn point to protect.
      *
      * @param value new spawn radius, or 0 if none
+     * @deprecated has not functioned for a long time as the spawn radius is defined by the server.properties file.
+     * There is no API replacement for this method. It is generally recommended to implement "protection"-like behaviour
+     * via events or third-party plugin APIs.
      */
+    @Deprecated(since = "1.21.4", forRemoval = true)
     public void setSpawnRadius(int value);
 
     /**
@@ -1191,8 +1231,10 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
      * @return true if the server should send a preview, false otherwise
      * @deprecated chat previews have been removed
      */
-    @Deprecated(since = "1.19.3")
-    public boolean shouldSendChatPreviews();
+    @Deprecated(since = "1.19.3", forRemoval = true)
+    default boolean shouldSendChatPreviews() {
+        return false;
+    }
 
     /**
      * Gets whether the server only allow players with Mojang-signed public key
@@ -1528,11 +1570,11 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
      * <br>
      * {@link InventoryType#WORKBENCH} will not process crafting recipes if
      * created with this method. Use
-     * {@link Player#openWorkbench(Location, boolean)} instead.
+     * {@link MenuType#CRAFTING} instead.
      * <br>
      * {@link InventoryType#ENCHANTING} will not process {@link ItemStack}s
      * for possible enchanting results. Use
-     * {@link Player#openEnchanting(Location, boolean)} instead.
+     * {@link MenuType#ENCHANTMENT} instead.
      *
      * @param owner the holder of the inventory, or null to indicate no holder
      * @param type the type of inventory to create
@@ -1555,11 +1597,11 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
      * <br>
      * {@link InventoryType#WORKBENCH} will not process crafting recipes if
      * created with this method. Use
-     * {@link Player#openWorkbench(Location, boolean)} instead.
+     * {@link MenuType#CRAFTING} instead.
      * <br>
      * {@link InventoryType#ENCHANTING} will not process {@link ItemStack}s
      * for possible enchanting results. Use
-     * {@link Player#openEnchanting(Location, boolean)} instead.
+     * {@link MenuType#ENCHANTMENT} instead.
      *
      * @param owner The holder of the inventory; can be null if there's no holder.
      * @param type The type of inventory to create.
@@ -1583,11 +1625,11 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
      * <br>
      * {@link InventoryType#WORKBENCH} will not process crafting recipes if
      * created with this method. Use
-     * {@link Player#openWorkbench(Location, boolean)} instead.
+     * {@link MenuType#CRAFTING} instead.
      * <br>
      * {@link InventoryType#ENCHANTING} will not process {@link ItemStack}s
      * for possible enchanting results. Use
-     * {@link Player#openEnchanting(Location, boolean)} instead.
+     * {@link MenuType#ENCHANTMENT} instead.
      *
      * @param owner The holder of the inventory; can be null if there's no holder.
      * @param type The type of inventory to create.
@@ -1654,7 +1696,10 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
      * @param title the title of the corresponding merchant inventory, displayed
      * when the merchant inventory is viewed
      * @return a new merchant
+     * @deprecated The title parameter is no-longer needed when used with
+     * {@link MenuType#MERCHANT} and {@link MenuType.Typed#builder()}.
      */
+    @Deprecated(since = "1.21.4")
     @NotNull Merchant createMerchant(net.kyori.adventure.text.@Nullable Component title);
     // Paper start
     /**
@@ -1663,7 +1708,8 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
      * @param title the title of the corresponding merchant inventory, displayed
      * when the merchant inventory is viewed
      * @return a new merchant
-     * @deprecated in favour of {@link #createMerchant(net.kyori.adventure.text.Component)}
+     * @deprecated in favour of {@link #createMerchant(net.kyori.adventure.text.Component)}, The title parameter is
+     * no-longer needed when used with {@link MenuType#MERCHANT} and {@link MenuType.Typed#builder()}.
      */
     @NotNull
     @Deprecated // Paper
@@ -1678,6 +1724,14 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
      */
     int getMaxChainedNeighborUpdates();
 
+    /**
+     * Creates an empty merchant.
+     *
+     * @return a new merchant
+     */
+    @NotNull
+    Merchant createMerchant();
+
     /**
      * Gets user-specified limit for number of monsters that can spawn in a
      * chunk.
@@ -2255,24 +2309,52 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
     // Spigot start
     public class Spigot {
 
+        /**
+         * @deprecated Server config options may be renamed or removed without notice. Prefer using existing API
+         *  wherever possible, rather than directly reading from a server config.
+         *
+         * @return The server's spigot config.
+         */
+        @Deprecated(since = "1.21.4", forRemoval = true)
         @NotNull
         public org.bukkit.configuration.file.YamlConfiguration getConfig() {
             throw new UnsupportedOperationException("Not supported yet.");
         }
 
+        /**
+         * @deprecated Server config options may be renamed or removed without notice. Prefer using existing API
+         *  wherever possible, rather than directly reading from a server config.
+         *
+         * @return The server's bukkit config.
+         */
         // Paper start
+        @Deprecated(since = "1.21.4", forRemoval = true)
         @NotNull
         public org.bukkit.configuration.file.YamlConfiguration getBukkitConfig()
         {
             throw new UnsupportedOperationException( "Not supported yet." );
         }
 
+        /**
+         * @deprecated Server config options may be renamed or removed without notice. Prefer using existing API
+         *  wherever possible, rather than directly reading from a server config.
+         *
+         * @return The server's spigot config.
+         */
+        @Deprecated(since = "1.21.4", forRemoval = true)
         @NotNull
         public org.bukkit.configuration.file.YamlConfiguration getSpigotConfig()
         {
             throw new UnsupportedOperationException("Not supported yet.");
         }
 
+        /**
+         * @deprecated Server config options may be renamed or removed without notice. Prefer using existing API
+         *  wherever possible, rather than directly reading from a server config.
+         *
+         * @return The server's paper config.
+         */
+        @Deprecated(since = "1.21.4", forRemoval = true)
         @NotNull
         public org.bukkit.configuration.file.YamlConfiguration getPaperConfig()
         {
@@ -2304,16 +2386,28 @@ public interface Server extends PluginMessageRecipient, net.kyori.adventure.audi
 
         /**
          * Restart the server. If the server administrator has not configured restarting, the server will stop.
+         *
+         * @deprecated Use {@link Server#restart()} instead.
          */
+        @Deprecated(since = "1.21.4", forRemoval = true)
         public void restart() {
             throw new UnsupportedOperationException("Not supported yet.");
         }
     }
 
+    /**
+     * @deprecated All methods on this class have been deprecated, see the individual methods for replacements.
+     */
+    @Deprecated(since = "1.21.4", forRemoval = true)
     @NotNull
     Spigot spigot();
     // Spigot end
 
+    /**
+     * Restarts the server. If the server administrator has not configured restarting, the server will stop.
+     */
+    void restart();
+
     void reloadPermissions(); // Paper
 
     boolean reloadCommandAliases(); // Paper

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

@@ -2,6 +2,7 @@ package org.bukkit;
 
 import com.google.common.base.Preconditions;
 import com.google.common.collect.Lists;
+import io.papermc.paper.registry.RegistryKey;
 import java.util.Locale;
 import org.bukkit.packs.DataPack;
 import org.bukkit.util.OldEnum;
@@ -1687,7 +1688,7 @@ public interface Sound extends OldEnum<Sound>, Keyed, net.kyori.adventure.sound.
     @NotNull
     @Deprecated(since = "1.21.3")
     static Sound valueOf(@NotNull String name) {
-        Sound sound = Bukkit.getUnsafe().get(Registry.SOUNDS, NamespacedKey.fromString(name.toLowerCase(Locale.ROOT)));
+        Sound sound = Bukkit.getUnsafe().get(RegistryKey.SOUND_EVENT, NamespacedKey.fromString(name.toLowerCase(Locale.ROOT)));
         if (sound != null) {
             return sound;
         }

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

@@ -2,12 +2,12 @@ package org.bukkit;
 
 import com.google.common.collect.Multimap;
 import io.papermc.paper.entity.EntitySerializationFlag;
+import io.papermc.paper.registry.RegistryKey;
 import org.bukkit.advancement.Advancement;
 import org.bukkit.attribute.Attribute;
 import org.bukkit.attribute.AttributeModifier;
 import org.bukkit.block.Biome;
 import org.bukkit.block.data.BlockData;
-import org.bukkit.damage.DamageEffect;
 import org.bukkit.damage.DamageSource;
 import org.bukkit.damage.DamageType;
 import org.bukkit.entity.Entity;
@@ -140,7 +140,7 @@ public interface UnsafeValues {
     String get(Class<?> aClass, String value);
 
     @ApiStatus.Internal
-    <B extends Keyed> B get(Registry<B> registry, NamespacedKey key);
+    <B extends Keyed> B get(RegistryKey<B> registry, NamespacedKey key);
 
     @ApiStatus.Internal
     Biome getCustomBiome();
@@ -358,14 +358,17 @@ public interface UnsafeValues {
     // Paper start - spawn egg color visibility
     /**
      * Obtains the underlying color informating for a spawn egg of a given
-     * entity type, or null if the entity passed does not have a spawn egg.
+     * entity type, or {@code null} if the entity passed does not have a spawn egg.
      * Spawn eggs have two colors - the background layer (0), and the
      * foreground layer (1)
-     * @param entityType The entity type to get the color for
-     * @param layer The texture layer to get a color for
-     * @return The color of the layer for the entity's spawn egg
+     *
+     * @param entityType the entity type to get the color for
+     * @param layer the texture layer to get a color for
+     * @return the color of the layer for the entity's spawn egg
+     * @deprecated the color is no longer available to the server
      */
-    @Nullable org.bukkit.Color getSpawnEggLayerColor(org.bukkit.entity.EntityType entityType, int layer);
+    @Deprecated(since = "1.21.4")
+    @Nullable Color getSpawnEggLayerColor(EntityType entityType, int layer);
     // Paper end - spawn egg color visibility
 
     // Paper start - lifecycle event API

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

@@ -1,8 +1,7 @@
 package org.bukkit;
 
+import io.papermc.paper.raytracing.PositionedRayTraceConfigurationBuilder;
 import java.io.File;
-import org.bukkit.generator.ChunkGenerator;
-
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.HashMap;
@@ -475,12 +474,15 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @param z Z-coordinate of the chunk
      * @return Whether the chunk was actually regenerated
      *
+     * @throws UnsupportedOperationException not implemented
      * @deprecated regenerating a single chunk is not likely to produce the same
      * chunk as before as terrain decoration may be spread across chunks. It may
      * or may not change blocks in the adjacent chunks as well.
      */
-    @Deprecated(since = "1.13")
-    public boolean regenerateChunk(int x, int z);
+    @Deprecated(since = "1.13", forRemoval = true)
+    default boolean regenerateChunk(int x, int z) {
+        throw new UnsupportedOperationException("Not supported in this Minecraft version! This is not a bug.");
+    }
 
     /**
      * Resends the {@link Chunk} to all clients
@@ -490,7 +492,6 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @return Whether the chunk was actually refreshed
      *
      */
-    // @Deprecated(since = "1.8") // Paper
     public boolean refreshChunk(int x, int z);
 
     /**
@@ -1119,8 +1120,8 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * on the main Server Thread.
      *
      * @deprecated Use either the Future or the Consumer based methods
-     * @param x Chunk X-coordinate of the chunk - floor(world coordinate / 16)
-     * @param z Chunk Z-coordinate of the chunk - floor(world coordinate / 16)
+     * @param x Chunk x-coordinate
+     * @param z Chunk z-coordinate
      * @param cb Callback to receive the chunk when it is loaded.
      *           will be executed synchronously
      */
@@ -1188,8 +1189,8 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * The {@link java.util.function.Consumer} will always be executed synchronously
      * on the main Server Thread.
      *
-     * @param x Chunk X-coordinate of the chunk - floor(world coordinate / 16)
-     * @param z Chunk Z-coordinate of the chunk - floor(world coordinate / 16)
+     * @param x Chunk x-coordinate
+     * @param z Chunk z-coordinate
      * @param cb Callback to receive the chunk when it is loaded.
      *           will be executed synchronously
      */
@@ -1210,8 +1211,8 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * The {@link java.util.function.Consumer} will always be executed synchronously
      * on the main Server Thread.
      *
-     * @param x Chunk X-coordinate of the chunk - floor(world coordinate / 16)
-     * @param z Chunk Z-coordinate of the chunk - floor(world coordinate / 16)
+     * @param x Chunk x-coordinate
+     * @param z Chunk z-coordinate
      * @param gen Should we generate a chunk if it doesn't exist or not
      * @param cb Callback to receive the chunk when it is loaded.
      *           will be executed synchronously
@@ -1233,8 +1234,8 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * The {@link java.util.function.Consumer} will always be executed synchronously
      * on the main Server Thread.
      *
-     * @param x Chunk X-coordinate of the chunk - floor(world coordinate / 16)
-     * @param z Chunk Z-coordinate of the chunk - floor(world coordinate / 16)
+     * @param x Chunk x-coordinate
+     * @param z Chunk z-coordinate
      * @param gen Should we generate a chunk if it doesn't exist or not
      * @param urgent If true, the chunk may be prioritised to be loaded above other chunks in queue
      * @param cb Callback to receive the chunk when it is loaded.
@@ -1256,10 +1257,10 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * The {@link Runnable} will always be executed synchronously
      * on the main Server Thread, and when invoked all chunks requested will be loaded.
      *
-     * @param minX Minimum chunk X-coordinate of the chunk - floor(world coordinate / 16)
-     * @param minZ Minimum chunk Z-coordinate of the chunk - floor(world coordinate / 16)
-     * @param maxX Maximum chunk X-coordinate of the chunk - floor(world coordinate / 16)
-     * @param maxZ Maximum chunk Z-coordinate of the chunk - floor(world coordinate / 16)
+     * @param minX Minimum Chunk x-coordinate
+     * @param minZ Minimum Chunk z-coordinate
+     * @param maxX Maximum Chunk x-coordinate
+     * @param maxZ Maximum Chunk z-coordinate
      * @param urgent If true, the chunks may be prioritised to be loaded above other chunks in queue
      * @param cb Callback to invoke when all chunks are loaded.
      *           Will be executed synchronously
@@ -1445,8 +1446,8 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * The future will always be executed synchronously
      * on the main Server Thread.
      *
-     * @param x Chunk X-coordinate of the chunk - floor(world coordinate / 16)
-     * @param z Chunk Z-coordinate of the chunk - floor(world coordinate / 16)
+     * @param x Chunk x-coordinate
+     * @param z Chunk z-coordinate
      * @return Future that will resolve when the chunk is loaded
      */
     default @NotNull java.util.concurrent.CompletableFuture<Chunk> getChunkAtAsync(final int x, final int z) {
@@ -1466,8 +1467,8 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * The future will always be executed synchronously
      * on the main Server Thread.
      *
-     * @param x Chunk X-coordinate of the chunk - floor(world coordinate / 16)
-     * @param z Chunk Z-coordinate of the chunk - floor(world coordinate / 16)
+     * @param x Chunk x-coordinate
+     * @param z Chunk z-coordinate
      * @param gen Should we generate a chunk if it doesn't exist or not
      * @return Future that will resolve when the chunk is loaded
      */
@@ -1477,14 +1478,14 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
 
     /**
      * Requests a {@link Chunk} to be loaded at the given coordinates
-     *
+     * <p>
      * This method makes no guarantee on how fast the chunk will load,
      * and will return the chunk to the callback at a later time.
-     *
+     * <p>
      * You should use this method if you need a chunk but do not need it
-     * immediately, and you wish to let the server control the speed
-     * of chunk loads, keeping performance in mind.
-     *
+     * immediately, and you wish for it to be prioritised over other
+     * chunk loads in queue.
+     * <p>
      * The future will always be executed synchronously
      * on the main Server Thread.
      * @param loc Location to load the corresponding chunk from
@@ -1496,14 +1497,14 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
 
     /**
      * Requests a {@link Chunk} to be loaded at the given coordinates
-     *
+     * <p>
      * This method makes no guarantee on how fast the chunk will load,
      * and will return the chunk to the callback at a later time.
-     *
+     * <p>
      * You should use this method if you need a chunk but do not need it
-     * immediately, and you wish to let the server control the speed
-     * of chunk loads, keeping performance in mind.
-     *
+     * immediately, and you wish for it to be prioritised over other
+     * chunk loads in queue.
+     * <p>
      * The future will always be executed synchronously
      * on the main Server Thread.
      * @param loc Location to load the corresponding chunk from
@@ -1516,14 +1517,14 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
 
     /**
      * Requests a {@link Chunk} to be loaded at the given coordinates
-     *
+     * <p>
      * This method makes no guarantee on how fast the chunk will load,
      * and will return the chunk to the callback at a later time.
-     *
+     * <p>
      * You should use this method if you need a chunk but do not need it
-     * immediately, and you wish to let the server control the speed
-     * of chunk loads, keeping performance in mind.
-     *
+     * immediately, and you wish for it to be prioritised over other
+     * chunk loads in queue.
+     * <p>
      * The future will always be executed synchronously
      * on the main Server Thread.
      * @param block Block to load the corresponding chunk from
@@ -1535,14 +1536,14 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
 
     /**
      * Requests a {@link Chunk} to be loaded at the given coordinates
-     *
+     * <p>
      * This method makes no guarantee on how fast the chunk will load,
      * and will return the chunk to the callback at a later time.
-     *
+     * <p>
      * You should use this method if you need a chunk but do not need it
-     * immediately, and you wish to let the server control the speed
-     * of chunk loads, keeping performance in mind.
-     *
+     * immediately, and you wish for it to be prioritised over other
+     * chunk loads in queue.
+     * <p>
      * The future will always be executed synchronously
      * on the main Server Thread.
      * @param block Block to load the corresponding chunk from
@@ -1555,25 +1556,45 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
 
     /**
      * Requests a {@link Chunk} to be loaded at the given coordinates
-     *
+     * <p>
      * This method makes no guarantee on how fast the chunk will load,
-     * and will return the chunk to the callback at a later time.
-     *
+     * and will complete the future at a later time.
+     * <p>
      * You should use this method if you need a chunk but do not need it
-     * immediately, and you wish to let the server control the speed
-     * of chunk loads, keeping performance in mind.
-     *
+     * immediately, and you wish for it to be prioritised over other
+     * chunk loads in queue.
+     * <p>
      * The future will always be executed synchronously
      * on the main Server Thread.
      *
-     * @param x X Coord
-     * @param z Z Coord
+     * @param x Chunk x-coordinate
+     * @param z Chunk z-coordinate
      * @return Future that will resolve when the chunk is loaded
      */
     default @NotNull java.util.concurrent.CompletableFuture<Chunk> getChunkAtAsyncUrgently(final int x, final int z) {
         return this.getChunkAtAsync(x, z, true, true);
     }
 
+    /**
+     * Requests a {@link Chunk} to be loaded at the given coordinates.
+     * <p>
+     * This method makes no guarantee on how fast the chunk will load,
+     * and will return the chunk to the callback at a later time.
+     * <p>
+     * You should use this method if you need a chunk but do not need it
+     * immediately, and you wish to let the server control the speed
+     * of chunk loads, keeping performance in mind.
+     * <p>
+     * The future will always be executed synchronously
+     * on the main Server Thread.
+     *
+     * @param x Chunk x-coordinate
+     * @param z Chunk z-coordinate
+     * @param gen Should the chunk generate if it doesn't exist
+     * @param urgent If true, the chunk may be prioritised to be loaded above other chunks in queue
+     *
+     * @return Future that will resolve when the chunk is loaded
+     */
     default @NotNull java.util.concurrent.CompletableFuture<Chunk> getChunkAtAsync(int x, int z, boolean gen, boolean urgent) {
         java.util.concurrent.CompletableFuture<Chunk> ret = new java.util.concurrent.CompletableFuture<>();
         this.getChunkAtAsync(x, z, gen, urgent, ret::complete);
@@ -1938,6 +1959,20 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
     @Nullable RayTraceResult rayTrace(io.papermc.paper.math.@NotNull Position start, @NotNull Vector direction, double maxDistance, @NotNull FluidCollisionMode fluidCollisionMode, boolean ignorePassableBlocks, double raySize, @Nullable Predicate<? super Entity> filter, @Nullable Predicate<? super Block> canCollide);
     // Paper end
 
+    /**
+     * Performs a ray trace that checks for collisions with the specified
+     * targets.
+     * <p>
+     * This may cause loading of chunks! Some implementations may impose
+     * artificial restrictions on the maximum distance.
+     *
+     * @param builderConsumer a consumer to configure the ray trace configuration.
+     *     The received builder is not valid for use outside the consumer
+     * @return the closest ray trace hit result with either a block or an
+     *     entity, or <code>null</code> if there is no hit
+     */
+    @Nullable RayTraceResult rayTrace(@NotNull Consumer<PositionedRayTraceConfigurationBuilder> builderConsumer);
+
     /**
      * Gets the default spawn {@link Location} of this world
      *
@@ -2373,9 +2408,17 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
     public BiomeProvider getBiomeProvider();
 
     /**
-     * Saves world to disk
+     * Saves the world to disk
      */
-    public void save();
+    default void save() {
+        save(false);
+    }
+
+    /**
+     * Saves the world to disk
+     * @param flush Whether to wait for the chunk writer to finish
+     */
+    void save(boolean flush);
 
     /**
      * Gets a list of all applied {@link BlockPopulator}s for this World
@@ -2440,7 +2483,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * @deprecated Use {@link #spawn(Location, Class, Consumer)} (or a variation thereof) in combination with {@link FallingBlock#setBlockData(BlockData)}
      */
     @NotNull
-    @Deprecated(since = "1.20.2") // Paper
+    @Deprecated(since = "1.20.2", forRemoval = true)
     public FallingBlock spawnFallingBlock(@NotNull Location location, @NotNull MaterialData data) throws IllegalArgumentException;
 
     /**
@@ -2475,7 +2518,7 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      *     Material} are null or {@link Material} is not a block
      * @deprecated Magic value. Use {@link #spawn(Location, Class, Consumer)} (or a variation thereof) in combination with {@link FallingBlock#setBlockData(BlockData)}
      */
-    @Deprecated(since = "1.7.5")
+    @Deprecated(since = "1.7.5", forRemoval = true)
     @NotNull
     public FallingBlock spawnFallingBlock(@NotNull Location location, @NotNull Material material, byte data) throws IllegalArgumentException;
 
@@ -2593,9 +2636,6 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * <p>
      * It is safe to run this method when the block does not exist, it will
      * not create the block.
-     * <p>
-     * This method will return the raw temperature without adjusting for block
-     * height effects.
      *
      * @param x X coordinate of the block
      * @param z Z coordinate of the block
@@ -2610,9 +2650,6 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      * <p>
      * It is safe to run this method when the block does not exist, it will
      * not create the block.
-     * <p>
-     * This method will return the raw temperature without adjusting for block
-     * height effects.
      *
      * @param x X coordinate of the block
      * @param y Y coordinate of the block
@@ -2772,6 +2809,8 @@ public interface World extends RegionAccessor, WorldInfo, PluginMessageRecipient
      *
      * @param value true if the world should automatically save, otherwise
      *     false
+     * @apiNote This does not disable saving entirely, the world will still be saved on shutdown.<br>
+     * The intended use of this method is to disable the periodical autosave by the game.
      */
     public void setAutoSave(boolean value);
 

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

@@ -2,6 +2,7 @@ package org.bukkit.attribute;
 
 import com.google.common.base.Preconditions;
 import com.google.common.collect.Lists;
+import io.papermc.paper.registry.RegistryKey;
 import java.util.Locale;
 import org.bukkit.Bukkit;
 import org.bukkit.Keyed;
@@ -158,7 +159,7 @@ public interface Attribute extends OldEnum<Attribute>, Keyed, Translatable, net.
     @NotNull
     @Deprecated(since = "1.21.3", forRemoval = true) @org.jetbrains.annotations.ApiStatus.ScheduledForRemoval(inVersion = "1.22") // Paper - will be removed via asm-utils
     static Attribute valueOf(@NotNull String name) {
-        Attribute attribute = Bukkit.getUnsafe().get(Registry.ATTRIBUTE, NamespacedKey.fromString(name.toLowerCase(Locale.ROOT)));
+        Attribute attribute = Bukkit.getUnsafe().get(RegistryKey.ATTRIBUTE, NamespacedKey.fromString(name.toLowerCase(Locale.ROOT)));
         Preconditions.checkArgument(attribute != null, "No attribute found with the name %s", name);
         return attribute;
     }