From df1d30a2bb169d2b3ea99e8a13b473be1316878d Mon Sep 17 00:00:00 2001 From: yusshu Date: Wed, 18 Oct 2023 01:09:19 -0500 Subject: [PATCH 1/2] feat: add ResourcePackRequest page --- source/index.rst | 1 + source/resource-pack-request.rst | 45 ++++++++++++++++++++++++++++++++ 2 files changed, 46 insertions(+) create mode 100644 source/resource-pack-request.rst diff --git a/source/index.rst b/source/index.rst index 0d8b97c..8cb3384 100644 --- a/source/index.rst +++ b/source/index.rst @@ -37,6 +37,7 @@ There are many community-supported libraries that extend the capabilities of Adv title book tablist + resource-pack-request minimessage/index platform/index diff --git a/source/resource-pack-request.rst b/source/resource-pack-request.rst new file mode 100644 index 0000000..71aed23 --- /dev/null +++ b/source/resource-pack-request.rst @@ -0,0 +1,45 @@ +===================== +Resource Pack Request +===================== + +Adventure contains an API to request an Audience to download a resource pack. + +Constructing a Resource Pack Request +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Resource Pack Requests are composed of: + * A URI to the resource pack ZIP file + * A string, containing the SHA-1 hash of the resource pack ZIP file + * A boolean, determining whether the resource pack is required to continue playing on the server or not + * An optional component used for the prompt + + +**Examples:** + +.. code:: java + + public void sendResourcePack(final @NonNull Audience target) { + // Build a required resource pack request + final ResourcePackRequest serverPackRequest = ResourcePackRequest.resourcePackRequest() + .uri(URI.create("https://example.com/resourcepack.zip")) + .hash("2849ace6aa689a8c610907a41c03537310949294") + .required(true) + .prompt(Component.text("Please download the resource pack!")) + .build(); + + // Send the resource pack request to the target audience + target.sendResourcePack(serverPackRequest); + } + + public void sendOptionalResourcePack(final @NonNull Audience target) { + // Build an optional resource pack request + final ResourcePackRequest optionalPackRequest = ResourcePackRequest.resourcePackRequest() + .uri(URI.create("https://download.example.com/optionalresourcepack.zip")) + .hash("74041e5b4b3fb4d30c48787b1e5d087b4dd1e57e") + .required(false) + .prompt(Component.text("You can download this resource pack if you want!")) + .build(); + + // Send the resource pack request to the target audience + target.sendResourcePack(optionalPackRequest); + } From 46f1d4c75ff4725c6daa2f820917caf241d53a2d Mon Sep 17 00:00:00 2001 From: zml Date: Sat, 1 Jun 2024 18:07:50 -0700 Subject: [PATCH 2/2] Update for resource pack api changes --- source/index.rst | 2 +- source/resource-pack-request.rst | 45 ------------------- source/resource-pack.rst | 75 ++++++++++++++++++++++++++++++++ 3 files changed, 76 insertions(+), 46 deletions(-) delete mode 100644 source/resource-pack-request.rst create mode 100644 source/resource-pack.rst diff --git a/source/index.rst b/source/index.rst index 8cb3384..5fe9bd9 100644 --- a/source/index.rst +++ b/source/index.rst @@ -37,7 +37,7 @@ There are many community-supported libraries that extend the capabilities of Adv title book tablist - resource-pack-request + resource-pack minimessage/index platform/index diff --git a/source/resource-pack-request.rst b/source/resource-pack-request.rst deleted file mode 100644 index 71aed23..0000000 --- a/source/resource-pack-request.rst +++ /dev/null @@ -1,45 +0,0 @@ -===================== -Resource Pack Request -===================== - -Adventure contains an API to request an Audience to download a resource pack. - -Constructing a Resource Pack Request -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Resource Pack Requests are composed of: - * A URI to the resource pack ZIP file - * A string, containing the SHA-1 hash of the resource pack ZIP file - * A boolean, determining whether the resource pack is required to continue playing on the server or not - * An optional component used for the prompt - - -**Examples:** - -.. code:: java - - public void sendResourcePack(final @NonNull Audience target) { - // Build a required resource pack request - final ResourcePackRequest serverPackRequest = ResourcePackRequest.resourcePackRequest() - .uri(URI.create("https://example.com/resourcepack.zip")) - .hash("2849ace6aa689a8c610907a41c03537310949294") - .required(true) - .prompt(Component.text("Please download the resource pack!")) - .build(); - - // Send the resource pack request to the target audience - target.sendResourcePack(serverPackRequest); - } - - public void sendOptionalResourcePack(final @NonNull Audience target) { - // Build an optional resource pack request - final ResourcePackRequest optionalPackRequest = ResourcePackRequest.resourcePackRequest() - .uri(URI.create("https://download.example.com/optionalresourcepack.zip")) - .hash("74041e5b4b3fb4d30c48787b1e5d087b4dd1e57e") - .required(false) - .prompt(Component.text("You can download this resource pack if you want!")) - .build(); - - // Send the resource pack request to the target audience - target.sendResourcePack(optionalPackRequest); - } diff --git a/source/resource-pack.rst b/source/resource-pack.rst new file mode 100644 index 0000000..bc52c85 --- /dev/null +++ b/source/resource-pack.rst @@ -0,0 +1,75 @@ +============== +Resource Packs +============== + +On top of the resource packs controlled by each player on their client, the game allows servers to send resource pack URLs to clients that the players can choose to accept. This allows servers to provide customized styling. + +Initially this just allowed sending a single resource pack, but starting with *Minecraft 1.20.3* the server can send multiple resource packs to be stacked, and if needed removed individually. + +Sending Resource Packs +^^^^^^^^^^^^^^^^^^^^^^ + +A resource pack is identified by: + * its UUID + * a URI to the resource pack ZIP file + * the SHA-1 hash of the resource pack ZIP file as a hex string + +This is referred to as ``ResourcePackInfo``. + +For every batch of resource packs being sent, a ``ResourcePackRequest``, there is: + * one or more resource packs + * a callback to perform actions based on the responses from the client + * a toggle for whether to replace any existing server-provided resource packs, or stack the most recent packs on top + * whether these resource packs are required + * a prompt to display to the user if they have not yet chosen whether to allow server resource packs + + +Examples +-------- + +Send a single resource pack to a client that is required, with a UUID computed based on its name. + +.. code:: java + + private static final ResourcePackInfo PACK_INFO = ResourcePackInfo.resourcePackInfo() + .uri(URI.create("https://example.com/resourcepack.zip")) + .hash("2849ace6aa689a8c610907a41c03537310949294") + .build(); + + public void sendResourcePack(final @NonNull Audience target) { + final ResourcePackRequest request = ResourcePackRequest.resourcePackRequest() + .packs(PACK_INFO) + .required(true) + .prompt(Component.text("Please download the resource pack!")) + .required(true) + .build(); + + // Send the resource pack request to the target audience + target.sendResourcePacks(request); + } + + public void sendOptionalResourcePack(final @NonNull Audience target) { + final ResourcePackRequest request = ResourcePackRequest.resourcePackRequest() + .packs(PACK_INFO) + .required(true) + .prompt(Component.text("Please download the resource pack!")) + .required(false) + .build(); + + // Send the resource pack request to the target audience + target.sendResourcePacks(request); + } + +Callbacks +--------- + +The callback function allows servers to respond to pack download feedback sent by the client. Newer versions of the game provide more information about different phases, but any version will provide basic status info about download and application. Keep in mind that the responses are entirely driven by the client, so modded clients may send incorrect information (for example, saying a required resource pack has been applied when it has not), none at all, or even nonsensical information (status updates after a terminal update has been received). Any action taken based on a callback should therefore be defensively designed to cope with client creativity. + +The audience provided in the callback aims to be the exact same audience the resource pack was sent to in the case of wrapping audiences, re-wrapping any underlying returned value where necessary. + +Removing Resource Packs +^^^^^^^^^^^^^^^^^^^^^^^ + +Resource packs can be removed, either some quantity at a time with :java:`Audience.removeResourcePacks()`, or all at once with :java:`Audience.clearResourcePacks()`. + +The removal methods have multiple overloads, allowing removal by a bare UUID, or by reusing the data structures used for applying resource packs.