Package org.geysermc.geyser.api.item.custom.v2

Interface CustomItemDefinition

All Known Subinterfaces:
NonVanillaCustomItemDefinition
@NonExtendable public interface CustomItemDefinition
This is used to define a custom item and its properties for a specific Java item and item model definition combination.

A custom Bedrock item definition will be used when translating any item stack that matches the vanilla Java item this definition is registered for, and the item model this item definition has specified. Additionally, predicates can be added that allow fine-grained control as to when to use this custom item. These predicates are similar to the predicates available in Java item model definitions.

In Geyser, all registered custom item definitions for a Java item model will be checked in a specific order:

  1. First by checking their priority values, higher priority values going first.
  2. Then by checking if they both have a similar ItemRangeDispatchPredicate predicate, the one with the highest (or lowest, when both are negated) threshold going first.
  3. Lastly by the amount of predicates, from most to least.

Please note! While this system in most cases ensures predicates will be checked in the correct order, the range dispatch predicate sorting only works when 2 definitions only have 1 range dispatch predicate that is similar enough. With more complicated predicate checks, it is recommended to make use of priority values, to ensure the intended order.

Since:
2.9.3

  • Method Details

    • bedrockIdentifier

      @NonNull Identifier bedrockIdentifier()
      The Bedrock identifier for this custom item. It cannot be in the minecraft namespace.
      Returns:
      the Bedrock item identifier
      Since:
      2.9.3

    • displayName

      @NonNull String displayName()
      The display name of the item. If none is set, the display name is taken from the item's Bedrock identifier.
      Returns:
      the display name shown to Bedrock clients
      Since:
      2.9.3

    • model

      @NonNull Identifier model()
      The item model this definition is for. If the model is in the minecraft namespace, then the definition must have at least one predicate.

      If multiple item definitions for a model are registered, then only one can have no predicate.

      Returns:
      the identifier of the Java item model used to match this definition
      Since:
      2.9.3

    • icon

      @NonNull String icon()
      The icon used for this item.

      If none is set in the item's Bedrock options, then the item's Bedrock identifier is used, the namespace separator (:) replaced with . and the path separators (/) replaced with _. For example:

      my_datapack:my_custom_item => my_datapack.my_custom_item

      my_datapack:cool_items/cool_item_1 => my_datapack.cool_items_cool_item_1

      Returns:
      the icon shown to Bedrock players
      Since:
      2.9.3

    • predicates

      @NonNull List<MinecraftPredicate<? super ItemPredicateContext>> predicates()
      The predicates that have to match for this item definition to be used. These predicates can access properties similar to the Java item model predicates.

      When adding predicates, avoid chaining many predicates that use an OR expression - instead, set the PredicateStrategy of the definition to PredicateStrategy.OR.

      It is recommended to use built-in predicates created from classes such as MatchPredicate, ItemMatchPredicate, ItemRangeDispatchPredicate, and ItemConditionPredicate when possible. These predicates have built in conflict detection, value caching, and, in the case of range dispatch predicates, proper predicate sorting. This makes bugs easier to discover, and is generally more performant.

      Since:
      2.9.3

    • predicateStrategy

      @NonNull PredicateStrategy predicateStrategy()
      The predicate strategy used when evaluating predicates. Determines if one of, or all of the predicates have to pass for this item definition to be used. Defaults to PredicateStrategy.AND.
      Since:
      2.9.3

    • priority

      int priority()
      Returns:
      the priority of this definition. For all definitions for a single Java item model, definitions with a higher priority will be matched first. Defaults to 0.
      Since:
      2.9.3

    • bedrockOptions

      @NonNull CustomItemBedrockOptions bedrockOptions()
      Returns:
      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.
      Since:
      2.9.3

    • components

      @NonNull ItemDataComponentMap components()
      The item's data components. It is expected that the item always has these components on the server. If the components mismatch, bugs will occur.

      Currently, the following components are (somewhat) supported:

      Note: some components, for example minecraft:rarity and minecraft:attribute_modifiers, are translated automatically, and do not have to be specified here. Components that are added here cannot be removed in removedComponents().

      Returns:
      the item's data component patch
      Since:
      2.9.3
      See Also:

    • removedComponents

      @NonNull List<Identifier> removedComponents()
      A list of removed default item data components. These are components that are present on the vanilla base item, but not on the custom item. Like with custom added components, it is expected that this always matches the removed components on the server. Removed components cannot be present in the added components in components().
      Returns:
      a list of removed default item data components
      Since:
      2.9.3
      See Also:

    • builder

      static CustomItemDefinition.Builder builder(@NonNull Identifier bedrockIdentifier, @NonNull Identifier itemModel)
      Creates a builder for the custom item definition.
      Parameters:
      bedrockIdentifier - the Bedrock item identifier
      itemModel - the Java item model identifier
      Returns:
      a new builder
      Since:
      2.9.3
      See Also: