Custom item API v2

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

@@ -27,8 +27,10 @@
 
 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 java.util.Collection;
 import java.util.List;
@@ -40,14 +42,25 @@
  * 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.
+     * Gets 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#getExistingCustomItemDefinitions()}
+     * @return a multimap of all the already custom items registered using {@link GeyserDefineCustomItemsEvent#register(String, CustomItemData)}
      */
+    @Deprecated
     @NonNull
     Map<String, Collection<CustomItemData>> getExistingCustomItems();
 
+    /**
+     * Gets a multimap of all the already registered custom item definitions indexed by the item's extended java item's identifier.
+     *
+     * @return a multimap of all the already registered custom item definitions
+     */
+    @NonNull
+    Map<String, Collection<CustomItemDefinition>> getExistingCustomItemDefinitions();
+
     /**
      * Gets the list of the already registered non-vanilla custom items.
      *
@@ -58,19 +71,31 @@ public interface GeyserDefineCustomItemsEvent extends Event {
 
     /**
      * 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 {@code CustomItemData} to {@code CustomItemDefinition} internally.
      *
+     * @deprecated use {@link GeyserDefineCustomItemsEvent#register(String, 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 String identifier, @NonNull CustomItemDefinition customItemDefinition) throws CustomItemDefinitionRegisterException;
+
     /**
      * Registers a custom item with no base item. This is used for mods.
      *
      * @param customItemData the custom item data to register
      * @return if the item was registered
      */
     boolean register(@NonNull NonVanillaCustomItemData customItemData);
-}
+}

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

@@ -0,0 +1,33 @@
+/*
+ * 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;
+
+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,25 @@
 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.predicate.CustomItemPredicate;
+import org.geysermc.geyser.api.item.custom.v2.predicate.RangeDispatchPredicateProperty;
+import org.geysermc.geyser.api.item.custom.v2.predicate.condition.ConditionPredicateProperty;
+import org.geysermc.geyser.api.util.CreativeCategory;
+import org.geysermc.geyser.api.util.Identifier;
+import org.geysermc.geyser.api.util.TriState;
+
+import java.util.Objects;
 import java.util.OptionalInt;
 import java.util.Set;
 
 /**
  * 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 +130,33 @@ static CustomItemData.Builder builder() {
         return GeyserApi.api().provider(CustomItemData.Builder.class);
     }
 
+    default CustomItemDefinition.Builder toDefinition(Identifier javaItem) {
+        // TODO non vanilla
+        CustomItemDefinition.Builder definition = CustomItemDefinition.builder(javaItem, 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())
+            );
+
+        CustomItemOptions options = customItemOptions();
+        if (options.customModelData().isPresent()) {
+            definition.predicate(CustomItemPredicate.rangeDispatch(RangeDispatchPredicateProperty.CUSTOM_MODEL_DATA, options.customModelData().getAsInt()));
+        }
+        if (options.damagePredicate().isPresent()) {
+            definition.predicate(CustomItemPredicate.rangeDispatch(RangeDispatchPredicateProperty.DAMAGE, options.damagePredicate().getAsInt()));
+        }
+        if (options.unbreakable() != TriState.NOT_SET) {
+            definition.predicate(CustomItemPredicate.condition(ConditionPredicateProperty.HAS_COMPONENT,
+                Objects.requireNonNull(options.unbreakable().toBoolean()), new Identifier("minecraft", "unbreakable")));
+        }
+        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/v2/CustomItemBedrockOptions.java

@@ -0,0 +1,121 @@
+/*
+ * Copyright (c) 2024 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.item.custom.v2;
+
+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.CustomRenderOffsets;
+import org.geysermc.geyser.api.util.CreativeCategory;
+
+import java.util.Set;
+
+/**
+ * This is used to store options for a custom item defintion that can't be described using item components.
+ */
+public interface CustomItemBedrockOptions {
+
+    /**
+     * Gets the item's icon. When not present, the item's Bedrock identifier is used.
+     *
+     * @return the item's icon
+     * @see CustomItemDefinition#icon()
+     */
+    @Nullable
+    String icon();
+
+    /**
+     * If the item is allowed to be put into the offhand. Defaults to true.
+     *
+     * @return true if the item is allowed to be used in the offhand, false otherwise
+     */
+    boolean allowOffhand();
+
+    /**
+     * If the item should be displayed as handheld, like a tool.
+     *
+     * @return true if the item should be displayed as handheld, false otherwise
+     */
+    boolean displayHandheld();
+
+    /**
+     * Since Bedrock doesn't properly support setting item armour values over attributes, this value
+     * determines how many armour points should be shown when this item is worn. This is purely visual.
+     *
+     * <p>Only has an effect when the item is equippable, and defaults to 0.</p>
+     *
+     * @return the item's protection value. Purely visual and for Bedrock only.
+     */
+    int protectionValue();
+
+    /**
+     * The item's creative category. Defaults to {@code NONE}.
+     *
+     * @return the item's creative category
+     */
+    @NonNull
+    CreativeCategory creativeCategory();
+
+    /**
+     * Gets the item's creative group.
+     *
+     * @return the item's creative group
+     */
+    @Nullable
+    String creativeGroup();
+
+    /**
+     * Gets the item's set of tags that can be used in Molang.
+     * Equivalent to "tag:some_tag"
+     *
+     * @return the item's tags, if they exist
+     */
+    @NonNull
+    Set<String> tags();
+
+    static Builder builder() {
+        return GeyserApi.api().provider(Builder.class);
+    }
+
+    interface Builder {
+
+        Builder icon(@Nullable String icon);
+
+        Builder allowOffhand(boolean allowOffhand);
+
+        Builder displayHandheld(boolean displayHandheld);
+
+        Builder protectionValue(int protectionValue);
+
+        Builder creativeCategory(CreativeCategory creativeCategory);
+
+        Builder creativeGroup(@Nullable String creativeGroup);
+
+        Builder tags(@Nullable Set<String> tags);
+
+        CustomItemBedrockOptions build();
+    }
+}