Release ItemType and BlockType (#12708)

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

@@ -76,16 +76,14 @@ public sealed interface RegistryKey<T> extends Keyed permits RegistryKeyImpl {
      */
     RegistryKey<PotionEffectType> MOB_EFFECT = create("mob_effect");
     /**
-     * @apiNote DO NOT USE
+     * Built-in registry for block types.
+     * @see io.papermc.paper.registry.keys.BlockTypeKeys
      */
-    @ApiStatus.Internal
     RegistryKey<BlockType> BLOCK = create("block");
     /**
-     * @apiNote use preferably only in the context of registry entries.
+     * Built-in registry for item types.
-     * @see io.papermc.paper.registry.data
      * @see io.papermc.paper.registry.keys.ItemTypeKeys
      */
-    @ApiStatus.Experimental // Paper - already required for registry builders
     RegistryKey<ItemType> ITEM = create("item");
     /**
      * Built-in registry for villager professions.

paper-api/src/main/java/org/bukkit/block/BlockType.java

@@ -2,9 +2,10 @@ package org.bukkit.block;
 
 import java.util.Collection;
 import java.util.function.Consumer;
+import net.kyori.adventure.key.Key;
+import net.kyori.adventure.key.KeyPattern;
 import org.bukkit.Keyed;
 import org.bukkit.Material;
-import org.bukkit.NamespacedKey;
 import org.bukkit.Registry;
 import org.bukkit.Translatable;
 import org.bukkit.World;
@@ -82,7 +83,6 @@ import org.bukkit.block.data.type.MangrovePropagule;
 import org.bukkit.block.data.type.MossyCarpet;
 import org.bukkit.block.data.type.NoteBlock;
 import org.bukkit.block.data.type.Observer;
-import org.bukkit.block.data.type.PinkPetals;
 import org.bukkit.block.data.type.Piston;
 import org.bukkit.block.data.type.PistonHead;
 import org.bukkit.block.data.type.PitcherCrop;
@@ -122,18 +122,14 @@ 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.jetbrains.annotations.NotNull;
-import org.jetbrains.annotations.Nullable;
 import org.jetbrains.annotations.Unmodifiable;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 /**
- * While this API is in a public interface, it is not intended for use by
+ * Represents a block type.
- * plugins until further notice. The purpose of these types is to make
- * {@link Material} more maintenance friendly, but will in due time be the
- * official replacement for the aforementioned enum. Entirely incompatible
- * changes may occur. Do not use this API in plugins.
  */
-@org.jetbrains.annotations.ApiStatus.Experimental // Paper - data component API - already required for data component API
+@NullMarked
 public interface BlockType extends Keyed, Translatable, net.kyori.adventure.translation.Translatable, io.papermc.paper.world.flag.FeatureDependant { // Paper - add translatable & feature flag API
 
     /**
@@ -150,7 +146,6 @@ public interface BlockType extends Keyed, Translatable, net.kyori.adventure.tran
          *
          * @return the BlockData class of this BlockType
          */
-        @NotNull
         @Override
         Class<B> getBlockDataClass();
 
@@ -161,7 +156,6 @@ public interface BlockType extends Keyed, Translatable, net.kyori.adventure.tran
          * @param consumer consumer to run on new instance before returning
          * @return new data instance
          */
-        @NotNull
         B createBlockData(@Nullable Consumer<? super B> consumer);
 
         /**
@@ -170,7 +164,6 @@ public interface BlockType extends Keyed, Translatable, net.kyori.adventure.tran
          *
          * @return new data instance
          */
-        @NotNull
         @Override
         B createBlockData();
 
@@ -181,7 +174,7 @@ public interface BlockType extends Keyed, Translatable, net.kyori.adventure.tran
          * @return new block data collection
          */
         @Override
-        @Unmodifiable @NotNull Collection<B> createBlockDataStates();
+        @Unmodifiable Collection<B> createBlockDataStates();
 
         /**
          * Creates a new {@link BlockData} instance for this block type, with all
@@ -192,7 +185,6 @@ public interface BlockType extends Keyed, Translatable, net.kyori.adventure.tran
          * @return new data instance
          * @throws IllegalArgumentException if the specified data is not valid
          */
-        @NotNull
         B createBlockData(@Nullable String data);
     }
 
@@ -2411,10 +2403,10 @@ public interface BlockType extends Keyed, Translatable, net.kyori.adventure.tran
     // End generate - BlockType
     //</editor-fold>
 
-    @NotNull
+    @SuppressWarnings("unchecked")
-    private static <B extends BlockType> B getBlockType(@NotNull String key) {
+    private static <B extends BlockType> B getBlockType(@KeyPattern.Value final String key) {
         // Cast instead of using BlockType#typed, since block type can be a mock during testing and would return null
-        return (B) Registry.BLOCK.getOrThrow(NamespacedKey.minecraft(key));
+        return (B) Registry.BLOCK.getOrThrow(Key.key(Key.MINECRAFT_NAMESPACE, key));
     }
 
     /**
@@ -2422,7 +2414,6 @@ public interface BlockType extends Keyed, Translatable, net.kyori.adventure.tran
      *
      * @return the typed block type.
      */
-    @NotNull
     BlockType.Typed<BlockData> typed();
 
     /**
@@ -2432,8 +2423,7 @@ public interface BlockType extends Keyed, Translatable, net.kyori.adventure.tran
      * @param <B>          the generic type of the block data to type this block type with.
      * @return the typed block type.
      */
-    @NotNull
+    <B extends BlockData> BlockType.Typed<B> typed(Class<B> blockDataType);
-    <B extends BlockData> BlockType.Typed<B> typed(@NotNull Class<B> blockDataType);
 
     /**
      * Returns true if this BlockType has a corresponding {@link ItemType}.
@@ -2447,12 +2437,14 @@ public interface BlockType extends Keyed, Translatable, net.kyori.adventure.tran
      * Returns the corresponding {@link ItemType} for the given BlockType.
      * <p>
      * If there is no corresponding {@link ItemType} an error will be thrown.
+     * <p>This is <b>NOT</b> the same as the {@link ItemType} with the same key,
+     * but instead is the item associated with this block if this block
+     * can be represented with an item.</p>
      *
      * @return the corresponding ItemType
      * @see #hasItemType()
      * @see BlockData#getPlacementMaterial()
      */
-    @NotNull
     ItemType getItemType();
 
     /**
@@ -2460,7 +2452,6 @@ public interface BlockType extends Keyed, Translatable, net.kyori.adventure.tran
      *
      * @return the BlockData class of this BlockType
      */
-    @NotNull
     Class<? extends BlockData> getBlockDataClass();
 
     /**
@@ -2469,7 +2460,6 @@ public interface BlockType extends Keyed, Translatable, net.kyori.adventure.tran
      *
      * @return new data instance
      */
-    @NotNull
     BlockData createBlockData();
 
     /**
@@ -2478,7 +2468,7 @@ public interface BlockType extends Keyed, Translatable, net.kyori.adventure.tran
      *
      * @return new block data collection
      */
-    @Unmodifiable @NotNull Collection<? extends BlockData> createBlockDataStates();
+    @Unmodifiable Collection<? extends BlockData> createBlockDataStates();
 
     /**
      * Creates a new {@link BlockData} instance for this block type, with all
@@ -2489,7 +2479,6 @@ public interface BlockType extends Keyed, Translatable, net.kyori.adventure.tran
      * @return new data instance
      * @throws IllegalArgumentException if the specified data is not valid
      */
-    @NotNull
     BlockData createBlockData(@Nullable String data);
 
     /**
@@ -2607,7 +2596,7 @@ public interface BlockType extends Keyed, Translatable, net.kyori.adventure.tran
      * @deprecated use {@link io.papermc.paper.world.flag.FeatureFlagSetHolder#isEnabled(io.papermc.paper.world.flag.FeatureDependant)}
      */
     @Deprecated(forRemoval = true, since = "1.21.1") // Paper
-    boolean isEnabledByFeature(@NotNull World world);
+    boolean isEnabledByFeature(World world);
 
     /**
      * Tries to convert this BlockType into a Material
@@ -2619,21 +2608,17 @@ public interface BlockType extends Keyed, Translatable, net.kyori.adventure.tran
     @Deprecated(since = "1.20.6")
     Material asMaterial();
 
-    // Paper start - add Translatable
     /**
      * @deprecated use {@link #translationKey()} and {@link net.kyori.adventure.text.Component#translatable(net.kyori.adventure.translation.Translatable)}
      */
     @Deprecated(forRemoval = true)
     @Override
-    @NotNull String getTranslationKey();
+    String getTranslationKey();
-    // Paper end - add Translatable
 
-    // Paper start - hasCollision API
     /**
      * Checks if this block type has collision.
      * <p>
      * @return false if this block never has collision, true if it <b>might</b> have collision
      */
     boolean hasCollision();
-    // Paper end - hasCollision API
 }

paper-api/src/main/java/org/bukkit/inventory/ItemType.java

@@ -1,10 +1,13 @@
 package org.bukkit.inventory;
 
 import com.google.common.collect.Multimap;
+import io.papermc.paper.datacomponent.DataComponentType;
+import java.util.Set;
 import java.util.function.Consumer;
+import net.kyori.adventure.key.Key;
+import net.kyori.adventure.key.KeyPattern;
 import org.bukkit.Keyed;
 import org.bukkit.Material;
-import org.bukkit.NamespacedKey;
 import org.bukkit.Registry;
 import org.bukkit.Translatable;
 import org.bukkit.World;
@@ -36,17 +39,14 @@ import org.bukkit.inventory.meta.SpawnEggMeta;
 import org.bukkit.inventory.meta.SuspiciousStewMeta;
 import org.bukkit.inventory.meta.TropicalFishBucketMeta;
 import org.jetbrains.annotations.ApiStatus;
-import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Unmodifiable;
-import org.jetbrains.annotations.Nullable;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 /**
- * While this API is in a public interface, it is not intended for use by
+ * Represents an item type.
- * plugins until further notice. The purpose of these types is to make
- * {@link Material} more maintenance friendly, but will in due time be the
- * official replacement for the aforementioned enum. Entirely incompatible
- * changes may occur. Do not use this API in plugins.
  */
-@ApiStatus.Experimental // Paper - already required for registry builders
+@NullMarked
 public interface ItemType extends Keyed, Translatable, net.kyori.adventure.translation.Translatable, io.papermc.paper.world.flag.FeatureDependant { // Paper - add Translatable & feature flag API
 
     /**
@@ -54,7 +54,11 @@ public interface ItemType extends Keyed, Translatable, net.kyori.adventure.trans
      * at compile time.
      *
      * @param <M> the generic type of the item meta that represents the item type.
+     * @apiNote Do not use methods exclusive to this interface unless you are
+     * fine with them being possibly removed in the future.
      */
+    @ApiStatus.Experimental
+    @ApiStatus.NonExtendable
     interface Typed<M extends ItemMeta> extends ItemType {
 
         /**
@@ -63,7 +67,7 @@ public interface ItemType extends Keyed, Translatable, net.kyori.adventure.trans
          * @return the ItemMeta class of this ItemType
          */
         @Override
-        @NotNull
+        @ApiStatus.Experimental
         Class<M> getItemMetaClass();
 
         /**
@@ -73,7 +77,7 @@ public interface ItemType extends Keyed, Translatable, net.kyori.adventure.trans
          *                         May be null if no intent exists to mutate the item meta at this point.
          * @return the created and configured item stack.
          */
-        @NotNull
+        @ApiStatus.Experimental
         ItemStack createItemStack(@Nullable Consumer<? super M> metaConfigurator);
 
         /**
@@ -84,7 +88,7 @@ public interface ItemType extends Keyed, Translatable, net.kyori.adventure.trans
          *                         May be null if no intent exists to mutate the item meta at this point.
          * @return the created and configured item stack.
          */
-        @NotNull
+        @ApiStatus.Experimental
         ItemStack createItemStack(int amount, @Nullable Consumer<? super M> metaConfigurator);
     }
 
@@ -2923,18 +2927,19 @@ public interface ItemType extends Keyed, Translatable, net.kyori.adventure.trans
     // End generate - ItemType
     //</editor-fold>
 
-    @NotNull
+    @SuppressWarnings("unchecked")
-    private static <M extends ItemType> M getItemType(@NotNull String key) {
+    private static <M extends ItemType> M getItemType(@KeyPattern.Value final String key) {
         // Cast instead of using ItemType#typed, since item type can be a mock during testing and would return null
-        return (M) Registry.ITEM.getOrThrow(NamespacedKey.minecraft(key));
+        return (M) Registry.ITEM.getOrThrow(Key.key(Key.MINECRAFT_NAMESPACE, key));
     }
 
     /**
      * Yields this item type as a typed version of itself with a plain {@link ItemMeta} representing it.
      *
      * @return the typed item type.
+     * @apiNote The Typed interface is experimental and may be removed in future versions.
      */
-    @NotNull
+    @ApiStatus.Experimental
     Typed<ItemMeta> typed();
 
     /**
@@ -2943,16 +2948,16 @@ public interface ItemType extends Keyed, Translatable, net.kyori.adventure.trans
      * @param itemMetaType the class type of the {@link ItemMeta} to type this {@link ItemType} with.
      * @param <M> the generic type of the item meta to type this item type with.
      * @return the typed item type.
+     * @apiNote The Typed interface is experimental and may be removed in future versions.
      */
-    @NotNull
+    @ApiStatus.Experimental
-    <M extends ItemMeta> Typed<M> typed(@NotNull Class<M> itemMetaType);
+    <M extends ItemMeta> Typed<M> typed(Class<M> itemMetaType);
 
     /**
      * Constructs a new itemstack with this item type that has the amount 1.
      *
      * @return the constructed item stack.
      */
-    @NotNull
     ItemStack createItemStack();
 
     /**
@@ -2961,7 +2966,6 @@ public interface ItemType extends Keyed, Translatable, net.kyori.adventure.trans
      * @param amount the amount of the item stack.
      * @return the constructed item stack.
      */
-    @NotNull
     ItemStack createItemStack(int amount);
 
     /**
@@ -2976,11 +2980,12 @@ public interface ItemType extends Keyed, Translatable, net.kyori.adventure.trans
      * Returns the corresponding {@link BlockType} for the given ItemType.
      * <p>
      * If there is no corresponding {@link BlockType} an error will be thrown.
+     * <p>This is <b>NOT</b> the same as the {@link BlockType} with the same key,
+     * but instead is the block associated with this item if this item represents a block.</p>
      *
      * @return the corresponding BlockType
      * @see #hasBlockType()
      */
-    @NotNull
     BlockType getBlockType();
 
     /**
@@ -2988,7 +2993,6 @@ public interface ItemType extends Keyed, Translatable, net.kyori.adventure.trans
      *
      * @return the ItemMeta class of this ItemType
      */
-    @NotNull
     Class<? extends ItemMeta> getItemMetaClass();
 
     /**
@@ -3064,20 +3068,8 @@ public interface ItemType extends Keyed, Translatable, net.kyori.adventure.trans
      *
      * @return the item left behind when crafting, or null if nothing is.
      */
-    @Nullable
+    @Nullable ItemType getCraftingRemainingItem();
-    ItemType getCraftingRemainingItem();
 
-//    /**
-//     * Get the best suitable slot for this item type.
-//     *
-//     * For most items this will be {@link EquipmentSlot#HAND}.
-//     *
-//     * @return the best EquipmentSlot for this item type
-//     */
-//    @NotNull
-//    EquipmentSlot getEquipmentSlot();
-
-    // Paper start - improve default item attribute API
     /**
      * Return an immutable copy of all default {@link Attribute}s and their
      * {@link AttributeModifier}s.
@@ -3089,8 +3081,7 @@ public interface ItemType extends Keyed, Translatable, net.kyori.adventure.trans
      * @return the immutable {@link Multimap} with the respective default
      * Attributes and modifiers, or an empty map if no attributes are set.
      */
-    @NotNull @org.jetbrains.annotations.Unmodifiable Multimap<Attribute, AttributeModifier> getDefaultAttributeModifiers();
+    @Unmodifiable Multimap<Attribute, AttributeModifier> getDefaultAttributeModifiers();
-    // Paper end - improve default item attribute API
 
     /**
      * Return an immutable copy of all default {@link Attribute}s and their
@@ -3103,8 +3094,7 @@ public interface ItemType extends Keyed, Translatable, net.kyori.adventure.trans
      * @return the immutable {@link Multimap} with the respective default
      * Attributes and modifiers, or an empty map if no attributes are set.
      */
-    @NotNull
+    @Unmodifiable Multimap<Attribute, AttributeModifier> getDefaultAttributeModifiers(EquipmentSlot slot);
-    Multimap<Attribute, AttributeModifier> getDefaultAttributeModifiers(@NotNull EquipmentSlot slot);
 
     /**
      * Get the {@link CreativeCategory} to which this item type belongs.
@@ -3112,9 +3102,8 @@ public interface ItemType extends Keyed, Translatable, net.kyori.adventure.trans
      * @return the creative category. null if does not belong to a category
      <!-- * @deprecated use #getCreativeCategories() -->
      */
-    @Nullable
     @Deprecated(since = "1.20.6", forRemoval = true)
-    CreativeCategory getCreativeCategory();
+    @Nullable CreativeCategory getCreativeCategory();
 
     /**
      * Gets if the ItemType is enabled by the features in a world.
@@ -3124,7 +3113,7 @@ public interface ItemType extends Keyed, Translatable, net.kyori.adventure.trans
      * @deprecated use {@link io.papermc.paper.world.flag.FeatureFlagSetHolder#isEnabled(io.papermc.paper.world.flag.FeatureDependant)}
      */
     @Deprecated(forRemoval = true, since = "1.21.1") // Paper
-    boolean isEnabledByFeature(@NotNull World world);
+    boolean isEnabledByFeature(World world);
 
     /**
      * Tries to convert this ItemType into a Material
@@ -3132,38 +3121,33 @@ public interface ItemType extends Keyed, Translatable, net.kyori.adventure.trans
      * @return the converted Material or null
      * @deprecated only for internal use
      */
-    @Nullable
     @Deprecated(since = "1.20.6")
-    Material asMaterial();
+    @Nullable Material asMaterial();
 
-    // Paper start - add Translatable
     /**
      * @deprecated use {@link #translationKey()} and {@link net.kyori.adventure.text.Component#translatable(net.kyori.adventure.translation.Translatable)}
      */
     @Deprecated(forRemoval = true)
     @Override
-    @NotNull String getTranslationKey();
+    String getTranslationKey();
-    // Paper end - add Translatable
 
-    // Paper start - expand ItemRarity API
     /**
      * Returns the item rarity for the item.
      *
      * @return the item rarity (or null if none is set)
      */
     @Nullable ItemRarity getItemRarity();
-    // Paper end - expand ItemRarity API
+
-    // Paper start - data component API
     /**
      * Gets the default value of the data component type for this item type.
      *
      * @param type the data component type
      * @param <T> the value type
      * @return the default value or {@code null} if there is none
-     * @see #hasDefaultData(io.papermc.paper.datacomponent.DataComponentType) for DataComponentType.NonValued
+     * @see #hasDefaultData(DataComponentType) for DataComponentType.NonValued
      */
-    @org.jetbrains.annotations.ApiStatus.Experimental
+    @ApiStatus.Experimental
-    @Nullable <T> T getDefaultData(io.papermc.paper.datacomponent.DataComponentType.@NotNull Valued<T> type);
+    @Nullable <T> T getDefaultData(DataComponentType.Valued<T> type);
 
     /**
      * Checks if the data component type has a default value for this item type.
@@ -3172,14 +3156,13 @@ public interface ItemType extends Keyed, Translatable, net.kyori.adventure.trans
      * @return {@code true} if there is a default value
      */
     @org.jetbrains.annotations.ApiStatus.Experimental
-    boolean hasDefaultData(io.papermc.paper.datacomponent.@NotNull DataComponentType type);
+    boolean hasDefaultData(DataComponentType type);
 
     /**
      * Gets the default data component types for this item type.
      *
      * @return an immutable set of data component types
      */
-    @org.jetbrains.annotations.ApiStatus.Experimental
+    @ApiStatus.Experimental
-    java.util.@org.jetbrains.annotations.Unmodifiable @NotNull Set<io.papermc.paper.datacomponent.DataComponentType> getDefaultDataTypes();
+    @Unmodifiable Set<DataComponentType> getDefaultDataTypes();
-    // Paper end - data component API
 }

paper-server/src/main/java/org/bukkit/craftbukkit/inventory/CraftItemType.java

@@ -185,11 +185,6 @@ public class CraftItemType<M extends ItemMeta> extends HolderableBase<Item> impl
         return expectedItem.isEmpty() ? null : CraftItemType.minecraftToBukkitNew(expectedItem.getItem());
     }
 
-//    @Override
-//    public EquipmentSlot getEquipmentSlot() {
-//        return CraftEquipmentSlot.getSlot(EntityInsentient.getEquipmentSlotForItem(CraftItemStack.asNMSCopy(ItemStack.of(this))));
-//    }
-
     @Override
     public Multimap<Attribute, AttributeModifier> getDefaultAttributeModifiers() {
         return this.getDefaultAttributeModifiers(sg -> true);