Add support for bedrock's dyeable component in the custom item API

Author: eclipseisoffline

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

@@ -25,12 +25,15 @@
 
 package org.geysermc.geyser.api.item.custom.v2;
 
+import org.checkerframework.checker.index.qual.NonNegative;
 import org.checkerframework.common.returnsreceiver.qual.This;
+import org.checkerframework.common.value.qual.IntRange;
 import org.geysermc.geyser.api.GeyserApi;
 import org.geysermc.geyser.api.util.CreativeCategory;
 import org.geysermc.geyser.api.util.Identifier;
 import org.jspecify.annotations.Nullable;
 
+import java.util.OptionalInt;
 import java.util.Set;
 
 /**
@@ -95,13 +98,23 @@ public interface CustomItemBedrockOptions {
 
     /**
      * Gets the item's set of bedrock tags that can be used in Molang.
-     * Equivalent to "tag:some_tag"
+     * Equivalent to tag:some_tag".
      *
      * @return the item's set of bedrock tags, can be empty
      * @since 2.9.3
      */
     Set<Identifier> tags();
 
+    /**
+     * Returns the default colour of the item if it is dyeable, and if not, an empty optional.
+     *
+     * <p>The client allows dyeing dyeable items using any of the vanilla dyes in a crafting table.</p>
+     *
+     * @return the default colour of the item if it is dyeable, and if not, an empty optional
+     * @since 2.10.1
+     */
+    OptionalInt dyeable();
+
     /**
      * Creates a new builder for custom item bedrock options.
      *
@@ -160,7 +173,7 @@ interface Builder {
          * @since 2.9.3
          */
         @This
-        Builder protectionValue(int protectionValue);
+        Builder protectionValue(@NonNegative int protectionValue);
 
         /**
          * Sets the item's creative category.
@@ -199,12 +212,46 @@ interface Builder {
          * 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
+         * @see CustomItemBedrockOptions#tags()
          * @return this builder
          * @since 2.9.3
          */
         @This
         Builder tags(@Nullable Set<Identifier> tags);
 
+        /**
+         * Marks the item as dyeable, and sets the default color of the item.
+         *
+         * @param defaultColor the default color of the item
+         * @see CustomItemBedrockOptions#dyeable()
+         * @return this builder
+         * @since 2.10.1
+         */
+        @This
+        Builder dyeable(@IntRange(from = 0x000000, to = 0xFFFFFF) int defaultColor);
+
+        /**
+         * Marks the item as dyeable, and sets the default color of the item.
+         *
+         * @param defaultRed the red component of the default color of the item
+         * @param defaultGreen the green component of the default color of the item
+         * @param defaultBlue the blue component of the default color of the item
+         * @see CustomItemBedrockOptions#dyeable()
+         * @return this builder
+         * @since 2.10.1
+         */
+        @This
+        default Builder dyeable(@IntRange(from = 0, to = 255) int defaultRed, @IntRange(from = 0, to = 255) int defaultGreen, @IntRange(from = 0, to = 255) int defaultBlue) {
+            if (defaultRed < 0 || defaultRed > 255) {
+                throw new IllegalArgumentException("Red component must be between 0 and 255, was: " + defaultRed);
+            }else if (defaultGreen < 0 || defaultGreen > 255) {
+                throw new IllegalArgumentException("Green component must be between 0 and 255, was: " + defaultGreen);
+            }else if (defaultBlue < 0 || defaultBlue > 255) {
+                throw new IllegalArgumentException("Blue component must be between 0 and 255, was: " + defaultBlue);
+            }
+            return dyeable((defaultRed << 16) | (defaultGreen << 8) | defaultBlue);
+        }
+
         /**
          * Creates the custom item bedrock options.
          *

core/src/main/java/org/geysermc/geyser/item/custom/GeyserCustomItemBedrockOptions.java

@@ -27,18 +27,22 @@
 
 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.item.custom.v2.CustomItemBedrockOptions;
 import org.geysermc.geyser.api.util.CreativeCategory;
 import org.geysermc.geyser.api.util.Identifier;
 import org.geysermc.geyser.registry.populator.custom.CustomItemContext;
 import org.jetbrains.annotations.NotNull;
 
 import java.util.HashSet;
+import java.util.Locale;
 import java.util.Objects;
+import java.util.OptionalInt;
 import java.util.Set;
 
 public record GeyserCustomItemBedrockOptions(@Nullable String icon, boolean allowOffhand, boolean displayHandheld, int protectionValue,
-                                             @NonNull CreativeCategory creativeCategory, @Nullable String creativeGroup, @NonNull Set<Identifier> tags) implements CustomItemBedrockOptions {
+                                             @NonNull CreativeCategory creativeCategory, @Nullable String creativeGroup, @NonNull Set<Identifier> tags,
+                                             OptionalInt dyeable) implements CustomItemBedrockOptions {
 
     @Override
     public int protectionValue() {
@@ -60,6 +64,7 @@ public static class Builder implements CustomItemBedrockOptions.Builder {
         private CreativeCategory creativeCategory = CreativeCategory.NONE;
         private String creativeGroup = null;
         private Set<Identifier> tags = new HashSet<>();
+        private @Nullable Integer dyeableColor;
 
         @Override
         public Builder icon(@Nullable String icon) {
@@ -81,6 +86,9 @@ public Builder displayHandheld(boolean displayHandheld) {
 
         @Override
         public Builder protectionValue(int protectionValue) {
+            if (protectionValue < 0) {
+                throw new IllegalArgumentException("protectionValue cannot be negative");
+            }
             this.protectionValue = protectionValue;
             return this;
         }
@@ -111,10 +119,19 @@ public Builder tags(@Nullable Set<Identifier> tags) {
             return this;
         }
 
+        @Override
+        public CustomItemBedrockOptions.@This Builder dyeable(int defaultColor) {
+            if (defaultColor < 0 || defaultColor > 0xFFFFFF) {
+                throw new IllegalArgumentException("defaultColor must be between 0x000000 and 0xFFFFFF, was: 0x" + Integer.toString(defaultColor, 16).toUpperCase(Locale.ROOT));
+            }
+            this.dyeableColor = defaultColor;
+            return this;
+        }
+
         @Override
         public CustomItemBedrockOptions build() {
             return new GeyserCustomItemBedrockOptions(icon, allowOffhand, displayHandheld, protectionValue,
-                creativeCategory, creativeGroup, Set.copyOf(tags));
+                creativeCategory, creativeGroup, Set.copyOf(tags), dyeableColor == null ? OptionalInt.empty() : OptionalInt.of(dyeableColor));
         }
     }
 }

core/src/main/java/org/geysermc/geyser/registry/mappings/definition/SingleDefinitionReader.java

@@ -147,6 +147,7 @@ private static void readBedrockOptions(CustomItemDefinition.Builder definitionBu
         MappingsUtil.readIfPresent(bedrockOptions, "creative_category", builder::creativeCategory, NodeReader.CREATIVE_CATEGORY, context);
         MappingsUtil.readIfPresent(bedrockOptions, "creative_group", builder::creativeGroup, NodeReader.NON_EMPTY_STRING, context);
         MappingsUtil.readArrayIfPresent(bedrockOptions, "tags", tags -> builder.tags(new HashSet<>(tags)), NodeReader.IDENTIFIER, context);
+        MappingsUtil.readIfPresent(bedrockOptions, "dyeable", builder::dyeable, NodeReader.HEX_INT, context);
 
         definitionBuilder.bedrockOptions(builder);
     }

core/src/main/java/org/geysermc/geyser/registry/mappings/util/NodeReader.java

@@ -59,6 +59,18 @@ public interface NodeReader<T> {
 
     NodeReader<Integer> POSITIVE_INT = INT.validate(i -> i > 0, "integer must be positive");
 
+    NodeReader<Integer> HEX_INT = node -> {
+        String s = node.getAsString();
+        if (s.startsWith("#")) {
+            s = s.substring(1);
+        }
+        try {
+            return Integer.parseInt(s, 16);
+        } catch (NumberFormatException exception) {
+            throw new InvalidCustomMappingsFileException("failed to parse hexadecimal string: " + s);
+        }
+    };
+
     NodeReader<Double> DOUBLE = JsonPrimitive::getAsDouble;
 
     NodeReader<Double> NON_NEGATIVE_DOUBLE = DOUBLE.validate(d -> d >= 0, "number must be non-negative");

core/src/main/java/org/geysermc/geyser/registry/populator/CustomItemRegistryPopulator.java

@@ -296,6 +296,17 @@ private static NbtMapBuilder createComponentNbt(Key itemIdentifier, CustomItemCo
                 .build());
         }
 
+        context.definition().bedrockOptions().dyeable().ifPresent(defaultColor -> {
+            // Please note that we are not including this component by default for items that override vanilla dyeable items, like leather armour
+            // This is because on Java, dyeable items are defined through recipes. As such, we don't know at this time whether the vanilla item actually is a
+            // dyeable: it could've been removed from the recipe!
+            // This unfortunately also applies to vanilla items that have been made dyeable through a nice recipe: again, we don't know about this recipe's existance here.
+            // As such, we have to rely on users putting this component in their mappings.
+            componentBuilder.putCompound("minecraft:dyeable", NbtMap.builder()
+                .putIntArray("default_color", new int[]{(defaultColor & 0xFF0000) >> 16, (defaultColor & 0x00FF00) >> 8, defaultColor & 0xFF})
+                .build());
+        });
+
         AttackRange attackRange = context.components().getOrDefault(DataComponentTypes.ATTACK_RANGE, DEFAULT_ATTACK_RANGE);
 
         KineticWeapon kineticWeapon = context.components().get(DataComponentTypes.KINETIC_WEAPON);