#1085: Add RegistryAware to indicate better that not all registry items are registered

src/main/java/org/bukkit/Art.java

@@ -4,6 +4,7 @@ import com.google.common.base.Preconditions;
 import com.google.common.collect.Lists;
 import java.util.Locale;
 import org.bukkit.packs.DataPack;
+import org.bukkit.registry.RegistryAware;
 import org.bukkit.util.OldEnum;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
@@ -16,7 +17,7 @@ import org.jetbrains.annotations.Nullable;
  * There may be additional arts present in the server, for example from a {@link DataPack}
  * which can be accessed via {@link Registry#ART}.
  */
-public interface Art extends OldEnum<Art>, Keyed {
+public interface Art extends OldEnum<Art>, Keyed, RegistryAware {
 
     Art KEBAB = getArt("kebab");
     Art AZTEC = getArt("aztec");
@@ -88,6 +89,18 @@ public interface Art extends OldEnum<Art>, Keyed {
      */
     int getBlockHeight();
 
+    /**
+     * {@inheritDoc}
+     *
+     * @see #getKeyOrThrow()
+     * @see #isRegistered()
+     * @deprecated A key might not always be present, use {@link #getKeyOrThrow()} instead.
+     */
+    @NotNull
+    @Override
+    @Deprecated(since = "1.21.4")
+    NamespacedKey getKey();
+
     /**
      * Get the ID of this painting.
      *

src/main/java/org/bukkit/Fluid.java

@@ -3,13 +3,14 @@ package org.bukkit;
 import com.google.common.base.Preconditions;
 import com.google.common.collect.Lists;
 import java.util.Locale;
+import org.bukkit.registry.RegistryAware;
 import org.bukkit.util.OldEnum;
 import org.jetbrains.annotations.NotNull;
 
 /**
  * Represents a fluid type.
  */
-public interface Fluid extends OldEnum<Fluid>, Keyed {
+public interface Fluid extends OldEnum<Fluid>, Keyed, RegistryAware {
 
     /**
      * No fluid.
@@ -37,6 +38,18 @@ public interface Fluid extends OldEnum<Fluid>, Keyed {
         return Registry.FLUID.getOrThrow(NamespacedKey.minecraft(key));
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @see #getKeyOrThrow()
+     * @see #isRegistered()
+     * @deprecated A key might not always be present, use {@link #getKeyOrThrow()} instead.
+     */
+    @NotNull
+    @Override
+    @Deprecated(since = "1.21.4")
+    NamespacedKey getKey();
+
     /**
      * @param name of the fluid.
      * @return the fluid with the given name.

src/main/java/org/bukkit/GameEvent.java

@@ -3,13 +3,14 @@ package org.bukkit;
 import com.google.common.collect.Lists;
 import java.util.Collection;
 import java.util.Collections;
+import org.bukkit.registry.RegistryAware;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 /**
  * Represents a generic Mojang game event.
  */
-public abstract class GameEvent implements Keyed {
+public abstract class GameEvent implements Keyed, RegistryAware {
 
     public static final GameEvent BLOCK_ACTIVATE = getEvent("block_activate");
     public static final GameEvent BLOCK_ATTACH = getEvent("block_attach");
@@ -112,6 +113,18 @@ public abstract class GameEvent implements Keyed {
     public static final GameEvent RESONATE_14 = getEvent("resonate_14");
     public static final GameEvent RESONATE_15 = getEvent("resonate_15");
 
+    /**
+     * {@inheritDoc}
+     *
+     * @see #getKeyOrThrow()
+     * @see #isRegistered()
+     * @deprecated A key might not always be present, use {@link #getKeyOrThrow()} instead.
+     */
+    @NotNull
+    @Override
+    @Deprecated(since = "1.21.4")
+    public abstract NamespacedKey getKey();
+
     /**
      * Returns a {@link GameEvent} by a {@link NamespacedKey}.
      *

src/main/java/org/bukkit/JukeboxSong.java

@@ -1,5 +1,6 @@
 package org.bukkit;
 
+import org.bukkit.registry.RegistryAware;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 
@@ -7,7 +8,7 @@ import org.jetbrains.annotations.NotNull;
  * Represents a song which may play in a Jukebox.
  */
 @ApiStatus.Experimental
-public interface JukeboxSong extends Keyed, Translatable {
+public interface JukeboxSong extends Keyed, Translatable, RegistryAware {
 
     public static final JukeboxSong THIRTEEN = get("13");
     public static final JukeboxSong CAT = get("cat");
@@ -33,4 +34,16 @@ public interface JukeboxSong extends Keyed, Translatable {
     private static JukeboxSong get(@NotNull String key) {
         return Registry.JUKEBOX_SONG.getOrThrow(NamespacedKey.minecraft(key));
     }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @see #getKeyOrThrow()
+     * @see #isRegistered()
+     * @deprecated A key might not always be present, use {@link #getKeyOrThrow()} instead.
+     */
+    @NotNull
+    @Override
+    @Deprecated(since = "1.21.4")
+    NamespacedKey getKey();
 }

src/main/java/org/bukkit/Material.java

@@ -128,6 +128,7 @@ import org.bukkit.inventory.ItemStack;
 import org.bukkit.inventory.ItemType;
 import org.bukkit.inventory.meta.ItemMeta;
 import org.bukkit.material.MaterialData;
+import org.bukkit.registry.RegistryAware;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
@@ -135,7 +136,7 @@ import org.jetbrains.annotations.Nullable;
 /**
  * An enum of all material IDs accepted by the official server and client
  */
-public enum Material implements Keyed, Translatable {
+public enum Material implements Keyed, Translatable, RegistryAware {
     //<editor-fold desc="Materials" defaultstate="collapsed">
     AIR(9648, 0),
     STONE(22948),
@@ -4839,11 +4840,36 @@ public enum Material implements Keyed, Translatable {
         return legacy;
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @see #getKeyOrThrow()
+     * @see #isRegistered()
+     * @deprecated A key might not always be present, use {@link #getKeyOrThrow()} instead.
+     */
     @NotNull
     @Override
+    @Deprecated(since = "1.21.4")
     public NamespacedKey getKey() {
-        Preconditions.checkArgument(!legacy, "Cannot get key of Legacy Material");
-        return key;
+        return getKeyOrThrow();
+    }
+
+    @NotNull
+    @Override
+    public NamespacedKey getKeyOrThrow() {
+        Preconditions.checkState(isRegistered(), "Cannot get key of this registry item, because it is not registered. Use #isRegistered() before calling this method.");
+        return this.key;
+    }
+
+    @Nullable
+    @Override
+    public NamespacedKey getKeyOrNull() {
+        return this.key;
+    }
+
+    @Override
+    public boolean isRegistered() {
+        return !legacy;
     }
 
     /**

src/main/java/org/bukkit/MusicInstrument.java

@@ -3,10 +3,11 @@ package org.bukkit;
 import com.google.common.collect.Lists;
 import java.util.Collection;
 import java.util.Collections;
+import org.bukkit.registry.RegistryAware;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
-public abstract class MusicInstrument implements Keyed {
+public abstract class MusicInstrument implements Keyed, RegistryAware {
 
     public static final MusicInstrument PONDER_GOAT_HORN = getInstrument("ponder_goat_horn");
     public static final MusicInstrument SING_GOAT_HORN = getInstrument("sing_goat_horn");
@@ -17,6 +18,18 @@ public abstract class MusicInstrument implements Keyed {
     public static final MusicInstrument YEARN_GOAT_HORN = getInstrument("yearn_goat_horn");
     public static final MusicInstrument DREAM_GOAT_HORN = getInstrument("dream_goat_horn");
 
+    /**
+     * {@inheritDoc}
+     *
+     * @see #getKeyOrThrow()
+     * @see #isRegistered()
+     * @deprecated A key might not always be present, use {@link #getKeyOrThrow()} instead.
+     */
+    @NotNull
+    @Override
+    @Deprecated(since = "1.21.4")
+    public abstract NamespacedKey getKey();
+
     /**
      * Returns a {@link MusicInstrument} by a {@link NamespacedKey}.
      *

src/main/java/org/bukkit/Particle.java

@@ -3,10 +3,12 @@ package org.bukkit;
 import com.google.common.base.Preconditions;
 import org.bukkit.block.data.BlockData;
 import org.bukkit.inventory.ItemStack;
+import org.bukkit.registry.RegistryAware;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
-public enum Particle implements Keyed {
+public enum Particle implements Keyed, RegistryAware {
     POOF("poof"),
     EXPLOSION("explosion"),
     EXPLOSION_EMITTER("explosion_emitter"),
@@ -198,12 +200,34 @@ public enum Particle implements Keyed {
 
     @NotNull
     @Override
-    public NamespacedKey getKey() {
-        if (key == null) {
-            throw new UnsupportedOperationException("Cannot get key from legacy particle");
-        }
+    public NamespacedKey getKeyOrThrow() {
+        Preconditions.checkState(isRegistered(), "Cannot get key of this registry item, because it is not registered. Use #isRegistered() before calling this method.");
+        return this.key;
+    }
 
-        return key;
+    @Nullable
+    @Override
+    public NamespacedKey getKeyOrNull() {
+        return this.key;
+    }
+
+    @Override
+    public boolean isRegistered() {
+        return this.key != null;
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @see #getKeyOrThrow()
+     * @see #isRegistered()
+     * @deprecated A key might not always be present, use {@link #getKeyOrThrow()} instead.
+     */
+    @NotNull
+    @Override
+    @Deprecated(since = "1.21.4")
+    public NamespacedKey getKey() {
+        return getKeyOrThrow();
     }
 
     /**

src/main/java/org/bukkit/Sound.java

@@ -4,6 +4,7 @@ import com.google.common.base.Preconditions;
 import com.google.common.collect.Lists;
 import java.util.Locale;
 import org.bukkit.packs.DataPack;
+import org.bukkit.registry.RegistryAware;
 import org.bukkit.util.OldEnum;
 import org.jetbrains.annotations.NotNull;
 
@@ -20,7 +21,7 @@ import org.jetbrains.annotations.NotNull;
  * guarantee values will not be removed from this interface. As such, you should not
  * depend on the ordinal values of this class.
  */
-public interface Sound extends OldEnum<Sound>, Keyed {
+public interface Sound extends OldEnum<Sound>, Keyed, RegistryAware {
 
     Sound AMBIENT_BASALT_DELTAS_ADDITIONS = getSound("ambient.basalt_deltas.additions");
     Sound AMBIENT_BASALT_DELTAS_LOOP = getSound("ambient.basalt_deltas.loop");
@@ -1679,6 +1680,18 @@ public interface Sound extends OldEnum<Sound>, Keyed {
         return Registry.SOUNDS.getOrThrow(NamespacedKey.minecraft(key));
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @see #getKeyOrThrow()
+     * @see #isRegistered()
+     * @deprecated A key might not always be present, use {@link #getKeyOrThrow()} instead.
+     */
+    @NotNull
+    @Override
+    @Deprecated(since = "1.21.4")
+    NamespacedKey getKey();
+
     /**
      * @param name of the sound.
      * @return the sound with the given name.

src/main/java/org/bukkit/attribute/Attribute.java

@@ -8,13 +8,14 @@ import org.bukkit.Keyed;
 import org.bukkit.NamespacedKey;
 import org.bukkit.Registry;
 import org.bukkit.Translatable;
+import org.bukkit.registry.RegistryAware;
 import org.bukkit.util.OldEnum;
 import org.jetbrains.annotations.NotNull;
 
 /**
  * Types of attributes which may be present on an {@link Attributable}.
  */
-public interface Attribute extends OldEnum<Attribute>, Keyed, Translatable {
+public interface Attribute extends OldEnum<Attribute>, Keyed, Translatable, RegistryAware {
 
     /**
      * Maximum health of an Entity.
@@ -150,6 +151,18 @@ public interface Attribute extends OldEnum<Attribute>, Keyed, Translatable {
         return Registry.ATTRIBUTE.getOrThrow(NamespacedKey.minecraft(key));
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @see #getKeyOrThrow()
+     * @see #isRegistered()
+     * @deprecated A key might not always be present, use {@link #getKeyOrThrow()} instead.
+     */
+    @NotNull
+    @Override
+    @Deprecated(since = "1.21.4")
+    NamespacedKey getKey();
+
     /**
      * @param name of the attribute.
      * @return the attribute with the given name.

src/main/java/org/bukkit/block/Biome.java

@@ -9,6 +9,7 @@ import org.bukkit.Keyed;
 import org.bukkit.NamespacedKey;
 import org.bukkit.Registry;
 import org.bukkit.packs.DataPack;
+import org.bukkit.registry.RegistryAware;
 import org.bukkit.util.OldEnum;
 import org.jetbrains.annotations.NotNull;
 
@@ -20,7 +21,7 @@ import org.jetbrains.annotations.NotNull;
  * There may be additional biomes present in the server, for example from a {@link DataPack}
  * which can be accessed via {@link Registry#BIOME}.
  */
-public interface Biome extends OldEnum<Biome>, Keyed {
+public interface Biome extends OldEnum<Biome>, Keyed, RegistryAware {
 
     Biome OCEAN = getBiome("ocean");
     Biome PLAINS = getBiome("plains");
@@ -101,6 +102,18 @@ public interface Biome extends OldEnum<Biome>, Keyed {
         return Registry.BIOME.getOrThrow(NamespacedKey.minecraft(key));
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @see #getKeyOrThrow()
+     * @see #isRegistered()
+     * @deprecated A key might not always be present, use {@link #getKeyOrThrow()} instead.
+     */
+    @NotNull
+    @Override
+    @Deprecated(since = "1.21.4")
+    NamespacedKey getKey();
+
     /**
      * @param name of the biome.
      * @return the biome with the given name.

src/main/java/org/bukkit/block/BlockType.java

@@ -117,6 +117,7 @@ import org.bukkit.block.data.type.WallHangingSign;
 import org.bukkit.block.data.type.WallSign;
 import org.bukkit.block.data.type.WallSkull;
 import org.bukkit.inventory.ItemType;
+import org.bukkit.registry.RegistryAware;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
@@ -129,7 +130,7 @@ import org.jetbrains.annotations.Nullable;
  * changes may occur. Do not use this API in plugins.
  */
 @ApiStatus.Internal
-public interface BlockType extends Keyed, Translatable {
+public interface BlockType extends Keyed, Translatable, RegistryAware {
 
     /**
      * Typed represents a subtype of {@link BlockType}s that have a known block
@@ -3602,6 +3603,18 @@ public interface BlockType extends Keyed, Translatable {
      */
     boolean isEnabledByFeature(@NotNull World world);
 
+    /**
+     * {@inheritDoc}
+     *
+     * @see #getKeyOrThrow()
+     * @see #isRegistered()
+     * @deprecated A key might not always be present, use {@link #getKeyOrThrow()} instead.
+     */
+    @NotNull
+    @Override
+    @Deprecated(since = "1.21.4")
+    NamespacedKey getKey();
+
     /**
      * Tries to convert this BlockType into a Material
      *

src/main/java/org/bukkit/block/banner/PatternType.java

@@ -6,12 +6,13 @@ import java.util.Locale;
 import org.bukkit.Keyed;
 import org.bukkit.NamespacedKey;
 import org.bukkit.Registry;
+import org.bukkit.registry.RegistryAware;
 import org.bukkit.util.OldEnum;
 import org.jetbrains.annotations.Contract;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
-public interface PatternType extends OldEnum<PatternType>, Keyed {
+public interface PatternType extends OldEnum<PatternType>, Keyed, RegistryAware {
     PatternType BASE = getType("base");
     PatternType SQUARE_BOTTOM_LEFT = getType("square_bottom_left");
     PatternType SQUARE_BOTTOM_RIGHT = getType("square_bottom_right");
@@ -56,9 +57,17 @@ public interface PatternType extends OldEnum<PatternType>, Keyed {
     PatternType FLOW = getType("flow");
     PatternType GUSTER = getType("guster");
 
-    @Override
+    /**
+     * {@inheritDoc}
+     *
+     * @see #getKeyOrThrow()
+     * @see #isRegistered()
+     * @deprecated A key might not always be present, use {@link #getKeyOrThrow()} instead.
+     */
     @NotNull
-    public NamespacedKey getKey();
+    @Override
+    @Deprecated(since = "1.21.4")
+    NamespacedKey getKey();
 
     /**
      * Returns the identifier used to represent

src/main/java/org/bukkit/damage/DamageType.java

@@ -4,6 +4,7 @@ import org.bukkit.Keyed;
 import org.bukkit.NamespacedKey;
 import org.bukkit.Registry;
 import org.bukkit.Translatable;
+import org.bukkit.registry.RegistryAware;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 
@@ -17,7 +18,7 @@ import org.jetbrains.annotations.NotNull;
  * @see <a href="https://minecraft.wiki/w/Damage_type">Minecraft Wiki</a>
  */
 @ApiStatus.Experimental
-public interface DamageType extends Keyed, Translatable {
+public interface DamageType extends Keyed, Translatable, RegistryAware {
 
     public static final DamageType IN_FIRE = getDamageType("in_fire");
     public static final DamageType CAMPFIRE = getDamageType("campfire");
@@ -117,4 +118,16 @@ public interface DamageType extends Keyed, Translatable {
      * @return the exhaustion
      */
     public float getExhaustion();
+
+    /**
+     * {@inheritDoc}
+     *
+     * @see #getKeyOrThrow()
+     * @see #isRegistered()
+     * @deprecated A key might not always be present, use {@link #getKeyOrThrow()} instead.
+     */
+    @NotNull
+    @Override
+    @Deprecated(since = "1.21.4")
+    NamespacedKey getKey();
 }

src/main/java/org/bukkit/enchantments/Enchantment.java

@@ -7,6 +7,7 @@ import org.bukkit.NamespacedKey;
 import org.bukkit.Registry;
 import org.bukkit.Translatable;
 import org.bukkit.inventory.ItemStack;
+import org.bukkit.registry.RegistryAware;
 import org.jetbrains.annotations.Contract;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
@@ -14,7 +15,7 @@ import org.jetbrains.annotations.Nullable;
 /**
  * The various type of enchantments that may be added to armour or weapons
  */
-public abstract class Enchantment implements Keyed, Translatable {
+public abstract class Enchantment implements Keyed, Translatable, RegistryAware {
     /**
      * Provides protection against environmental damage
      */
@@ -311,6 +312,18 @@ public abstract class Enchantment implements Keyed, Translatable {
      */
     public abstract boolean canEnchantItem(@NotNull ItemStack item);
 
+    /**
+     * {@inheritDoc}
+     *
+     * @see #getKeyOrThrow()
+     * @see #isRegistered()
+     * @deprecated A key might not always be present, use {@link #getKeyOrThrow()} instead.
+     */
+    @NotNull
+    @Override
+    @Deprecated(since = "1.21.4")
+    public abstract NamespacedKey getKey();
+
     /**
      * Gets the Enchantment at the specified key
      *

src/main/java/org/bukkit/entity/Cat.java

@@ -7,6 +7,7 @@ import org.bukkit.DyeColor;
 import org.bukkit.Keyed;
 import org.bukkit.NamespacedKey;
 import org.bukkit.Registry;
+import org.bukkit.registry.RegistryAware;
 import org.bukkit.util.OldEnum;
 import org.jetbrains.annotations.NotNull;
 
@@ -48,7 +49,7 @@ public interface Cat extends Tameable, Sittable {
     /**
      * Represents the various different cat types there are.
      */
-    interface Type extends OldEnum<Type>, Keyed {
+    interface Type extends OldEnum<Type>, Keyed, RegistryAware {
 
         Type TABBY = getType("tabby");
         Type BLACK = getType("black");
@@ -67,6 +68,18 @@ public interface Cat extends Tameable, Sittable {
             return Registry.CAT_VARIANT.getOrThrow(NamespacedKey.minecraft(key));
         }
 
+        /**
+         * {@inheritDoc}
+         *
+         * @see #getKeyOrThrow()
+         * @see #isRegistered()
+         * @deprecated A key might not always be present, use {@link #getKeyOrThrow()} instead.
+         */
+        @NotNull
+        @Override
+        @Deprecated(since = "1.21.4")
+        NamespacedKey getKey();
+
         /**
          * @param name of the cat type.
          * @return the cat type with the given name.

src/main/java/org/bukkit/entity/EntityType.java

@@ -39,11 +39,12 @@ import org.bukkit.entity.minecart.SpawnerMinecart;
 import org.bukkit.entity.minecart.StorageMinecart;
 import org.bukkit.inventory.ItemStack;
 import org.bukkit.potion.PotionEffectType;
+import org.bukkit.registry.RegistryAware;
 import org.jetbrains.annotations.Contract;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
-public enum EntityType implements Keyed, Translatable {
+public enum EntityType implements Keyed, Translatable, RegistryAware {
 
     // These strings MUST match the strings in nms.EntityTypes and are case sensitive.
     /**
@@ -388,12 +389,18 @@ public enum EntityType implements Keyed, Translatable {
         return name;
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @see #getKeyOrThrow()
+     * @see #isRegistered()
+     * @deprecated A key might not always be present, use {@link #getKeyOrThrow()} instead.
+     */
     @NotNull
     @Override
+    @Deprecated(since = "1.21.4")
     public NamespacedKey getKey() {
-        Preconditions.checkArgument(key != null, "EntityType doesn't have key! Is it UNKNOWN?");
-
-        return key;
+        return getKeyOrThrow();
     }
 
     @Nullable
@@ -476,4 +483,22 @@ public enum EntityType implements Keyed, Translatable {
     public boolean isEnabledByFeature(@NotNull World world) {
         return Bukkit.getDataPackManager().isEnabledByFeature(this, world);
     }
+
+    @NotNull
+    @Override
+    public NamespacedKey getKeyOrThrow() {
+        Preconditions.checkState(isRegistered(), "Cannot get key of this registry item, because it is not registered. Use #isRegistered() before calling this method.");
+        return this.key;
+    }
+
+    @Nullable
+    @Override
+    public NamespacedKey getKeyOrNull() {
+        return this.key;
+    }
+
+    @Override
+    public boolean isRegistered() {
+        return this != UNKNOWN;
+    }
 }

src/main/java/org/bukkit/entity/Frog.java

@@ -6,6 +6,7 @@ import java.util.Locale;
 import org.bukkit.Keyed;
 import org.bukkit.NamespacedKey;
 import org.bukkit.Registry;
+import org.bukkit.registry.RegistryAware;
 import org.bukkit.util.OldEnum;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
@@ -48,7 +49,7 @@ public interface Frog extends Animals {
     /**
      * Represents the variant of a frog - ie its color.
      */
-    interface Variant extends OldEnum<Variant>, Keyed {
+    interface Variant extends OldEnum<Variant>, Keyed, RegistryAware {
 
         /**
          * Temperate (brown-orange) frog.
@@ -68,6 +69,18 @@ public interface Frog extends Animals {
             return Registry.FROG_VARIANT.getOrThrow(NamespacedKey.minecraft(key));
         }
 
+        /**
+         * {@inheritDoc}
+         *
+         * @see #getKeyOrThrow()
+         * @see #isRegistered()
+         * @deprecated A key might not always be present, use {@link #getKeyOrThrow()} instead.
+         */
+        @NotNull
+        @Override
+        @Deprecated(since = "1.21.4")
+        NamespacedKey getKey();
+
         /**
          * @param name of the frog variant.
          * @return the frog variant with the given name.

src/main/java/org/bukkit/entity/Villager.java

@@ -9,6 +9,7 @@ import org.bukkit.Keyed;
 import org.bukkit.Location;
 import org.bukkit.NamespacedKey;
 import org.bukkit.Registry;
+import org.bukkit.registry.RegistryAware;
 import org.bukkit.util.OldEnum;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
@@ -287,7 +288,7 @@ public interface Villager extends AbstractVillager {
      * Represents Villager type, usually corresponding to what biome they spawn
      * in.
      */
-    interface Type extends OldEnum<Type>, Keyed {
+    interface Type extends OldEnum<Type>, Keyed, RegistryAware {
 
         Type DESERT = getType("desert");
         Type JUNGLE = getType("jungle");
@@ -302,6 +303,18 @@ public interface Villager extends AbstractVillager {
             return Registry.VILLAGER_TYPE.getOrThrow(NamespacedKey.minecraft(key));
         }
 
+        /**
+         * {@inheritDoc}
+         *
+         * @see #getKeyOrThrow()
+         * @see #isRegistered()
+         * @deprecated A key might not always be present, use {@link #getKeyOrThrow()} instead.
+         */
+        @NotNull
+        @Override
+        @Deprecated(since = "1.21.4")
+        NamespacedKey getKey();
+
         /**
          * @param name of the villager type.
          * @return the villager type with the given name.
@@ -330,7 +343,7 @@ public interface Villager extends AbstractVillager {
      * Represents the various different Villager professions there may be.
      * Villagers have different trading options depending on their profession,
      */
-    interface Profession extends OldEnum<Profession>, Keyed {
+    interface Profession extends OldEnum<Profession>, Keyed, RegistryAware {
 
         Profession NONE = getProfession("none");
         /**
@@ -409,6 +422,18 @@ public interface Villager extends AbstractVillager {
             return Registry.VILLAGER_PROFESSION.getOrThrow(NamespacedKey.minecraft(key));
         }
 
+        /**
+         * {@inheritDoc}
+         *
+         * @see #getKeyOrThrow()
+         * @see #isRegistered()
+         * @deprecated A key might not always be present, use {@link #getKeyOrThrow()} instead.
+         */
+        @NotNull
+        @Override
+        @Deprecated(since = "1.21.4")
+        NamespacedKey getKey();
+
         /**
          * @param name of the villager profession.
          * @return the villager profession with the given name.

src/main/java/org/bukkit/entity/Wolf.java

@@ -4,6 +4,7 @@ import org.bukkit.DyeColor;
 import org.bukkit.Keyed;
 import org.bukkit.NamespacedKey;
 import org.bukkit.Registry;
+import org.bukkit.registry.RegistryAware;
 import org.jetbrains.annotations.NotNull;
 
 /**
@@ -89,7 +90,7 @@ public interface Wolf extends Tameable, Sittable {
     /**
      * Represents the variant of a wolf.
      */
-    interface Variant extends Keyed {
+    interface Variant extends Keyed, RegistryAware {
 
         Variant PALE = getVariant("pale");
         Variant SPOTTED = getVariant("spotted");
@@ -105,5 +106,17 @@ public interface Wolf extends Tameable, Sittable {
         private static Variant getVariant(@NotNull String key) {
             return Registry.WOLF_VARIANT.getOrThrow(NamespacedKey.minecraft(key));
         }
+
+        /**
+         * {@inheritDoc}
+         *
+         * @see #getKeyOrThrow()
+         * @see #isRegistered()
+         * @deprecated A key might not always be present, use {@link #getKeyOrThrow()} instead.
+         */
+        @NotNull
+        @Override
+        @Deprecated(since = "1.21.4")
+        NamespacedKey getKey();
     }
 }

src/main/java/org/bukkit/entity/memory/MemoryKey.java

@@ -1,5 +1,6 @@
 package org.bukkit.entity.memory;
 
+import com.google.common.base.Preconditions;
 import java.util.HashMap;
 import java.util.HashSet;
 import java.util.Map;
@@ -8,6 +9,7 @@ import java.util.UUID;
 import org.bukkit.Keyed;
 import org.bukkit.Location;
 import org.bukkit.NamespacedKey;
+import org.bukkit.registry.RegistryAware;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
@@ -17,7 +19,7 @@ import org.jetbrains.annotations.Nullable;
  *
  * @param <T> the class type of the memory value
  */
-public final class MemoryKey<T> implements Keyed {
+public final class MemoryKey<T> implements Keyed, RegistryAware {
 
     private final NamespacedKey namespacedKey;
     private final Class<T> tClass;
@@ -30,8 +32,34 @@ public final class MemoryKey<T> implements Keyed {
 
     @NotNull
     @Override
+    public NamespacedKey getKeyOrThrow() {
+        Preconditions.checkState(isRegistered(), "Cannot get key of this registry item, because it is not registered. Use #isRegistered() before calling this method.");
+        return this.namespacedKey;
+    }
+
+    @Nullable
+    @Override
+    public NamespacedKey getKeyOrNull() {
+        return this.namespacedKey;
+    }
+
+    @Override
+    public boolean isRegistered() {
+        return this.namespacedKey != null;
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @see #getKeyOrThrow()
+     * @see #isRegistered()
+     * @deprecated A key might not always be present, use {@link #getKeyOrThrow()} instead.
+     */
+    @NotNull
+    @Override
+    @Deprecated(since = "1.21.4")
     public NamespacedKey getKey() {
-        return namespacedKey;
+        return getKeyOrThrow();
     }
 
     /**

src/main/java/org/bukkit/generator/structure/Structure.java

@@ -3,6 +3,7 @@ package org.bukkit.generator.structure;
 import org.bukkit.Keyed;
 import org.bukkit.NamespacedKey;
 import org.bukkit.Registry;
+import org.bukkit.registry.RegistryAware;
 import org.jetbrains.annotations.NotNull;
 
 /**
@@ -12,7 +13,7 @@ import org.jetbrains.annotations.NotNull;
  * there might be additional structures present (for example structures added by
  * data packs), which can be received via {@link Registry#STRUCTURE}.
  */
-public abstract class Structure implements Keyed {
+public abstract class Structure implements Keyed, RegistryAware {
 
     public static final Structure PILLAGER_OUTPOST = getStructure("pillager_outpost");
     public static final Structure MINESHAFT = getStructure("mineshaft");
@@ -61,4 +62,16 @@ public abstract class Structure implements Keyed {
      */
     @NotNull
     public abstract StructureType getStructureType();
+
+    /**
+     * {@inheritDoc}
+     *
+     * @see #getKeyOrThrow()
+     * @see #isRegistered()
+     * @deprecated A key might not always be present, use {@link #getKeyOrThrow()} instead.
+     */
+    @NotNull
+    @Override
+    @Deprecated(since = "1.21.4")
+    public abstract NamespacedKey getKey();
 }

src/main/java/org/bukkit/generator/structure/StructureType.java

@@ -3,6 +3,7 @@ package org.bukkit.generator.structure;
 import org.bukkit.Keyed;
 import org.bukkit.NamespacedKey;
 import org.bukkit.Registry;
+import org.bukkit.registry.RegistryAware;
 import org.jetbrains.annotations.NotNull;
 
 /**
@@ -13,7 +14,7 @@ import org.jetbrains.annotations.NotNull;
  * structure types added by data packs), which can be received via
  * {@link Registry#STRUCTURE_TYPE}.
  */
-public abstract class StructureType implements Keyed {
+public abstract class StructureType implements Keyed, RegistryAware {
 
     public static final StructureType BURIED_TREASURE = getStructureType("buried_treasure");
     public static final StructureType DESERT_PYRAMID = getStructureType("desert_pyramid");
@@ -36,4 +37,16 @@ public abstract class StructureType implements Keyed {
     private static StructureType getStructureType(@NotNull String name) {
         return Registry.STRUCTURE_TYPE.getOrThrow(NamespacedKey.minecraft(name));
     }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @see #getKeyOrThrow()
+     * @see #isRegistered()
+     * @deprecated A key might not always be present, use {@link #getKeyOrThrow()} instead.
+     */
+    @NotNull
+    @Override
+    @Deprecated(since = "1.21.4")
+    public abstract NamespacedKey getKey();
 }

src/main/java/org/bukkit/inventory/ItemType.java

@@ -35,6 +35,7 @@ import org.bukkit.inventory.meta.SkullMeta;
 import org.bukkit.inventory.meta.SpawnEggMeta;
 import org.bukkit.inventory.meta.SuspiciousStewMeta;
 import org.bukkit.inventory.meta.TropicalFishBucketMeta;
+import org.bukkit.registry.RegistryAware;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
@@ -47,7 +48,7 @@ import org.jetbrains.annotations.Nullable;
  * changes may occur. Do not use this API in plugins.
  */
 @ApiStatus.Internal
-public interface ItemType extends Keyed, Translatable {
+public interface ItemType extends Keyed, Translatable, RegistryAware {
 
     /**
      * Typed represents a subtype of {@link ItemType}s that have a known item meta type
@@ -2400,6 +2401,18 @@ public interface ItemType extends Keyed, Translatable {
      */
     boolean isEnabledByFeature(@NotNull World world);
 
+    /**
+     * {@inheritDoc}
+     *
+     * @see #getKeyOrThrow()
+     * @see #isRegistered()
+     * @deprecated A key might not always be present, use {@link #getKeyOrThrow()} instead.
+     */
+    @NotNull
+    @Override
+    @Deprecated(since = "1.21.4")
+    NamespacedKey getKey();
+
     /**
      * Tries to convert this ItemType into a Material
      *

src/main/java/org/bukkit/inventory/MenuType.java

@@ -17,6 +17,7 @@ import org.bukkit.inventory.view.StonecutterView;
 import org.bukkit.inventory.view.builder.InventoryViewBuilder;
 import org.bukkit.inventory.view.builder.LocationInventoryViewBuilder;
 import org.bukkit.inventory.view.builder.MerchantInventoryViewBuilder;
+import org.bukkit.registry.RegistryAware;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 
@@ -25,7 +26,7 @@ import org.jetbrains.annotations.NotNull;
  * created and viewed by the player.
  */
 @ApiStatus.Experimental
-public interface MenuType extends Keyed {
+public interface MenuType extends Keyed, RegistryAware {
 
     /**
      * A MenuType which represents a chest with 1 row.
@@ -197,6 +198,18 @@ public interface MenuType extends Keyed {
     @NotNull
     Class<? extends InventoryView> getInventoryViewClass();
 
+    /**
+     * {@inheritDoc}
+     *
+     * @see #getKeyOrThrow()
+     * @see #isRegistered()
+     * @deprecated A key might not always be present, use {@link #getKeyOrThrow()} instead.
+     */
+    @NotNull
+    @Override
+    @Deprecated(since = "1.21.4")
+    NamespacedKey getKey();
+
     @NotNull
     private static <T extends MenuType> T get(@NotNull final String key) {
         return (T) Registry.MENU.getOrThrow(NamespacedKey.minecraft(key));

src/main/java/org/bukkit/inventory/meta/trim/TrimMaterial.java

@@ -5,12 +5,13 @@ import org.bukkit.Material;
 import org.bukkit.NamespacedKey;
 import org.bukkit.Registry;
 import org.bukkit.Translatable;
+import org.bukkit.registry.RegistryAware;
 import org.jetbrains.annotations.NotNull;
 
 /**
  * Represents a material that may be used in an {@link ArmorTrim}.
  */
-public interface TrimMaterial extends Keyed, Translatable {
+public interface TrimMaterial extends Keyed, Translatable, RegistryAware {
 
     /**
      * {@link Material#QUARTZ}.
@@ -61,4 +62,16 @@ public interface TrimMaterial extends Keyed, Translatable {
     private static TrimMaterial getTrimMaterial(@NotNull String key) {
         return Registry.TRIM_MATERIAL.getOrThrow(NamespacedKey.minecraft(key));
     }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @see #getKeyOrThrow()
+     * @see #isRegistered()
+     * @deprecated A key might not always be present, use {@link #getKeyOrThrow()} instead.
+     */
+    @NotNull
+    @Override
+    @Deprecated(since = "1.21.4")
+    NamespacedKey getKey();
 }

src/main/java/org/bukkit/inventory/meta/trim/TrimPattern.java

@@ -5,12 +5,13 @@ import org.bukkit.Material;
 import org.bukkit.NamespacedKey;
 import org.bukkit.Registry;
 import org.bukkit.Translatable;
+import org.bukkit.registry.RegistryAware;
 import org.jetbrains.annotations.NotNull;
 
 /**
  * Represents a pattern that may be used in an {@link ArmorTrim}.
  */
-public interface TrimPattern extends Keyed, Translatable {
+public interface TrimPattern extends Keyed, Translatable, RegistryAware {
 
     /**
      * {@link Material#SENTRY_ARMOR_TRIM_SMITHING_TEMPLATE}.
@@ -89,4 +90,16 @@ public interface TrimPattern extends Keyed, Translatable {
     private static TrimPattern getTrimPattern(@NotNull String key) {
         return Registry.TRIM_PATTERN.getOrThrow(NamespacedKey.minecraft(key));
     }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @see #getKeyOrThrow()
+     * @see #isRegistered()
+     * @deprecated A key might not always be present, use {@link #getKeyOrThrow()} instead.
+     */
+    @NotNull
+    @Override
+    @Deprecated(since = "1.21.4")
+    NamespacedKey getKey();
 }

src/main/java/org/bukkit/map/MapCursor.java

@@ -6,6 +6,7 @@ import java.util.Locale;
 import org.bukkit.Keyed;
 import org.bukkit.NamespacedKey;
 import org.bukkit.Registry;
+import org.bukkit.registry.RegistryAware;
 import org.bukkit.util.OldEnum;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
@@ -229,7 +230,7 @@ public final class MapCursor {
      * index in the file './assets/minecraft/textures/map/map_icons.png' from minecraft.jar or from a
      * resource pack.
      */
-    public interface Type extends OldEnum<Type>, Keyed {
+    public interface Type extends OldEnum<Type>, Keyed, RegistryAware {
 
         Type PLAYER = getType("player");
         Type FRAME = getType("frame");
@@ -272,6 +273,18 @@ public final class MapCursor {
             return Registry.MAP_DECORATION_TYPE.getOrThrow(NamespacedKey.minecraft(key));
         }
 
+        /**
+         * {@inheritDoc}
+         *
+         * @see #getKeyOrThrow()
+         * @see #isRegistered()
+         * @deprecated A key might not always be present, use {@link #getKeyOrThrow()} instead.
+         */
+        @NotNull
+        @Override
+        @Deprecated(since = "1.21.4")
+        NamespacedKey getKey();
+
         /**
          * Gets the internal value of the cursor.
          *

src/main/java/org/bukkit/potion/PotionEffectType.java

@@ -10,6 +10,7 @@ import org.bukkit.Keyed;
 import org.bukkit.NamespacedKey;
 import org.bukkit.Registry;
 import org.bukkit.Translatable;
+import org.bukkit.registry.RegistryAware;
 import org.jetbrains.annotations.Contract;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
@@ -17,7 +18,7 @@ import org.jetbrains.annotations.Nullable;
 /**
  * Represents a type of potion and its effect on an entity.
  */
-public abstract class PotionEffectType implements Keyed, Translatable {
+public abstract class PotionEffectType implements Keyed, Translatable, RegistryAware {
     private static final BiMap<Integer, PotionEffectType> ID_MAP = HashBiMap.create();
 
     /**
@@ -265,6 +266,18 @@ public abstract class PotionEffectType implements Keyed, Translatable {
     @NotNull
     public abstract Color getColor();
 
+    /**
+     * {@inheritDoc}
+     *
+     * @see #getKeyOrThrow()
+     * @see #isRegistered()
+     * @deprecated A key might not always be present, use {@link #getKeyOrThrow()} instead.
+     */
+    @NotNull
+    @Override
+    @Deprecated(since = "1.21.4")
+    public abstract NamespacedKey getKey();
+
     /**
      * Returns the duration modifier applied to effects of this type.
      *

src/main/java/org/bukkit/potion/PotionType.java

@@ -1,11 +1,13 @@
 package org.bukkit.potion;
 
+import com.google.common.base.Preconditions;
 import com.google.common.base.Suppliers;
 import java.util.List;
 import java.util.function.Supplier;
 import org.bukkit.Bukkit;
 import org.bukkit.Keyed;
 import org.bukkit.NamespacedKey;
+import org.bukkit.registry.RegistryAware;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
@@ -14,7 +16,7 @@ import org.jetbrains.annotations.Nullable;
  * This enum reflects and matches each potion state that can be obtained from
  * the Creative mode inventory
  */
-public enum PotionType implements Keyed {
+public enum PotionType implements Keyed, RegistryAware {
     WATER("water"),
     MUNDANE("mundane"),
     THICK("thick"),
@@ -124,6 +126,24 @@ public enum PotionType implements Keyed {
         return internalPotionDataSupplier.get().getMaxLevel();
     }
 
+    @NotNull
+    @Override
+    public NamespacedKey getKeyOrThrow() {
+        Preconditions.checkState(isRegistered(), "Cannot get key of this registry item, because it is not registered. Use #isRegistered() before calling this method.");
+        return this.key;
+    }
+
+    @Nullable
+    @Override
+    public NamespacedKey getKeyOrNull() {
+        return this.key;
+    }
+
+    @Override
+    public boolean isRegistered() {
+        return this.key != null;
+    }
+
     /**
      * @param effectType the effect to get by
      * @return the matching potion type
@@ -141,10 +161,18 @@ public enum PotionType implements Keyed {
         return null;
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @see #getKeyOrThrow()
+     * @see #isRegistered()
+     * @deprecated A key might not always be present, use {@link #getKeyOrThrow()} instead.
+     */
     @NotNull
     @Override
+    @Deprecated(since = "1.21.4")
     public NamespacedKey getKey() {
-        return key;
+        return getKeyOrThrow();
     }
 
     /**

src/main/java/org/bukkit/registry/RegistryAware.java

@@ -0,0 +1,47 @@
+package org.bukkit.registry;
+
+import org.bukkit.NamespacedKey;
+import org.bukkit.Registry;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Indicates that instances of a class may be registered to the server and have a key associated with them.
+ *
+ * @see Registry
+ */
+public interface RegistryAware {
+
+    /**
+     * Gets the key of this instance if it is registered otherwise throws an error.
+     * <br>
+     * This is a convenience method and plugins should always check {@link #isRegistered()} before using this method.
+     *
+     * @return the key with which this instance is registered.
+     * @throws IllegalStateException if this instance is not registered.
+     * @see #isRegistered()
+     * @see #getKeyOrNull()
+     * @see Registry
+     */
+    @NotNull
+    NamespacedKey getKeyOrThrow();
+
+    /**
+     * Gets the key of this instance if it is registered otherwise returns {@code null}.
+     *
+     * @return the key with which this instance is registered or {@code null} if not registered.
+     * @see #getKeyOrThrow()
+     * @see Registry
+     */
+    @Nullable
+    NamespacedKey getKeyOrNull();
+
+    /**
+     * Returns whether this instance is register in a registry and therefore has a key or not.
+     *
+     * @return true, if this instance is registered. Otherwise, false.
+     * @see #getKeyOrThrow()
+     * @see Registry
+     */
+    boolean isRegistered();
+}

src/main/java/org/bukkit/registry/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * Class related to {@link org.bukkit.Registry}
+ */
+package org.bukkit.registry;