Implement ProtocolState API (#1224)

* Implement ProtocolState API

* Renamed method to #getProtocolState

* Added sinceMinecraft javadoc tag

* Fixed PreLoginEvent#getUniqueId documentation

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

@@ -72,9 +72,12 @@ public final class PreLoginEvent implements ResultedEvent<PreLoginEvent.PreLogin
   }
 
   /**
-   * 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/network/ProtocolState.java

@@ -0,0 +1,52 @@
+/*
+ * 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;
+
+/**
+ * Representation of the state of the protocol
+ * in which a connection can be present.
+ *
+ * @since 3.3.0
+ */
+public enum ProtocolState {
+  /**
+   * Initial connection State.
+   * <p>This status can be caused by a STATUS, LOGIN or TRANSFER intent.</p>
+   * If the intent is LOGIN or TRANSFER, the next state will be {@link #LOGIN},
+   * otherwise, it will go to the {@link #STATUS} state.
+   */
+  HANDSHAKE,
+  /**
+   * Ping State of a connection.
+   * <p>Connections with the STATUS HandshakeIntent will pass through this state
+   * and be disconnected after it requests the ping from the server
+   * and the server responds with the respective ping.</p>
+   */
+  STATUS,
+  /**
+   * Authentication State of a connection.
+   * <p>At this moment the player is authenticating with the authentication servers.</p>
+   */
+  LOGIN,
+  /**
+   * Configuration State of a connection.
+   * <p>At this point the player allows the server to send information
+   * such as resource packs and plugin messages, at the same time the player
+   * will send his client brand and the respective plugin messages
+   * if it is a modded client.</p>
+   *
+   * @sinceMinecraft 1.20.2
+   */
+  CONFIGURATION,
+  /**
+   * Game State of a connection.
+   * <p>In this state is where the whole game runs, the server is able to change
+   * the player's state to {@link #CONFIGURATION} as needed in versions 1.20.2 and higher.</p>
+   */
+  PLAY
+}

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

@@ -7,6 +7,7 @@
 
 package com.velocitypowered.api.proxy;
 
+import com.velocitypowered.api.network.ProtocolState;
 import com.velocitypowered.api.network.ProtocolVersion;
 import java.net.InetSocketAddress;
 import java.util.Optional;
@@ -43,4 +44,11 @@ public interface InboundConnection {
    * @return the protocol version the connection uses
    */
   ProtocolVersion getProtocolVersion();
+
+  /**
+   * Returns the current protocol state of this connection.
+   *
+   * @return the protocol state of the connection
+   */
+  ProtocolState getProtocolState();
 }

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

@@ -190,7 +190,7 @@ public interface Player extends
    *
    * @param reason component with the reason
    */
-  void disconnect(net.kyori.adventure.text.Component reason);
+  void disconnect(Component reason);
 
   /**
    * Sends chat input onto the players current server as if they typed it into the client chat box.

api/src/main/java/com/velocitypowered/api/proxy/player/PlayerSettings.java

@@ -64,6 +64,7 @@ public interface PlayerSettings {
    * This feature was introduced in 1.18.
    *
    * @return whether or not the client explicitly allows listing. Always false on older clients.
+   * @sinceMinecraft 1.18
    */
   boolean isClientListingAllowed();