Add PlayerConfigurationEvent and PlayerEnteredConfigurationEvent (#1371)

* Configuring the player (i.e. sending resource packs) should now be done in the new PlayerConfigurationEvent.

* The new PlayerEnteredConfigurationEvent is called when a player acknowledged the switch to configuration state.

* The PlayerEnterConfigurationEvent is no longer called twice. It is now called when the backed wants to reconfigure the player.

* The PlayerFinishConfigurationEvent should no longer be used to configure the player (i.e. sending resource packs). This is because since 1.20.5 the backend server can't send keep alive packets between switching state anymore and the connection will thus time out.

api/src/main/java/com/velocitypowered/api/event/player/configuration/PlayerConfigurationEvent.java

@@ -0,0 +1,26 @@
+/*
+ * 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.player.configuration;
+
+import com.velocitypowered.api.event.annotation.AwaitingEvent;
+import com.velocitypowered.api.proxy.Player;
+import com.velocitypowered.api.proxy.ServerConnection;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * This event is executed when a player entered the configuration state and can be configured by Velocity.
+ * <p>Velocity will wait for this event before continuing/ending the configuration state.</p>
+ *
+ * @param player The player who can be configured.
+ * @param server The server that is currently configuring the player.
+ * @since 3.3.0
+ * @sinceMinecraft 1.20.2
+ */
+@AwaitingEvent
+public record PlayerConfigurationEvent(@NotNull Player player, ServerConnection server) {
+}

api/src/main/java/com/velocitypowered/api/event/player/configuration/PlayerEnterConfigurationEvent.java

@@ -7,21 +7,23 @@
 
 package com.velocitypowered.api.event.player.configuration;
 
-import com.velocitypowered.api.network.ProtocolState;
+import com.velocitypowered.api.event.annotation.AwaitingEvent;
 import com.velocitypowered.api.proxy.Player;
 import com.velocitypowered.api.proxy.ServerConnection;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * This event is executed when a player with version 1.20.2 or higher enters the configuration phase.
- * <p>From this moment on, until the {@link PlayerFinishedConfigurationEvent} is executed,
- * the {@linkplain Player#getProtocolState()} method is guaranteed
- * to return {@link ProtocolState#CONFIGURATION}.</p>
+ * This event is executed when a player is about to enter the configuration state.
+ * It is <b>not</b> called for the initial configuration of a player after login.
+ * <p>Velocity will wait for this event before asking the client to enter configuration state.
+ * However due to backend server being unable to keep the connection alive during state changes,
+ * Velocity will only wait for a maximum of 5 seconds.</p>
  *
- * @param player The player that has entered the configuration phase.
- * @param server The server that will now (re-)configure the player.
+ * @param player The player who is about to enter configuration state.
+ * @param server The server that wants to reconfigure the player.
  * @since 3.3.0
  * @sinceMinecraft 1.20.2
  */
+@AwaitingEvent
 public record PlayerEnterConfigurationEvent(@NotNull Player player, ServerConnection server) {
 }

api/src/main/java/com/velocitypowered/api/event/player/configuration/PlayerEnteredConfigurationEvent.java

@@ -0,0 +1,27 @@
+/*
+ * 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.player.configuration;
+
+import com.velocitypowered.api.network.ProtocolState;
+import com.velocitypowered.api.proxy.Player;
+import com.velocitypowered.api.proxy.ServerConnection;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * This event is executed when a player has entered the configuration state.
+ * <p>From this moment on, until the {@link PlayerFinishedConfigurationEvent} is executed,
+ * the {@linkplain Player#getProtocolState()} method is guaranteed
+ * to return {@link ProtocolState#CONFIGURATION}.</p>
+ *
+ * @param player The player who has entered the configuration state.
+ * @param server The server that will now (re-)configure the player.
+ * @since 3.3.0
+ * @sinceMinecraft 1.20.2
+ */
+public record PlayerEnteredConfigurationEvent(@NotNull Player player, ServerConnection server) {
+}

api/src/main/java/com/velocitypowered/api/event/player/configuration/PlayerFinishConfigurationEvent.java

@@ -13,11 +13,14 @@ import com.velocitypowered.api.proxy.ServerConnection;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * This event is executed when the player is about to finish the Configuration state.
- * <p>Velocity will wait for this event to finish the configuration phase on the client.</p>
+ * This event is executed when a player is about to finish the configuration state.
+ * <p>Velocity will wait for this event before asking the client to finish the configuration state.
+ * However due to backend server being unable to keep the connection alive during state changes,
+ * Velocity will only wait for a maximum of 5 seconds. If you need to hold a player in configuration
+ * state, use the {@link PlayerConfigurationEvent}.</p>
  *
- * @param player The player who is about to complete the configuration phase.
- * @param server The server that is currently (re-)configuring the player.
+ * @param player The player who is about to finish the configuration phase.
+ * @param server The server that has (re-)configured the player.
  * @since 3.3.0
  * @sinceMinecraft 1.20.2
  */

api/src/main/java/com/velocitypowered/api/event/player/configuration/PlayerFinishedConfigurationEvent.java

@@ -13,11 +13,11 @@ import com.velocitypowered.api.proxy.ServerConnection;
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Event executed when a player of version 1.20.2 or higher finishes the Configuration state.
+ * This event is executed when a player has finished the configuration state.
  * <p>From this moment on, the {@link Player#getProtocolState()} method
  * will return {@link ProtocolState#PLAY}.</p>
  *
- * @param player The player who has completed the Configuration state
+ * @param player The player who has finished the configuration state.
  * @param server The server that has (re-)configured the player.
  * @since 3.3.0
  * @sinceMinecraft 1.20.2