Merge remote-tracking branch 'upstream/dev/3.0.0'

# Conflicts:
#	proxy/src/main/java/com/velocitypowered/proxy/protocol/StateRegistry.java

api/build.gradle.kts

@@ -70,7 +70,7 @@ tasks {
             "https://jd.advntr.dev/api/${libs.adventure.bom.get().version}/",
             "https://jd.advntr.dev/text-minimessage/${libs.adventure.bom.get().version}/",
             "https://jd.advntr.dev/key/${libs.adventure.bom.get().version}/",
-            "https://javadoc.io/doc/com.github.ben-manes.caffeine/caffeine/${libs.caffeine.get().version}/",
+            "https://www.javadocs.dev/com.github.ben-manes.caffeine/caffeine/${libs.caffeine.get().version}/",
         )
 
         o.tags(

api/src/ap/java/com/velocitypowered/api/plugin/ap/PluginAnnotationProcessor.java

@@ -14,7 +14,6 @@ import com.velocitypowered.api.plugin.Plugin;
 import java.io.BufferedWriter;
 import java.io.IOException;
 import java.io.Writer;
-import java.util.Objects;
 import java.util.Set;
 import javax.annotation.processing.AbstractProcessor;
 import javax.annotation.processing.ProcessingEnvironment;
@@ -68,8 +67,8 @@ public class PluginAnnotationProcessor extends AbstractProcessor {
 
       Name qualifiedName = ((TypeElement) element).getQualifiedName();
 
-      if (Objects.equals(pluginClassFound, qualifiedName.toString())) {
-        if (!warnedAboutMultiplePlugins) {
+      if (pluginClassFound != null) {
+        if (!pluginClassFound.equals(qualifiedName.toString()) && !warnedAboutMultiplePlugins) {
           environment.getMessager()
               .printMessage(Diagnostic.Kind.WARNING, "Velocity does not yet currently support "
                   + "multiple plugins. We are using " + pluginClassFound

api/src/main/java/com/velocitypowered/api/event/EventManager.java

@@ -60,7 +60,8 @@ public interface EventManager {
    *
    * @param plugin the plugin to associate with the handler
    * @param eventClass the class for the event handler to register
-   * @param postOrder the relative order in which events should be posted to the handler
+   * @param postOrder the relative order in which events should be posted to the handler. The higher
+   *     the priority, the earlier the event handler will be called
    * @param handler the handler to register
    * @param <E> the event type to handle
    */

api/src/main/java/com/velocitypowered/api/event/proxy/ProxyPreShutdownEvent.java

@@ -0,0 +1,33 @@
+/*
+ * Copyright (C) 2018-2025 Velocity Contributors
+ *
+ * The Velocity API is licensed under the terms of the MIT License. For more details,
+ * reference the LICENSE file in the api top-level directory.
+ */
+
+package com.velocitypowered.api.event.proxy;
+
+import com.google.common.annotations.Beta;
+import com.velocitypowered.api.event.annotation.AwaitingEvent;
+
+/**
+ * This event is fired by the proxy after it has stopped accepting new connections,
+ * but before players are disconnected.
+ * This is the last point at which you can interact with currently connected players,
+ * for example to transfer them to another proxy or perform other cleanup tasks.
+ *
+ * @implNote Velocity will wait for all event listeners to complete before disconnecting players,
+ *     but note that the event will time out after the configured value of the
+ *     <code>velocity.pre-shutdown-timeout</code> system property, default 10 seconds,
+ *     in seconds to prevent shutdown from hanging indefinitely
+ * @since 3.4.0
+ */
+@Beta
+@AwaitingEvent
+public final class ProxyPreShutdownEvent {
+
+  @Override
+  public String toString() {
+    return "ProxyPreShutdownEvent";
+  }
+}

api/src/main/java/com/velocitypowered/api/network/ProtocolVersion.java

@@ -92,7 +92,8 @@ public enum ProtocolVersion implements Ordered<ProtocolVersion> {
   MINECRAFT_1_21_4(769, "1.21.4"),
   MINECRAFT_1_21_5(770, "1.21.5"),
   MINECRAFT_1_21_6(771, "1.21.6"),
-  MINECRAFT_1_21_7(772, "1.21.7", "1.21.8");
+  MINECRAFT_1_21_7(772, "1.21.7", "1.21.8"),
+  MINECRAFT_1_21_9(773, "1.21.9", "1.21.10");
 
   private static final int SNAPSHOT_BIT = 30;
 

api/src/main/java/com/velocitypowered/api/proxy/Player.java

@@ -29,6 +29,7 @@ import java.util.Locale;
 import java.util.Optional;
 import java.util.UUID;
 import java.util.function.UnaryOperator;
+import net.kyori.adventure.dialog.DialogLike;
 import net.kyori.adventure.identity.Identified;
 import net.kyori.adventure.inventory.Book;
 import net.kyori.adventure.key.Key;
@@ -48,7 +49,7 @@ public interface Player extends
     /* Fundamental Velocity interfaces */
     CommandSource, InboundConnection, ChannelMessageSource, ChannelMessageSink,
     /* Adventure-specific interfaces */
-    Identified, HoverEventSource<HoverEvent.ShowEntity>, Keyed, KeyIdentifiable {
+    Identified, HoverEventSource<HoverEvent.ShowEntity>, Keyed, KeyIdentifiable, Sound.Emitter {
 
   /**
    * Returns the player's current username.
@@ -383,8 +384,12 @@ public interface Player extends
   /**
    * {@inheritDoc}
    *
-   * <b>This method is not currently implemented in Velocity
-   * and will not perform any actions.</b>
+   *
+   * @apiNote <b>This method is not currently implemented in Velocity
+   *     and will not perform any actions.</b>
+   * @see #playSound(Sound, Sound.Emitter)
+   * @see <a href="https://docs.papermc.io/velocity/dev/pitfalls/#audience-operations-are-not-fully-supported">
+   *   Unsupported Adventure Operations</a>
    */
   @Override
   default void playSound(@NotNull Sound sound) {
@@ -393,8 +398,11 @@ public interface Player extends
   /**
    * {@inheritDoc}
    *
-   * <b>This method is not currently implemented in Velocity
-   * and will not perform any actions.</b>
+   * @apiNote <b>This method is not currently implemented in Velocity
+   *     and will not perform any actions.</b>
+   * @see #playSound(Sound, Sound.Emitter)
+   * @see <a href="https://docs.papermc.io/velocity/dev/pitfalls/#audience-operations-are-not-fully-supported">
+   *   Unsupported Adventure Operations</a>
    */
   @Override
   default void playSound(@NotNull Sound sound, double x, double y, double z) {
@@ -403,18 +411,28 @@ public interface Player extends
   /**
    * {@inheritDoc}
    *
-   * <b>This method is not currently implemented in Velocity
-   * and will not perform any actions.</b>
+   * <p><b>Note</b>: Due to <a href="https://bugs.mojang.com/browse/MC/issues/MC-146721">MC-146721</a>, stereo sounds are always played globally in 1.14+.
+   *
+   * <p><b>Note</b>: Due to <a href="https://bugs.mojang.com/browse/MC/issues/MC-138832">MC-138832</a>, the volume and pitch are ignored when using this method in 1.14 to 1.16.5.
+   *
+   * @param sound the sound to play
+   * @param emitter the emitter of the sound; may be another player of this player's server
+   * @since 3.4.0
+   * @sinceMinecraft 1.19.3
+   * @apiNote This method is currently only implemented for players on 1.19.3+
+   *     and requires a present {@link #getCurrentServer} for the emitting player as well as this player.
    */
   @Override
-  default void playSound(@NotNull Sound sound, Sound.Emitter emitter) {
+  default void playSound(@NotNull Sound sound, @NotNull Sound.Emitter emitter) {
   }
 
   /**
    * {@inheritDoc}
    *
-   * <b>This method is not currently implemented in Velocity
-   * and will not perform any actions.</b>
+   * @param stop the sound and/or a sound source, to stop
+   * @since 3.4.0
+   * @sinceMinecraft 1.19.3
+   * @apiNote This method is currently only implemented for players on 1.19.3+.
    */
   @Override
   default void stopSound(@NotNull SoundStop stop) {
@@ -425,11 +443,40 @@ public interface Player extends
    *
    * <b>This method is not currently implemented in Velocity
    * and will not perform any actions.</b>
+   *
+   * @see <a href="https://docs.papermc.io/velocity/dev/pitfalls/#audience-operations-are-not-fully-supported">
+   *   Unsupported Adventure Operations</a>
    */
   @Override
   default void openBook(@NotNull Book book) {
   }
 
+  /**
+   * {@inheritDoc}
+   *
+   * <b>This method is not currently implemented in Velocity
+   * and will not perform any actions.</b>
+   *
+   * @see <a href="https://docs.papermc.io/velocity/dev/pitfalls/#audience-operations-are-not-fully-supported">
+   *   Unsupported Adventure Operations</a>
+   */
+  @Override
+  default void showDialog(@NotNull DialogLike dialog) {
+  }
+
+  /**
+   * {@inheritDoc}
+   *
+   * <b>This method is not currently implemented in Velocity
+   * and will not perform any actions.</b>
+   *
+   * @see <a href="https://docs.papermc.io/velocity/dev/pitfalls/#audience-operations-are-not-fully-supported">
+   *   Unsupported Adventure Operations</a>
+   */
+  @Override
+  default void closeDialog() {
+  }
+
   /**
    * Transfers a Player to a host.
    *

api/src/main/java/com/velocitypowered/api/proxy/server/ServerPing.java

@@ -19,7 +19,9 @@ import java.util.List;
 import java.util.Objects;
 import java.util.Optional;
 import java.util.UUID;
-import org.checkerframework.checker.nullness.qual.Nullable;
+import net.kyori.adventure.text.Component;
+import org.jspecify.annotations.Nullable;
+
 
 /**
  * Represents a 1.7 and above server list ping response. This class is immutable.
@@ -28,7 +30,7 @@ public final class ServerPing {
 
   private final Version version;
   private final @Nullable Players players;
-  private final net.kyori.adventure.text.Component description;
+  private final @Nullable Component description;
   private final @Nullable Favicon favicon;
   private final @Nullable ModInfo modinfo;
   private final boolean preventsChatReports = true;
@@ -48,8 +50,8 @@ public final class ServerPing {
    * @param modinfo the mods this server runs
    */
   public ServerPing(Version version, @Nullable Players players,
-      net.kyori.adventure.text.Component description, @Nullable Favicon favicon,
-      @Nullable ModInfo modinfo) {
+                    Component description, @Nullable Favicon favicon,
+                    @Nullable ModInfo modinfo) {
     this.version = Preconditions.checkNotNull(version, "version");
     this.players = players;
     this.description = Preconditions.checkNotNull(description, "description");
@@ -65,7 +67,8 @@ public final class ServerPing {
     return Optional.ofNullable(players);
   }
 
-  public net.kyori.adventure.text.Component getDescriptionComponent() {
+  @Nullable
+  public Component getDescriptionComponent() {
     return description;
   }
 
@@ -152,7 +155,7 @@ public final class ServerPing {
     private final List<SamplePlayer> samplePlayers = new ArrayList<>();
     private String modType = "FML";
     private final List<ModInfo.Mod> mods = new ArrayList<>();
-    private net.kyori.adventure.text.Component description;
+    private Component description;
     private @Nullable Favicon favicon;
     private boolean nullOutPlayers;
     private boolean nullOutModinfo;
@@ -300,7 +303,7 @@ public final class ServerPing {
      * @param description Component to use as the description.
      * @return this builder, for chaining
      */
-    public Builder description(net.kyori.adventure.text.Component description) {
+    public Builder description(Component description) {
       this.description = Preconditions.checkNotNull(description, "description");
       return this;
     }
@@ -360,7 +363,7 @@ public final class ServerPing {
       return samplePlayers;
     }
 
-    public Optional<net.kyori.adventure.text.Component> getDescriptionComponent() {
+    public Optional<Component> getDescriptionComponent() {
       return Optional.ofNullable(description);
     }