SPIGOT-6789: Improve resource pack related API

By: Patrick Choe <mailpatrickkr@gmail.com>

paper-api/src/main/java/org/bukkit/Bukkit.java

@@ -245,6 +245,49 @@ public final class Bukkit {
         return server.getAllowNether();
     }
 
+    /**
+     * Gets the server resource pack uri, or empty string if not specified.
+     *
+     * @return the server resource pack uri, otherwise empty string
+     */
+    @NotNull
+    public static String getResourcePack() {
+        return server.getResourcePack();
+    }
+
+    /**
+     * Gets the SHA-1 digest of the server resource pack, or empty string if
+     * not specified.
+     *
+     * @return the SHA-1 digest of the server resource pack, otherwise empty
+     *     string
+     */
+    @NotNull
+    public static String getResourcePackHash() {
+        return server.getResourcePackHash();
+    }
+
+    /**
+     * Gets the custom prompt message to be shown when the server resource
+     * pack is required, or empty string if not specified.
+     *
+     * @return the custom prompt message to be shown when the server resource,
+     *     otherwise empty string
+     */
+    @NotNull
+    public static String getResourcePackPrompt() {
+        return server.getResourcePackPrompt();
+    }
+
+    /**
+     * Gets whether the server resource pack is enforced.
+     *
+     * @return whether the server resource pack is enforced
+     */
+    public static boolean isResourcePackRequired() {
+        return server.isResourcePackRequired();
+    }
+
     /**
      * Gets whether this server has a whitelist or not.
      *

paper-api/src/main/java/org/bukkit/Server.java

@@ -202,6 +202,41 @@ public interface Server extends PluginMessageRecipient {
      */
     public boolean getAllowNether();
 
+    /**
+     * Gets the server resource pack uri, or empty string if not specified.
+     *
+     * @return the server resource pack uri, otherwise empty string
+     */
+    @NotNull
+    public String getResourcePack();
+
+    /**
+     * Gets the SHA-1 digest of the server resource pack, or empty string if
+     * not specified.
+     *
+     * @return the SHA-1 digest of the server resource pack, otherwise empty
+     *     string
+     */
+    @NotNull
+    public String getResourcePackHash();
+
+    /**
+     * Gets the custom prompt message to be shown when the server resource
+     * pack is required, or empty string if not specified.
+     *
+     * @return the custom prompt message to be shown when the server resource,
+     *     otherwise empty string
+     */
+    @NotNull
+    public String getResourcePackPrompt();
+
+    /**
+     * Gets whether the server resource pack is enforced.
+     *
+     * @return whether the server resource pack is enforced
+     */
+    public boolean isResourcePackRequired();
+
     /**
      * Gets whether this server has a whitelist or not.
      *

paper-api/src/main/java/org/bukkit/entity/Player.java

@@ -909,7 +909,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * <li>There is no concept of resetting resource packs back to default
      *     within Minecraft, so players will have to relog to do so or you
      *     have to send an empty pack.
-     * <li>The request is send with "null" as the hash. This might result
+     * <li>The request is send with empty string as the hash. This might result
      *     in newer versions not loading the pack correctly.
      * </ul>
      *
@@ -929,9 +929,13 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * in the background, and will automatically switch to it once the
      * download is complete. If the client has downloaded and cached a
      * resource pack with the same hash in the past it will not download but
-     * directly apply the cached pack. When this request is sent for the very
+     * directly apply the cached pack. If the hash is null and the client has
-     * first time from a given server, the client will first display a
+     * downloaded and cached the same resource pack in the past, it will
-     * confirmation GUI to the player before proceeding with the download.
+     * perform a file size check against the response content to determine if
+     * the resource pack has changed and needs to be downloaded again. When
+     * this request is sent for the very first time from a given server, the
+     * client will first display a confirmation GUI to the player before
+     * proceeding with the download.
      * <p>
      * Notes:
      * <ul>
@@ -942,6 +946,9 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * <li>There is no concept of resetting resource packs back to default
      *     within Minecraft, so players will have to relog to do so or you
      *     have to send an empty pack.
+     * <li>The request is sent with empty string as the hash when the hash is
+     *     not provided. This might result in newer versions not loading the
+     *     pack correctly.
      * </ul>
      *
      * @param url The URL from which the client will download the resource
@@ -953,11 +960,145 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      * @throws IllegalArgumentException Thrown if the URL is null.
      * @throws IllegalArgumentException Thrown if the URL is too long. The
      *     length restriction is an implementation specific arbitrary value.
-     * @throws IllegalArgumentException Thrown if the hash is null.
      * @throws IllegalArgumentException Thrown if the hash is not 20 bytes
      *     long.
      */
-    public void setResourcePack(@NotNull String url, @NotNull byte[] hash);
+    public void setResourcePack(@NotNull String url, @Nullable byte[] hash);
+
+    /**
+     * Request that the player's client download and switch resource packs.
+     * <p>
+     * The player's client will download the new resource pack asynchronously
+     * in the background, and will automatically switch to it once the
+     * download is complete. If the client has downloaded and cached a
+     * resource pack with the same hash in the past it will not download but
+     * directly apply the cached pack. If the hash is null and the client has
+     * downloaded and cached the same resource pack in the past, it will
+     * perform a file size check against the response content to determine if
+     * the resource pack has changed and needs to be downloaded again. When
+     * this request is sent for the very first time from a given server, the
+     * client will first display a confirmation GUI to the player before
+     * proceeding with the download.
+     * <p>
+     * Notes:
+     * <ul>
+     * <li>Players can disable server resources on their client, in which
+     *     case this method will have no affect on them. Use the
+     *     {@link PlayerResourcePackStatusEvent} to figure out whether or not
+     *     the player loaded the pack!
+     * <li>There is no concept of resetting resource packs back to default
+     *     within Minecraft, so players will have to relog to do so or you
+     *     have to send an empty pack.
+     * <li>The request is sent with empty string as the hash when the hash is
+     *     not provided. This might result in newer versions not loading the
+     *     pack correctly.
+     * </ul>
+     *
+     * @param url The URL from which the client will download the resource
+     *     pack. The string must contain only US-ASCII characters and should
+     *     be encoded as per RFC 1738.
+     * @param hash The sha1 hash sum of the resource pack file which is used
+     *     to apply a cached version of the pack directly without downloading
+     *     if it is available. Hast to be 20 bytes long!
+     * @param prompt The optional custom prompt message to be shown to client.
+     * @throws IllegalArgumentException Thrown if the URL is null.
+     * @throws IllegalArgumentException Thrown if the URL is too long. The
+     *     length restriction is an implementation specific arbitrary value.
+     * @throws IllegalArgumentException Thrown if the hash is not 20 bytes
+     *     long.
+     */
+    public void setResourcePack(@NotNull String url, @Nullable byte[] hash, @Nullable String prompt);
+
+    /**
+     * Request that the player's client download and switch resource packs.
+     * <p>
+     * The player's client will download the new resource pack asynchronously
+     * in the background, and will automatically switch to it once the
+     * download is complete. If the client has downloaded and cached a
+     * resource pack with the same hash in the past it will not download but
+     * directly apply the cached pack. If the hash is null and the client has
+     * downloaded and cached the same resource pack in the past, it will
+     * perform a file size check against the response content to determine if
+     * the resource pack has changed and needs to be downloaded again. When
+     * this request is sent for the very first time from a given server, the
+     * client will first display a confirmation GUI to the player before
+     * proceeding with the download.
+     * <p>
+     * Notes:
+     * <ul>
+     * <li>Players can disable server resources on their client, in which
+     *     case this method will have no affect on them. Use the
+     *     {@link PlayerResourcePackStatusEvent} to figure out whether or not
+     *     the player loaded the pack!
+     * <li>There is no concept of resetting resource packs back to default
+     *     within Minecraft, so players will have to relog to do so or you
+     *     have to send an empty pack.
+     * <li>The request is sent with empty string as the hash when the hash is
+     *     not provided. This might result in newer versions not loading the
+     *     pack correctly.
+     * </ul>
+     *
+     * @param url The URL from which the client will download the resource
+     *     pack. The string must contain only US-ASCII characters and should
+     *     be encoded as per RFC 1738.
+     * @param hash The sha1 hash sum of the resource pack file which is used
+     *     to apply a cached version of the pack directly without downloading
+     *     if it is available. Hast to be 20 bytes long!
+     * @param force If true, the client will be disconnected from the server
+     *     when it declines to use the resource pack.
+     * @throws IllegalArgumentException Thrown if the URL is null.
+     * @throws IllegalArgumentException Thrown if the URL is too long. The
+     *     length restriction is an implementation specific arbitrary value.
+     * @throws IllegalArgumentException Thrown if the hash is not 20 bytes
+     *     long.
+     */
+    public void setResourcePack(@NotNull String url, @Nullable byte[] hash, boolean force);
+
+    /**
+     * Request that the player's client download and switch resource packs.
+     * <p>
+     * The player's client will download the new resource pack asynchronously
+     * in the background, and will automatically switch to it once the
+     * download is complete. If the client has downloaded and cached a
+     * resource pack with the same hash in the past it will not download but
+     * directly apply the cached pack. If the hash is null and the client has
+     * downloaded and cached the same resource pack in the past, it will
+     * perform a file size check against the response content to determine if
+     * the resource pack has changed and needs to be downloaded again. When
+     * this request is sent for the very first time from a given server, the
+     * client will first display a confirmation GUI to the player before
+     * proceeding with the download.
+     * <p>
+     * Notes:
+     * <ul>
+     * <li>Players can disable server resources on their client, in which
+     *     case this method will have no affect on them. Use the
+     *     {@link PlayerResourcePackStatusEvent} to figure out whether or not
+     *     the player loaded the pack!
+     * <li>There is no concept of resetting resource packs back to default
+     *     within Minecraft, so players will have to relog to do so or you
+     *     have to send an empty pack.
+     * <li>The request is sent with empty string as the hash when the hash is
+     *     not provided. This might result in newer versions not loading the
+     *     pack correctly.
+     * </ul>
+     *
+     * @param url The URL from which the client will download the resource
+     *     pack. The string must contain only US-ASCII characters and should
+     *     be encoded as per RFC 1738.
+     * @param hash The sha1 hash sum of the resource pack file which is used
+     *     to apply a cached version of the pack directly without downloading
+     *     if it is available. Hast to be 20 bytes long!
+     * @param prompt The optional custom prompt message to be shown to client.
+     * @param force If true, the client will be disconnected from the server
+     *     when it declines to use the resource pack.
+     * @throws IllegalArgumentException Thrown if the URL is null.
+     * @throws IllegalArgumentException Thrown if the URL is too long. The
+     *     length restriction is an implementation specific arbitrary value.
+     * @throws IllegalArgumentException Thrown if the hash is not 20 bytes
+     *     long.
+     */
+    public void setResourcePack(@NotNull String url, @Nullable byte[] hash, @Nullable String prompt, boolean force);
 
     /**
      * Gets the Scoreboard displayed to this player