For new registry values, allow copying from existing (#11796)

Co-authored-by: Bjarne Koll <git@lynxplay.dev>

paper-api/src/main/java/io/papermc/paper/registry/RegistryBuilderFactory.java

@@ -0,0 +1,39 @@
+package io.papermc.paper.registry;
+
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.Contract;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * A factory to create a {@link RegistryBuilder} for a given {@link TypedKey}. For
+ * each instance of this class, once either {@link #empty()} or {@link #copyFrom(TypedKey)}
+ * is called once, any future calls to either method will throw an {@link IllegalStateException}.
+ *
+ * @param <T> The type of the registry
+ * @param <B> The type of the registry builder
+ */
+@NullMarked
+@ApiStatus.Experimental
+@ApiStatus.NonExtendable
+public interface RegistryBuilderFactory<T, B extends RegistryBuilder<T>> {
+
+    /**
+     * Creates a new empty {@link RegistryBuilder}.
+     *
+     * @return A new empty {@link RegistryBuilder}
+     * @throws IllegalStateException if this method or {@link #copyFrom(TypedKey)}) has already been called once
+     */
+    @Contract("-> new")
+    B empty();
+
+    /**
+     * Creates a new {@link RegistryBuilder} with the same properties as the given {@link TypedKey}.
+     *
+     * @param key The key to copy properties from
+     * @return A new {@link RegistryBuilder} with the same properties as the given key
+     * @throws IllegalStateException if this method or {@link #empty()} has already been called once
+     * @throws IllegalArgumentException if key doesn't exist
+     */
+    @Contract("_ -> new")
+    B copyFrom(TypedKey<T> key);
+}

paper-api/src/main/java/io/papermc/paper/registry/RegistryKey.java

@@ -1,6 +1,8 @@
 package io.papermc.paper.registry;
 
 import io.papermc.paper.datacomponent.DataComponentType;
+import net.kyori.adventure.key.Key;
+import net.kyori.adventure.key.KeyPattern;
 import net.kyori.adventure.key.Keyed;
 import org.bukkit.Art;
 import org.bukkit.Fluid;
@@ -200,4 +202,26 @@ public sealed interface RegistryKey<T> extends Keyed permits RegistryKeyImpl {
     RegistryKey<Particle> PARTICLE_TYPE = create("particle_type");
     RegistryKey<PotionType> POTION = create("potion");
     RegistryKey<MemoryKey<?>> MEMORY_MODULE_TYPE = create("memory_module_type");
+
+    /**
+     * Constructs a new {@link TypedKey} for this registry given the typed key's key.
+     *
+     * @param key the key of the typed key.
+     * @return the constructed typed key.
+     */
+    @ApiStatus.Experimental
+    default TypedKey<T> typedKey(final Key key) {
+        return TypedKey.create(this, key);
+    }
+
+    /**
+     * Constructs a new {@link TypedKey} for this registry given the typed key's key.
+     *
+     * @param key the string representation of the key that will be passed to {@link Key#key(String)}.
+     * @return the constructed typed key.
+     */
+    @ApiStatus.Experimental
+    default TypedKey<T> typedKey(final @KeyPattern String key) {
+        return TypedKey.create(this, key);
+    }
 }

paper-api/src/main/java/io/papermc/paper/registry/TypedKey.java

@@ -1,6 +1,7 @@
 package io.papermc.paper.registry;
 
 import net.kyori.adventure.key.Key;
+import net.kyori.adventure.key.KeyPattern;
 import net.kyori.adventure.key.Keyed;
 import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
@@ -42,4 +43,18 @@ public sealed interface TypedKey<T> extends Key permits TypedKeyImpl {
     static <T> TypedKey<T> create(final RegistryKey<T> registryKey, final Key key) {
         return new TypedKeyImpl<>(key, registryKey);
     }
+
+    /**
+     * Create a typed key from a string and a registry key.
+     *
+     * @param registryKey the registry this key is for
+     * @param key         the string version of a {@link Key} that will be passed to {@link Key#key(String)} for parsing.
+     * @param <T>         value type
+     * @return a new key for the value key and registry key
+     * @see Key#key(String)
+     */
+    @ApiStatus.Experimental
+    static <T> TypedKey<T> create(final RegistryKey<T> registryKey, final @KeyPattern String key) {
+        return create(registryKey, Key.key(key));
+    }
 }

paper-api/src/main/java/io/papermc/paper/registry/event/WritableRegistry.java

@@ -1,6 +1,7 @@
 package io.papermc.paper.registry.event;
 
 import io.papermc.paper.registry.RegistryBuilder;
+import io.papermc.paper.registry.RegistryBuilderFactory;
 import io.papermc.paper.registry.TypedKey;
 import java.util.function.Consumer;
 import org.jetbrains.annotations.ApiStatus;
@@ -24,5 +25,18 @@ public interface WritableRegistry<T, B extends RegistryBuilder<T>> {
      * @param key the entry's key (must be unique from others)
      * @param value a consumer for the entry's builder
      */
-    void register(TypedKey<T> key, Consumer<? super B> value);
+    default void register(final TypedKey<T> key, final Consumer<? super B> value) {
+        this.registerWith(key, factory -> value.accept(factory.empty()));
+    }
+
+    /**
+     * Register a new value with the specified key. This will
+     * fire a {@link RegistryEntryAddEvent} for the new entry. The
+     * {@link RegistryBuilderFactory} lets you pre-fill a builder with
+     * an already-existing entry's properties.
+     *
+     * @param key the entry's key (must be unique from others)
+     * @param value a consumer of a builder factory
+     */
+    void registerWith(TypedKey<T> key, Consumer<RegistryBuilderFactory<T, B>> value);
 }