Merge remote-tracking branch 'PaperMC/dev/3.0.0' into merge/dev3.0.0

# Conflicts:
#	build-logic/src/main/kotlin/velocity-publish.gradle.kts
#	proxy/src/main/java/com/velocitypowered/proxy/protocol/packet/chat/RateLimitedCommandHandler.java

Author: WiIIiam278

.github/workflows/gradle.yml

@@ -6,16 +6,16 @@ on: [push]
 
 jobs:
   build:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     steps:
     - name: Checkout Repository
-      uses: actions/checkout@v4
+      uses: actions/checkout@v6
       with:
         persist-credentials: false
     - name: Set up Gradle
-      uses: gradle/actions/setup-gradle@v4
+      uses: gradle/actions/setup-gradle@v5
     - name: Set up JDK 21
-      uses: actions/setup-java@v4
+      uses: actions/setup-java@v5
       with:
         java-version: 21
         distribution: 'zulu'

api/build.gradle.kts

@@ -24,7 +24,7 @@ dependencies {
     api(libs.guava)
 
     // DEPRECATED: Will be removed in Velocity Polymer
-    api("com.moandjiezana.toml:toml4j:0.7.2")
+    api("io.hotmoka:toml4j:0.7.3")
 
     api(platform(libs.adventure.bom))
     api("net.kyori:adventure-api")
@@ -55,22 +55,20 @@ tasks {
         }
     }
     withType<Javadoc> {
-        exclude("com/velocitypowered/api/plugin/ap/**")
-
         val o = options as StandardJavadocDocletOptions
         o.encoding = "UTF-8"
-        o.source = "17"
+        o.source = "21"
 
         o.use()
         o.links(
-            "https://www.slf4j.org/apidocs/",
+            "https://www.javadocs.dev/org.slf4j/slf4j-api/${libs.slf4j.get().version}/",
             "https://guava.dev/releases/${libs.guava.get().version}/api/docs/",
             "https://google.github.io/guice/api-docs/${libs.guice.get().version}/javadoc/",
-            "https://docs.oracle.com/en/java/javase/17/docs/api/",
+            "https://docs.oracle.com/en/java/javase/21/docs/api/",
             "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(
@@ -79,8 +77,5 @@ tasks {
             "implNote:a:Implementation Note:",
             "sinceMinecraft:a:Since Minecraft:"
         )
-
-        // Disable the crazy super-strict doclint tool in Java 8
-        o.addStringOption("Xdoclint:none", "-quiet")
     }
 }

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

@@ -14,7 +14,6 @@
 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;
@@ -37,6 +36,15 @@
 @SupportedAnnotationTypes({"com.velocitypowered.api.plugin.Plugin"})
 public class PluginAnnotationProcessor extends AbstractProcessor {
 
+  /**
+   * Creates a new {@code PluginAnnotationProcessor}.
+   *
+   * <p>The processor is instantiated by the Java compiler and initialized via
+   * {@link #init(ProcessingEnvironment)}.</p>
+   */
+  public PluginAnnotationProcessor() {
+  }
+
   private ProcessingEnvironment environment;
   private String pluginClassFound;
   private boolean warnedAboutMultiplePlugins;
@@ -68,8 +76,8 @@ public synchronized boolean process(Set<? extends TypeElement> annotations,
 
       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/ap/java/com/velocitypowered/api/plugin/ap/SerializedPluginDescription.java

@@ -24,7 +24,20 @@
  */
 public final class SerializedPluginDescription {
 
-  public static final Pattern ID_PATTERN = Pattern.compile("[a-z][a-z0-9-_]{0,63}");
+  /**
+   * The string pattern used to validate plugin IDs.
+   *
+   * <p>Plugin IDs must start with a lowercase letter and may contain lowercase letters,
+   * digits, hyphens, and underscores. The total length must not exceed 64 characters.</p>
+   */
+  public static final String ID_PATTERN_STRING = "[a-z][a-z0-9-_]{0,63}";
+  /**
+   * The compiled pattern used to validate plugin IDs.
+   *
+   * <p>Plugin IDs must start with a lowercase letter and may contain lowercase letters,
+   * digits, hyphens, and underscores. The total length must not exceed 64 characters.</p>
+   */
+  public static final Pattern ID_PATTERN = Pattern.compile(ID_PATTERN_STRING);
 
   // @Nullable is used here to make GSON skip these in the serialized file
   private final String id;
@@ -63,34 +76,78 @@ static SerializedPluginDescription from(Plugin plugin, String qualifiedName) {
             .collect(Collectors.toList()), dependencies, qualifiedName);
   }
 
+  /**
+   * Gets the ID of the plugin this dependency refers to.
+   *
+   * @return the plugin ID
+   */
   public String getId() {
     return id;
   }
 
+  /**
+   * Gets the human-readable name of the plugin.
+   *
+   * @return the plugin's name, or {@code null} if not specified
+   */
   public @Nullable String getName() {
     return name;
   }
 
+  /**
+   * Gets the version string of the plugin.
+   *
+   * @return the plugin version, or {@code null} if not specified
+   */
   public @Nullable String getVersion() {
     return version;
   }
 
+  /**
+   * Gets the plugin's description, typically a short summary of its functionality.
+   *
+   * @return the description, or {@code null} if not specified
+   */
   public @Nullable String getDescription() {
     return description;
   }
 
+  /**
+   * Gets the website URL for the plugin.
+   *
+   * <p>This is often used to link to documentation, support, or the plugin's homepage.</p>
+   *
+   * @return the plugin URL, or {@code null} if not specified
+   */
   public @Nullable String getUrl() {
     return url;
   }
 
+  /**
+   * Gets the list of authors who contributed to the plugin.
+   *
+   * @return an immutable list of authors; empty if none were specified
+   */
   public List<String> getAuthors() {
     return authors == null ? ImmutableList.of() : authors;
   }
 
+  /**
+   * Gets the list of declared dependencies for the plugin.
+   *
+   * <p>Dependencies may be required or optional and describe other plugins, this one depends.</p>
+   *
+   * @return an immutable list of plugin dependencies
+   */
   public List<Dependency> getDependencies() {
     return dependencies == null ? ImmutableList.of() : dependencies;
   }
 
+  /**
+   * Gets the fully qualified name of the plugin's main class.
+   *
+   * @return the main class name
+   */
   public String getMain() {
     return main;
   }
@@ -141,15 +198,33 @@ public static final class Dependency {
     private final String id;
     private final boolean optional;
 
+    /**
+     * Constructs a new dependency class.
+     *
+     * @param id the ID of the dependent plugin
+     * @param optional whether the dependency is optional
+     */
     public Dependency(String id, boolean optional) {
       this.id = id;
       this.optional = optional;
     }
 
+    /**
+     * Gets the ID of the plugin this dependency refers to.
+     *
+     * @return the plugin ID
+     */
     public String getId() {
       return id;
     }
 
+    /**
+     * Indicates whether this dependency is optional.
+     *
+     * <p>Optional dependencies are not required for the plugin to load.</p>
+     *
+     * @return {@code true} if the dependency is optional; {@code false} otherwise
+     */
     public boolean isOptional() {
       return optional;
     }

api/src/main/java/com/velocitypowered/api/command/CommandSource.java

@@ -23,22 +23,22 @@ public interface CommandSource extends Audience, PermissionSubject {
    * Sends a message with the MiniMessage format to this source.
    *
    * @param message MiniMessage content
-   * @see <a href="https://docs.advntr.dev/minimessage/format.html">MiniMessage docs</a>
+   * @see <a href="https://docs.papermc.io/adventure/minimessage/format/">MiniMessage docs</a>
    *      for more information on the format.
-   **/
+   */
   default void sendRichMessage(final @NotNull String message) {
     this.sendMessage(MiniMessage.miniMessage().deserialize(message, this));
   }
 
   /**
-  * Sends a message with the MiniMessage format to this source.
-  *
-  * @param message MiniMessage content
-  * @param resolvers resolvers to use
-  * @see <a href="https://docs.advntr.dev/minimessage/">MiniMessage docs</a>
-  *     and <a href="https://docs.advntr.dev/minimessage/dynamic-replacements">MiniMessage Placeholders docs</a>
-  *     for more information on the format.
-  **/
+   * Sends a message with the MiniMessage format to this source.
+   *
+   * @param message MiniMessage content
+   * @param resolvers resolvers to use
+   * @see <a href="https://docs.papermc.io/adventure/minimessage/">MiniMessage docs</a>
+   *     and <a href="https://docs.papermc.io/adventure/minimessage/dynamic-replacements">MiniMessage Placeholders docs</a>
+   *     for more information on the format.
+   */
   default void sendRichMessage(
           final @NotNull String message,
           final @NotNull TagResolver @NotNull... resolvers
@@ -47,13 +47,13 @@ default void sendRichMessage(
   }
 
   /**
-  * Sends a plain message to this source.
-  *
-  * @param message plain message
-  * @apiNote This method will not apply any form of parse to the text provided,
-  *      however, it is recommended not to use legacy color codes as this is a deprecated format
+   * Sends a plain message to this source.
+   *
+   * @param message plain message
+   * @apiNote This method will not apply any form of parse to the text provided,
+   *      however, it is recommended not to use legacy color codes as this is a deprecated format
    *     and not recommended.
-  */
+   */
   default void sendPlainMessage(final @NotNull String message) {
     this.sendMessage(Component.text(message));
   }

api/src/main/java/com/velocitypowered/api/command/VelocityBrigadierMessage.java

@@ -20,6 +20,12 @@
  */
 public final class VelocityBrigadierMessage implements Message, ComponentLike {
 
+  /**
+   * Creates a new {@link VelocityBrigadierMessage} using the given {@link Component} as the message.
+   *
+   * @param message the component to use as the tooltip message
+   * @return a new instance of {@link VelocityBrigadierMessage}
+   */
   public static VelocityBrigadierMessage tooltip(Component message) {
     return new VelocityBrigadierMessage(message);
   }

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

@@ -20,6 +20,8 @@ public interface Continuation {
 
   /**
    * Resumes the continuation after the executed task failed.
+   *
+   * @param exception the {@link Throwable} that caused the failure
    */
   void resumeWithException(Throwable exception);
-}
+}

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

@@ -13,12 +13,28 @@
  * Represents an interface to perform direct dispatch of an event. This makes integration easier to
  * achieve with platforms such as RxJava. While this interface can be used to implement an awaiting
  * event handler, {@link AwaitingEventExecutor} provides a more idiomatic means to doing so.
+ *
+ * @param <E> the event type this handler accepts
  */
 @FunctionalInterface
 public interface EventHandler<E> {
 
+  /**
+   * Executes this handler synchronously with the given event.
+   *
+   * @param event the event to handle
+   */
   void execute(E event);
 
+  /**
+   * Executes this handler asynchronously with the given event.
+   *
+   * <p>If asynchronous handling is not implemented, the event is executed synchronously
+   * and this method returns {@code null}.</p>
+   *
+   * @param event the event to handle
+   * @return an {@link EventTask} representing the async task, or {@code null} if not async
+   */
   default @Nullable EventTask executeAsync(E event) {
     execute(event);
     return null;

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

@@ -60,7 +60,8 @@ <E> void register(Object plugin, Class<E> eventClass, PostOrder postOrder,
    *
    * @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
    */
@@ -72,6 +73,7 @@ <E> void register(Object plugin, Class<E> eventClass, short postOrder,
    * servicing connections while a plugin handles a potentially long-running operation such as a
    * database query.
    *
+   * @param <E> the event type
    * @param event the event to fire
    * @return a {@link CompletableFuture} representing the posted event
    */

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

@@ -12,7 +12,34 @@
  */
 public enum PostOrder {
 
-  FIRST, EARLY, NORMAL, LATE, LAST,
+  /**
+   * Indicates the listener should be invoked first, before any other listener.
+   * This order is suitable for listeners that must handle the event before others.
+   */
+  FIRST,
+  /**
+   * Indicates the listener should be invoked early, but after listeners with {@link #FIRST}.
+   * This order is suitable for handling the event before most other listeners.
+   */
+  EARLY,
+  /**
+   * Indicates the listener should be invoked in the normal order of execution.
+   * This is the default and most commonly used order.
+   */
+  NORMAL,
+  /**
+   * Indicates the listener should be invoked later in the execution order,
+   * after listeners with {@link #NORMAL}.
+   * This order is suitable for listeners that should observe the results of
+   * earlier listeners.
+   */
+  LATE,
+  /**
+   * Indicates the listener should be invoked last, after all other listeners.
+   * This order is suitable for listeners that should run only after all others
+   * have completed handling the event.
+   */
+  LAST,
 
   /**
    * Previously used to specify that {@link Subscribe#priority()} should be used.