Add RegistryAccess for managing registries

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

@@ -0,0 +1,47 @@
+package io.papermc.paper.registry;
+
+import org.bukkit.Keyed;
+import org.bukkit.NamespacedKey;
+import org.bukkit.Registry;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Represents a reference to a server-backed registry value that may
+ * change.
+ *
+ * @param <T> type of the value
+ */
+@Deprecated(forRemoval = true, since = "1.20.6")
+public interface Reference<T extends Keyed> extends Keyed {
+
+    /**
+     * Gets the value from the registry with the key.
+     *
+     * @return the value
+     * @throws java.util.NoSuchElementException if there is no value with this key
+     */
+    @Deprecated(forRemoval = true, since = "1.20.6")
+    @NotNull T value();
+
+    /**
+     * Gets the value from the registry with the key.
+     *
+     * @return the value or null if it doesn't exist
+     */
+    @Deprecated(forRemoval = true, since = "1.20.6")
+    @Nullable T valueOrNull();
+
+    /**
+     * Creates a reference to a registered value.
+     *
+     * @param registry the registry the value is located in
+     * @param key the key to the value
+     * @param <T> the type of the value
+     * @return a reference
+     */
+    @Deprecated(forRemoval = true, since = "1.20.6")
+    static <T extends Keyed> @NotNull Reference<T> create(@NotNull Registry<T> registry, @NotNull NamespacedKey key) {
+        return new ReferenceImpl<>(registry, key);
+    }
+}

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

@@ -0,0 +1,31 @@
+package io.papermc.paper.registry;
+
+import org.bukkit.Keyed;
+import org.bukkit.NamespacedKey;
+import org.bukkit.Registry;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+import java.util.NoSuchElementException;
+
+record ReferenceImpl<T extends Keyed>(@NotNull Registry<T> registry, @NotNull NamespacedKey key) implements Reference<T> {
+
+    @Override
+    public @NotNull T value() {
+        final T value = this.registry.get(this.key);
+        if (value == null) {
+            throw new NoSuchElementException("No such value with key " + this.key);
+        }
+        return value;
+    }
+
+    @Override
+    public @Nullable T valueOrNull() {
+        return this.registry.get(this.key);
+    }
+
+    @Override
+    public @NotNull NamespacedKey getKey() {
+        return this.key;
+    }
+}

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

@@ -0,0 +1,50 @@
+package io.papermc.paper.registry;
+
+import org.bukkit.Keyed;
+import org.bukkit.Registry;
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * Used for accessing different {@link Registry} instances
+ * by a {@link RegistryKey}. Get the main instance of {@link RegistryAccess}
+ * with {@link RegistryAccess#registryAccess()}.
+ */
+@NullMarked
+@ApiStatus.NonExtendable
+public interface RegistryAccess {
+
+    /**
+     * Get the {@link RegistryAccess} instance for the server.
+     *
+     * @return the RegistryAccess instance
+     */
+    static RegistryAccess registryAccess() {
+        return RegistryAccessHolder.INSTANCE.orElseThrow(() -> new IllegalStateException("No RegistryAccess implementation found"));
+    }
+
+    /**
+     * Gets the registry based on the type.
+     *
+     * @param type the type
+     * @return the registry or null if none found
+     * @param <T> the type
+     * @deprecated use {@link #getRegistry(RegistryKey)} with keys from {@link RegistryKey}
+     */
+    @Deprecated(since = "1.20.6", forRemoval = true)
+    <T extends Keyed> @Nullable Registry<T> getRegistry(Class<T> type);
+
+    /**
+     * Gets the registry with the specified key.
+     *
+     * @param registryKey the key
+     * @return the registry
+     * @param <T> the type
+     * @throws java.util.NoSuchElementException if no registry with the key is found
+     * @throws IllegalArgumentException if the registry is not available yet
+     */
+    // Future note: We should have no trouble removing this generic qualifier when
+    // registry types no longer have to be "keyed" as it shouldn't break ABI or API.
+    <T extends Keyed> Registry<T> getRegistry(RegistryKey<T> registryKey);
+}

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

@@ -0,0 +1,12 @@
+package io.papermc.paper.registry;
+
+import java.util.Optional;
+import java.util.ServiceLoader;
+
+final class RegistryAccessHolder {
+
+    static final Optional<RegistryAccess> INSTANCE = ServiceLoader.load(RegistryAccess.class).findFirst();
+
+    private RegistryAccessHolder() {
+    }
+}

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

@@ -12,6 +12,17 @@ record RegistryKeyImpl<T>(Key key) implements RegistryKey<T> {
 
     static final Set<RegistryKey<?>> REGISTRY_KEYS = Sets.newIdentityHashSet();
 
+    // override equals and hashCode to this can be used to simulate an "identity" hashmap
+    @Override
+    public boolean equals(final @Nullable Object obj) {
+        return obj == this;
+    }
+
+    @Override
+    public int hashCode() {
+        return System.identityHashCode(this);
+    }
+
     static <T> RegistryKey<T> create(@Subst("some_key") final String key) {
         final RegistryKey<T> registryKey = createInternal(key);
         REGISTRY_KEYS.add(registryKey);