Merge branch 'main' into fix/disabling-vanilla-registry-values

.github/workflows/build.yml

@@ -17,7 +17,7 @@ on:
 jobs:
   build:
     # Run on all label events (won't be duplicated) or all push events or on PR syncs not from the same repo
-    if: (github.event_name == 'pull_request' && github.event.action == 'labeled') || github.event_name != 'pull_request' || github.repository != github.event.pull_request.head.repo.full_name
+    if: (github.event_name == 'pull_request' && github.event.action == 'labeled' && github.event.label.name == 'build-pr-jar') || github.event_name != 'pull_request' || github.repository != github.event.pull_request.head.repo.full_name
     runs-on: ubuntu-latest
     strategy:
       matrix:

paper-api/src/main/java/io/papermc/paper/entity/EntitySerializationFlag.java

@@ -0,0 +1,38 @@
+package io.papermc.paper.entity;
+
+import org.bukkit.UnsafeValues;
+import org.bukkit.entity.Entity;
+import org.bukkit.entity.Player;
+
+/**
+ * Represents flags for entity serialization.
+ *
+ * @see UnsafeValues#serializeEntity(Entity, EntitySerializationFlag... serializationFlags)
+ * @since 1.21.4
+ */
+public enum EntitySerializationFlag {
+
+    /**
+     * Serialize entities that wouldn't be serialized normally
+     * (e.g. dead, despawned, non-persistent, etc.).
+     *
+     * @see Entity#isValid()
+     * @see Entity#isPersistent()
+     */
+    FORCE,
+    /**
+     * Serialize misc non-saveable entities like lighting bolts, fishing bobbers, etc.
+     * <br>Note: players require a separate flag: {@link #PLAYER}.
+     */
+    MISC,
+    /**
+     * Include passengers in the serialized data.
+     */
+    PASSENGERS,
+    /**
+     * Allow serializing {@link Player}s.
+     * <p>Note: deserializing player data will always fail.
+     */
+    PLAYER
+
+}

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/data/BannerPatternRegistryEntry.java

@@ -0,0 +1,65 @@
+package io.papermc.paper.registry.data;
+
+import io.papermc.paper.registry.RegistryBuilder;
+import net.kyori.adventure.key.Key;
+import org.bukkit.block.banner.PatternType;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.Contract;
+
+/**
+ * A data-centric version-specific registry entry for the {@link PatternType} type.
+ */
+@ApiStatus.Experimental
+@ApiStatus.NonExtendable
+public interface BannerPatternRegistryEntry {
+
+    /**
+     * Provides the asset id of the pattern type, which is the location of the sprite to use.
+     *
+     * @return the asset id.
+     */
+    Key assetId();
+
+    /**
+     * Provides the translation key for displaying the pattern inside the banner's tooltip.
+     *
+     * @return the translation key.
+     */
+    String translationKey();
+
+    /**
+     * A mutable builder for the {@link BannerPatternRegistryEntry} plugins may change in applicable registry events.
+     * <p>
+     * The following values are required for each builder:
+     * <ul>
+     *     <li>{@link #assetId(Key)}</li>
+     *     <li>{@link #translationKey(String)}</li>
+     * </ul>
+     */
+    @ApiStatus.Experimental
+    @ApiStatus.NonExtendable
+    interface Builder extends BannerPatternRegistryEntry, RegistryBuilder<PatternType> {
+
+        /**
+         * Sets the asset id of the pattern type, which is the location of the sprite to use.
+         *
+         * @param assetId the asset id.
+         * @return this builder instance.
+         * @see BannerPatternRegistryEntry#assetId()
+         */
+        @Contract(value = "_ -> this", mutates = "this")
+        Builder assetId(Key assetId);
+
+        /**
+         * Sets the translation key for displaying the pattern inside the banner's tooltip.
+         *
+         * @param translationKey the translation key.
+         * @return this builder instance.
+         * @see BannerPatternRegistryEntry#translationKey()
+         */
+        @Contract(value = "_ -> this", mutates = "this")
+        Builder translationKey(String translationKey);
+
+    }
+
+}

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

@@ -1,11 +1,13 @@
 package io.papermc.paper.registry.event;
 
 import io.papermc.paper.registry.RegistryKey;
+import io.papermc.paper.registry.data.BannerPatternRegistryEntry;
 import io.papermc.paper.registry.data.EnchantmentRegistryEntry;
 import io.papermc.paper.registry.data.GameEventRegistryEntry;
 import io.papermc.paper.registry.data.PaintingVariantRegistryEntry;
 import org.bukkit.Art;
 import org.bukkit.GameEvent;
+import org.bukkit.block.banner.PatternType;
 import org.bukkit.enchantments.Enchantment;
 import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.NullMarked;
@@ -23,6 +25,7 @@ public final class RegistryEvents {
     public static final RegistryEventProvider<GameEvent, GameEventRegistryEntry.Builder> GAME_EVENT = create(RegistryKey.GAME_EVENT);
     public static final RegistryEventProvider<Enchantment, EnchantmentRegistryEntry.Builder> ENCHANTMENT = create(RegistryKey.ENCHANTMENT);
     public static final RegistryEventProvider<Art, PaintingVariantRegistryEntry.Builder> PAINTING_VARIANT = create(RegistryKey.PAINTING_VARIANT);
+    public static final RegistryEventProvider<PatternType, BannerPatternRegistryEntry.Builder> BANNER_PATTERN = create(RegistryKey.BANNER_PATTERN);
 
     private RegistryEvents() {
     }

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);
 }