SPIGOT-7530, #948: Improve Resource Pack API with new 1.20.3 functionality

By: Doc <nachito94@msn.com>

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

@@ -44,6 +44,7 @@ import org.bukkit.inventory.meta.ItemMeta;
 import org.bukkit.loot.LootTable;
 import org.bukkit.map.MapView;
 import org.bukkit.packs.DataPackManager;
+import org.bukkit.packs.ResourcePack;
 import org.bukkit.permissions.Permissible;
 import org.bukkit.plugin.PluginManager;
 import org.bukkit.plugin.ServicesManager;
@@ -280,6 +281,16 @@ public final class Bukkit {
         return server.getDataPackManager();
     }
 
+    /**
+     * Gets the resource pack configured to be sent to clients by the server.
+     *
+     * @return the resource pack
+     */
+    @Nullable
+    public static ResourcePack getServerResourcePack() {
+        return server.getServerResourcePack();
+    }
+
     /**
      * Get the ServerTick Manager.
      *

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

@@ -44,6 +44,7 @@ import org.bukkit.inventory.meta.ItemMeta;
 import org.bukkit.loot.LootTable;
 import org.bukkit.map.MapView;
 import org.bukkit.packs.DataPackManager;
+import org.bukkit.packs.ResourcePack;
 import org.bukkit.permissions.Permissible;
 import org.bukkit.plugin.PluginManager;
 import org.bukkit.plugin.ServicesManager;
@@ -247,6 +248,14 @@ public interface Server extends PluginMessageRecipient {
     @NotNull
     public ServerTickManager getServerTickManager();
 
+    /**
+     * Gets the resource pack configured to be sent to clients by the server.
+     *
+     * @return the resource pack
+     */
+    @Nullable
+    public ResourcePack getServerResourcePack();
+
     /**
      * Gets the server resource pack uri, or empty string if not specified.
      *

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

@@ -1610,6 +1610,52 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      */
     public void setResourcePack(@NotNull UUID id, @NotNull String url, @Nullable byte[] hash, @Nullable String prompt, boolean force);
 
+    /**
+     * Request that the player's client download and include another resource pack.
+     * <p>
+     * The player's client will download the new resource pack asynchronously
+     * in the background, and will automatically add 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>To remove a resource pack you can use
+     *     {@link #removeResourcePack(UUID)} or {@link #removeResourcePacks()}.
+     * <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 id Unique resource pack ID.
+     * @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 addResourcePack(@NotNull UUID id, @NotNull String url, @Nullable byte[] hash, @Nullable String prompt, boolean force);
+
     /**
      * Request that the player's client remove a resource pack sent by the
      * server.

paper-api/src/main/java/org/bukkit/packs/ResourcePack.java

@@ -0,0 +1,54 @@
+package org.bukkit.packs;
+
+import java.util.UUID;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Represents a resource pack.
+ *
+ * @see <a href="https://minecraft.wiki/w/Resource_pack">Minecraft wiki</a>
+ */
+@ApiStatus.Experimental
+public interface ResourcePack {
+
+    /**
+     * Gets the id of the resource pack.
+     *
+     * @return the id
+     */
+    @NotNull
+    public UUID getId();
+
+    /**
+     * Gets the url of the resource pack.
+     *
+     * @return the url
+     */
+    @NotNull
+    public String getUrl();
+
+    /**
+     * Gets the hash of the resource pack.
+     *
+     * @return the hash
+     */
+    @Nullable
+    public String getHash();
+
+    /**
+     * Gets the prompt to show of the resource pack.
+     *
+     * @return the prompt
+     */
+    @Nullable
+    public String getPrompt();
+
+    /**
+     * Gets if the resource pack is required by the server.
+     *
+     * @return True if is required
+     */
+    public boolean isRequired();
+}