feat(api): Expand the supported resource pack operations for 1.20.3

api/src/main/java/net/kyori/adventure/audience/Audience.java

@@ -25,6 +25,7 @@
 
 import java.util.Arrays;
 import java.util.Objects;
+import java.util.UUID;
 import java.util.function.Consumer;
 import java.util.function.Predicate;
 import java.util.stream.Collector;
@@ -36,6 +37,7 @@
 import net.kyori.adventure.identity.Identity;
 import net.kyori.adventure.inventory.Book;
 import net.kyori.adventure.pointer.Pointered;
+import net.kyori.adventure.resource.ResourcePackCallback;
 import net.kyori.adventure.resource.ResourcePackRequest;
 import net.kyori.adventure.resource.ResourcePackRequestLike;
 import net.kyori.adventure.sound.Sound;
@@ -708,24 +710,192 @@ default void openBook(final @NotNull Book book) {
   // ------------------------
 
   /**
-   * Sends a resource pack request to this audience.
+   * Sends resource pack requests to this audience, replacing any existing resource packs that might be present.
+   *
+   * <p>Multiple resource packs are only supported since 1.20.3. On older versions, only the first pack will be sent.</p>
+   *
+   * @param request the first resource pack request
+   * @param others other requests
+   * @see ResourcePackRequest
+   * @since 4.15.0
+   */
+  @SuppressWarnings("checkstyle:MethodName")
+  @ForwardingAudienceOverrideNotRequired
+  default void setResourcePack(final @NotNull ResourcePackRequestLike request, final @NotNull ResourcePackRequestLike@NotNull... others) {
+    final ResourcePackRequest[] otherReqs = new ResourcePackRequest[others.length];
+    for (int i = 0; i < others.length; i++) {
+      otherReqs[i] = others[i].asResourcePackRequest();
+    }
+    this.setResourcePack(request.asResourcePackRequest(), otherReqs);
+  }
+
+  /**
+   * Sends resource pack requests to this audience, replacing any resource packs that might be present.
+   *
+   * <p>Multiple resource packs are only supported since 1.20.3. On older versions, only the first pack will be sent.</p>
    *
    * @param request the resource pack request
+   * @param others other requests
    * @see ResourcePackRequest
    * @since 4.15.0
    */
+  @SuppressWarnings("checkstyle:MethodName")
+  default void setResourcePack(final @NotNull ResourcePackRequest request, final @NotNull ResourcePackRequest@NotNull... others) {
+  }
+
+  /**
+   * Sends resource pack requests to this audience, replacing any existing resource packs that might be present.
+   *
+   * <p>Multiple resource packs are only supported since 1.20.3. On older versions, only the first pack will be sent.</p>
+   *
+   * @param cb a callback to be executed when resource pack events associated with this application are received
+   * @param request the first resource pack request
+   * @param others other requests
+   * @see ResourcePackRequest
+   * @since 4.15.0
+   */
+  @SuppressWarnings("checkstyle:MethodName")
   @ForwardingAudienceOverrideNotRequired
-  default void sendResourcePack(final @NotNull ResourcePackRequestLike request) {
-    this.sendResourcePack(request.asResourcePackRequest());
+  default void setResourcePack(final @NotNull ResourcePackCallback cb, final @NotNull ResourcePackRequestLike request, final @NotNull ResourcePackRequestLike@NotNull... others) {
+    final ResourcePackRequest[] otherReqs = new ResourcePackRequest[others.length];
+    for (int i = 0; i < others.length; i++) {
+      otherReqs[i] = others[i].asResourcePackRequest();
+    }
+    this.setResourcePack(cb, request.asResourcePackRequest(), otherReqs);
   }
 
   /**
-   * Sends a resource pack request to this audience.
+   * Sends resource pack requests to this audience, replacing any resource packs that might be present.
+   *
+   * <p>Multiple resource packs are only supported since 1.20.3. On older versions, only the first pack will be sent.</p>
    *
+   * @param cb a callback to be executed when resource pack events associated with this application are received
    * @param request the resource pack request
+   * @param others other requests
    * @see ResourcePackRequest
    * @since 4.15.0
    */
-  default void sendResourcePack(final @NotNull ResourcePackRequest request) {
+  @SuppressWarnings("checkstyle:MethodName")
+  default void setResourcePack(final @NotNull ResourcePackCallback cb, final @NotNull ResourcePackRequest request, final @NotNull ResourcePackRequest@NotNull... others) {
+  }
+
+  /**
+   * Sends resource pack requests to this audience, adding to any existing resource packs that might be present.
+   *
+   * <p>Multiple resource packs are only supported since 1.20.3. On older versions, this behaves identically to {@link #setResourcePack(ResourcePackRequestLike, ResourcePackRequestLike...)}.</p>
+   *
+   * @param request the resource pack request
+   * @param others other requests
+   * @see ResourcePackRequest
+   * @since 4.15.0
+   */
+  @ForwardingAudienceOverrideNotRequired
+  default void sendResourcePack(final @NotNull ResourcePackRequestLike request, final @NotNull ResourcePackRequestLike@NotNull... others) {
+    final ResourcePackRequest[] otherReqs = new ResourcePackRequest[others.length];
+    for (int i = 0; i < others.length; i++) {
+      otherReqs[i] = others[i].asResourcePackRequest();
+    }
+    this.sendResourcePack(request.asResourcePackRequest(), otherReqs);
+  }
+
+  /**
+   * Sends resource pack requests to this audience, adding to any existing resource packs that might be present.
+   *
+   * <p>Multiple resource packs are only supported since 1.20.3. On older versions, this behaves identically to {@link #setResourcePack(ResourcePackRequest, ResourcePackRequest...)}.</p>
+   *
+   * @param request the resource pack request
+   * @param others other requests
+   * @see ResourcePackRequest
+   * @since 4.15.0
+   */
+  default void sendResourcePack(final @NotNull ResourcePackRequest request, final @NotNull ResourcePackRequest@NotNull... others) {
+  }
+
+  /**
+   * Sends resource pack requests to this audience, adding to any existing resource packs that might be present.
+   *
+   * <p>Multiple resource packs are only supported since 1.20.3. On older versions, this behaves identically to {@link #setResourcePack(ResourcePackRequestLike, ResourcePackRequestLike...)}.</p>
+   *
+   * @param cb a callback to be executed when resource pack events associated with this application are received
+   * @param request the resource pack request
+   * @param others other requests
+   * @see ResourcePackRequest
+   * @since 4.15.0
+   */
+  @ForwardingAudienceOverrideNotRequired
+  default void sendResourcePack(final @NotNull ResourcePackCallback cb, final @NotNull ResourcePackRequestLike request, final @NotNull ResourcePackRequestLike@NotNull... others) {
+    final ResourcePackRequest[] otherReqs = new ResourcePackRequest[others.length];
+    for (int i = 0; i < others.length; i++) {
+      otherReqs[i] = others[i].asResourcePackRequest();
+    }
+    this.sendResourcePack(cb, request.asResourcePackRequest(), otherReqs);
+  }
+
+  /**
+   * Sends resource pack requests to this audience, adding to any existing resource packs that might be present.
+   *
+   * <p>Multiple resource packs are only supported since 1.20.3. On older versions, this behaves identically to {@link #setResourcePack(ResourcePackRequest, ResourcePackRequest...)}.</p>
+   *
+   * @param cb a callback to be executed when resource pack events associated with this application are received
+   * @param request the resource pack request
+   * @param others other requests
+   * @see ResourcePackRequest
+   * @since 4.15.0
+   */
+  default void sendResourcePack(final @NotNull ResourcePackCallback cb, final @NotNull ResourcePackRequest request, final @NotNull ResourcePackRequest@NotNull... others) {
+  }
+
+  /**
+   * Clear resource packs with the IDs used in the provided requests if they are present.
+   *
+   * @param request the first request used to originally apply the pack
+   * @param others requests for other packs that should be removed
+   * @since 4.15.0
+   * @sinceMinecraft 1.20.3
+   */
+  @ForwardingAudienceOverrideNotRequired
+  default void removeResourcePack(final @NotNull ResourcePackRequestLike request, final @NotNull ResourcePackRequestLike@NotNull... others) {
+    final ResourcePackRequest[] otherReqs = new ResourcePackRequest[others.length];
+    for (int i = 0; i < others.length; i++) {
+      otherReqs[i] = others[i].asResourcePackRequest();
+    }
+    this.removeResourcePack(request.asResourcePackRequest(), otherReqs);
+  }
+
+  /**
+   * Clear resource packs with the IDs used in the provided requests if they are present.
+   * Clear a resource pack with id {@code id} if it is present for a certain user.
+   *
+   * @param request the first request used to originally apply the pack
+   * @param others requests for other packs that should be removed
+   * @since 4.15.0
+   * @sinceMinecraft 1.20.3
+   */
+  @ForwardingAudienceOverrideNotRequired
+  default void removeResourcePack(final @NotNull ResourcePackRequest request, final @NotNull ResourcePackRequest@NotNull... others) {
+    final UUID[] otherIds = new UUID[others.length];
+    for (int i = 0; i < others.length; i++) {
+      otherIds[i] = others[i].id();
+    }
+    this.removeResourcePack(request.id(), otherIds);
+  }
+
+  /**
+   * Clear resource packs with the provided ids if they are present.
+   *
+   * @param id the id
+   * @param others the ids of any additional resource packs
+   * @since 4.15.0
+   * @sinceMinecraft 1.20.3
+   */
+  default void removeResourcePack(final @NotNull UUID id, final @NotNull UUID@NotNull... others) {
+  }
+
+  /**
+   * Clear all server-provided resource packs that have been sent to this user.
+   *
+   * @since 4.15.0
+   */
+  default void clearResourcePacks() {
   }
 }

api/src/main/java/net/kyori/adventure/audience/EmptyAudience.java

@@ -33,6 +33,7 @@
 import net.kyori.adventure.identity.Identity;
 import net.kyori.adventure.inventory.Book;
 import net.kyori.adventure.pointer.Pointer;
+import net.kyori.adventure.resource.ResourcePackRequest;
 import net.kyori.adventure.resource.ResourcePackRequestLike;
 import net.kyori.adventure.text.Component;
 import net.kyori.adventure.text.ComponentLike;
@@ -120,7 +121,19 @@ public void openBook(final Book.@NotNull Builder book) {
   }
 
   @Override
-  public void sendResourcePack(final @NotNull ResourcePackRequestLike request) {
+  public void sendResourcePack(final @NotNull ResourcePackRequestLike request, final @NotNull ResourcePackRequestLike@NotNull... others) {
+  }
+
+  @Override
+  public void setResourcePack(final @NotNull ResourcePackRequestLike request, final @NotNull ResourcePackRequestLike @NotNull ... others) {
+  }
+
+  @Override
+  public void removeResourcePack(final @NotNull ResourcePackRequestLike request, final @NotNull ResourcePackRequestLike@NotNull... others) {
+  }
+
+  @Override
+  public void removeResourcePack(final @NotNull ResourcePackRequest request, final @NotNull ResourcePackRequest @NotNull ... others) {
   }
 
   @Override

api/src/main/java/net/kyori/adventure/audience/ForwardingAudience.java

@@ -27,6 +27,7 @@
 import java.util.Collections;
 import java.util.List;
 import java.util.Optional;
+import java.util.UUID;
 import java.util.function.Consumer;
 import java.util.function.Predicate;
 import java.util.function.Supplier;
@@ -38,6 +39,7 @@
 import net.kyori.adventure.inventory.Book;
 import net.kyori.adventure.pointer.Pointer;
 import net.kyori.adventure.pointer.Pointers;
+import net.kyori.adventure.resource.ResourcePackCallback;
 import net.kyori.adventure.resource.ResourcePackRequest;
 import net.kyori.adventure.sound.Sound;
 import net.kyori.adventure.sound.SoundStop;
@@ -201,8 +203,33 @@ default void openBook(final @NotNull Book book) {
   }
 
   @Override
-  default void sendResourcePack(final @NotNull ResourcePackRequest request) {
-    for (final Audience audience : this.audiences()) audience.sendResourcePack(request);
+  default void setResourcePack(final @NotNull ResourcePackRequest request, final @NotNull ResourcePackRequest@NotNull... others) {
+    for (final Audience audience : this.audiences()) audience.setResourcePack(request, others);
+  }
+
+  @Override
+  default void setResourcePack(final @NotNull ResourcePackCallback cb, final @NotNull ResourcePackRequest request, final @NotNull ResourcePackRequest @NotNull ... others) {
+    for (final Audience audience : this.audiences()) audience.setResourcePack(cb, request, others);
+  }
+
+  @Override
+  default void sendResourcePack(final @NotNull ResourcePackRequest request, final @NotNull ResourcePackRequest@NotNull... others) {
+    for (final Audience audience : this.audiences()) audience.sendResourcePack(request, others);
+  }
+
+  @Override
+  default void sendResourcePack(final @NotNull ResourcePackCallback cb, final @NotNull ResourcePackRequest request, final @NotNull ResourcePackRequest@NotNull ... others) {
+    for (final Audience audience : this.audiences()) audience.sendResourcePack(cb, request, others);
+  }
+
+  @Override
+  default void removeResourcePack(final @NotNull UUID id, final @NotNull UUID @NotNull ... others) {
+    for (final Audience audience : this.audiences()) audience.removeResourcePack(id, others);
+  }
+
+  @Override
+  default void clearResourcePacks() {
+    for (final Audience audience : this.audiences()) audience.clearResourcePacks();
   }
 
   /**
@@ -369,8 +396,33 @@ default void openBook(final @NotNull Book book) {
     }
 
     @Override
-    default void sendResourcePack(final @NotNull ResourcePackRequest request) {
-      this.audience().sendResourcePack(request);
+    default void setResourcePack(final @NotNull ResourcePackRequest request, final @NotNull ResourcePackRequest... others) {
+      this.audience().setResourcePack(request, others);
+    }
+
+    @Override
+    default void setResourcePack(final @NotNull ResourcePackCallback cb, final @NotNull ResourcePackRequest request, final @NotNull ResourcePackRequest @NotNull ... others) {
+      this.audience().setResourcePack((uuid, status, audience) -> cb.packEventReceived(uuid, status, this), request, others);
+    }
+
+    @Override
+    default void sendResourcePack(final @NotNull ResourcePackRequest request, final @NotNull ResourcePackRequest@NotNull... others) {
+      this.audience().sendResourcePack(request, others);
+    }
+
+    @Override
+    default void sendResourcePack(final @NotNull ResourcePackCallback cb, final @NotNull ResourcePackRequest request, final @NotNull ResourcePackRequest @NotNull ... others) {
+      this.audience().sendResourcePack((uuid, status, audience) -> cb.packEventReceived(uuid, status, this), request, others);
+    }
+
+    @Override
+    default void removeResourcePack(final @NotNull UUID id, final @NotNull UUID @NotNull ... others) {
+      this.audience().removeResourcePack(id, others);
+    }
+
+    @Override
+    default void clearResourcePacks() {
+      this.audience().clearResourcePacks();
     }
   }
 }

api/src/main/java/net/kyori/adventure/resource/ResourcePackCallback.java

@@ -0,0 +1,68 @@
+/*
+ * This file is part of adventure, licensed under the MIT License.
+ *
+ * Copyright (c) 2017-2023 KyoriPowered
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package net.kyori.adventure.resource;
+
+import java.util.UUID;
+import java.util.function.BiConsumer;
+import net.kyori.adventure.audience.Audience;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * A callback for a resource pack application operation.
+ *
+ * @since 4.15.0
+ */
+@FunctionalInterface
+public interface ResourcePackCallback {
+  /**
+   * Create a pack callback that will only execute the provided functions when the pack application has completed, discarding all intermediate events.
+   *
+   * @param success the success callback
+   * @param failure the failure callback
+   * @return the created callback
+   * @since 4.15.0
+   */
+  static @NotNull ResourcePackCallback onTerminal(final @NotNull BiConsumer<UUID, Audience> success, final @NotNull BiConsumer<UUID, Audience> failure) {
+    return (uuid, status, audience) -> {
+      if (status == ResourcePackStatus.SUCCESSFULLY_LOADED) {
+        success.accept(uuid, audience);
+      } else if (!status.intermediate()) {
+        failure.accept(uuid, audience);
+      }
+    };
+  }
+
+  /**
+   * Called when a pack event has been received.
+   *
+   * <p>If the pack apply action was executed on a group audience, {@code audience} will referer to the
+   * individual member audiences the action is executed on. Forwarding audiences may wrap callbacks to ensure they receive the appropriate wrapped audience.</p>
+   *
+   * @param uuid the uuid of the pack that has been applied.
+   * @param status the current pack status
+   * @param audience the audience the pack is being applied to
+   * @since 4.15.0
+   */
+  void packEventReceived(final @NotNull UUID uuid, final @NotNull ResourcePackStatus status, final @NotNull Audience audience);
+}