From a44ad8b54a29b9d5feaba0c393334d2ae8dbe51a Mon Sep 17 00:00:00 2001 From: Bukkit/Spigot Date: Sat, 18 Dec 2021 11:46:20 +1100 Subject: [PATCH] SPIGOT-6789: Improve resource pack related API By: Patrick Choe --- .../src/main/java/org/bukkit/Bukkit.java | 43 +++++ .../src/main/java/org/bukkit/Server.java | 35 ++++ .../main/java/org/bukkit/entity/Player.java | 153 +++++++++++++++++- 3 files changed, 225 insertions(+), 6 deletions(-) diff --git a/paper-api/src/main/java/org/bukkit/Bukkit.java b/paper-api/src/main/java/org/bukkit/Bukkit.java index 3b150b9623..47f1ff8f83 100644 --- a/paper-api/src/main/java/org/bukkit/Bukkit.java +++ b/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. * diff --git a/paper-api/src/main/java/org/bukkit/Server.java b/paper-api/src/main/java/org/bukkit/Server.java index 7d2ba1f5e4..8a6a3867ac 100644 --- a/paper-api/src/main/java/org/bukkit/Server.java +++ b/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. * diff --git a/paper-api/src/main/java/org/bukkit/entity/Player.java b/paper-api/src/main/java/org/bukkit/entity/Player.java index a9b650834b..73f9118d51 100644 --- a/paper-api/src/main/java/org/bukkit/entity/Player.java +++ b/paper-api/src/main/java/org/bukkit/entity/Player.java @@ -909,7 +909,7 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM *
  • 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. - *
  • The request is send with "null" as the hash. This might result + *
  • The request is send with empty string as the hash. This might result * in newer versions not loading the pack correctly. * * @@ -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 - * first time from a given server, the client will first display a - * confirmation GUI to the player before proceeding with the download. + * 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. *

    * Notes: *

      @@ -942,6 +946,9 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM *
    • 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. + *
    • 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. *
    * * @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. + *

    + * 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. + *

    + * Notes: + *

      + *
    • 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! + *
    • 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. + *
    • 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. + *
    + * + * @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. + *

    + * 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. + *

    + * Notes: + *

      + *
    • 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! + *
    • 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. + *
    • 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. + *
    + * + * @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. + *

    + * 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. + *

    + * Notes: + *

      + *
    • 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! + *
    • 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. + *
    • 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. + *
    + * + * @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