Add RegistryRetriever for future use in registry API

Machine-Maker · Machine-Maker · commit 89059c25dcde · 2025-06-14T10:56:22.000-07:00
diff --git a/paper-api/src/main/java/io/papermc/paper/registry/event/RegistryComposeEvent.java b/paper-api/src/main/java/io/papermc/paper/registry/event/RegistryComposeEvent.java
@@ -1,11 +1,8 @@
 package io.papermc.paper.registry.event;
 
 import io.papermc.paper.registry.RegistryBuilder;
-import io.papermc.paper.registry.tag.Tag;
-import io.papermc.paper.registry.tag.TagKey;
-import org.bukkit.Keyed;
 import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
+import org.jetbrains.annotations.Contract;
 
 /**
  * Event object for {@link RegistryEventProvider#compose()}. This
@@ -16,7 +13,6 @@
  * @param <B> registry entry builder type
  */
 @ApiStatus.Experimental
-@NullMarked
 @ApiStatus.NonExtendable
 public interface RegistryComposeEvent<T, B extends RegistryBuilder<T>> extends RegistryEvent<T> {
 
@@ -28,13 +24,11 @@ public interface RegistryComposeEvent<T, B extends RegistryBuilder<T>> extends R
     WritableRegistry<T, B> registry();
 
     /**
-     * Gets or creates a tag for the given tag key. This tag
-     * is then required to be filled either from the built-in or
-     * custom datapack.
+     * Gets the registry retriever, which can be used to retrieve or create
+     * entries in the registry.
      *
-     * @param tagKey the tag key
-     * @return the tag
-     * @param <V> the tag value type
+     * @return the registry retriever
      */
-    <V extends Keyed> Tag<V> getOrCreateTag(TagKey<V> tagKey);
+    @Contract(pure = true)
+    RegistryRetriever retriever();
 }
diff --git a/paper-api/src/main/java/io/papermc/paper/registry/event/RegistryEntryAddEvent.java b/paper-api/src/main/java/io/papermc/paper/registry/event/RegistryEntryAddEvent.java
@@ -6,7 +6,7 @@
 import io.papermc.paper.registry.tag.TagKey;
 import org.bukkit.Keyed;
 import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
+import org.jetbrains.annotations.Contract;
 
 /**
  * Event object for {@link RegistryEventProvider#entryAdd()}. This
@@ -16,8 +16,6 @@
  * @param <T> registry entry type
  * @param <B> registry entry builder type
  */
-@ApiStatus.Experimental
-@NullMarked
 @ApiStatus.NonExtendable
 public interface RegistryEntryAddEvent<T, B extends RegistryBuilder<T>> extends RegistryEvent<T> {
 
@@ -43,6 +41,19 @@ public interface RegistryEntryAddEvent<T, B extends RegistryBuilder<T>> extends
      * @param tagKey the tag key
      * @return the tag
      * @param <V> the tag value type
+     * @deprecated use {@link #retriever()}
      */
-    <V extends Keyed> Tag<V> getOrCreateTag(TagKey<V> tagKey);
+    @Deprecated(forRemoval = true)
+    default <V extends Keyed> Tag<V> getOrCreateTag(final TagKey<V> tagKey) {
+        return this.retriever().getOrCreateTag(tagKey);
+    }
+
+    /**
+     * Gets the registry retriever, which can be used to retrieve or create
+     * entries in the registry.
+     *
+     * @return the registry retriever
+     */
+    @Contract(pure = true)
+    RegistryRetriever retriever();
 }
diff --git a/paper-api/src/main/java/io/papermc/paper/registry/event/RegistryEvent.java b/paper-api/src/main/java/io/papermc/paper/registry/event/RegistryEvent.java
@@ -3,15 +3,12 @@
 import io.papermc.paper.plugin.lifecycle.event.LifecycleEvent;
 import io.papermc.paper.registry.RegistryKey;
 import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
 
 /**
  * Base type for all registry events.
  *
  * @param <T> registry entry type
  */
-@ApiStatus.Experimental
-@NullMarked
 @ApiStatus.NonExtendable
 public interface RegistryEvent<T> extends LifecycleEvent {
 
diff --git a/paper-api/src/main/java/io/papermc/paper/registry/event/RegistryEventProvider.java b/paper-api/src/main/java/io/papermc/paper/registry/event/RegistryEventProvider.java
@@ -7,7 +7,6 @@
 import io.papermc.paper.registry.RegistryKey;
 import io.papermc.paper.registry.event.type.RegistryEntryAddEventType;
 import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
 
 /**
  * Provider for registry events for a specific registry.
@@ -21,8 +20,6 @@
  * @param <T> registry entry type
  * @param <B> registry entry builder type
  */
-@ApiStatus.Experimental
-@NullMarked
 @ApiStatus.NonExtendable
 public interface RegistryEventProvider<T, B extends RegistryBuilder<T>> {
 
diff --git a/paper-api/src/main/java/io/papermc/paper/registry/event/RegistryEventProviderImpl.java b/paper-api/src/main/java/io/papermc/paper/registry/event/RegistryEventProviderImpl.java
@@ -6,10 +6,8 @@
 import io.papermc.paper.registry.RegistryKey;
 import io.papermc.paper.registry.event.type.RegistryEntryAddEventType;
 import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
 
 @ApiStatus.Internal
-@NullMarked
 record RegistryEventProviderImpl<T, B extends RegistryBuilder<T>>(RegistryKey<T> registryKey) implements RegistryEventProvider<T, B> {
 
     static <T, B extends RegistryBuilder<T>> RegistryEventProvider<T, B> create(final RegistryKey<T> registryKey) {
diff --git a/paper-api/src/main/java/io/papermc/paper/registry/event/RegistryEvents.java b/paper-api/src/main/java/io/papermc/paper/registry/event/RegistryEvents.java
@@ -23,17 +23,13 @@
 import org.bukkit.entity.Frog;
 import org.bukkit.entity.Pig;
 import org.bukkit.entity.Wolf;
-import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
 
 import static io.papermc.paper.registry.event.RegistryEventProviderImpl.create;
 
 /**
  * Holds providers for {@link RegistryEntryAddEvent} and {@link RegistryComposeEvent}
  * handlers for each applicable registry.
  */
-@ApiStatus.Experimental
-@NullMarked
 public final class RegistryEvents {
 
     // Start generate - RegistryEvents
diff --git a/paper-api/src/main/java/io/papermc/paper/registry/event/RegistryFreezeEvent.java b/paper-api/src/main/java/io/papermc/paper/registry/event/RegistryFreezeEvent.java
@@ -1,8 +1,10 @@
 package io.papermc.paper.registry.event;
 
 import io.papermc.paper.registry.RegistryBuilder;
+import io.papermc.paper.registry.tag.Tag;
+import io.papermc.paper.registry.tag.TagKey;
+import org.bukkit.Keyed;
 import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
 
 /**
  * Event object for {@link RegistryEventProvider#freeze()}. This
@@ -15,7 +17,21 @@
  */
 @ApiStatus.ScheduledForRemoval(inVersion = "1.21.7 or 1.22, whichever comes first")
 @Deprecated(since = "1.21.6", forRemoval = true)
-@NullMarked
 @ApiStatus.NonExtendable
 public interface RegistryFreezeEvent<T, B extends RegistryBuilder<T>> extends RegistryComposeEvent<T, B> {
+
+    /**
+     * Gets or creates a tag for the given tag key. This tag
+     * is then required to be filled either from the built-in or
+     * custom datapack.
+     *
+     * @param tagKey the tag key
+     * @param <V> the tag value type
+     * @return the tag
+     * @deprecated Use {@link #retriever()}
+     */
+    @Deprecated(forRemoval = true)
+    default <V extends Keyed> Tag<V> getOrCreateTag(final TagKey<V> tagKey) {
+        return this.retriever().getOrCreateTag(tagKey);
+    }
 }
diff --git a/paper-api/src/main/java/io/papermc/paper/registry/event/RegistryRetriever.java b/paper-api/src/main/java/io/papermc/paper/registry/event/RegistryRetriever.java
@@ -0,0 +1,35 @@
+package io.papermc.paper.registry.event;
+
+import io.papermc.paper.registry.TypedKey;
+import io.papermc.paper.registry.tag.Tag;
+import io.papermc.paper.registry.tag.TagKey;
+import org.bukkit.Keyed;
+import org.jetbrains.annotations.ApiStatus;
+
+@ApiStatus.NonExtendable
+public interface RegistryRetriever {
+
+    /**
+     * Gets or creates a tag for the given tag key. This tag
+     * is then required to be filled either from the built-in or
+     * custom datapack.
+     *
+     * @param tagKey the tag key
+     * @param <V> the tag value type
+     * @return the tag
+     */
+    <V extends Keyed> Tag<V> getOrCreateTag(TagKey<V> tagKey); // TODO remove Keyed
+
+    /**
+     * Gets or creates an empty instance of the given {@link TypedKey}.
+     * <br>
+     * Can only create instances if the applicable registry still supports adding
+     * new references. If the registry doesn't, this method will throw an exception.
+     *
+     * @param key the key to get or create an instance for
+     * @param <V> the type of the value associated with the key
+     * @return an instance of the given key, or a new instance if it does not exist
+     * @throws IllegalStateException if this registry does not support adding new references and the key does not exist
+     */
+    <V extends Keyed> V getOrCreate(TypedKey<V> key); // TODO remove Keyed
+}
diff --git a/paper-api/src/main/java/io/papermc/paper/registry/event/WritableRegistry.java b/paper-api/src/main/java/io/papermc/paper/registry/event/WritableRegistry.java
@@ -5,16 +5,13 @@
 import io.papermc.paper.registry.TypedKey;
 import java.util.function.Consumer;
 import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
 
 /**
  * A registry which supports registering new objects.
  *
  * @param <T> registry entry type
  * @param <B> registry entry builder type
  */
-@ApiStatus.Experimental
-@NullMarked
 @ApiStatus.NonExtendable
 public interface WritableRegistry<T, B extends RegistryBuilder<T>> {
 
diff --git a/paper-api/src/main/java/io/papermc/paper/registry/event/package-info.java b/paper-api/src/main/java/io/papermc/paper/registry/event/package-info.java
@@ -0,0 +1,9 @@
+/**
+ * This package contains events related to the Paper registry system.
+ */
+@ApiStatus.Experimental
+@NullMarked
+package io.papermc.paper.registry.event;
+
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.NullMarked;
diff --git a/paper-api/src/main/java/io/papermc/paper/registry/event/type/RegistryEntryAddConfiguration.java b/paper-api/src/main/java/io/papermc/paper/registry/event/type/RegistryEntryAddConfiguration.java
@@ -4,15 +4,15 @@
 import io.papermc.paper.plugin.lifecycle.event.handler.configuration.PrioritizedLifecycleEventHandlerConfiguration;
 import io.papermc.paper.registry.TypedKey;
 import java.util.function.Predicate;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.Contract;
-import org.jspecify.annotations.NullMarked;
 
 /**
  * Specific configuration for {@link io.papermc.paper.registry.event.RegistryEntryAddEvent}s.
  *
  * @param <T> registry entry type
  */
-@NullMarked
+@ApiStatus.NonExtendable
 public interface RegistryEntryAddConfiguration<T> extends PrioritizedLifecycleEventHandlerConfiguration<BootstrapContext> {
 
     /**
diff --git a/paper-api/src/main/java/io/papermc/paper/registry/event/type/RegistryEntryAddEventType.java b/paper-api/src/main/java/io/papermc/paper/registry/event/type/RegistryEntryAddEventType.java
@@ -5,16 +5,13 @@
 import io.papermc.paper.registry.RegistryBuilder;
 import io.papermc.paper.registry.event.RegistryEntryAddEvent;
 import org.jetbrains.annotations.ApiStatus;
-import org.jspecify.annotations.NullMarked;
 
 /**
  * Lifecycle event type for {@link RegistryEntryAddEvent}s.
  *
  * @param <T> registry entry type
  * @param <B> registry entry builder type
  */
-@ApiStatus.Experimental
-@NullMarked
 @ApiStatus.NonExtendable
 public interface RegistryEntryAddEventType<T, B extends RegistryBuilder<T>> extends LifecycleEventType<BootstrapContext, RegistryEntryAddEvent<T, B>, RegistryEntryAddConfiguration<T>> {
 }
diff --git a/paper-api/src/main/java/io/papermc/paper/registry/event/type/package-info.java b/paper-api/src/main/java/io/papermc/paper/registry/event/type/package-info.java
@@ -0,0 +1,9 @@
+/**
+ * This package contains events related to the Paper registry system.
+ */
+@ApiStatus.Experimental
+@NullMarked
+package io.papermc.paper.registry.event.type;
+
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.NullMarked;
diff --git a/paper-server/patches/sources/net/minecraft/core/registries/BuiltInRegistries.java.patch b/paper-server/patches/sources/net/minecraft/core/registries/BuiltInRegistries.java.patch
@@ -22,7 +22,7 @@
          ResourceKey<? extends Registry<T>> key, R registry, BuiltInRegistries.RegistryBootstrap<T> bootstrap
      ) {
          Bootstrap.checkBootstrapCalled(() -> "registry " + key.location());
-+        io.papermc.paper.registry.PaperRegistryAccess.instance().registerRegistry(registry.key(), registry); // Paper - initialize API registry
++        io.papermc.paper.registry.PaperRegistryAccess.instance().registerRegistry(registry); // Paper - initialize API registry
          ResourceLocation resourceLocation = key.location();
          LOADERS.put(resourceLocation, () -> bootstrap.run(registry));
          WRITABLE_REGISTRY.register((ResourceKey)key, registry, RegistrationInfo.BUILT_IN);
diff --git a/paper-server/patches/sources/net/minecraft/resources/RegistryDataLoader.java.patch b/paper-server/patches/sources/net/minecraft/resources/RegistryDataLoader.java.patch
@@ -66,7 +66,7 @@
  
          RegistryDataLoader.Loader<T> create(Lifecycle registryLifecycle, Map<ResourceKey<?>, Exception> loadingErrors) {
              WritableRegistry<T> writableRegistry = new MappedRegistry<>(this.key, registryLifecycle);
-+            io.papermc.paper.registry.PaperRegistryAccess.instance().registerRegistry(this.key, writableRegistry); // Paper - initialize API registry
++            io.papermc.paper.registry.PaperRegistryAccess.instance().registerRegistry(writableRegistry); // Paper - initialize API registry
              return new RegistryDataLoader.Loader<>(this, writableRegistry, loadingErrors);
          }
  
diff --git a/paper-server/patches/sources/net/minecraft/server/ReloadableServerRegistries.java.patch b/paper-server/patches/sources/net/minecraft/server/ReloadableServerRegistries.java.patch
@@ -21,7 +21,7 @@
          return CompletableFuture.supplyAsync(
              () -> {
                  WritableRegistry<T> writableRegistry = new MappedRegistry<>(lootDataType.registryKey(), Lifecycle.experimental());
-+                io.papermc.paper.registry.PaperRegistryAccess.instance().registerReloadableRegistry(lootDataType.registryKey(), writableRegistry); // Paper - register reloadable registry
++                io.papermc.paper.registry.PaperRegistryAccess.instance().registerReloadableRegistry(writableRegistry); // Paper - register reloadable registry
                  Map<ResourceLocation, T> map = new HashMap<>();
                  SimpleJsonResourceReloadListener.scanDirectory(resourceManager, lootDataType.registryKey(), ops, lootDataType.codec(), map);
                  map.forEach(
diff --git a/paper-server/src/main/java/io/papermc/paper/registry/PaperRegistryAccess.java b/paper-server/src/main/java/io/papermc/paper/registry/PaperRegistryAccess.java
@@ -97,12 +97,12 @@ private static <T extends Keyed> Registry<T> possiblyUnwrap(final Registry<T> re
         return registry;
     }
 
-    public <M> void registerReloadableRegistry(final ResourceKey<? extends net.minecraft.core.Registry<M>> resourceKey, final net.minecraft.core.Registry<M> registry) {
-        this.registerRegistry(resourceKey, registry, true);
+    public <M> void registerReloadableRegistry(final net.minecraft.core.Registry<M> registry) {
+        this.registerRegistry(registry, true);
     }
 
-    public <M> void registerRegistry(final ResourceKey<? extends net.minecraft.core.Registry<M>> resourceKey, final net.minecraft.core.Registry<M> registry) {
-        this.registerRegistry(resourceKey, registry, false);
+    public <M> void registerRegistry(final net.minecraft.core.Registry<M> registry) {
+        this.registerRegistry(registry, false);
     }
 
     public <M> void lockReferenceHolders(final ResourceKey<? extends net.minecraft.core.Registry<M>> resourceKey) {
@@ -115,8 +115,8 @@ public <M> void lockReferenceHolders(final ResourceKey<? extends net.minecraft.c
     }
 
     @SuppressWarnings("unchecked") // this method should be called right after any new MappedRegistry instances are created to later be used by the server.
-    private <M, B extends Keyed, R extends Registry<B>> void registerRegistry(final ResourceKey<? extends net.minecraft.core.Registry<M>> resourceKey, final net.minecraft.core.Registry<M> registry, final boolean replace) {
-        final RegistryEntry<M, B> entry = PaperRegistries.getEntry(resourceKey);
+    private <M, B extends Keyed, R extends Registry<B>> void registerRegistry(final net.minecraft.core.Registry<M> registry, final boolean replace) {
+        final RegistryEntry<M, B> entry = PaperRegistries.getEntry(registry.key());
         if (entry == null) { // skip registries that don't have API entries
             return;
         }
@@ -129,7 +129,7 @@ private <M, B extends Keyed, R extends Registry<B>> void registerRegistry(final
                 // if the registry holder is delayed, and the entry is marked as "delayed", then load the holder with the CraftRegistry instance that wraps the actual nms Registry.
                 ((RegistryHolder.Delayed<B, R>) registryHolder).loadFrom(delayedEntry, registry);
             } else {
-                throw new IllegalArgumentException(resourceKey + " has already been created");
+                throw new IllegalArgumentException(registry.key() + " has already been created");
             }
         }
     }
diff --git a/paper-server/src/main/java/io/papermc/paper/registry/entry/RegistryEntryMeta.java b/paper-server/src/main/java/io/papermc/paper/registry/entry/RegistryEntryMeta.java
@@ -6,6 +6,7 @@
 import io.papermc.paper.registry.TypedKey;
 import io.papermc.paper.registry.WritableCraftRegistry;
 import io.papermc.paper.registry.data.util.Conversions;
+import io.papermc.paper.registry.event.PaperRegistryRetriever;
 import io.papermc.paper.registry.event.RegistryEntryAddEventImpl;
 import io.papermc.paper.registry.event.RegistryComposeEventImpl;
 import java.util.function.BiFunction;
@@ -103,11 +104,11 @@ record Buildable<M, A extends Keyed, B extends PaperRegistryBuilder<M, A>>( // T
     ) implements ServerSide<M, A> {
 
         public RegistryEntryAddEventImpl<A, B> createEntryAddEvent(final TypedKey<A> key, final B initialBuilder, final Conversions conversions) {
-            return new RegistryEntryAddEventImpl<>(key, initialBuilder, this.apiKey(), conversions);
+            return new RegistryEntryAddEventImpl<>(key, initialBuilder, this.apiKey(), conversions, new PaperRegistryRetriever(conversions));
         }
 
         public RegistryComposeEventImpl<A, B> createPostLoadEvent(final WritableCraftRegistry<M, A, B> writableRegistry, final Conversions conversions) {
-            return new RegistryComposeEventImpl<>(this.apiKey(), writableRegistry.createApiWritableRegistry(conversions), conversions);
+            return new RegistryComposeEventImpl<>(this.apiKey(), writableRegistry.createApiWritableRegistry(conversions), conversions, new PaperRegistryRetriever(conversions));
         }
 
         @Override
diff --git a/paper-server/src/main/java/io/papermc/paper/registry/event/PaperRegistryRetriever.java b/paper-server/src/main/java/io/papermc/paper/registry/event/PaperRegistryRetriever.java
diff --git a/paper-server/src/main/java/io/papermc/paper/registry/event/RegistryComposeEventImpl.java b/paper-server/src/main/java/io/papermc/paper/registry/event/RegistryComposeEventImpl.java
diff --git a/paper-server/src/main/java/io/papermc/paper/registry/event/RegistryEntryAddEventImpl.java b/paper-server/src/main/java/io/papermc/paper/registry/event/RegistryEntryAddEventImpl.java
diff --git a/paper-server/src/main/java/org/bukkit/craftbukkit/CraftRegistry.java b/paper-server/src/main/java/org/bukkit/craftbukkit/CraftRegistry.java
diff --git a/paper-server/src/main/java/org/bukkit/craftbukkit/entity/CraftWolf.java b/paper-server/src/main/java/org/bukkit/craftbukkit/entity/CraftWolf.java
diff --git a/paper-server/src/test/java/org/bukkit/registry/RegistryConversionTest.java b/paper-server/src/test/java/org/bukkit/registry/RegistryConversionTest.java
diff --git a/paper-server/src/test/java/org/bukkit/support/provider/RegistryArgumentProvider.java b/paper-server/src/test/java/org/bukkit/support/provider/RegistryArgumentProvider.java
diff --git a/paper-server/src/test/java/org/bukkit/support/test/RegistryTest.java b/paper-server/src/test/java/org/bukkit/support/test/RegistryTest.java
diff --git a/test-plugin/src/main/java/io/papermc/testplugin/TestPluginBootstrap.java b/test-plugin/src/main/java/io/papermc/testplugin/TestPluginBootstrap.java
