Custom item API v2

api/build.gradle.kts

@@ -8,6 +8,7 @@ plugins {
 dependencies {
     api(libs.base.api)
     api(libs.math)
+    api(libs.jetbrains.annotations)
 }
 
 version = property("version")!!

api/src/main/java/org/geysermc/geyser/api/GeyserApi.java

@@ -39,6 +39,7 @@
 import org.geysermc.geyser.api.network.RemoteServer;
 import org.geysermc.geyser.api.util.MinecraftVersion;
 import org.geysermc.geyser.api.util.PlatformType;
+import org.jetbrains.annotations.ApiStatus;
 
 import java.nio.file.Path;
 import java.util.List;
@@ -47,6 +48,7 @@
 /**
  * Represents the API used in Geyser.
  */
+@ApiStatus.NonExtendable
 public interface GeyserApi extends GeyserApiBase {
     /**
      * {@inheritDoc}

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

@@ -27,8 +27,13 @@
 
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.geysermc.event.Event;
+import org.geysermc.geyser.api.item.custom.v2.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 org.jetbrains.annotations.ApiStatus;
 
 import java.util.Collection;
 import java.util.List;
@@ -37,40 +42,86 @@
 /**
  * Called on Geyser's startup when looking for custom items. Custom items must be registered through this event.
  * <p>
- * This event will not be called if the "add non-Bedrock items" setting is disabled in the Geyser config.
+ * This event will not be called if the "add-non-bedrock-items" setting is disabled in the Geyser config.
  */
+@ApiStatus.NonExtendable
 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 custom items indexed by the item's extended java item's identifier.
+     * The map returned here will only contain items registered with the deprecated
+     * {@link GeyserDefineCustomItemsEvent#register(String, CustomItemData)} method.
      *
-     * @return a multimap of all the already registered custom items
+     * @deprecated replaced by {@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 {@link Identifier} of the Java item which the item is based on.
+     */
+    @NonNull
+    Map<Identifier, Collection<CustomItemDefinition>> customItemDefinitions();
+
+    /**
+     * A list of the already registered non-vanilla custom items.
+     * The map returned here will only contain items registered with the deprecated
+     * {@link GeyserDefineCustomItemsEvent#register(NonVanillaCustomItemData)} method.
      *
-     * @return the list of the already registered non-vanilla custom items
+     * @deprecated replaced by {@link GeyserDefineCustomItemsEvent#nonVanillaCustomItemDefinitions()}
      */
+    @Deprecated
     @NonNull
     List<NonVanillaCustomItemData> getExistingNonVanillaCustomItems();
 
+    /**
+     * A multimap of all the already registered non-vanilla custom item definitions indexed by the non-vanilla Java item {@link Identifier} these are mapped to.
+     *
+     * <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.
      *
      * @param identifier the base (java) item
      * @param customItemData the custom item data to register
      * @return if the item was registered
+     * @deprecated use {@link GeyserDefineCustomItemsEvent#register(Identifier, CustomItemDefinition)}
      */
+    @Deprecated
     boolean register(@NonNull String identifier, @NonNull CustomItemData customItemData);
 
+    /**
+     * Registers a Bedrock custom item definition based on a Java item. This is used to register items with custom textures and properties
+     * created using item data component patches.
+     *
+     * @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);
+
     /**
      * 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.
      *
      * @param customItemData the custom item data to register
      * @return if the item was registered
+     * @deprecated use {@link GeyserDefineCustomItemsEvent#register(NonVanillaCustomItemDefinition)}
      */
+    @Deprecated
     boolean register(@NonNull NonVanillaCustomItemData customItemData);
-}
+
+    /**
+     * Registers a custom item with no base Java edition item. This is used for non-vanilla items added by mods.
+     *
+     * @param customItemDefinition the custom item definition to register
+     * @throws CustomItemDefinitionRegisterException when an error occurred while registering the item
+     */
+    void register(@NonNull NonVanillaCustomItemDefinition customItemDefinition);
+}

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

@@ -34,7 +34,10 @@
 
 /**
  * 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.

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

@@ -34,7 +34,10 @@
 
 /**
  * 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.

api/src/main/java/org/geysermc/geyser/api/item/custom/v2/CustomItemBedrockOptions.java

@@ -0,0 +1,202 @@
+/*
+ * 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.checkerframework.common.returnsreceiver.qual.This;
+import org.geysermc.geyser.api.GeyserApi;
+import org.geysermc.geyser.api.util.CreativeCategory;
+import org.geysermc.geyser.api.util.Identifier;
+
+import java.util.Set;
+
+/**
+ * This is used to store options for a custom item definition 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. Defaults to false.
+     *
+     * @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();
+
+    /**
+     * The item's creative group.
+     *
+     * <p>A list of creative groups available in vanilla can be found <a href="https://wiki.bedrock.dev/documentation/menu-categories#list-of-vanilla-groups">here</a>.</p>
+     *
+     * @return the item's creative group
+     */
+    @Nullable
+    String creativeGroup();
+
+    /**
+     * Gets the item's set of bedrock tags that can be used in Molang.
+     * Equivalent to "tag:some_tag"
+     *
+     * @return the item's set of bedrock tags, can be empty
+     */
+    @NonNull
+    Set<Identifier> tags();
+
+    /**
+     * Creates a new builder for custom item bedrock options.
+     *
+     * @return a new builder
+     */
+    static Builder builder() {
+        return GeyserApi.api().provider(Builder.class);
+    }
+
+    /**
+     * Builder for custom item bedrock options.
+     */
+    interface Builder {
+
+        /**
+         * Sets the item's icon.
+         *
+         * @param icon the item's icon
+         * @see CustomItemBedrockOptions#icon()
+         * @return this builder
+         */
+        @This
+        Builder icon(@Nullable String icon);
+
+        /**
+         * Sets if the item is allowed to be put into the offhand.
+         *
+         * @param allowOffhand if the item is allowed to be put into the offhand slot
+         * @see CustomItemBedrockOptions#allowOffhand()
+         * @return this builder
+         */
+        @This
+        Builder allowOffhand(boolean allowOffhand);
+
+        /**
+         * Sets if the item should be displayed as handheld, like a tool.
+         *
+         * @param displayHandheld if the item should be displayed as handheld
+         * @see CustomItemBedrockOptions#displayHandheld()
+         * @return this builder
+         */
+        @This
+        Builder displayHandheld(boolean displayHandheld);
+
+        /**
+         * Sets the item's protection value.
+         *
+         * @param protectionValue the item's protection value
+         * @see CustomItemBedrockOptions#protectionValue()
+         * @return this builder
+         */
+        @This
+        Builder protectionValue(int protectionValue);
+
+        /**
+         * Sets the item's creative category.
+         *
+         * @param creativeCategory the item's creative category
+         * @see CustomItemBedrockOptions#creativeCategory()
+         * @return this builder
+         */
+        @This
+        Builder creativeCategory(@NonNull CreativeCategory creativeCategory);
+
+        /**
+         * Sets the item's creative group.
+         *
+         * @param creativeGroup the item's creative group
+         * @see CustomItemBedrockOptions#creativeGroup()
+         * @return this builder
+         */
+        @This
+        Builder creativeGroup(@Nullable String creativeGroup);
+
+        /**
+         * Adds a tag to the set of bedrock tags this item has, for use in Molang.
+         *
+         * @param tag the tag to be added
+         * @see CustomItemBedrockOptions#tags()
+         * @return this builder
+         */
+        @This
+        Builder tag(@NonNull Identifier tag);
+
+        /**
+         * Sets the item's set of bedrock tags, for use in Molang. Pass {@code null} to clear all tags.
+         *
+         * @param tags the tags to be set, or {@code null} to clear all tags
+         * @return this builder
+         */
+        @This
+        Builder tags(@Nullable Set<Identifier> tags);
+
+        /**
+         * Creates the custom item bedrock options.
+         *
+         * @return the new instance of bedrock options
+         */
+        CustomItemBedrockOptions build();
+    }
+}