From 8c39d9a1e44f5ae6be29d50cc826b9971bc60c8e Mon Sep 17 00:00:00 2001 From: Andrew Steinborn Date: Thu, 23 Dec 2021 02:52:56 -0500 Subject: [PATCH] Document every event Velocity will await on. --- .../api/event/annotation/AwaitingEvent.java | 22 +++++++++++++++++++ .../event/command/CommandExecuteEvent.java | 5 ++++- .../command/PlayerAvailableCommandsEvent.java | 6 ++++- .../connection/ConnectionHandshakeEvent.java | 2 ++ .../api/event/connection/DisconnectEvent.java | 15 +++++++++++-- .../api/event/connection/LoginEvent.java | 8 +++++-- .../event/connection/PluginMessageEvent.java | 5 ++++- .../api/event/connection/PostLoginEvent.java | 7 +++++- .../api/event/connection/PreLoginEvent.java | 6 ++++- .../permission/PermissionsSetupEvent.java | 12 +++++++++- .../event/player/GameProfileRequestEvent.java | 8 +++++++ .../event/player/KickedFromServerEvent.java | 5 ++++- .../player/PlayerChannelRegisterEvent.java | 2 +- .../api/event/player/PlayerChatEvent.java | 5 ++++- .../PlayerChooseInitialServerEvent.java | 8 +++++-- .../event/player/PlayerClientBrandEvent.java | 3 ++- .../api/event/player/PlayerModInfoEvent.java | 1 + .../player/PlayerResourcePackStatusEvent.java | 6 +++-- .../player/PlayerSettingsChangedEvent.java | 5 +++++ .../event/player/ServerConnectedEvent.java | 8 +++++++ .../player/ServerLoginPluginMessageEvent.java | 6 ++++- .../event/player/ServerPostConnectEvent.java | 3 ++- .../event/player/ServerPreConnectEvent.java | 5 ++++- .../api/event/player/TabCompleteEvent.java | 5 +++++ .../api/event/proxy/ProxyInitializeEvent.java | 6 ++++- .../api/event/proxy/ProxyPingEvent.java | 7 +++++- .../api/event/proxy/ProxyShutdownEvent.java | 5 ++++- .../api/event/query/ProxyQueryEvent.java | 5 ++++- 28 files changed, 156 insertions(+), 25 deletions(-) create mode 100644 api/src/main/java/com/velocitypowered/api/event/annotation/AwaitingEvent.java diff --git a/api/src/main/java/com/velocitypowered/api/event/annotation/AwaitingEvent.java b/api/src/main/java/com/velocitypowered/api/event/annotation/AwaitingEvent.java new file mode 100644 index 000000000..35e678e28 --- /dev/null +++ b/api/src/main/java/com/velocitypowered/api/event/annotation/AwaitingEvent.java @@ -0,0 +1,22 @@ +/* + * Copyright (C) 2018 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.annotation; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Target; + +/** + * Marks an event as an event the proxy will wait on to completely fire (including any + * {@link com.velocitypowered.api.event.EventTask}s) before continuing handling it. Annotated + * classes are suitable candidates for using EventTasks for handling complex asynchronous + * operations in a non-blocking matter. + */ +@Target(ElementType.TYPE) +public @interface AwaitingEvent { + +} diff --git a/api/src/main/java/com/velocitypowered/api/event/command/CommandExecuteEvent.java b/api/src/main/java/com/velocitypowered/api/event/command/CommandExecuteEvent.java index 72ee2f8cd..df807f5de 100644 --- a/api/src/main/java/com/velocitypowered/api/event/command/CommandExecuteEvent.java +++ b/api/src/main/java/com/velocitypowered/api/event/command/CommandExecuteEvent.java @@ -10,14 +10,17 @@ package com.velocitypowered.api.event.command; import com.google.common.base.Preconditions; import com.velocitypowered.api.command.CommandSource; import com.velocitypowered.api.event.ResultedEvent; +import com.velocitypowered.api.event.annotation.AwaitingEvent; import com.velocitypowered.api.event.command.CommandExecuteEvent.CommandResult; import java.util.Optional; import org.checkerframework.checker.nullness.qual.NonNull; import org.checkerframework.checker.nullness.qual.Nullable; /** - * This event is fired when someone executing command. + * This event is fired when someone executes a command. Velocity will wait for this event to finish + * firing before trying to handle the command and/or forwarding it to the server. */ +@AwaitingEvent public final class CommandExecuteEvent implements ResultedEvent { private final CommandSource commandSource; diff --git a/api/src/main/java/com/velocitypowered/api/event/command/PlayerAvailableCommandsEvent.java b/api/src/main/java/com/velocitypowered/api/event/command/PlayerAvailableCommandsEvent.java index ed006537e..64440f1ee 100644 --- a/api/src/main/java/com/velocitypowered/api/event/command/PlayerAvailableCommandsEvent.java +++ b/api/src/main/java/com/velocitypowered/api/event/command/PlayerAvailableCommandsEvent.java @@ -11,12 +11,16 @@ import static com.google.common.base.Preconditions.checkNotNull; import com.google.common.annotations.Beta; import com.mojang.brigadier.tree.RootCommandNode; +import com.velocitypowered.api.event.annotation.AwaitingEvent; import com.velocitypowered.api.proxy.Player; /** * Allows plugins to modify the packet indicating commands available on the server to a - * Minecraft 1.13+ client. + * Minecraft 1.13+ client. The given {@link RootCommandNode} is mutable. Velocity will wait + * for this event to finish firing before sending the list of available commands to the + * client. */ +@AwaitingEvent @Beta public class PlayerAvailableCommandsEvent { diff --git a/api/src/main/java/com/velocitypowered/api/event/connection/ConnectionHandshakeEvent.java b/api/src/main/java/com/velocitypowered/api/event/connection/ConnectionHandshakeEvent.java index 64ba04b00..a9e594cec 100644 --- a/api/src/main/java/com/velocitypowered/api/event/connection/ConnectionHandshakeEvent.java +++ b/api/src/main/java/com/velocitypowered/api/event/connection/ConnectionHandshakeEvent.java @@ -12,6 +12,8 @@ import com.velocitypowered.api.proxy.InboundConnection; /** * This event is fired when a handshake is established between a client and the proxy. + * Velocity will fire this event asynchronously and will not wait for it to complete before + * handling the connection. */ public final class ConnectionHandshakeEvent { diff --git a/api/src/main/java/com/velocitypowered/api/event/connection/DisconnectEvent.java b/api/src/main/java/com/velocitypowered/api/event/connection/DisconnectEvent.java index c4c2d6fdd..cb89984a2 100644 --- a/api/src/main/java/com/velocitypowered/api/event/connection/DisconnectEvent.java +++ b/api/src/main/java/com/velocitypowered/api/event/connection/DisconnectEvent.java @@ -8,12 +8,23 @@ package com.velocitypowered.api.event.connection; import com.google.common.base.Preconditions; +import com.velocitypowered.api.event.annotation.AwaitingEvent; import com.velocitypowered.api.proxy.Player; /** - * This event is fired when a player disconnects from the proxy. Operations on the provided player, - * aside from basic data retrieval operations, may behave in undefined ways. + * This event is fired when a player disconnects from the proxy. This operation can take place + * when the player disconnects due to normal network activity or when the proxy shuts down. + * Operations on the provided player, aside from basic data retrieval operations, may behave in + * undefined ways. + * + *

+ * Velocity typically fires this event asynchronously and does not wait for a response. However, + * it will wait for all {@link DisconnectEvent}s for every player on the proxy to fire + * successfully before the proxy shuts down. This event is the sole exception to the + * {@link AwaitingEvent} contract. + *

*/ +@AwaitingEvent public final class DisconnectEvent { private final Player player; diff --git a/api/src/main/java/com/velocitypowered/api/event/connection/LoginEvent.java b/api/src/main/java/com/velocitypowered/api/event/connection/LoginEvent.java index e48e92b08..4bd116034 100644 --- a/api/src/main/java/com/velocitypowered/api/event/connection/LoginEvent.java +++ b/api/src/main/java/com/velocitypowered/api/event/connection/LoginEvent.java @@ -9,12 +9,16 @@ package com.velocitypowered.api.event.connection; import com.google.common.base.Preconditions; import com.velocitypowered.api.event.ResultedEvent; +import com.velocitypowered.api.event.annotation.AwaitingEvent; import com.velocitypowered.api.proxy.Player; /** - * This event is fired once the player has been authenticated but before they connect to a server on - * the proxy. + * This event is fired once the player has been authenticated, but before they connect to a server. + * Velocity will wait for this event to finish firing before proceeding with the rest of the login + * process, but you should try to limit the work done in any event that fires during the login + * process. */ +@AwaitingEvent public final class LoginEvent implements ResultedEvent { private final Player player; diff --git a/api/src/main/java/com/velocitypowered/api/event/connection/PluginMessageEvent.java b/api/src/main/java/com/velocitypowered/api/event/connection/PluginMessageEvent.java index 917c70973..27fff9ac7 100644 --- a/api/src/main/java/com/velocitypowered/api/event/connection/PluginMessageEvent.java +++ b/api/src/main/java/com/velocitypowered/api/event/connection/PluginMessageEvent.java @@ -11,6 +11,7 @@ import com.google.common.base.Preconditions; import com.google.common.io.ByteArrayDataInput; import com.google.common.io.ByteStreams; import com.velocitypowered.api.event.ResultedEvent; +import com.velocitypowered.api.event.annotation.AwaitingEvent; import com.velocitypowered.api.proxy.Player; import com.velocitypowered.api.proxy.ServerConnection; import com.velocitypowered.api.proxy.messages.ChannelIdentifier; @@ -21,8 +22,10 @@ import java.util.Arrays; /** * This event is fired when a plugin message is sent to the proxy, either from a client ({@link - * Player}) or a server ({@link ServerConnection}). + * Player}) or a server ({@link ServerConnection}). Velocity will wait on this event to finish + * firing before discarding the sent plugin message (if handled) or forwarding it to the server. */ +@AwaitingEvent public final class PluginMessageEvent implements ResultedEvent { private final ChannelMessageSource source; diff --git a/api/src/main/java/com/velocitypowered/api/event/connection/PostLoginEvent.java b/api/src/main/java/com/velocitypowered/api/event/connection/PostLoginEvent.java index e6a7e37de..f5ac9d77d 100644 --- a/api/src/main/java/com/velocitypowered/api/event/connection/PostLoginEvent.java +++ b/api/src/main/java/com/velocitypowered/api/event/connection/PostLoginEvent.java @@ -8,12 +8,17 @@ package com.velocitypowered.api.event.connection; import com.google.common.base.Preconditions; +import com.velocitypowered.api.event.annotation.AwaitingEvent; import com.velocitypowered.api.proxy.Player; /** * This event is fired once the player has been fully initialized and is about to connect to their - * first server. + * first server. Velocity will wait for this event to finish firing before it fires + * {@link com.velocitypowered.api.event.player.PlayerChooseInitialServerEvent} with any default + * servers specified in the configuration, but you should try to limit the work done in any event + * that fires during the login process. */ +@AwaitingEvent public final class PostLoginEvent { private final Player player; diff --git a/api/src/main/java/com/velocitypowered/api/event/connection/PreLoginEvent.java b/api/src/main/java/com/velocitypowered/api/event/connection/PreLoginEvent.java index 47817f487..222b6790c 100644 --- a/api/src/main/java/com/velocitypowered/api/event/connection/PreLoginEvent.java +++ b/api/src/main/java/com/velocitypowered/api/event/connection/PreLoginEvent.java @@ -9,6 +9,7 @@ package com.velocitypowered.api.event.connection; import com.google.common.base.Preconditions; import com.velocitypowered.api.event.ResultedEvent; +import com.velocitypowered.api.event.annotation.AwaitingEvent; import com.velocitypowered.api.proxy.InboundConnection; import java.util.Optional; import org.checkerframework.checker.nullness.qual.NonNull; @@ -17,8 +18,11 @@ import org.checkerframework.checker.nullness.qual.Nullable; /** * This event is fired when a player has initiated a connection with the proxy but before the proxy * authenticates the player with Mojang or before the player's proxy connection is fully established - * (for offline mode). + * (for offline mode). Velocity will wait for this event to finish firing before proceeding further + * with the login process, but you should try to limit the work done in any event that fires during + * the login process. */ +@AwaitingEvent public final class PreLoginEvent implements ResultedEvent { private final InboundConnection connection; diff --git a/api/src/main/java/com/velocitypowered/api/event/permission/PermissionsSetupEvent.java b/api/src/main/java/com/velocitypowered/api/event/permission/PermissionsSetupEvent.java index 99ba8c841..b314326f2 100644 --- a/api/src/main/java/com/velocitypowered/api/event/permission/PermissionsSetupEvent.java +++ b/api/src/main/java/com/velocitypowered/api/event/permission/PermissionsSetupEvent.java @@ -8,16 +8,26 @@ package com.velocitypowered.api.event.permission; import com.google.common.base.Preconditions; +import com.velocitypowered.api.event.annotation.AwaitingEvent; import com.velocitypowered.api.permission.PermissionFunction; import com.velocitypowered.api.permission.PermissionProvider; import com.velocitypowered.api.permission.PermissionSubject; import org.checkerframework.checker.nullness.qual.Nullable; /** - * Called when a {@link PermissionSubject}'s permissions are being setup. + * Called when a {@link PermissionSubject}'s permissions are being setup. This event is typically + * called for the {@link com.velocitypowered.api.proxy.ConsoleCommandSource} and any + * {@link com.velocitypowered.api.proxy.Player}s who join the proxy. * *

This event is only called once per subject, on initialisation.

+ * + *

+ * Velocity will wait for this event to finish firing before proceeding further with server + * startup (for the console command source) and logins (for players) but it is strongly + * recommended to minimize the amount of work that must be done in this event. + *

*/ +@AwaitingEvent public final class PermissionsSetupEvent { private final PermissionSubject subject; diff --git a/api/src/main/java/com/velocitypowered/api/event/player/GameProfileRequestEvent.java b/api/src/main/java/com/velocitypowered/api/event/player/GameProfileRequestEvent.java index 135de25d0..d490180fb 100644 --- a/api/src/main/java/com/velocitypowered/api/event/player/GameProfileRequestEvent.java +++ b/api/src/main/java/com/velocitypowered/api/event/player/GameProfileRequestEvent.java @@ -8,6 +8,7 @@ package com.velocitypowered.api.event.player; import com.google.common.base.Preconditions; +import com.velocitypowered.api.event.annotation.AwaitingEvent; import com.velocitypowered.api.proxy.InboundConnection; import com.velocitypowered.api.util.GameProfile; import org.checkerframework.checker.nullness.qual.Nullable; @@ -16,7 +17,14 @@ import org.checkerframework.checker.nullness.qual.Nullable; * This event is fired after the {@link com.velocitypowered.api.event.connection.PreLoginEvent} in * order to set up the game profile for the user. This can be used to configure a custom profile for * a user, i.e. skin replacement. + * + *

+ * Velocity will wait for this event to finish firing before proceeding with the rest of the login + * process, but you should try to limit the work done in any event that fires during the login + * process. + *

*/ +@AwaitingEvent public final class GameProfileRequestEvent { private final String username; diff --git a/api/src/main/java/com/velocitypowered/api/event/player/KickedFromServerEvent.java b/api/src/main/java/com/velocitypowered/api/event/player/KickedFromServerEvent.java index eed14a0c6..1616376bd 100644 --- a/api/src/main/java/com/velocitypowered/api/event/player/KickedFromServerEvent.java +++ b/api/src/main/java/com/velocitypowered/api/event/player/KickedFromServerEvent.java @@ -9,6 +9,7 @@ package com.velocitypowered.api.event.player; import com.google.common.base.Preconditions; import com.velocitypowered.api.event.ResultedEvent; +import com.velocitypowered.api.event.annotation.AwaitingEvent; import com.velocitypowered.api.proxy.Player; import com.velocitypowered.api.proxy.server.RegisteredServer; import java.util.Optional; @@ -19,8 +20,10 @@ import org.checkerframework.checker.nullness.qual.Nullable; * Fired when a player is kicked from a server. You may either allow Velocity to kick the player * (with an optional reason override) or redirect the player to a separate server. By default, * Velocity will notify the user (if they are already connected to a server) or disconnect them - * (if they are not on a server and no other servers are available). + * (if they are not on a server and no other servers are available). Velocity will wait on this + * event to finish firing before taking the specified action. */ +@AwaitingEvent public final class KickedFromServerEvent implements ResultedEvent { diff --git a/api/src/main/java/com/velocitypowered/api/event/player/PlayerChannelRegisterEvent.java b/api/src/main/java/com/velocitypowered/api/event/player/PlayerChannelRegisterEvent.java index 21e4efb2d..5929fa9c0 100644 --- a/api/src/main/java/com/velocitypowered/api/event/player/PlayerChannelRegisterEvent.java +++ b/api/src/main/java/com/velocitypowered/api/event/player/PlayerChannelRegisterEvent.java @@ -15,7 +15,7 @@ import java.util.List; /** * This event is fired when a client ({@link Player}) sends a plugin message through the - * register channel. + * register channel. Velocity will not wait on this event to finish firing. */ public final class PlayerChannelRegisterEvent { diff --git a/api/src/main/java/com/velocitypowered/api/event/player/PlayerChatEvent.java b/api/src/main/java/com/velocitypowered/api/event/player/PlayerChatEvent.java index 2ddcd5e29..172ac82b0 100644 --- a/api/src/main/java/com/velocitypowered/api/event/player/PlayerChatEvent.java +++ b/api/src/main/java/com/velocitypowered/api/event/player/PlayerChatEvent.java @@ -9,14 +9,17 @@ package com.velocitypowered.api.event.player; import com.google.common.base.Preconditions; import com.velocitypowered.api.event.ResultedEvent; +import com.velocitypowered.api.event.annotation.AwaitingEvent; import com.velocitypowered.api.proxy.Player; import java.util.Optional; import org.checkerframework.checker.nullness.qual.NonNull; import org.checkerframework.checker.nullness.qual.Nullable; /** - * This event is fired when a player types in a chat message. + * This event is fired when a player types in a chat message. Velocity will wait on this event + * to finish firing before forwarding it to the server, if the result allows it. */ +@AwaitingEvent public final class PlayerChatEvent implements ResultedEvent { private final Player player; diff --git a/api/src/main/java/com/velocitypowered/api/event/player/PlayerChooseInitialServerEvent.java b/api/src/main/java/com/velocitypowered/api/event/player/PlayerChooseInitialServerEvent.java index 3fc02107b..353f7c4f3 100644 --- a/api/src/main/java/com/velocitypowered/api/event/player/PlayerChooseInitialServerEvent.java +++ b/api/src/main/java/com/velocitypowered/api/event/player/PlayerChooseInitialServerEvent.java @@ -8,15 +8,19 @@ package com.velocitypowered.api.event.player; import com.google.common.base.Preconditions; +import com.velocitypowered.api.event.annotation.AwaitingEvent; import com.velocitypowered.api.proxy.Player; import com.velocitypowered.api.proxy.server.RegisteredServer; import java.util.Optional; import org.checkerframework.checker.nullness.qual.Nullable; /** - * Fired when a player has finished connecting to the proxy and we need to choose the first server - * to connect to. + * Fired when a player has finished the login process, and we need to choose the first server + * to connect to. Velocity will wait on this event to finish firing before initiating the connection + * but you should try to limit the work done in this event. Failures will be handled by + * {@link KickedFromServerEvent} as normal. */ +@AwaitingEvent public class PlayerChooseInitialServerEvent { private final Player player; diff --git a/api/src/main/java/com/velocitypowered/api/event/player/PlayerClientBrandEvent.java b/api/src/main/java/com/velocitypowered/api/event/player/PlayerClientBrandEvent.java index 03942404e..854486f4a 100644 --- a/api/src/main/java/com/velocitypowered/api/event/player/PlayerClientBrandEvent.java +++ b/api/src/main/java/com/velocitypowered/api/event/player/PlayerClientBrandEvent.java @@ -11,7 +11,8 @@ import com.google.common.base.Preconditions; import com.velocitypowered.api.proxy.Player; /** - * Fired when a {@link Player} sends the minecraft:brand plugin message. + * Fired when a {@link Player} sends the minecraft:brand plugin message. Velocity will + * not wait on the result of this event. */ public final class PlayerClientBrandEvent { private final Player player; diff --git a/api/src/main/java/com/velocitypowered/api/event/player/PlayerModInfoEvent.java b/api/src/main/java/com/velocitypowered/api/event/player/PlayerModInfoEvent.java index 7f3c301e3..0c451fcc4 100644 --- a/api/src/main/java/com/velocitypowered/api/event/player/PlayerModInfoEvent.java +++ b/api/src/main/java/com/velocitypowered/api/event/player/PlayerModInfoEvent.java @@ -14,6 +14,7 @@ import com.velocitypowered.api.util.ModInfo; /** * This event is fired when a Forge client sends its mods to the proxy while connecting to a server. + * Velocity will not wait on this event to finish firing. */ public final class PlayerModInfoEvent { diff --git a/api/src/main/java/com/velocitypowered/api/event/player/PlayerResourcePackStatusEvent.java b/api/src/main/java/com/velocitypowered/api/event/player/PlayerResourcePackStatusEvent.java index bfd7a5ea5..86211e510 100644 --- a/api/src/main/java/com/velocitypowered/api/event/player/PlayerResourcePackStatusEvent.java +++ b/api/src/main/java/com/velocitypowered/api/event/player/PlayerResourcePackStatusEvent.java @@ -8,6 +8,7 @@ package com.velocitypowered.api.event.player; import com.google.common.base.Preconditions; +import com.velocitypowered.api.event.annotation.AwaitingEvent; import com.velocitypowered.api.network.ProtocolVersion; import com.velocitypowered.api.proxy.Player; import com.velocitypowered.api.proxy.player.ResourcePackInfo; @@ -16,8 +17,10 @@ import org.checkerframework.checker.nullness.qual.Nullable; /** * This event is fired when the status of a resource pack sent to the player by the server is - * changed. + * changed. Depending on the result of this event (which Velocity will wait until completely fired), + * the player may be kicked from the server. */ +@AwaitingEvent public class PlayerResourcePackStatusEvent { private final Player player; @@ -25,7 +28,6 @@ public class PlayerResourcePackStatusEvent { private final @MonotonicNonNull ResourcePackInfo packInfo; private boolean overwriteKick; - /** * Instantiates this event. * @deprecated Use {@link PlayerResourcePackStatusEvent#PlayerResourcePackStatusEvent diff --git a/api/src/main/java/com/velocitypowered/api/event/player/PlayerSettingsChangedEvent.java b/api/src/main/java/com/velocitypowered/api/event/player/PlayerSettingsChangedEvent.java index bff9c5d5e..ead4e18f2 100644 --- a/api/src/main/java/com/velocitypowered/api/event/player/PlayerSettingsChangedEvent.java +++ b/api/src/main/java/com/velocitypowered/api/event/player/PlayerSettingsChangedEvent.java @@ -12,6 +12,11 @@ import com.google.common.base.Preconditions; import com.velocitypowered.api.proxy.Player; import com.velocitypowered.api.proxy.player.PlayerSettings; +/** + * This event is fired when the client sends new client settings for the player. This event can + * and typically will be fired multiple times per connection. Velocity will not wait on this event + * to finish firing. + */ public final class PlayerSettingsChangedEvent { private final Player player; diff --git a/api/src/main/java/com/velocitypowered/api/event/player/ServerConnectedEvent.java b/api/src/main/java/com/velocitypowered/api/event/player/ServerConnectedEvent.java index fdf18f13e..610e62f9f 100644 --- a/api/src/main/java/com/velocitypowered/api/event/player/ServerConnectedEvent.java +++ b/api/src/main/java/com/velocitypowered/api/event/player/ServerConnectedEvent.java @@ -8,6 +8,7 @@ package com.velocitypowered.api.event.player; import com.google.common.base.Preconditions; +import com.velocitypowered.api.event.annotation.AwaitingEvent; import com.velocitypowered.api.proxy.Player; import com.velocitypowered.api.proxy.server.RegisteredServer; import java.util.Optional; @@ -16,7 +17,14 @@ import org.checkerframework.checker.nullness.qual.Nullable; /** * This event is fired once the player has successfully connected to the target server and the * connection to the previous server has been de-established. + * + *

+ * Note: For historical reasons, Velocity does wait on this event to finish + * firing before continuing the server connection process. This behavior is + * deprecated and likely to be removed in Polymer. + *

*/ +@AwaitingEvent public final class ServerConnectedEvent { private final Player player; diff --git a/api/src/main/java/com/velocitypowered/api/event/player/ServerLoginPluginMessageEvent.java b/api/src/main/java/com/velocitypowered/api/event/player/ServerLoginPluginMessageEvent.java index 45e9db3d3..66f163721 100644 --- a/api/src/main/java/com/velocitypowered/api/event/player/ServerLoginPluginMessageEvent.java +++ b/api/src/main/java/com/velocitypowered/api/event/player/ServerLoginPluginMessageEvent.java @@ -13,6 +13,7 @@ import com.google.common.io.BaseEncoding; import com.google.common.io.ByteArrayDataInput; import com.google.common.io.ByteStreams; import com.velocitypowered.api.event.ResultedEvent; +import com.velocitypowered.api.event.annotation.AwaitingEvent; import com.velocitypowered.api.event.player.ServerLoginPluginMessageEvent.ResponseResult; import com.velocitypowered.api.proxy.ServerConnection; import com.velocitypowered.api.proxy.messages.ChannelIdentifier; @@ -22,8 +23,11 @@ import org.checkerframework.checker.nullness.qual.Nullable; /** * Fired when a server sends a login plugin message to the proxy. Plugins have the opportunity to - * respond to the messages as needed. + * respond to the messages as needed. Velocity will wait on this event to finish. The server will + * be responsible for continuing the login process once the server is satisfied with any login + * plugin responses sent by proxy plugins (or messages indicating a lack of response). */ +@AwaitingEvent public class ServerLoginPluginMessageEvent implements ResultedEvent { private final ServerConnection connection; private final ChannelIdentifier identifier; diff --git a/api/src/main/java/com/velocitypowered/api/event/player/ServerPostConnectEvent.java b/api/src/main/java/com/velocitypowered/api/event/player/ServerPostConnectEvent.java index e2135be62..d67f0c7de 100644 --- a/api/src/main/java/com/velocitypowered/api/event/player/ServerPostConnectEvent.java +++ b/api/src/main/java/com/velocitypowered/api/event/player/ServerPostConnectEvent.java @@ -15,7 +15,8 @@ import org.checkerframework.checker.nullness.qual.Nullable; /** * Fired after the player has connected to a server. The server the player is now connected to is - * available in {@link Player#getCurrentServer()}. + * available in {@link Player#getCurrentServer()}. Velocity will not wait on this event to finish + * firing. */ @Beta public class ServerPostConnectEvent { diff --git a/api/src/main/java/com/velocitypowered/api/event/player/ServerPreConnectEvent.java b/api/src/main/java/com/velocitypowered/api/event/player/ServerPreConnectEvent.java index 04d0538ac..bb0597473 100644 --- a/api/src/main/java/com/velocitypowered/api/event/player/ServerPreConnectEvent.java +++ b/api/src/main/java/com/velocitypowered/api/event/player/ServerPreConnectEvent.java @@ -9,6 +9,7 @@ package com.velocitypowered.api.event.player; import com.google.common.base.Preconditions; import com.velocitypowered.api.event.ResultedEvent; +import com.velocitypowered.api.event.annotation.AwaitingEvent; import com.velocitypowered.api.proxy.ConnectionRequestBuilder; import com.velocitypowered.api.proxy.ConnectionRequestBuilder.Status; import com.velocitypowered.api.proxy.Player; @@ -17,8 +18,10 @@ import java.util.Optional; import org.checkerframework.checker.nullness.qual.Nullable; /** - * This event is fired before the player connects to a server. + * This event is fired before the player connects to a server. Velocity will wait on this event to + * finish firing before initiating the connection. */ +@AwaitingEvent public final class ServerPreConnectEvent implements ResultedEvent { diff --git a/api/src/main/java/com/velocitypowered/api/event/player/TabCompleteEvent.java b/api/src/main/java/com/velocitypowered/api/event/player/TabCompleteEvent.java index 14bb63554..99653504f 100644 --- a/api/src/main/java/com/velocitypowered/api/event/player/TabCompleteEvent.java +++ b/api/src/main/java/com/velocitypowered/api/event/player/TabCompleteEvent.java @@ -9,6 +9,7 @@ package com.velocitypowered.api.event.player; import static com.google.common.base.Preconditions.checkNotNull; +import com.velocitypowered.api.event.annotation.AwaitingEvent; import com.velocitypowered.api.proxy.Player; import java.util.ArrayList; import java.util.List; @@ -16,7 +17,11 @@ import java.util.List; /** * This event is fired after a tab complete response is sent by the remote server, for clients on * 1.12.2 and below. You have the opportunity to modify the response sent to the remote player. + * Velocity will wait for this event to finish firing before sending the tab complete results to + * the client. Be sure to be as fast as possible, since the client will freeze while it waits for + * the tab complete results. */ +@AwaitingEvent public class TabCompleteEvent { private final Player player; private final String partialMessage; diff --git a/api/src/main/java/com/velocitypowered/api/event/proxy/ProxyInitializeEvent.java b/api/src/main/java/com/velocitypowered/api/event/proxy/ProxyInitializeEvent.java index 80c5b8405..ebde60b4c 100644 --- a/api/src/main/java/com/velocitypowered/api/event/proxy/ProxyInitializeEvent.java +++ b/api/src/main/java/com/velocitypowered/api/event/proxy/ProxyInitializeEvent.java @@ -7,10 +7,14 @@ package com.velocitypowered.api.event.proxy; +import com.velocitypowered.api.event.annotation.AwaitingEvent; + /** * This event is fired by the proxy after plugins have been loaded but before the proxy starts - * accepting connections. + * accepting connections. Velocity will wait for this event to finish firing before it begins to + * accept new connections. */ +@AwaitingEvent public final class ProxyInitializeEvent { @Override diff --git a/api/src/main/java/com/velocitypowered/api/event/proxy/ProxyPingEvent.java b/api/src/main/java/com/velocitypowered/api/event/proxy/ProxyPingEvent.java index 0df9e6650..b7e040eef 100644 --- a/api/src/main/java/com/velocitypowered/api/event/proxy/ProxyPingEvent.java +++ b/api/src/main/java/com/velocitypowered/api/event/proxy/ProxyPingEvent.java @@ -8,12 +8,17 @@ package com.velocitypowered.api.event.proxy; import com.google.common.base.Preconditions; +import com.velocitypowered.api.event.annotation.AwaitingEvent; import com.velocitypowered.api.proxy.InboundConnection; import com.velocitypowered.api.proxy.server.ServerPing; /** - * This event is fired when a server list ping request is sent by a remote client. + * This event is fired when a server list ping request is sent by a remote client. Velocity will + * wait on this event to finish firing before delivering the results to the remote client, but + * you are urged to be as parsimonious as possible when handling this event due to the amount of + * ping packets a client can send. */ +@AwaitingEvent public final class ProxyPingEvent { private final InboundConnection connection; diff --git a/api/src/main/java/com/velocitypowered/api/event/proxy/ProxyShutdownEvent.java b/api/src/main/java/com/velocitypowered/api/event/proxy/ProxyShutdownEvent.java index 49183600a..929686987 100644 --- a/api/src/main/java/com/velocitypowered/api/event/proxy/ProxyShutdownEvent.java +++ b/api/src/main/java/com/velocitypowered/api/event/proxy/ProxyShutdownEvent.java @@ -7,10 +7,13 @@ package com.velocitypowered.api.event.proxy; +import com.velocitypowered.api.event.annotation.AwaitingEvent; + /** * This event is fired by the proxy after the proxy has stopped accepting connections but before the - * proxy process exits. + * proxy process exits. Velocity will wait for this event to finish firing before it exits. */ +@AwaitingEvent public final class ProxyShutdownEvent { @Override diff --git a/api/src/main/java/com/velocitypowered/api/event/query/ProxyQueryEvent.java b/api/src/main/java/com/velocitypowered/api/event/query/ProxyQueryEvent.java index 2d3cf315a..efdd644af 100644 --- a/api/src/main/java/com/velocitypowered/api/event/query/ProxyQueryEvent.java +++ b/api/src/main/java/com/velocitypowered/api/event/query/ProxyQueryEvent.java @@ -8,12 +8,15 @@ package com.velocitypowered.api.event.query; import com.google.common.base.Preconditions; +import com.velocitypowered.api.event.annotation.AwaitingEvent; import com.velocitypowered.api.proxy.server.QueryResponse; import java.net.InetAddress; /** - * This event is fired if proxy is getting queried over GS4 Query protocol. + * This event is fired if proxy is getting queried over GS4 Query protocol. Velocity will wait on + * this event to fire before providing a response to the client. */ +@AwaitingEvent public final class ProxyQueryEvent { private final QueryType queryType;