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

api/build.gradle.kts

@@ -67,7 +67,9 @@ tasks {
             "https://google.github.io/guice/api-docs/${libs.guice.get().version}/javadoc/",
             "https://docs.oracle.com/en/java/javase/17/docs/api/",
             "https://jd.advntr.dev/api/${libs.adventure.bom.get().version}/",
-            "https://javadoc.io/doc/com.github.ben-manes.caffeine/caffeine"
+            "https://jd.advntr.dev/text-minimessage/${libs.adventure.bom.get().version}/",
+            "https://jd.advntr.dev/key/${libs.adventure.bom.get().version}/",
+            "https://javadoc.io/doc/com.github.ben-manes.caffeine/caffeine/${libs.caffeine.get().version}/",
         )
 
         o.tags(

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

@@ -44,7 +44,7 @@ public interface CommandManager {
    * @param otherAliases additional aliases
    * @throws IllegalArgumentException if one of the given aliases is already registered, or
    *         the given command does not implement a registrable {@link Command} subinterface
-   * @see Command for a list of registrable {@link Command} subinterfaces
+   * @see Command for a list of registrable Command subinterfaces
    */
   default void register(String alias, Command command, String... otherAliases) {
     register(metaBuilder(alias).aliases(otherAliases).build(), command);
@@ -65,7 +65,7 @@ public interface CommandManager {
    * @param command the command to register
    * @throws IllegalArgumentException if one of the given aliases is already registered, or
    *         the given command does not implement a registrable {@link Command} subinterface
-   * @see Command for a list of registrable {@link Command} subinterfaces
+   * @see Command for a list of registrable Command subinterfaces
    */
   void register(CommandMeta meta, Command command);
 

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

@@ -0,0 +1,68 @@
+/*
+ * Copyright (C) 2018-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.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.ServerConnection;
+import java.util.UUID;
+import org.checkerframework.checker.nullness.qual.MonotonicNonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
+/**
+ * This event is fired when the downstream server tries to remove a resource pack from player
+ * or clear all of them. The proxy will wait on this event to finish before forwarding the
+ * action to the user. If this event is denied, no resource packs will be removed from player.
+ */
+@AwaitingEvent
+public class ServerResourcePackRemoveEvent implements ResultedEvent<ResultedEvent.GenericResult> {
+
+  private GenericResult result;
+  private final @MonotonicNonNull UUID packId;
+  private final ServerConnection serverConnection;
+
+  /**
+   * Instantiates this event.
+   */
+  public ServerResourcePackRemoveEvent(UUID packId, ServerConnection serverConnection) {
+    this.result = ResultedEvent.GenericResult.allowed();
+    this.packId = packId;
+    this.serverConnection = serverConnection;
+  }
+
+  /**
+   * Returns the id of the resource pack, if it's null all the resource packs
+   * from player will be cleared.
+   *
+   * @return the id
+   */
+  @Nullable
+  public UUID getPackId() {
+    return packId;
+  }
+
+  /**
+   * Returns the server that tries to remove a resource pack from player or clear all of them.
+   *
+   * @return the server connection
+   */
+  public ServerConnection getServerConnection() {
+    return serverConnection;
+  }
+
+  @Override
+  public GenericResult getResult() {
+    return this.result;
+  }
+
+  @Override
+  public void setResult(GenericResult result) {
+    this.result = Preconditions.checkNotNull(result, "result");
+  }
+}

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

@@ -0,0 +1,29 @@
+/*
+ * 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 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 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

@@ -0,0 +1,29 @@
+/*
+ * 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 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 finish the configuration phase.
+ * @param server The server that has (re-)configured the player.
+ * @since 3.3.0
+ * @sinceMinecraft 1.20.2
+ */
+@AwaitingEvent
+public record PlayerFinishConfigurationEvent(@NotNull Player player, @NotNull ServerConnection server) {
+}

api/src/main/java/com/velocitypowered/api/event/player/configuration/PlayerFinishedConfigurationEvent.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.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 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 finished the configuration state.
+ * @param server The server that has (re-)configured the player.
+ * @since 3.3.0
+ * @sinceMinecraft 1.20.2
+ */
+public record PlayerFinishedConfigurationEvent(@NotNull Player player, @NotNull ServerConnection server) {
+}

api/src/main/java/com/velocitypowered/api/event/proxy/server/ServerRegisteredEvent.java

@@ -0,0 +1,31 @@
+/*
+ * 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.proxy.server;
+
+import com.google.common.annotations.Beta;
+import com.google.common.base.Preconditions;
+import com.velocitypowered.api.proxy.server.RegisteredServer;
+import com.velocitypowered.api.proxy.server.ServerInfo;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * This event is fired by the proxy after a backend server is registered to the server map.
+ * Currently, it may occur when a server is registered dynamically at runtime or when a server is
+ * replaced due to configuration reload.
+ *
+ * @see com.velocitypowered.api.proxy.ProxyServer#registerServer(ServerInfo)
+ *
+ * @param registeredServer A {@link RegisteredServer} that has been registered.
+ * @since 3.3.0
+ */
+@Beta
+public record ServerRegisteredEvent(@NotNull RegisteredServer registeredServer) {
+  public ServerRegisteredEvent {
+    Preconditions.checkNotNull(registeredServer, "registeredServer");
+  }
+}

api/src/main/java/com/velocitypowered/api/event/proxy/server/ServerUnregisteredEvent.java

@@ -0,0 +1,31 @@
+/*
+ * 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.proxy.server;
+
+import com.google.common.annotations.Beta;
+import com.google.common.base.Preconditions;
+import com.velocitypowered.api.proxy.server.RegisteredServer;
+import com.velocitypowered.api.proxy.server.ServerInfo;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * This event is fired by the proxy after a backend server is unregistered from the server map.
+ * Currently, it may occur when a server is unregistered dynamically at runtime
+ * or when a server is replaced due to configuration reload.
+ *
+ * @see com.velocitypowered.api.proxy.ProxyServer#unregisterServer(ServerInfo)
+ *
+ * @param unregisteredServer A {@link RegisteredServer} that has been unregistered.
+ * @since 3.3.0
+ */
+@Beta
+public record ServerUnregisteredEvent(@NotNull RegisteredServer unregisteredServer) {
+  public ServerUnregisteredEvent {
+    Preconditions.checkNotNull(unregisteredServer, "unregisteredServer");
+  }
+}

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

@@ -87,7 +87,7 @@ public enum ProtocolVersion implements Ordered<ProtocolVersion> {
   MINECRAFT_1_20_2(764, "1.20.2"),
   MINECRAFT_1_20_3(765, "1.20.3", "1.20.4"),
   MINECRAFT_1_20_5(766, "1.20.5", "1.20.6"),
-  MINECRAFT_1_21(767, "1.21");
+  MINECRAFT_1_21(767, "1.21", "1.21.1");
 
   private static final int SNAPSHOT_BIT = 30;
 

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

@@ -21,6 +21,7 @@ import com.velocitypowered.api.proxy.player.TabList;
 import com.velocitypowered.api.proxy.server.RegisteredServer;
 import com.velocitypowered.api.util.GameProfile;
 import com.velocitypowered.api.util.ModInfo;
+import com.velocitypowered.api.util.ServerLink;
 import java.net.InetSocketAddress;
 import java.util.Collection;
 import java.util.List;
@@ -461,4 +462,16 @@ public interface Player extends
    * @sinceMinecraft 1.20.5
    */
   void requestCookie(Key key);
+
+  /**
+   * Send the player a list of custom links to display in their client's pause menu.
+   *
+   * <p>Note that later packets sent by the backend server may override links sent by the proxy.
+   *
+   * @param links an ordered list of {@link ServerLink}s to send to the player
+   * @throws IllegalArgumentException if the player is from a version lower than 1.21
+   * @since 3.3.0
+   * @sinceMinecraft 1.21
+   */
+  void setServerLinks(@NotNull List<ServerLink> links);
 }

api/src/main/java/com/velocitypowered/api/util/ServerLink.java

@@ -0,0 +1,101 @@
+/*
+ * Copyright (C) 2021-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.util;
+
+import com.google.common.base.Preconditions;
+import java.net.URI;
+import java.util.Optional;
+import net.kyori.adventure.text.Component;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Represents a custom URL servers can show in player pause menus.
+ * Links can be of a built-in type or use a custom component text label.
+ */
+public final class ServerLink {
+
+  private @Nullable Type type;
+  private @Nullable Component label;
+  private final URI url;
+
+  private ServerLink(Component label, String url) {
+    this.label = Preconditions.checkNotNull(label, "label");
+    this.url = URI.create(url);
+  }
+
+  private ServerLink(Type type, String url) {
+    this.type = Preconditions.checkNotNull(type, "type");
+    this.url = URI.create(url);
+  }
+
+  /**
+   * Construct a server link with a custom component label.
+   *
+   * @param label a custom component label to display
+   * @param link  the URL to open when clicked
+   */
+  public static ServerLink serverLink(Component label, String link) {
+    return new ServerLink(label, link);
+  }
+
+  /**
+   * Construct a server link with a built-in type.
+   *
+   * @param type the {@link Type built-in type} of link
+   * @param link the URL to open when clicked
+   */
+  public static ServerLink serverLink(Type type, String link) {
+    return new ServerLink(type, link);
+  }
+
+  /**
+   * Get the type of the server link.
+   *
+   * @return the type of the server link
+   */
+  public Optional<Type> getBuiltInType() {
+    return Optional.ofNullable(type);
+  }
+
+  /**
+   * Get the custom component label of the server link.
+   *
+   * @return the custom component label of the server link
+   */
+  public Optional<Component> getCustomLabel() {
+    return Optional.ofNullable(label);
+  }
+
+  /**
+   * Get the link {@link URI}.
+   *
+   * @return the link {@link URI}
+   */
+  public URI getUrl() {
+    return url;
+  }
+
+  /**
+   * Built-in types of server links.
+   *
+   * @apiNote {@link Type#BUG_REPORT} links are shown on the connection error screen
+   */
+  public enum Type {
+    BUG_REPORT,
+    COMMUNITY_GUIDELINES,
+    SUPPORT,
+    STATUS,
+    FEEDBACK,
+    COMMUNITY,
+    WEBSITE,
+    FORUMS,
+    NEWS,
+    ANNOUNCEMENTS
+  }
+
+}