Custom item API v2

api/src/main/java/org/geysermc/geyser/api/event/lifecycle/GeyserDefineCustomItemsEvent.java

@@ -27,8 +27,12 @@
 
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.geysermc.event.Event;
+import org.geysermc.geyser.api.exception.CustomItemDefinitionRegisterException;
 import org.geysermc.geyser.api.item.custom.CustomItemData;
 import org.geysermc.geyser.api.item.custom.NonVanillaCustomItemData;
+import org.geysermc.geyser.api.item.custom.v2.CustomItemDefinition;
+import org.geysermc.geyser.api.item.custom.v2.NonVanillaCustomItemDefinition;
+import org.geysermc.geyser.api.util.Identifier;
 
 import java.util.Collection;
 import java.util.List;
@@ -40,37 +44,77 @@
  * This event will not be called if the "add non-Bedrock items" setting is disabled in the Geyser config.
  */
 public interface GeyserDefineCustomItemsEvent extends Event {
+
     /**
-     * Gets a multimap of all the already registered custom items indexed by the item's extended java item's identifier.
+     * A multimap of all the already registered (using the deprecated method) custom items indexed by the item's extended java item's identifier.
      *
-     * @return a multimap of all the already registered custom items
+     * @deprecated use {@link GeyserDefineCustomItemsEvent#customItemDefinitions()}
      */
+    @Deprecated
     @NonNull
     Map<String, Collection<CustomItemData>> getExistingCustomItems();
 
     /**
-     * Gets the list of the already registered non-vanilla custom items.
+     * A multimap of all the already registered custom item definitions indexed by the item's extended java item's identifier.
+     */
+    @NonNull
+    Map<Identifier, Collection<CustomItemDefinition>> customItemDefinitions();
+
+    /**
+     * A list of the already registered (using the deprecated method) non-vanilla custom items.
      *
-     * @return the list of the already registered non-vanilla custom items
+     * @deprecated use {@link GeyserDefineCustomItemsEvent#nonVanillaCustomItemDefinitions()}
      */
+    @Deprecated
     @NonNull
     List<NonVanillaCustomItemData> getExistingNonVanillaCustomItems();
 
+    /**
+     * A multimap of all the already registered non-vanilla custom items indexed by the item's extended java item's identifier.
+     *
+     * <p>This multimap will, at the moment, always have one entry per key.</p>
+     */
+    @NonNull
+    Map<Identifier, Collection<NonVanillaCustomItemDefinition>> nonVanillaCustomItemDefinitions();
+
     /**
      * Registers a custom item with a base Java item. This is used to register items with custom textures and properties
-     * based on NBT data.
+     * based on NBT data. This method should not be used anymore, {@link CustomItemDefinition}s are preferred now and this method will convert {@link CustomItemData} to {@link CustomItemDefinition} internally.
      *
+     * @deprecated use {@link GeyserDefineCustomItemsEvent#register(Identifier, CustomItemDefinition)}
      * @param identifier the base (java) item
      * @param customItemData the custom item data to register
      * @return if the item was registered
      */
+    @Deprecated
     boolean register(@NonNull String identifier, @NonNull CustomItemData customItemData);
 
+    /**
+     * Registers a custom item with a base Java item. This is used to register items with custom textures and properties
+     * based on NBT data.
+     *
+     * @param identifier of the Java edition base item
+     * @param customItemDefinition the custom item definition to register
+     * @throws CustomItemDefinitionRegisterException when an error occurred while registering the item
+     */
+    void register(@NonNull Identifier identifier, @NonNull CustomItemDefinition customItemDefinition) throws CustomItemDefinitionRegisterException;
+
     /**
      * Registers a custom item with no base item. This is used for mods.
+     * This method should not be used anymore, {@link NonVanillaCustomItemDefinition}s are preferred now and this method will convert {@link NonVanillaCustomItemData} to {@link NonVanillaCustomItemDefinition} internally.
      *
+     * @deprecated use {@link GeyserDefineCustomItemsEvent#register(NonVanillaCustomItemDefinition)}
      * @param customItemData the custom item data to register
      * @return if the item was registered
      */
+    @Deprecated
     boolean register(@NonNull NonVanillaCustomItemData customItemData);
-}
+
+    /**
+     * Registers a custom item with no base item. This is used for mods.
+     *
+     * @param customItemDefinition  the custom item definition to register
+     * @throws CustomItemDefinitionRegisterException when an error occurred while registering the item
+     */
+    void register(@NonNull NonVanillaCustomItemDefinition customItemDefinition) throws CustomItemDefinitionRegisterException;
+}

api/src/main/java/org/geysermc/geyser/api/exception/CustomItemDefinitionRegisterException.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) 2025 GeyserMC. http://geysermc.org
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @author GeyserMC
+ * @link https://github.com/GeyserMC/Geyser
+ */
+
+package org.geysermc.geyser.api.exception;
+
+/**
+ * Thrown when there was an error registering the custom item definition. The exception message will have details as to what went wrong.
+ */
+public class CustomItemDefinitionRegisterException extends Exception {
+
+    public CustomItemDefinitionRegisterException(String message) {
+        super(message);
+    }
+}

api/src/main/java/org/geysermc/geyser/api/item/custom/CustomItemData.java

@@ -28,13 +28,24 @@
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
 import org.geysermc.geyser.api.GeyserApi;
+import org.geysermc.geyser.api.item.custom.v2.CustomItemBedrockOptions;
+import org.geysermc.geyser.api.item.custom.v2.CustomItemDefinition;
+import org.geysermc.geyser.api.predicate.item.ItemConditionPredicate;
+import org.geysermc.geyser.api.predicate.item.ItemRangeDispatchPredicate;
+import org.geysermc.geyser.api.util.CreativeCategory;
+import org.geysermc.geyser.api.util.Identifier;
+import org.geysermc.geyser.api.util.TriState;
 
 import java.util.OptionalInt;
 import java.util.Set;
+import java.util.stream.Collectors;
 
 /**
  * This is used to store data for a custom item.
+ *
+ * @deprecated use the new {@link org.geysermc.geyser.api.item.custom.v2.CustomItemDefinition}
  */
+@Deprecated
 public interface CustomItemData {
     /**
      * Gets the item's name.
@@ -118,6 +129,35 @@ static CustomItemData.Builder builder() {
         return GeyserApi.api().provider(CustomItemData.Builder.class);
     }
 
+    default CustomItemDefinition.Builder toDefinition(Identifier javaItem) {
+        CustomItemDefinition.Builder definition = CustomItemDefinition.builder(Identifier.of("geyser_custom", name()), javaItem)
+            .displayName(displayName())
+            .bedrockOptions(CustomItemBedrockOptions.builder()
+                .icon(icon())
+                .allowOffhand(allowOffhand())
+                .displayHandheld(displayHandheld())
+                .creativeCategory(creativeCategory().isEmpty() ? CreativeCategory.NONE : CreativeCategory.values()[creativeCategory().getAsInt()])
+                .creativeGroup(creativeGroup())
+                .tags(tags().stream().map(Identifier::of).collect(Collectors.toSet()))
+            );
+
+        CustomItemOptions options = customItemOptions();
+        if (options.customModelData().isPresent()) {
+            definition.predicate(ItemRangeDispatchPredicate.LEGACY_CUSTOM_MODEL_DATA.create(options.customModelData().getAsInt()));
+        }
+        if (options.damagePredicate().isPresent()) {
+            definition.predicate(ItemRangeDispatchPredicate.DAMAGE.create(options.damagePredicate().getAsInt()));
+        }
+        if (options.unbreakable() != TriState.NOT_SET) {
+            if (options.unbreakable() == TriState.TRUE) {
+                definition.predicate(ItemConditionPredicate.UNBREAKABLE);
+            } else {
+                definition.predicate(ItemConditionPredicate.UNBREAKABLE.negate());
+            }
+        }
+        return definition;
+    }
+
     interface Builder {
         /**
          * Will also set the display name and icon to the provided parameter, if it is currently not set.

api/src/main/java/org/geysermc/geyser/api/item/custom/CustomItemOptions.java

@@ -33,7 +33,10 @@
 
 /**
  * This class represents the different ways you can register custom items
+ *
+ * @deprecated use the new {@link org.geysermc.geyser.api.item.custom.v2.CustomItemDefinition}.
  */
+@Deprecated
 public interface CustomItemOptions {
     /**
      * Gets if the item should be unbreakable.

api/src/main/java/org/geysermc/geyser/api/item/custom/NonVanillaCustomItemData.java

@@ -29,12 +29,28 @@
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.checkerframework.checker.nullness.qual.Nullable;
 import org.geysermc.geyser.api.GeyserApi;
+import org.geysermc.geyser.api.item.custom.v2.CustomItemBedrockOptions;
+import org.geysermc.geyser.api.item.custom.v2.CustomItemDefinition;
+import org.geysermc.geyser.api.item.custom.v2.NonVanillaCustomItemDefinition;
+import org.geysermc.geyser.api.item.custom.v2.component.BlockPlacer;
+import org.geysermc.geyser.api.item.custom.v2.component.Chargeable;
+import org.geysermc.geyser.api.item.custom.v2.component.Consumable;
+import org.geysermc.geyser.api.item.custom.v2.component.DataComponent;
+import org.geysermc.geyser.api.item.custom.v2.component.Equippable;
+import org.geysermc.geyser.api.item.custom.v2.component.FoodProperties;
+import org.geysermc.geyser.api.item.custom.v2.component.GeyserDataComponent;
+import org.geysermc.geyser.api.util.CreativeCategory;
+import org.geysermc.geyser.api.util.Identifier;
 
 import java.util.Set;
+import java.util.stream.Collectors;
 
 /**
  * Represents a completely custom item that is not based on an existing vanilla Minecraft item.
+ *
+ * @deprecated use the new {@link org.geysermc.geyser.api.item.custom.v2.NonVanillaCustomItemDefinition}
  */
+@Deprecated
 public interface NonVanillaCustomItemData extends CustomItemData {
     /**
      * Gets the java identifier for this item.
@@ -170,6 +186,61 @@ static NonVanillaCustomItemData.Builder builder() {
         return GeyserApi.api().provider(NonVanillaCustomItemData.Builder.class);
     }
 
+    @Override
+    default CustomItemDefinition.Builder toDefinition(Identifier javaItem) {
+        throw new UnsupportedOperationException("Use toDefinition()");
+    }
+
+    default NonVanillaCustomItemDefinition.Builder toDefinition() {
+        NonVanillaCustomItemDefinition.Builder definition = NonVanillaCustomItemDefinition.builder(Identifier.of(identifier()), javaId())
+            .displayName(displayName())
+            .bedrockOptions(CustomItemBedrockOptions.builder()
+                .icon(icon())
+                .allowOffhand(allowOffhand())
+                .displayHandheld(displayHandheld())
+                .creativeCategory(creativeCategory().isEmpty() ? CreativeCategory.NONE : CreativeCategory.values()[creativeCategory().getAsInt()])
+                .creativeGroup(creativeGroup())
+                .tags(tags().stream().map(Identifier::of).collect(Collectors.toSet()))
+                .protectionValue(protectionValue())
+            )
+            .component(DataComponent.MAX_STACK_SIZE, stackSize())
+            .component(DataComponent.MAX_DAMAGE, maxDamage())
+            .component(GeyserDataComponent.ATTACK_DAMAGE, attackDamage())
+            .translationString(translationString());
+
+        if (isHat()) {
+            definition.component(DataComponent.EQUIPPABLE, new Equippable(Equippable.EquipmentSlot.HEAD));
+        } else if (armorType() != null) {
+            switch (armorType()) {
+                case "helmet" -> definition.component(DataComponent.EQUIPPABLE, new Equippable(Equippable.EquipmentSlot.HEAD));
+                case "chestplate" -> definition.component(DataComponent.EQUIPPABLE, new Equippable(Equippable.EquipmentSlot.CHEST));
+                case "leggings" -> definition.component(DataComponent.EQUIPPABLE, new Equippable(Equippable.EquipmentSlot.LEGS));
+                case "boots" -> definition.component(DataComponent.EQUIPPABLE, new Equippable(Equippable.EquipmentSlot.FEET));
+            }
+        }
+
+        if (isEdible()) {
+            definition.component(DataComponent.CONSUMABLE, new Consumable(1.6F, Consumable.Animation.EAT)); // Default values
+            if (canAlwaysEat()) {
+                definition.component(DataComponent.FOOD, new FoodProperties(0, 0, true));
+            }
+        }
+
+        if (isChargeable() && toolType() != null) {
+            if (toolType().equals("bow")) {
+                definition.component(GeyserDataComponent.CHARGEABLE, new Chargeable(1.0F, true, Identifier.of("arrow")));
+            } else {
+                definition.component(GeyserDataComponent.CHARGEABLE, new Chargeable(0.0F, false, Identifier.of("arrow")));
+            }
+        }
+
+        if (block() != null) {
+            definition.component(GeyserDataComponent.BLOCK_PLACER, new BlockPlacer(Identifier.of(block()), false));
+        }
+
+        return definition;
+    }
+
     interface Builder extends CustomItemData.Builder {
         @Override
         Builder name(@NonNull String name);