Feature: Allow API users to set ResourcePackOption's, add a GeyserDefineResourcePacksEvent

api/src/main/java/org/geysermc/geyser/api/event/bedrock/SessionLoadResourcePacksEvent.java

@@ -26,10 +26,13 @@
 package org.geysermc.geyser.api.event.bedrock;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
 import org.geysermc.geyser.api.connection.GeyserConnection;
 import org.geysermc.geyser.api.event.connection.ConnectionEvent;
 import org.geysermc.geyser.api.pack.ResourcePack;
+import org.geysermc.geyser.api.pack.option.ResourcePackOption;
 
+import java.util.Collection;
 import java.util.List;
 import java.util.UUID;
 
@@ -42,7 +45,7 @@ public SessionLoadResourcePacksEvent(@NonNull GeyserConnection connection) {
     }
 
     /**
-     * Gets an unmodifiable list of {@link ResourcePack}s that will be sent to the client.
+     * Gets an unmodifiable list of {@link ResourcePack}'s that will be sent to the client.
      *
      * @return an unmodifiable list of resource packs that will be sent to the client.
      */
@@ -51,11 +54,49 @@ public SessionLoadResourcePacksEvent(@NonNull GeyserConnection connection) {
     /**
      * Registers a {@link ResourcePack} to be sent to the client.
      *
+     * @param pack a resource pack that will be sent to the client
+     * @return true if the resource pack was added successfully,
+     *         or false if already present
+     */
+    public abstract boolean register(@NonNull ResourcePack pack);
+
+    /**
+     * Registers a {@link ResourcePack} to be sent to the client, alongside
+     * specific options.
+     *
      * @param resourcePack a resource pack that will be sent to the client.
+     * @param options {@link ResourcePackOption}'s that specify how clients load the pack
      * @return true if the resource pack was added successfully,
      *         or false if already present
      */
-    public abstract boolean register(@NonNull ResourcePack resourcePack);
+    public abstract boolean register(@NonNull ResourcePack resourcePack, @Nullable ResourcePackOption<?>... options);
+
+    /**
+     * Sets {@link ResourcePackOption}'s for a resource pack
+     *
+     * @param uuid the resource pack uuid to register the options for
+     * @param options the options to register for the pack
+     * @throws IllegalArgumentException if the pack is not registered.
+     */
+    public abstract void registerOptions(@NonNull UUID uuid, @NonNull ResourcePackOption<?>... options);
+
+    /**
+     * Returns the subpack options set for a specific resource pack uuid.
+     * These are not modifiable.
+     *
+     * @param uuid the resource pack for which the options are set
+     * @return a list of {@link ResourcePackOption}
+     */
+    public abstract Collection<ResourcePackOption<?>> options(@NonNull UUID uuid);
+
+    /**
+     * Returns the current option, or null, for a given ResourcePackOption type.
+     *
+     * @param uuid the resource pack for which the option type is set
+     * @param type the {@link ResourcePackOption.Type} of the option to query
+     * @throws IllegalArgumentException if the pack is not registered.
+     */
+    public abstract @Nullable ResourcePackOption<?> option(@NonNull UUID uuid, ResourcePackOption.@NonNull Type type);
 
     /**
      * Unregisters a resource pack from being sent to the client.

api/src/main/java/org/geysermc/geyser/api/event/lifecycle/GeyserDefineResourcePacksEvent.java

@@ -0,0 +1,95 @@
+/*
+ * Copyright (c) 2019-2023 GeyserMC. http://geysermc.org
+ *
+ * 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.
+ *
+ * @author GeyserMC
+ * @link https://github.com/GeyserMC/Geyser
+ */
+
+package org.geysermc.geyser.api.event.lifecycle;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+import org.geysermc.event.Event;
+import org.geysermc.geyser.api.pack.ResourcePack;
+import org.geysermc.geyser.api.pack.option.ResourcePackOption;
+
+import java.util.Collection;
+import java.util.List;
+import java.util.UUID;
+
+/**
+ * Called when {@link ResourcePack}'s are loaded within Geyser.
+ */
+public abstract class GeyserDefineResourcePacksEvent implements Event {
+
+    /**
+     * Gets an unmodifiable list of {@link ResourcePack}'s that will be sent to clients.
+     *
+     * @return an unmodifiable list of resource packs that will be sent to clients.
+     */
+    public abstract @NonNull List<ResourcePack> resourcePacks();
+
+    /**
+     * Registers a {@link ResourcePack} to be sent to the client, optionally alongside
+     * {@link ResourcePackOption} options specifying how it will be applied on clients.
+     *
+     * @param pack a resource pack that will be sent to the client.
+     * @param options {@link ResourcePackOption}'s that specify how clients load the pack
+     * @return true if the resource pack was added successfully,
+     *         or false if already present
+     */
+    public abstract boolean register(@NonNull ResourcePack pack, @Nullable ResourcePackOption<?>... options);
+
+    /**
+     * Sets {@link ResourcePackOption}'s for a resource pack
+     *
+     * @param uuid the resource pack uuid to register the options for
+     * @param options the options to register for the pack
+     * @throws IllegalArgumentException if the pack is not registered.
+     */
+    public abstract void registerOptions(@NonNull UUID uuid, @NonNull ResourcePackOption<?>... options);
+
+    /**
+     * Returns the subpack options set for a specific resource pack uuid.
+     * These are not modifiable.
+     *
+     * @param uuid the resource pack uuid for which the options are set
+     * @return a list of {@link ResourcePackOption}
+     */
+    public abstract Collection<ResourcePackOption<?>> options(@NonNull UUID uuid);
+
+    /**
+     * Returns the current option, or null, for a given ResourcePackOption type.
+     *
+     * @param uuid the resource pack for which the option type is set
+     * @param type the {@link ResourcePackOption.Type} of the option to query
+     * @throws IllegalArgumentException if the pack is not registered.
+     */
+    public abstract @Nullable ResourcePackOption<?> option(@NonNull UUID uuid, ResourcePackOption.@NonNull Type type);
+
+    /**
+     * Unregisters a {@link ResourcePack} from being sent to clients.
+     *
+     * @param uuid the uuid of the resource pack to remove.
+     * @return true whether the resource pack was removed successfully.
+     */
+    public abstract boolean unregister(@NonNull UUID uuid);
+}

api/src/main/java/org/geysermc/geyser/api/event/lifecycle/GeyserLoadResourcePacksEvent.java

@@ -32,9 +32,8 @@
 import java.util.List;
 
 /**
- * Called when resource packs are loaded within Geyser.
- *
- * @param resourcePacks a mutable list of the currently listed resource packs
+ * @deprecated Use {@link GeyserDefineResourcePacksEvent} instead.
  */
+@Deprecated(forRemoval = true)
 public record GeyserLoadResourcePacksEvent(@NonNull List<Path> resourcePacks) implements Event {
 }

api/src/main/java/org/geysermc/geyser/api/pack/PackCodec.java

@@ -53,13 +53,21 @@ public abstract class PackCodec {
     public abstract long size();
 
     /**
-     * Serializes the given resource pack into a byte buffer.
+     * Use {@link #serialize()} instead.
+     */
+    @Deprecated
+    @NonNull
+    public SeekableByteChannel serialize(@NonNull ResourcePack resourcePack) throws IOException {
+        return serialize();
+    };
+
+    /**
+     * Serializes the given codec into a byte buffer.
      *
-     * @param resourcePack the resource pack to serialize
      * @return the serialized resource pack
      */
     @NonNull
-    public abstract SeekableByteChannel serialize(@NonNull ResourcePack resourcePack) throws IOException;
+    public abstract SeekableByteChannel serialize() throws IOException;
 
     /**
      * Creates a new resource pack from this codec.
@@ -69,14 +77,32 @@ public abstract class PackCodec {
     @NonNull
     protected abstract ResourcePack create();
 
+    /**
+     * Creates a new resource pack builder from this codec.
+     *
+     * @return the new resource pack builder
+     */
+    protected abstract ResourcePack.@NonNull Builder createBuilder();
+
     /**
      * Creates a new pack provider from the given path.
      *
      * @param path the path to create the pack provider from
      * @return the new pack provider
      */
     @NonNull
-    public static PackCodec path(@NonNull Path path) {
+    public static PathPackCodec path(@NonNull Path path) {
         return GeyserApi.api().provider(PathPackCodec.class, path);
     }
+
+    /**
+     * Creates a new pack provider from the given url.
+     *
+     * @param url the url to create the pack provider from
+     * @return the new pack provider
+     */
+    @NonNull
+    public static UrlPackCodec url(@NonNull String url) {
+        return GeyserApi.api().provider(UrlPackCodec.class, url);
+    }
 }

api/src/main/java/org/geysermc/geyser/api/pack/ResourcePack.java

@@ -26,6 +26,9 @@
 package org.geysermc.geyser.api.pack;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
+import org.geysermc.geyser.api.GeyserApi;
+
+import java.util.UUID;
 
 /**
  * Represents a resource pack sent to Bedrock clients
@@ -59,6 +62,14 @@ public interface ResourcePack {
     @NonNull
     String contentKey();
 
+    /**
+     * @return the resource pack uuid. Shortcut for getting the UUID from the header.
+     */
+    @NonNull
+    default UUID uuid() {
+        return manifest().header().uuid();
+    }
+
     /**
      * Creates a resource pack with the given {@link PackCodec}.
      *
@@ -69,4 +80,49 @@ public interface ResourcePack {
     static ResourcePack create(@NonNull PackCodec codec) {
         return codec.create();
     }
+
+    /**
+     * Returns a {@link Builder} for a resource pack.
+     * It can be used to set a content key.
+     *
+     * @param codec the {@link PackCodec} to base the builder on
+     * @return a {@link Builder} to build a resource pack.
+     */
+    static Builder builder(@NonNull PackCodec codec) {
+        return GeyserApi.api().provider(Builder.class, codec);
+    }
+
+    /**
+     * A builder for a resource pack. It allows providing a content key manually.
+     */
+    interface Builder {
+
+        /**
+         * @return the {@link ResourcePackManifest} of this resource pack
+         */
+        ResourcePackManifest manifest();
+
+        /**
+         * @return the {@link PackCodec} of this resource pack
+         */
+        PackCodec codec();
+
+        /**
+         * @return the current content key, or an empty string if not set
+         */
+        String contentKey();
+
+        /**
+         * Sets a content key for this resource pack.
+         *
+         * @param contentKey the content key
+         * @return this builder
+         */
+        Builder contentKey(@NonNull String contentKey);
+
+        /**
+         * @return the resource pack
+         */
+        ResourcePack build();
+    }
 }