Merge remote-tracking branch 'refs/remotes/upstream/dev/3.0.0' into d…

…ev/3.0.0

# Conflicts:
#	.github/workflows/gradle.yml
#	proxy/src/main/java/com/velocitypowered/proxy/config/VelocityConfiguration.java
#	proxy/src/main/resources/default-velocity.toml

.github/workflows/gradle.yml

@@ -2,23 +2,22 @@
 # For more information see: https://docs.github.com/actions/language-and-framework-guides/building-and-testing-java-with-gradle
 
 name: Java CI with Gradle
-
 on: [push, pull_request]
 
 jobs:
-  build-17:
-    runs-on: ubuntu-latest
+  build:
+    runs-on: ubuntu-22.04
     steps:
-    - uses: actions/checkout@v3
-    - uses: gradle/wrapper-validation-action@v1
+    - name: Checkout Repository
+      uses: actions/checkout@v4
+    - name: Validate Gradle Wrapper
+      uses: gradle/actions/wrapper-validation@v3
     - name: Set up JDK 17
-      uses: actions/setup-java@v3
+      uses: actions/setup-java@v4
       with:
         java-version: 17
         distribution: 'temurin'
         cache: 'gradle'
-    - name: Grant execute permission for gradlew
-      run: chmod +x gradlew
     - name: Build with Gradle
       run: ./gradlew build
 

api/build.gradle.kts

@@ -73,7 +73,8 @@ tasks {
         o.tags(
             "apiNote:a:API Note:",
             "implSpec:a:Implementation Requirements:",
-            "implNote:a:Implementation Note:"
+            "implNote:a:Implementation Note:",
+            "sinceMinecraft:a:Since Minecraft:"
         )
 
         // Disable the crazy super-strict doclint tool in Java 8

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

@@ -0,0 +1,31 @@
+/*
+ * Copyright (C) 2020-2021 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.command;
+
+/**
+ * The result of a command invocation attempt.
+ */
+public enum CommandResult {
+  /**
+   * The command was successfully executed by the proxy.
+   */
+  EXECUTED,
+  /**
+   * The command was forwarded to the backend server.
+   * The command may be successfully executed or not
+   */
+  FORWARDED,
+  /**
+   * The provided command input contained syntax errors.
+   */
+  SYNTAX_ERROR,
+  /**
+   * An unexpected exception occurred while executing the command in the proxy.
+   */
+  EXCEPTION
+}

api/src/main/java/com/velocitypowered/api/event/command/PostCommandInvocationEvent.java

@@ -0,0 +1,82 @@
+/*
+ * Copyright (C) 2020-2023 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.command;
+
+import com.google.common.base.Preconditions;
+import com.velocitypowered.api.command.CommandResult;
+import com.velocitypowered.api.command.CommandSource;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * This event is fired when velocity executed a command. This event is called after the event
+ * is handled.
+ *
+ * <p>Commands can be cancelled or forwarded to backend servers in {@link CommandExecuteEvent}.
+ * This will prevent firing this event.</p>
+ *
+ * @since 3.3.0
+ */
+public final class PostCommandInvocationEvent {
+
+  private final CommandSource commandSource;
+  private final String command;
+  private final CommandResult result;
+
+  /**
+   * Constructs a PostCommandInvocationEvent.
+   *
+   * @param commandSource the source executing the command
+   * @param command the command being executed without first slash
+   * @param result the result of this command
+   */
+  public PostCommandInvocationEvent(
+          final @NotNull CommandSource commandSource,
+          final @NotNull String command,
+          final @NotNull CommandResult result
+  ) {
+    this.commandSource = Preconditions.checkNotNull(commandSource, "commandSource");
+    this.command = Preconditions.checkNotNull(command, "command");
+    this.result = Preconditions.checkNotNull(result, "result");
+  }
+
+  /**
+   * Get the source of this executed command.
+   *
+   * @return the source
+   */
+  public @NotNull CommandSource getCommandSource() {
+    return commandSource;
+  }
+
+  /**
+   * Gets the original command line executed without the first slash.
+   *
+   * @return the original command
+   * @see CommandExecuteEvent#getCommand()
+   */
+  public @NotNull String getCommand() {
+    return command;
+  }
+
+  /**
+   * Returns the result of the command execution.
+   *
+   * @return the execution result
+   */
+  public @NotNull CommandResult getResult() {
+    return result;
+  }
+
+  @Override
+  public String toString() {
+    return "PostCommandInvocationEvent{"
+            + "commandSource=" + commandSource
+            + ", command=" + command
+            + '}';
+  }
+}

api/src/main/java/com/velocitypowered/api/event/connection/ConnectionHandshakeEvent.java

@@ -8,6 +8,7 @@
 package com.velocitypowered.api.event.connection;
 
 import com.google.common.base.Preconditions;
+import com.velocitypowered.api.network.HandshakeIntent;
 import com.velocitypowered.api.proxy.InboundConnection;
 
 /**
@@ -18,19 +19,39 @@
 public final class ConnectionHandshakeEvent {
 
   private final InboundConnection connection;
+  private final HandshakeIntent intent;
 
+  public ConnectionHandshakeEvent(InboundConnection connection, HandshakeIntent intent) {
+    this.connection = Preconditions.checkNotNull(connection, "connection");
+    this.intent = Preconditions.checkNotNull(intent, "intent");
+  }
+
+  /**
+   * This method is only retained to avoid breaking plugins
+   * that have not yet updated their integration tests.
+   *
+   * @param connection the inbound connection
+   * @deprecated use {@link #ConnectionHandshakeEvent(InboundConnection, HandshakeIntent)}
+   */
+  @Deprecated(forRemoval = true)
   public ConnectionHandshakeEvent(InboundConnection connection) {
     this.connection = Preconditions.checkNotNull(connection, "connection");
+    this.intent = HandshakeIntent.LOGIN;
   }
 
   public InboundConnection getConnection() {
     return connection;
   }
 
+  public HandshakeIntent getIntent() {
+    return this.intent;
+  }
+
   @Override
   public String toString() {
     return "ConnectionHandshakeEvent{"
         + "connection=" + connection
+        + ", intent=" + intent
         + '}';
   }
 }

api/src/main/java/com/velocitypowered/api/event/connection/PreLoginEvent.java

@@ -72,9 +72,12 @@ public String getUsername() {
   }
 
   /**
-   * Returns the UUID of the connecting player. This value is {@code null} on 1.19.1 and lower.
+   * Returns the UUID of the connecting player.
+   * <p>This value is {@code null} on 1.19.2 and lower,
+   * up to 1.20.1 it is optional and from 1.20.2 it will always be available.</p>
    *
    * @return the uuid
+   * @sinceMinecraft 1.19.3
    */
   public @Nullable UUID getUniqueId() {
     return uuid;

api/src/main/java/com/velocitypowered/api/event/connection/PreTransferEvent.java

@@ -0,0 +1,100 @@
+/*
+ * Copyright (C) 2024 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.connection;
+
+import static java.util.Objects.requireNonNull;
+
+import com.velocitypowered.api.event.ResultedEvent;
+import com.velocitypowered.api.event.annotation.AwaitingEvent;
+import com.velocitypowered.api.proxy.Player;
+import java.net.InetSocketAddress;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * This event is executed before sending a player to another host,
+ * either by the backend server or by a plugin using
+ * the {@link Player#transferToHost(InetSocketAddress)} method.
+ */
+@AwaitingEvent
+@ApiStatus.Experimental
+public final class PreTransferEvent implements ResultedEvent<PreTransferEvent.TransferResult> {
+  private final InetSocketAddress originalAddress;
+  private final Player player;
+  private TransferResult result = TransferResult.ALLOWED;
+
+  public PreTransferEvent(final Player player, final InetSocketAddress address) {
+    this.player = requireNonNull(player);
+    this.originalAddress = requireNonNull(address);
+  }
+
+  public Player player() {
+    return this.player;
+  }
+
+  public InetSocketAddress originalAddress() {
+    return this.originalAddress;
+  }
+
+  @Override
+  public TransferResult getResult() {
+    return this.result;
+  }
+
+  @Override
+  public void setResult(final TransferResult result) {
+    requireNonNull(result);
+    this.result = result;
+  }
+
+  /**
+   * Transfer Result of a player to another host.
+   */
+  public static class TransferResult implements ResultedEvent.Result {
+    private static final TransferResult ALLOWED = new TransferResult(true, null);
+    private static final TransferResult DENIED = new TransferResult(false, null);
+
+    private final InetSocketAddress address;
+    private final boolean allowed;
+
+    private TransferResult(final boolean allowed, final InetSocketAddress address) {
+      this.address = address;
+      this.allowed = allowed;
+    }
+
+    public static TransferResult allowed() {
+      return ALLOWED;
+    }
+
+    public static TransferResult denied() {
+      return DENIED;
+    }
+
+    /**
+     * Sets the result of transfer to a specific host.
+     *
+     * @param address the address specified
+     * @return a new TransferResult
+     */
+    public static TransferResult transferTo(final InetSocketAddress address) {
+      requireNonNull(address);
+
+      return new TransferResult(true, address);
+    }
+
+    @Override
+    public boolean isAllowed() {
+      return this.allowed;
+    }
+
+    @Nullable
+    public InetSocketAddress address() {
+      return this.address;
+    }
+  }
+}

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

@@ -150,7 +150,7 @@ public static DisconnectPlayer create(Component reason) {
 
     @Override
     public String toString() {
-      return "KickedFromServerEvent#DisconnectPlater{isAllowed=%s,component=%s}"
+      return "KickedFromServerEvent#DisconnectPlayer{isAllowed=%s,component=%s}"
               .formatted(isAllowed(), component);
     }
   }

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

@@ -0,0 +1,42 @@
+/*
+ * Copyright (C) 2024 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.network;
+
+/**
+ * Represents the ClientIntent of a client in the Handshake state.
+ */
+public enum HandshakeIntent {
+  STATUS(1),
+  LOGIN(2),
+  TRANSFER(3);
+
+  private final int id;
+
+  HandshakeIntent(int id) {
+    this.id = id;
+  }
+
+  public int id() {
+    return this.id;
+  }
+
+  /**
+   * Obtain the HandshakeIntent by ID.
+   *
+   * @param id the intent id
+   * @return the HandshakeIntent desired
+   */
+  public static HandshakeIntent getById(int id) {
+    return switch (id) {
+      case 1 -> STATUS;
+      case 2 -> LOGIN;
+      case 3 -> TRANSFER;
+      default -> null;
+    };
+  }
+}