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

api/build.gradle.kts

@@ -70,6 +70,12 @@ tasks {
             "https://javadoc.io/doc/com.github.ben-manes.caffeine/caffeine"
         )
 
+        o.tags(
+            "apiNote:a:API Note:",
+            "implSpec:a:Implementation Requirements:",
+            "implNote:a:Implementation Note:"
+        )
+
         // Disable the crazy super-strict doclint tool in Java 8
         o.addStringOption("Xdoclint:none", "-quiet")
     }

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

@@ -9,10 +9,52 @@
 
 import com.velocitypowered.api.permission.PermissionSubject;
 import net.kyori.adventure.audience.Audience;
+import net.kyori.adventure.text.Component;
+import net.kyori.adventure.text.minimessage.MiniMessage;
+import net.kyori.adventure.text.minimessage.tag.resolver.TagResolver;
+import org.jetbrains.annotations.NotNull;
 
 /**
  * Represents something that can be used to run a {@link Command}.
  */
 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>
+   *      for more information on the format.
+   **/
+  default void sendRichMessage(final @NotNull String message) {
+    this.sendMessage(MiniMessage.miniMessage().deserialize(message));
+  }
+
+  /**
+  * 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.
+  **/
+  default void sendRichMessage(
+          final @NotNull String message,
+          final @NotNull TagResolver @NotNull... resolvers
+  ) {
+    this.sendMessage(MiniMessage.miniMessage().deserialize(message, resolvers));
+  }
+
+  /**
+  * 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/event/command/CommandExecuteEvent.java

@@ -39,6 +39,11 @@ public CommandExecuteEvent(CommandSource commandSource, String command) {
     this.result = CommandResult.allowed();
   }
 
+  /**
+   * Gets the source responsible for the execution of this command.
+   *
+   * @return the source executing the command
+   */
   public CommandSource getCommandSource() {
     return commandSource;
   }
@@ -47,6 +52,10 @@ public CommandSource getCommandSource() {
    * Gets the original command being executed without the first slash.
    *
    * @return the original command being executed
+   * @apiNote Note that the player can provide a command that begins with spaces,
+   *          but still be validly executed. For example, the command {@code /  velocity info},
+   *          although not valid in the chat bar, will be executed as correctly as if
+   *          the player had executed {@code /velocity info}
    */
   public String getCommand() {
     return command;
@@ -58,7 +67,7 @@ public CommandResult getResult() {
   }
 
   @Override
-  public void setResult(CommandResult result) {
+  public void setResult(final @NonNull CommandResult result) {
     this.result = Preconditions.checkNotNull(result, "result");
   }
 
@@ -80,11 +89,11 @@ public static final class CommandResult implements ResultedEvent.Result {
     private static final CommandResult DENIED = new CommandResult(false, false, null);
     private static final CommandResult FORWARD_TO_SERVER = new CommandResult(false, true, null);
 
-    private @Nullable String command;
+    private final @Nullable String command;
     private final boolean status;
     private final boolean forward;
 
-    private CommandResult(boolean status, boolean forward, @Nullable String command) {
+    private CommandResult(final boolean status, final boolean forward, final @Nullable String command) {
       this.status = status;
       this.forward = forward;
       this.command = command;
@@ -142,7 +151,7 @@ public static CommandResult forwardToServer() {
      * @param newCommand the command without first slash to use instead
      * @return a result with a new command being forwarded to server
      */
-    public static CommandResult forwardToServer(@NonNull String newCommand) {
+    public static CommandResult forwardToServer(final @NonNull String newCommand) {
       Preconditions.checkNotNull(newCommand, "newCommand");
       return new CommandResult(false, true, newCommand);
     }
@@ -154,7 +163,7 @@ public static CommandResult forwardToServer(@NonNull String newCommand) {
      * @param newCommand the command to use instead without first slash
      * @return a result with a new command
      */
-    public static CommandResult command(@NonNull String newCommand) {
+    public static CommandResult command(final @NonNull String newCommand) {
       Preconditions.checkNotNull(newCommand, "newCommand");
       return new CommandResult(true, false, newCommand);
     }

api/src/main/java/com/velocitypowered/api/event/player/KickedFromServerEvent.java

@@ -13,6 +13,7 @@
 import com.velocitypowered.api.proxy.Player;
 import com.velocitypowered.api.proxy.server.RegisteredServer;
 import java.util.Optional;
+import net.kyori.adventure.text.Component;
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
 
@@ -29,7 +30,7 @@ public final class KickedFromServerEvent implements
 
   private final Player player;
   private final RegisteredServer server;
-  private final net.kyori.adventure.text.@Nullable Component originalReason;
+  private final @Nullable Component originalReason;
   private final boolean duringServerConnect;
   private ServerKickResult result;
 
@@ -43,7 +44,7 @@ public final class KickedFromServerEvent implements
    * @param result the initial result
    */
   public KickedFromServerEvent(Player player, RegisteredServer server,
-      net.kyori.adventure.text.@Nullable Component originalReason,
+      @Nullable Component originalReason,
       boolean duringServerConnect, ServerKickResult result) {
     this.player = Preconditions.checkNotNull(player, "player");
     this.server = Preconditions.checkNotNull(server, "server");
@@ -53,24 +54,39 @@ public KickedFromServerEvent(Player player, RegisteredServer server,
   }
 
   @Override
-  public ServerKickResult getResult() {
+  public @NonNull ServerKickResult getResult() {
     return result;
   }
 
   @Override
-  public void setResult(@NonNull ServerKickResult result) {
+  public void setResult(final @NonNull ServerKickResult result) {
     this.result = Preconditions.checkNotNull(result, "result");
   }
 
-  public Player getPlayer() {
+  /**
+   * The player who has been kicked out.
+   *
+   * @return the player affected
+   */
+  public @NonNull Player getPlayer() {
     return player;
   }
 
-  public RegisteredServer getServer() {
+  /**
+   * The server from which the player has been kicked.
+   *
+   * @return the server the player disconnected from
+   */
+  public @NonNull RegisteredServer getServer() {
     return server;
   }
 
-  public Optional<net.kyori.adventure.text.Component> getServerKickReason() {
+  /**
+   * The reason why the player was kicked, the server may or may not provide this reason.
+   *
+   * @return the reason for being kicked, optional
+   */
+  public Optional<Component> getServerKickReason() {
     return Optional.ofNullable(originalReason);
   }
 
@@ -98,7 +114,7 @@ public boolean kickedDuringLogin() {
   /**
    * Represents the base interface for {@link KickedFromServerEvent} results.
    */
-  public interface ServerKickResult extends ResultedEvent.Result {
+  public sealed interface ServerKickResult extends ResultedEvent.Result {
 
   }
 
@@ -107,9 +123,9 @@ public interface ServerKickResult extends ResultedEvent.Result {
    */
   public static final class DisconnectPlayer implements ServerKickResult {
 
-    private final net.kyori.adventure.text.Component component;
+    private final Component component;
 
-    private DisconnectPlayer(net.kyori.adventure.text.Component component) {
+    private DisconnectPlayer(final Component component) {
       this.component = Preconditions.checkNotNull(component, "component");
     }
 
@@ -118,7 +134,7 @@ public boolean isAllowed() {
       return true;
     }
 
-    public net.kyori.adventure.text.Component getReasonComponent() {
+    public Component getReasonComponent() {
       return component;
     }
 
@@ -128,21 +144,26 @@ public net.kyori.adventure.text.Component getReasonComponent() {
      * @param reason the reason to use when disconnecting the player
      * @return the disconnect result
      */
-    public static DisconnectPlayer create(net.kyori.adventure.text.Component reason) {
+    public static DisconnectPlayer create(Component reason) {
       return new DisconnectPlayer(reason);
     }
+
+    @Override
+    public String toString() {
+      return "KickedFromServerEvent#DisconnectPlater{isAllowed=%s,component=%s}"
+              .formatted(isAllowed(), component);
+    }
   }
 
   /**
    * Tells the proxy to redirect the player to another server.
    */
   public static final class RedirectPlayer implements ServerKickResult {
 
-    private final net.kyori.adventure.text.Component message;
+    private final Component message;
     private final RegisteredServer server;
 
-    private RedirectPlayer(RegisteredServer server,
-        net.kyori.adventure.text.@Nullable Component message) {
+    private RedirectPlayer(final RegisteredServer server, final @Nullable Component message) {
       this.server = Preconditions.checkNotNull(server, "server");
       this.message = message;
     }
@@ -152,11 +173,11 @@ public boolean isAllowed() {
       return false;
     }
 
-    public RegisteredServer getServer() {
+    public @NonNull RegisteredServer getServer() {
       return server;
     }
 
-    public net.kyori.adventure.text.@Nullable Component getMessageComponent() {
+    public @Nullable Component getMessageComponent() {
       return message;
     }
 
@@ -169,8 +190,7 @@ public RegisteredServer getServer() {
      * @param message the message will be sent to the player after redirecting
      * @return the redirect result
      */
-    public static RedirectPlayer create(RegisteredServer server,
-        net.kyori.adventure.text.Component message) {
+    public static RedirectPlayer create(final @NonNull RegisteredServer server, final Component message) {
       return new RedirectPlayer(server, message);
     }
 
@@ -181,9 +201,15 @@ public static RedirectPlayer create(RegisteredServer server,
      * @param server the server to send the player to
      * @return the redirect result
      */
-    public static ServerKickResult create(RegisteredServer server) {
+    public static ServerKickResult create(final RegisteredServer server) {
       return new RedirectPlayer(server, null);
     }
+
+    @Override
+    public String toString() {
+      return "KickedFromServerEvent#RedirectPlayer{isAllowed=%s,message=%s,server=%s}"
+              .formatted(isAllowed(), this.message, this.server);
+    }
   }
 
   /**
@@ -193,9 +219,9 @@ public static ServerKickResult create(RegisteredServer server) {
    */
   public static final class Notify implements ServerKickResult {
 
-    private final net.kyori.adventure.text.Component message;
+    private final Component message;
 
-    private Notify(net.kyori.adventure.text.Component message) {
+    private Notify(Component message) {
       this.message = Preconditions.checkNotNull(message, "message");
     }
 
@@ -204,7 +230,7 @@ public boolean isAllowed() {
       return false;
     }
 
-    public net.kyori.adventure.text.Component getMessageComponent() {
+    public Component getMessageComponent() {
       return message;
     }
 
@@ -214,8 +240,14 @@ public net.kyori.adventure.text.Component getMessageComponent() {
      * @param message the server to send the player to
      * @return the redirect result
      */
-    public static Notify create(net.kyori.adventure.text.Component message) {
+    public static Notify create(final @NonNull Component message) {
       return new Notify(message);
     }
+
+    @Override
+    public String toString() {
+      return "KickedFromServerEvent#Notify{isAllowed=%s,message=%s}"
+              .formatted(isAllowed(), message);
+    }
   }
 }