Snapshot 21w15a

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

@@ -8,7 +8,11 @@
 package com.velocitypowered.api.event.player;
 
 import com.google.common.base.Preconditions;
+import com.velocitypowered.api.network.ProtocolVersion;
 import com.velocitypowered.api.proxy.Player;
+import com.velocitypowered.api.proxy.player.ResourcePackInfo;
+import org.checkerframework.checker.nullness.qual.MonotonicNonNull;
+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
@@ -18,10 +22,29 @@ public class PlayerResourcePackStatusEvent {
 
   private final Player player;
   private final Status status;
+  private final @MonotonicNonNull ResourcePackInfo packInfo;
+  private boolean overwriteKick;
 
+
+  /**
+   * Instates this event.
+   * @deprecated Use {@link PlayerResourcePackStatusEvent#PlayerResourcePackStatusEvent
+   *             (Player, Status, ResourcePackInfo)} instead.
+   */
+  @Deprecated
   public PlayerResourcePackStatusEvent(Player player, Status status) {
     this.player = Preconditions.checkNotNull(player, "player");
     this.status = Preconditions.checkNotNull(status, "status");
+    this.packInfo = null;
+  }
+
+  /**
+   * Instates this event.
+   */
+  public PlayerResourcePackStatusEvent(Player player, Status status, ResourcePackInfo packInfo) {
+    this.player = Preconditions.checkNotNull(player, "player");
+    this.status = Preconditions.checkNotNull(status, "status");
+    this.packInfo = packInfo;
   }
 
   /**
@@ -42,11 +65,49 @@ public class PlayerResourcePackStatusEvent {
     return status;
   }
 
+  /**
+   * Returns the {@link ResourcePackInfo} this response is for.
+   *
+   * @return the resource-pack info or null if no request was recorded
+   */
+  @Nullable
+  public ResourcePackInfo getPackInfo() {
+    return packInfo;
+  }
+
+  /**
+   * Gets whether or not to override the kick resulting from
+   * {@link ResourcePackInfo#getShouldForce()} being true.
+   *
+   * @return whether or not to overwrite the result
+   */
+  public boolean isOverwriteKick() {
+    return overwriteKick;
+  }
+
+  /**
+   * Set to true to prevent {@link ResourcePackInfo#getShouldForce()}
+   * from kicking the player.
+   * Overwriting this kick is only possible on versions older than 1.17,
+   * as the client or server will enforce this regardless. Cancelling the resulting
+   * kick-events will not prevent the player from disconnecting from the proxy.
+   *
+   * @param overwriteKick whether or not to cancel the kick
+   * @throws IllegalArgumentException if the player version is 1.17 or newer
+   */
+  public void setOverwriteKick(boolean overwriteKick) {
+    Preconditions.checkArgument(player.getProtocolVersion()
+            .compareTo(ProtocolVersion.MINECRAFT_1_17) < 0,
+            "overwriteKick is not supported on 1.17 or newer");
+    this.overwriteKick = overwriteKick;
+  }
+
   @Override
   public String toString() {
     return "PlayerResourcePackStatusEvent{"
         + "player=" + player
         + ", status=" + status
+        + ", packInfo=" + packInfo
         + '}';
   }
 

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

@@ -54,7 +54,7 @@ public enum ProtocolVersion {
   MINECRAFT_1_16_2(751, "1.16.2"),
   MINECRAFT_1_16_3(753, "1.16.3"),
   MINECRAFT_1_16_4(754, "1.16.4", "1.16.5"),
-  MINECRAFT_1_17(-1, 21, "1.17"); // Snapshot: 21w14a, future protocol: 755
+  MINECRAFT_1_17(-1, 22, "1.17"); // Snapshot: 21w15a, future protocol: 755
 
   private static final int SNAPSHOT_BIT = 30;
 

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

@@ -13,6 +13,7 @@ import com.velocitypowered.api.proxy.messages.ChannelIdentifier;
 import com.velocitypowered.api.proxy.messages.ChannelMessageSink;
 import com.velocitypowered.api.proxy.messages.ChannelMessageSource;
 import com.velocitypowered.api.proxy.player.PlayerSettings;
+import com.velocitypowered.api.proxy.player.ResourcePackInfo;
 import com.velocitypowered.api.proxy.player.TabList;
 import com.velocitypowered.api.proxy.server.RegisteredServer;
 import com.velocitypowered.api.util.GameProfile;
@@ -25,6 +26,7 @@ import java.util.UUID;
 import net.kyori.adventure.identity.Identified;
 import net.kyori.adventure.identity.Identity;
 import net.kyori.adventure.text.Component;
+import org.checkerframework.checker.nullness.qual.Nullable;
 
 /**
  * Represents a player who is connected to the proxy.
@@ -215,7 +217,9 @@ public interface Player extends CommandSource, Identified, InboundConnection,
    * sent resource pack, subscribe to {@link PlayerResourcePackStatusEvent}.
    *
    * @param url the URL for the resource pack
+   * @deprecated Use {@link #sendResourcePackOffer(ResourcePackInfo)} instead
    */
+  @Deprecated
   void sendResourcePack(String url);
 
   /**
@@ -225,10 +229,37 @@ public interface Player extends CommandSource, Identified, InboundConnection,
    *
    * @param url the URL for the resource pack
    * @param hash the SHA-1 hash value for the resource pack
+   * @deprecated Use {@link #sendResourcePackOffer(ResourcePackInfo)} instead
    */
-  default void sendResourcePack(String url, byte[] hash) {
-    sendResourcePack(url, hash, false);
-  }
+  @Deprecated
+  void sendResourcePack(String url, byte[] hash);
+
+  /**
+   * Queues and sends a new Resource-pack offer to the player.
+   * To monitor the status of the sent resource pack, subscribe to
+   * {@link PlayerResourcePackStatusEvent}.
+   *
+   * @param packInfo the resource-pack in question
+   */
+  void sendResourcePackOffer(ResourcePackInfo packInfo);
+
+  /**
+   * Gets the {@link ResourcePackInfo} of the currently applied
+   * resource-pack or null if none.
+   *
+   * @return the applied resource pack
+   */
+  @Nullable
+  ResourcePackInfo getAppliedResourcePack();
+
+  /**
+   * Gets the {@link ResourcePackInfo} of the currently accepted
+   * and currently downloading resource-pack or null if none.
+   *
+   * @return the pending resource pack
+   */
+  @Nullable
+  ResourcePackInfo getPendingResourcePack();
 
   /**
    * <strong>Note that this method does not send a plugin message to the server the player
@@ -241,21 +272,4 @@ public interface Player extends CommandSource, Identified, InboundConnection,
    */
   @Override
   boolean sendPluginMessage(ChannelIdentifier identifier, byte[] data);
-
-  /**
-   * Sends the specified resource pack from {@code url} to the user, using the specified 20-byte
-   * SHA-1 hash. To monitor the status of the sent resource pack, subscribe to
-   * {@link PlayerResourcePackStatusEvent}.
-   * In 1.17 and newer you can additionally specify
-   * whether the resource pack is required or not. Setting this for an older client will have
-   * no effect.
-   *
-   * @param url the URL for the resource pack
-   * @param hash the SHA-1 hash value for the resource pack
-   * @param isRequired Only in 1.17+ or newer: If true shows the pack as required to play,
-   *     and removes the decline option. Declining it anyway will disconnect the user.
-   */
-  void sendResourcePack(String url, byte[] hash, boolean isRequired);
- 
 }
-

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

@@ -13,6 +13,7 @@ import com.velocitypowered.api.event.EventManager;
 import com.velocitypowered.api.plugin.PluginManager;
 import com.velocitypowered.api.proxy.config.ProxyConfig;
 import com.velocitypowered.api.proxy.messages.ChannelRegistrar;
+import com.velocitypowered.api.proxy.player.ResourcePackInfo;
 import com.velocitypowered.api.proxy.server.RegisteredServer;
 import com.velocitypowered.api.proxy.server.ServerInfo;
 import com.velocitypowered.api.scheduler.Scheduler;
@@ -217,4 +218,24 @@ public interface ProxyServer extends Audience {
   @NonNull
   BossBar createBossBar(net.kyori.text.Component title, @NonNull BossBarColor color,
       @NonNull BossBarOverlay overlay, float progress);
+
+  /**
+   * Creates a builder to build a {@link ResourcePackInfo} instance for use with
+   * {@link com.velocitypowered.api.proxy.Player#sendResourcePackOffer(ResourcePackInfo)}.
+   *
+   * <p>Note: The resource-pack location should always:
+   * - Use HTTPS with a valid certificate.
+   * - Be in a crawler-accessible location. Having it behind Cloudflare or Cloudfront
+   *   may cause issues in downloading.
+   * - Be in location with appropriate bandwidth so the download does not time out or fail.</p>
+   *
+   * <p>Do also make sure that the resource pack is in the correct format for the version
+   * of the client. It is also highly recommended to always provide the resource-pack SHA-1 hash
+   * of the resource pack with {@link ResourcePackInfo.Builder#setHash(byte[])}
+   * whenever possible to save bandwidth.</p>
+   *
+   * @param url The url where the resource pack can be found
+   * @return a ResourcePackInfo builder
+   */
+  ResourcePackInfo.Builder createResourcePackBuilder(String url);
 }

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

@@ -0,0 +1,120 @@
+/*
+ * 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.proxy.player;
+
+import net.kyori.adventure.text.Component;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
+public interface ResourcePackInfo {
+
+  /**
+   * Gets the link the resource-pack can be found at.
+   *
+   * @return the location of the resource-pack
+   */
+  String getUrl();
+
+  /**
+   * Gets the {@link Component} that is displayed on the resource-pack prompt.
+   * This is only displayed if the client version is 1.17 or newer.
+   *
+   * @return the prompt if present or null otherwise
+   */
+  @Nullable
+  Component getPrompt();
+
+  /**
+   * Gets whether or not the acceptance of the resource-pack is enforced.
+   * See {@link Builder#setShouldForce(boolean)} for more information.
+   *
+   * @return whether or not to force usage of this resource-pack
+   */
+  boolean getShouldForce();
+
+  /**
+   * Gets the SHA-1 hash of the resource-pack
+   * See {@link Builder#setHash(byte[])} for more information.
+   *
+   * @return the hash if present or null otherwise
+   */
+  @Nullable
+  byte[] getHash();
+
+  /**
+   * Gets the {@link Origin} of the resource-pack.
+   *
+   * @return the origin of the resource pack
+   */
+  Origin getOrigin();
+
+  interface Builder {
+
+    /**
+     * Sets the resource-pack as required to play on the network.
+     * This feature was introduced in 1.17.
+     * Setting this to true has one of two effects:
+     * If the client is on 1.17 or newer:
+     *  - The resource-pack prompt will display without a decline button
+     *  - Accept or disconnect are the only available options but players may still press escape.
+     *  - Forces the resource-pack offer prompt to display even if the player has
+     *    previously declined or disabled resource packs
+     *  - The player will be disconnected from the network if they close/skip the prompt.
+     * If the client is on a version older than 1.17:
+     *  - If the player accepts the resource pack or has previously accepted a resource-pack
+     *    then nothing else will happen.
+     *  - If the player declines the resource pack or has previously declined a resource-pack
+     *    the player will be disconnected from the network
+     *
+     * @param shouldForce whether or not to force the client to accept the resource pack
+     */
+    Builder setShouldForce(boolean shouldForce);
+
+    /**
+     * Sets the SHA-1 hash of the provided resource pack.
+     * Note: It is recommended to always set this hash.
+     * If this hash is not set/ not present then the client will always download
+     * the resource pack even if it may still be cached. By having this hash present,
+     * the client will check first whether or not a resource pack by this hash is cached
+     * before downloading.
+     *
+     * @param hash the SHA-1 hash of the resource-pack
+     */
+    Builder setHash(@Nullable byte[] hash);
+
+    /**
+     * Sets a {@link Component} to display on the download prompt.
+     * This will only display if the client version is 1.17 or newer.
+     *
+     * @param prompt the component to display
+     */
+    Builder setPrompt(@Nullable Component prompt);
+
+    /**
+     * Builds the {@link ResourcePackInfo} from the provided info for use with
+     * {@link com.velocitypowered.api.proxy.Player#sendResourcePackOffer(ResourcePackInfo)}.
+     * Note: Some features may be version-dependent. Check before use.
+     *
+     * @return a ResourcePackInfo instance from the provided information
+     */
+    ResourcePackInfo build();
+  }
+
+  /**
+   * Represents the origin of the resource-pack.
+   */
+  enum Origin {
+    /**
+     * Resource-pack originated from the downstream server.
+     */
+    DOWNSTREAM_SERVER,
+    /**
+     * The player declined to download the resource pack.
+     */
+    PLUGIN_ON_PROXY
+  }
+}