Custom item API v2

api/build.gradle.kts

@@ -8,6 +8,15 @@ plugins {
 dependencies {
     api(libs.base.api)
     api(libs.math)
+
+    // Adventure text serialization
+    api(libs.bundles.adventure)
+
+    // TODO? can we exclude more
+    api(libs.mcprotocollib) {
+        exclude("io.netty", "netty-all")
+        exclude("net.raphimc", "MinecraftAuth")
+    }
 }
 
 version = property("version")!!

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

@@ -25,16 +25,23 @@
 
 package org.geysermc.geyser.api.item.custom;
 
+import net.kyori.adventure.key.Key;
 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.BedrockCreativeTab;
+import org.geysermc.geyser.api.item.custom.v2.CustomItemBedrockOptions;
+import org.geysermc.geyser.api.item.custom.v2.CustomItemDefinition;
 
 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 +125,23 @@ static CustomItemData.Builder builder() {
         return GeyserApi.api().provider(CustomItemData.Builder.class);
     }
 
+    default CustomItemDefinition toDefinition(String javaItem) {
+        // TODO predicate
+        return CustomItemDefinition.builder(Key.key(javaItem), Key.key(javaItem))
+            .displayName(displayName())
+            .bedrockOptions(CustomItemBedrockOptions.builder()
+                .icon(icon())
+                .allowOffhand(allowOffhand())
+                .displayHandheld(displayHandheld())
+                .creativeCategory(creativeCategory().isEmpty() ? BedrockCreativeTab.NONE : BedrockCreativeTab.values()[creativeCategory().getAsInt()])
+                .creativeGroup(creativeGroup())
+                .textureSize(textureSize())
+                .renderOffsets(renderOffsets())
+                .tags(tags())
+            )
+            .build();
+    }
+
     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/BedrockCreativeTab.java

@@ -0,0 +1,34 @@
+/*
+ * 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;
+
+public enum BedrockCreativeTab {
+    NONE,
+    CONSTRUCTION,
+    NATURE,
+    EQUIPMENT,
+    ITEMS
+}

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

@@ -0,0 +1,127 @@
+/*
+ * 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 java.util.Set;
+
+/**
+ * This is used to store options for a custom item 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();
+
+    /**
+     * The item's creative category. Defaults to {@code NONE}.
+     *
+     * @return the item's creative category
+     */
+    @NonNull
+    BedrockCreativeTab creativeCategory();
+
+    /**
+     * Gets the item's creative group.
+     *
+     * @return the item's creative group
+     */
+    @Nullable
+    String creativeGroup();
+
+    /**
+     * Gets the item's texture size. This is to resize the item if the texture is not 16x16.
+     *
+     * @return the item's texture size
+     */
+    int textureSize();
+
+    /**
+     * Gets the item's render offsets. If it is null, the item will be rendered normally, with no offsets.
+     *
+     * @return the item's render offsets
+     */
+    @Nullable
+    CustomRenderOffsets renderOffsets();
+
+    /**
+     * 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 creativeCategory(BedrockCreativeTab creativeCategory);
+
+        Builder creativeGroup(@Nullable String creativeGroup);
+
+        Builder textureSize(int textureSize);
+
+        Builder renderOffsets(@Nullable CustomRenderOffsets renderOffsets);
+
+        Builder tags(@Nullable Set<String> tags);
+
+        CustomItemBedrockOptions build();
+    }
+}

api/src/main/java/org/geysermc/geyser/api/item/custom/v2/CustomItemDefinition.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 net.kyori.adventure.key.Key;
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.geysermc.geyser.api.GeyserApi;
+import org.geysermc.geyser.api.item.custom.v2.predicate.CustomItemPredicate;
+import org.geysermc.mcprotocollib.protocol.data.game.item.component.DataComponents;
+
+import java.util.List;
+
+/**
+ * This is used to define a custom item and its properties.
+ */
+// TODO note that definitions will be sorted by predicates
+public interface CustomItemDefinition {
+
+    /**
+     * The Bedrock identifier for this custom item. This can't be in the {@code minecraft} namespace. If the {@code minecraft} namespace is given in the builder, the default
+     * namespace of the implementation is used.
+     *
+     * @implNote for Geyser, the default namespace is the {@code geyser_custom} namespace.
+     */
+    @NonNull Key bedrockIdentifier();
+
+    /**
+     * The display name of the item. If none is set, the display name is taken from the item's Bedrock identifier.
+     */
+    @NonNull String displayName();
+
+    /**
+     * The item model this definition is for. If the model is in the {@code minecraft} namespace, then the definition is required to have a predicate.
+     *
+     * <p>If multiple item definitions for a model are registered, then only one can have no predicate.</p>
+     */
+    @NonNull Key model();
+
+    /**
+     * The icon used for this item.
+     *
+     * <p>If none is set in the item's Bedrock options, then the item's Bedrock identifier is used,
+     * the namespace separator replaced with {@code .} and the path separators ({@code /}) replaced with {@code _}.</p>
+     */
+    default @NonNull String icon() {
+        return bedrockOptions().icon() == null ? bedrockIdentifier().asString().replaceAll(":", ".").replaceAll("/", "_") : bedrockOptions().icon();
+    }
+
+    /**
+     * The predicates that have to match for this item to be used. These predicates are similar to the Java item model predicates.
+     *
+     * <p>If all predicates match for multiple definitions, then the first registered item with all matching predicates is used. If no predicates match, then the item definition without any predicates
+     * is used, if any.</p>
+     */
+    @NonNull List<CustomItemPredicate> predicates();
+
+    /**
+     * The item's Bedrock options. These describe item properties that can't be described in item components, e.g. item texture size and if the item is allowed in the off-hand.
+     */
+    @NonNull CustomItemBedrockOptions bedrockOptions();
+
+    /**
+     * The item's data components. It is expected that the item <em>always</em> has these components on the server. If the components mismatch, bugs will occur.
+     *
+     * <p>Currently, the following components are supported:</p>
+     *
+     * <ul>
+     *     <li>{@code minecraft:consumable}</li>
+     *     <li>{@code minecraft:equippable}</li>
+     *     <li>{@code minecraft:food}</li>
+     *     <li>{@code minecraft:max_damage}</li>
+     *     <li>{@code minecraft:max_stack_size}</li>
+     *     <li>{@code minecraft:use_cooldown}</li>
+     * </ul>
+     *
+     * <p>Note: some components, for example {@code minecraft:rarity}, {@code minecraft:enchantment_glint_override}, and {@code minecraft:attribute_modifiers} are translated automatically,
+     * and do not have to be specified here.</p>
+     */
+    @NonNull DataComponents components();
+
+    static Builder builder(Key identifier, Key itemModel) {
+        return GeyserApi.api().provider(Builder.class, identifier, itemModel);
+    }
+
+    interface Builder {
+
+        Builder displayName(String displayName);
+
+        Builder predicate(@NonNull CustomItemPredicate predicate);
+
+        Builder bedrockOptions(CustomItemBedrockOptions.@NonNull Builder options);
+
+        // TODO do we want another format for this?
+        Builder components(@NonNull DataComponents components);
+
+        CustomItemDefinition build();
+    }
+}

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

@@ -0,0 +1,29 @@
+/*
+ * 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.predicate;
+
+public interface CustomItemPredicate { // TODO this probably needs to be different since people can implement this
+}