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.

.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:

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
@@ -504,6 +505,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
@@ -623,9 +625,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
@@ -724,6 +733,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.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.10" apply false
+    id("io.papermc.paperweight.core") version "2.0.0-beta.14" apply false
 }
 
 subprojects {

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/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.19.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())

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/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/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/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/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));
     }
 
     /**
@@ -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;
@@ -1372,7 +1373,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);
     }
@@ -1925,7 +1930,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 +1944,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 +1953,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.

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

@@ -8,6 +8,7 @@ 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;
@@ -411,6 +412,19 @@ public class Location implements Cloneable, ConfigurationSerializable, io.paperm
         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.
      *
@@ -480,6 +494,19 @@ public class Location implements Cloneable, ConfigurationSerializable, io.paperm
         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
@@ -622,6 +649,20 @@ 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 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>

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

@@ -5706,8 +5706,9 @@ public enum Material implements Keyed, Translatable, net.kyori.adventure.transla
      *
      * @param world the world to check
      * @return true if this material can be used in this World.
+     * @deprecated use {@link io.papermc.paper.world.flag.FeatureFlagSetHolder#isEnabled(io.papermc.paper.world.flag.FeatureDependant)}
      */
-    @Deprecated(forRemoval = true, since = "1.20") // Paper
+    @Deprecated(forRemoval = true, since = "1.20")
     public boolean isEnabledByFeature(@NotNull World world) {
         if (isItem()) {
             return Bukkit.getDataPackManager().isEnabledByFeature(asItemType(), world);

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/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

@@ -271,7 +271,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);
     /**

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

@@ -43,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;
@@ -1218,7 +1219,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);
 
     /**
@@ -1565,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
@@ -1592,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.
@@ -1620,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.
@@ -1691,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
     /**
@@ -1700,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
@@ -1715,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.

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,6 +1,7 @@
 package org.bukkit;
 
 import java.io.File;
+import io.papermc.paper.raytracing.PositionedRayTraceConfigurationBuilder;
 import org.bukkit.generator.ChunkGenerator;
 
 import java.util.ArrayList;
@@ -475,12 +476,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
@@ -1119,8 +1123,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 +1192,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 +1214,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 +1237,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 +1260,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 +1449,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 +1470,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 +1481,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 +1500,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 +1520,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 +1539,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 +1559,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 +1962,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
      *
@@ -2593,9 +2631,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 +2645,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 +2804,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;
     }

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

@@ -2,13 +2,14 @@ package org.bukkit.block;
 
 import com.google.common.base.Preconditions;
 import com.google.common.collect.Lists;
+import io.papermc.paper.registry.RegistryAccess;
+import io.papermc.paper.registry.RegistryKey;
 import java.util.Locale;
 import org.bukkit.Bukkit;
 import org.bukkit.FeatureFlag;
 import org.bukkit.Keyed;
 import org.bukkit.NamespacedKey;
 import org.bukkit.Registry;
-import org.bukkit.packs.DataPack;
 import org.bukkit.util.OldEnum;
 import org.jetbrains.annotations.NotNull;
 
@@ -17,8 +18,8 @@ import org.jetbrains.annotations.NotNull;
  * <p>
  * The Biomes listed in this interface are present in the default server
  * or can be enabled via a {@link FeatureFlag}.
- * There may be additional biomes present in the server, for example from a {@link DataPack}
- * which can be accessed via {@link Registry#BIOME}.
+ * There may be additional biomes present in the server, for example from a {@link io.papermc.paper.datapack.Datapack}
+ * which can be accessed via {@link io.papermc.paper.registry.RegistryAccess#getRegistry(RegistryKey)} and {@link RegistryKey#BIOME}.
  */
 public interface Biome extends OldEnum<Biome>, Keyed, net.kyori.adventure.translation.Translatable { // Paper - Adventure translations
 
@@ -98,7 +99,7 @@ public interface Biome extends OldEnum<Biome>, Keyed, net.kyori.adventure.transl
 
     @NotNull
     private static Biome getBiome(@NotNull String key) {
-        return Registry.BIOME.getOrThrow(NamespacedKey.minecraft(key));
+        return RegistryAccess.registryAccess().getRegistry(RegistryKey.BIOME).getOrThrow(NamespacedKey.minecraft(key));
     }
 
     /**
@@ -113,7 +114,7 @@ public interface Biome extends OldEnum<Biome>, Keyed, net.kyori.adventure.transl
             return Biome.CUSTOM;
         }
 
-        Biome biome = Bukkit.getUnsafe().get(Registry.BIOME, NamespacedKey.fromString(name.toLowerCase(Locale.ROOT)));
+        Biome biome = Bukkit.getUnsafe().get(RegistryKey.BIOME, NamespacedKey.fromString(name.toLowerCase(Locale.ROOT)));
         Preconditions.checkArgument(biome != null, "No biome found with the name %s", name);
         return biome;
     }

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

@@ -509,9 +509,6 @@ public interface Block extends Metadatable, Translatable, net.kyori.adventure.tr
 
     /**
      * Gets the temperature of this block.
-     * <p>
-     * If the raw biome temperature without adjusting for height effects is
-     * required then please use {@link World#getTemperature(int, int, int)}.
      *
      * @return Temperature of this block
      */

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

@@ -1,5 +1,6 @@
 package org.bukkit.block;
 
+import java.util.Collection;
 import java.util.function.Consumer;
 import org.bukkit.Keyed;
 import org.bukkit.Material;
@@ -120,6 +121,7 @@ import org.bukkit.inventory.ItemType;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
+import org.jetbrains.annotations.Unmodifiable;
 
 /**
  * While this API is in a public interface, it is not intended for use by
@@ -169,6 +171,15 @@ public interface BlockType extends Keyed, Translatable, net.kyori.adventure.tran
         @Override
         B createBlockData();
 
+        /**
+         * Creates a collection of {@link BlockData} instances for this block type, with all
+         * possible combinations of properties values.
+         *
+         * @return new block data collection
+         */
+        @Override
+        @Unmodifiable @NotNull Collection<B> createBlockDataStates();
+
         /**
          * Creates a new {@link BlockData} instance for this block type, with all
          * properties initialized to unspecified defaults, except for those provided
@@ -3480,6 +3491,14 @@ public interface BlockType extends Keyed, Translatable, net.kyori.adventure.tran
     @NotNull
     BlockData createBlockData();
 
+    /**
+     * Creates a collection of {@link BlockData} instances for this block type, with all
+     * possible combinations of properties values.
+     *
+     * @return new block data collection
+     */
+    @Unmodifiable @NotNull Collection<? extends BlockData> createBlockDataStates();
+
     /**
      * Creates a new {@link BlockData} instance for this block type, with all
      * properties initialized to unspecified defaults, except for those provided
@@ -3551,7 +3570,7 @@ public interface BlockType extends Keyed, Translatable, net.kyori.adventure.tran
      * state as well. This method will return true if there is at least one
      * state in which additional interact handling is performed for the
      * block type.
-     * 
+     *
      * @deprecated This method is not comprehensive and does not accurately reflect what block types are
      * interactable. Many "interactions" are defined on the item not block, and many are conditional on some other world state
      * checks being true.
@@ -3604,7 +3623,7 @@ public interface BlockType extends Keyed, Translatable, net.kyori.adventure.tran
      *
      * @param world the world to check
      * @return true if this BlockType can be used in this World.
-     * @deprecated Use {@link io.papermc.paper.world.flag.FeatureFlagSetHolder#isEnabled(io.papermc.paper.world.flag.FeatureDependant)}
+     * @deprecated use {@link io.papermc.paper.world.flag.FeatureFlagSetHolder#isEnabled(io.papermc.paper.world.flag.FeatureDependant)}
      */
     @Deprecated(forRemoval = true, since = "1.21.1") // Paper
     boolean isEnabledByFeature(@NotNull World world);

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

@@ -1,8 +1,5 @@
 package org.bukkit.block;
 
-import org.bukkit.loot.Lootable;
-import org.jetbrains.annotations.ApiStatus;
-
 /**
  * Represents a captured state of a crafter.
  */

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

@@ -1,10 +1,7 @@
 package org.bukkit.block;
 
-import org.jetbrains.annotations.ApiStatus;
-
 /**
  * Represents a captured state of a creaking heart.
  */
-@ApiStatus.Experimental
 public interface CreakingHeart extends TileState {
 }

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

@@ -4,27 +4,57 @@ import java.util.Collection;
 import org.bukkit.entity.Entity;
 import org.bukkit.entity.Player;
 import org.bukkit.spawner.TrialSpawnerConfiguration;
-import org.jetbrains.annotations.ApiStatus;
-import org.jetbrains.annotations.NotNull;
+import org.jspecify.annotations.NullMarked;
 
 /**
  * Represents a captured state of a trial spawner.
  */
+@NullMarked
 public interface TrialSpawner extends TileState {
 
+    /**
+     * Gets the game time in ticks when the cooldown ends. 0 if not currently in cooldown.
+     *
+     * @return the game time in ticks
+     * @see org.bukkit.World#getGameTime()
+     */
+    long getCooldownEnd();
+
+    /**
+     * Sets the game time in ticks when the cooldown ends.
+     *
+     * @param ticks the game time in ticks for the new cooldown
+     */
+    void setCooldownEnd(long ticks);
+
+    /**
+     * Gets the game time in ticks when the next spawn attempt happens. 0 if not currently active.
+     *
+     * @return the game time in ticks
+     * @see org.bukkit.World#getGameTime()
+     */
+    long getNextSpawnAttempt();
+
+    /**
+     * Sets the game time in ticks when the next spawn attempt happens.
+     *
+     * @param ticks the game time in ticks for the next mob spawn
+     */
+    void setNextSpawnAttempt(long ticks);
+
     /**
      * Gets the length in ticks the spawner will stay in cooldown for.
      *
      * @return the number of ticks
      */
-    public int getCooldownLength();
+    int getCooldownLength();
 
     /**
      * Sets the length in ticks the spawner will stay in cooldown for.
      *
      * @param ticks the number of ticks
      */
-    public void setCooldownLength(int ticks);
+    void setCooldownLength(int ticks);
 
     /**
      * Get the maximum distance(squared) a player can be in order for this
@@ -38,7 +68,7 @@ public interface TrialSpawner extends TileState {
      * @return the maximum distance(squared) a player can be in order for this
      * spawner to be active.
      */
-    public int getRequiredPlayerRange();
+    int getRequiredPlayerRange();
 
     /**
      * Set the maximum distance (squared) a player can be in order for this
@@ -50,7 +80,7 @@ public interface TrialSpawner extends TileState {
      * @param requiredPlayerRange the maximum distance (squared) a player can be
      * in order for this spawner to be active.
      */
-    public void setRequiredPlayerRange(int requiredPlayerRange);
+    void setRequiredPlayerRange(int requiredPlayerRange);
 
     /**
      * Gets the players this spawner is currently tracking.
@@ -62,8 +92,7 @@ public interface TrialSpawner extends TileState {
      * @return a collection of players this spawner is tracking or an empty
      *         collection if there aren't any
      */
-    @NotNull
-    public Collection<Player> getTrackedPlayers();
+    Collection<Player> getTrackedPlayers();
 
     /**
      * Checks if this spawner is currently tracking the provided player.
@@ -71,7 +100,7 @@ public interface TrialSpawner extends TileState {
      * @param player the player
      * @return true if this spawner is tracking the provided player
      */
-    public boolean isTrackingPlayer(@NotNull Player player);
+    boolean isTrackingPlayer(final Player player);
 
     /**
      * Force this spawner to start tracking the provided player.
@@ -81,7 +110,7 @@ public interface TrialSpawner extends TileState {
      *
      * @param player the player
      */
-    public void startTrackingPlayer(@NotNull Player player);
+    void startTrackingPlayer(final Player player);
 
     /**
      * Force this spawner to stop tracking the provided player.
@@ -91,7 +120,7 @@ public interface TrialSpawner extends TileState {
      *
      * @param player the player
      */
-    public void stopTrackingPlayer(@NotNull Player player);
+    void stopTrackingPlayer(final Player player);
 
     /**
      * Gets a list of entities this spawner is currently tracking.
@@ -103,8 +132,7 @@ public interface TrialSpawner extends TileState {
      * @return a collection of entities this spawner is tracking or an empty
      *         collection if there aren't any
      */
-    @NotNull
-    public Collection<Entity> getTrackedEntities();
+    Collection<Entity> getTrackedEntities();
 
     /**
      * Checks if this spawner is currently tracking the provided entity.
@@ -112,7 +140,7 @@ public interface TrialSpawner extends TileState {
      * @param entity the entity
      * @return true if this spawner is tracking the provided entity
      */
-    public boolean isTrackingEntity(@NotNull Entity entity);
+    boolean isTrackingEntity(final Entity entity);
 
     /**
      * Force this spawner to start tracking the provided entity.
@@ -122,7 +150,7 @@ public interface TrialSpawner extends TileState {
      *
      * @param entity the entity
      */
-    public void startTrackingEntity(@NotNull Entity entity);
+    void startTrackingEntity(final Entity entity);
 
     /**
      * Force this spawner to stop tracking the provided entity.
@@ -132,7 +160,7 @@ public interface TrialSpawner extends TileState {
      *
      * @param entity the entity
      */
-    public void stopTrackingEntity(@NotNull Entity entity);
+    void stopTrackingEntity(final Entity entity);
 
     /**
      * Checks if this spawner is using the ominous
@@ -140,7 +168,7 @@ public interface TrialSpawner extends TileState {
      *
      * @return true is using the ominous configuration
      */
-    public boolean isOminous();
+    boolean isOminous();
 
     /**
      * Changes this spawner between the normal and ominous
@@ -149,7 +177,7 @@ public interface TrialSpawner extends TileState {
      * @param ominous true to use the ominous TrialSpawnerConfiguration, false to
      *                use the normal one.
      */
-    public void setOminous(boolean ominous);
+    void setOminous(boolean ominous);
 
     /**
      * Gets the {@link TrialSpawnerConfiguration} used when {@link #isOminous()} is
@@ -157,8 +185,7 @@ public interface TrialSpawner extends TileState {
      *
      * @return the TrialSpawnerConfiguration
      */
-    @NotNull
-    public TrialSpawnerConfiguration getNormalConfiguration();
+    TrialSpawnerConfiguration getNormalConfiguration();
 
     /**
      * Gets the {@link TrialSpawnerConfiguration} used when {@link #isOminous()} is
@@ -166,6 +193,5 @@ public interface TrialSpawner extends TileState {
      *
      * @return the TrialSpawnerConfiguration
      */
-    @NotNull
-    public TrialSpawnerConfiguration getOminousConfiguration();
+    TrialSpawnerConfiguration getOminousConfiguration();
 }

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

@@ -1,9 +1,184 @@
 package org.bukkit.block;
 
-import org.jetbrains.annotations.ApiStatus;
+import org.bukkit.World;
+import org.bukkit.inventory.ItemStack;
+import org.bukkit.loot.LootTable;
+import org.jetbrains.annotations.Unmodifiable;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+import java.util.Collection;
+import java.util.Set;
+import java.util.UUID;
 
 /**
- * Represents a captured state of a trial spawner.
+ * Represents a captured state of a vault.
  */
+@NullMarked
 public interface Vault extends TileState {
+    /**
+     * Gets the range in blocks at which this vault will become active when a player is near.
+     *
+     * @return This vault's activation range.
+     */
+    double getActivationRange();
+
+    /**
+     * Sets the range in blocks at which the vault will become active when a player is near.
+     *
+     * @param activationRange The new activation range.
+     * @throws IllegalArgumentException if the new range is not a number, or if the new range is more than {@link #getDeactivationRange()}.
+     */
+    void setActivationRange(double activationRange);
+
+    /**
+     * Gets the range in blocks at which this vault will become inactive when a player is not near.
+     *
+     * @return This vault's deactivation range.
+     */
+    double getDeactivationRange();
+
+    /**
+     * Sets the range in blocks at which this vault will become inactive when a player is not near.
+     *
+     * @param deactivationRange The new deactivation range
+     * @throws IllegalArgumentException if the new range is not a number, or if the new range is less than {@link #getActivationRange()}.
+     */
+    void setDeactivationRange(double deactivationRange);
+
+    /**
+     * Gets the {@link ItemStack} that players must use to unlock this vault.
+     *
+     * @return The item that players must use to unlock this vault.
+     */
+    ItemStack getKeyItem();
+
+    /**
+     * Sets the {@link ItemStack} that players must use to unlock this vault.
+     *
+     * @param key The key item.
+     */
+    void setKeyItem(ItemStack key);
+
+    /**
+     * Gets the {@link LootTable} that this vault will select rewards from.
+     *
+     * @return The loot table.
+     */
+    LootTable getLootTable();
+
+    /**
+     * Sets the {@link LootTable} that this vault will select rewards from.
+     *
+     * @param lootTable The new loot table.
+     */
+    void setLootTable(LootTable lootTable);
+
+    /**
+     * Gets the loot table that this vault will display items from.
+     * <p>
+     * Falls back to the regular {@link #getLootTable() loot table} if unset.
+     *
+     * @return The {@link LootTable} that will be used to display items.
+     */
+    @Nullable
+    LootTable getDisplayedLootTable();
+
+    /**
+     * Sets the loot table that this vault will display items from.
+     *
+     * @param lootTable The new loot table to display, or {@code null} to clear this display override.
+     */
+    void setDisplayedLootTable(@Nullable LootTable lootTable);
+
+    /**
+     * Gets the next time (in {@link World#getGameTime() game time}) that this vault block will be updated/ticked at.
+     *
+     * @return The next time that this vault block will be updated/ticked at.
+     * @see World#getGameTime()
+     */
+    long getNextStateUpdateTime();
+
+    /**
+     * Sets the next time that this vault block will be updated/ticked at, if this value is less than or equals to the current
+     * {@link World#getGameTime()}, then it will be updated in the first possible tick.
+     *
+     * @param nextStateUpdateTime The next time that this vault block will be updated/ticked at.
+     * @see World#getGameTime()
+     */
+    void setNextStateUpdateTime(long nextStateUpdateTime);
+
+    /**
+     * Gets the players who have used a key on this vault and unlocked it.
+     *
+     * @return An unmodifiable collection of player uuids.
+     *
+     * @apiNote Only the most recent 128 player UUIDs will be stored by vault blocks.
+     */
+    @Unmodifiable
+    Collection<UUID> getRewardedPlayers();
+
+    /**
+     * Adds a player as rewarded for this vault.
+     *
+     * @param playerUUID The player's uuid.
+     * @return {@code true} if this player was previously not rewarded, and has been added as a result of this operation.
+     *
+     * @apiNote Only the most recent 128 player UUIDs will be stored by vault blocks. Attempting to add more will result in
+     *      the first player UUID being removed.
+     */
+    boolean addRewardedPlayer(UUID playerUUID);
+
+    /**
+     * Removes a player as rewarded for this vault, allowing them to use a {@link #getKeyItem() key item} again to receive rewards.
+     *
+     * @param playerUUID The player's uuid.
+     * @return {@code true} if this player was previously rewarded, and has been removed as a result of this operation.
+     *
+     * @apiNote Only the most recent 128 player UUIDs will be stored by vault blocks.
+     */
+    boolean removeRewardedPlayer(UUID playerUUID);
+
+    /**
+     * Returns whether a given player has already been rewarded by this vault.
+     *
+     * @param playerUUID The player's uuid.
+     * @return Whether this player was previously rewarded by this vault.
+     */
+    boolean hasRewardedPlayer(UUID playerUUID);
+
+    /**
+     * Gets an unmodifiable set of "connected players"; players who are inside this vault's activation range and who have not received rewards yet.
+     *
+     * @apiNote Vaults will only periodically scan for nearby players, so it may take until the next {@link #getNextStateUpdateTime() update time} for this
+     * collection to be updated upon a player entering its range.
+     *
+     * @return An unmodifiable set of connected player uuids.
+     */
+    @Unmodifiable
+    Set<UUID> getConnectedPlayers();
+
+    /**
+     * Returns whether a given player is currently connected to this vault.
+     *
+     * @param playerUUID the player's uuid
+     * @return {@code true} if this player is currently connected to this vault.
+     *
+     * @see #getConnectedPlayers()
+     */
+    boolean hasConnectedPlayer(UUID playerUUID);
+
+    /**
+     * Gets the item currently being displayed inside this vault. Displayed items will automatically cycle between random items from the {@link #getDisplayedLootTable()}
+     * or {@link #getLootTable()} loot tables while this vault is active.
+     *
+     * @return The item currently being displayed inside this vault.
+     */
+    ItemStack getDisplayedItem();
+
+    /**
+     * Sets the item to display inside this vault until the next cycle.
+     *
+     * @param displayedItem The item to display
+     */
+    void setDisplayedItem(ItemStack displayedItem);
 }

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

@@ -2,6 +2,7 @@ package org.bukkit.block.banner;
 
 import com.google.common.base.Preconditions;
 import com.google.common.collect.ImmutableMap;
+import io.papermc.paper.registry.RegistryKey;
 import java.util.Map;
 import java.util.NoSuchElementException;
 import org.bukkit.Bukkit;
@@ -45,7 +46,7 @@ public class Pattern implements ConfigurationSerializable {
         PatternType patternType = PatternType.getByIdentifier(value);
 
         if (patternType == null) {
-            patternType = Bukkit.getUnsafe().get(Registry.BANNER_PATTERN, NamespacedKey.fromString(value));
+            patternType = Bukkit.getUnsafe().get(RegistryKey.BANNER_PATTERN, NamespacedKey.fromString(value));
         }
 
         Preconditions.checkNotNull(patternType, "Pattern type for key %s cannot be null", value);

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

@@ -2,6 +2,8 @@ package org.bukkit.block.banner;
 
 import com.google.common.base.Preconditions;
 import com.google.common.collect.Lists;
+import io.papermc.paper.registry.RegistryAccess;
+import io.papermc.paper.registry.RegistryKey;
 import java.util.Locale;
 import org.bukkit.Keyed;
 import org.bukkit.NamespacedKey;
@@ -95,8 +97,7 @@ public interface PatternType extends OldEnum<PatternType>, Keyed {
      *
      * @param identifier the identifier
      * @return the matched pattern type or null
-     * @see Registry#BANNER_PATTERN
-     * @deprecated magic value, use {@link Registry#get(NamespacedKey)} instead
+     * @deprecated magic value, use {@link Registry#get(NamespacedKey)} instead with {@link io.papermc.paper.registry.RegistryAccess#getRegistry(io.papermc.paper.registry.RegistryKey)} and {@link io.papermc.paper.registry.RegistryKey#BANNER_PATTERN}
      */
     @Contract("null -> null")
     @Nullable
@@ -117,7 +118,7 @@ public interface PatternType extends OldEnum<PatternType>, Keyed {
 
     @NotNull
     private static PatternType getType(@NotNull String key) {
-        return Registry.BANNER_PATTERN.getOrThrow(NamespacedKey.minecraft(key));
+        return RegistryAccess.registryAccess().getRegistry(RegistryKey.BANNER_PATTERN).getOrThrow(NamespacedKey.minecraft(key));
     }
 
     /**

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

@@ -1,14 +1,12 @@
 package org.bukkit.block.data.type;
 
 import org.bukkit.block.data.Orientable;
-import org.jetbrains.annotations.ApiStatus;
 
 /**
  * 'active' is whether the block is active.
  * <br>
  * 'natural' is whether this is a naturally generated block.
  */
-@ApiStatus.Experimental
 public interface CreakingHeart extends Orientable {
 
     /**

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

@@ -1,12 +1,10 @@
 package org.bukkit.block.data.type;
 
 import org.bukkit.block.data.BlockData;
-import org.jetbrains.annotations.ApiStatus;
 
 /**
  * 'tip' indicates whether this block is a tip.
  */
-@ApiStatus.Experimental
 public interface HangingMoss extends BlockData {
 
     /**

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

@@ -2,7 +2,6 @@ package org.bukkit.block.data.type;
 
 import org.bukkit.block.BlockFace;
 import org.bukkit.block.data.BlockData;
-import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 
 /**
@@ -11,7 +10,6 @@ import org.jetbrains.annotations.NotNull;
  *
  * 'bottom' denotes whether this is a bottom block.
  */
-@ApiStatus.Experimental
 public interface MossyCarpet extends BlockData {
 
     /**

paper-api/src/main/java/org/bukkit/damage/DamageSource.java

@@ -51,6 +51,8 @@ public interface DamageSource {
      * be present if an entity did not cause the damage.
      *
      * @return the location, or null if none
+     * @apiNote the world of the location might be null for positioned-only damage source
+     * not caused by any entity
      */
     @Nullable
     public Location getDamageLocation();
@@ -66,6 +68,8 @@ public interface DamageSource {
      * returned.
      *
      * @return the source of the location or null.
+     * @apiNote the world of the location might be null for positioned-only damage source
+     * not caused by any entity
      */
     @Nullable
     public Location getSourceLocation();

paper-api/src/main/java/org/bukkit/damage/DamageType.java

@@ -1,5 +1,7 @@
 package org.bukkit.damage;
 
+import io.papermc.paper.registry.RegistryAccess;
+import io.papermc.paper.registry.RegistryKey;
 import org.bukkit.Keyed;
 import org.bukkit.NamespacedKey;
 import org.bukkit.Registry;
@@ -12,7 +14,7 @@ import org.jetbrains.annotations.NotNull;
  * <p>
  * Constants in this class include the base types provided by the vanilla
  * server. Data packs are capable of registering more types of damage which may
- * be obtained through the {@link Registry#DAMAGE_TYPE}.
+ * be obtained through {@link io.papermc.paper.registry.RegistryAccess#getRegistry(RegistryKey)} and {@link RegistryKey#DAMAGE_TYPE}.
  *
  * @see <a href="https://minecraft.wiki/w/Damage_type">Minecraft Wiki</a>
  */
@@ -71,7 +73,7 @@ public interface DamageType extends Keyed, Translatable {
 
     @NotNull
     private static DamageType getDamageType(@NotNull String key) {
-        return Registry.DAMAGE_TYPE.getOrThrow(NamespacedKey.minecraft(key));
+        return RegistryAccess.registryAccess().getRegistry(RegistryKey.DAMAGE_TYPE).getOrThrow(NamespacedKey.minecraft(key));
     }
 
     /**

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

@@ -1,6 +1,8 @@
 package org.bukkit.enchantments;
 
 import com.google.common.collect.Lists;
+import io.papermc.paper.registry.RegistryAccess;
+import io.papermc.paper.registry.RegistryKey;
 import java.util.Locale;
 import org.bukkit.Keyed;
 import org.bukkit.NamespacedKey;
@@ -229,7 +231,7 @@ public abstract class Enchantment implements Keyed, Translatable, net.kyori.adve
 
     @NotNull
     private static Enchantment getEnchantment(@NotNull String key) {
-        return Registry.ENCHANTMENT.getOrThrow(NamespacedKey.minecraft(key));
+        return RegistryAccess.registryAccess().getRegistry(RegistryKey.ENCHANTMENT).getOrThrow(NamespacedKey.minecraft(key));
     }
 
     /**

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

@@ -5,6 +5,8 @@ import org.bukkit.inventory.ItemStack;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
+import org.jetbrains.annotations.Unmodifiable;
+import java.util.List;
 
 /**
  * Represents an arrow.
@@ -99,10 +101,23 @@ public interface AbstractArrow extends Projectile {
      * Gets the block to which this arrow is attached.
      *
      * @return the attached block or null if not attached
+     * @deprecated can be attached to multiple blocks use {@link AbstractArrow#getAttachedBlocks()} instead
      */
     @Nullable
+    @Deprecated(since = "1.21.4")
     public Block getAttachedBlock();
 
+    /**
+     * Gets the block(s) which this arrow is attached to.
+     * All the returned blocks are responsible for preventing
+     * the arrow from falling.
+     *
+     * @return the attached block(s) or an empty list if not attached
+     */
+    @NotNull
+    @Unmodifiable
+    List<Block> getAttachedBlocks();
+
     /**
      * Gets the current pickup status of this arrow.
      *