Record Class ItemMatch

java.lang.Object
java.lang.Record
com.trevlar.menukit.api.element.ItemMatch
Record Components:
stack - the rule's stack: the item, and for EXACT and CONTAINS its count and components
match - how a stack is compared with it
ignored - component types left out of the comparison (none by default)
countIgnored - whether EXACT leaves the count out (false by default)
public record ItemMatch(net.minecraft.world.item.ItemStack stack, ItemMatch.Match match, Set<net.minecraft.core.component.DataComponentType<?>> ignored, boolean countIgnored) extends Record
An item rule: a stack and how another stack has to match it. What an ItemPicker slot holds, and the one comparison every mod uses, so none writes its own. 
// A rule the player set with an item picker, tested against a stack in play.
if (rule.matches(stack)) lock(slot);

// A plain stack and the mode the setting declares.
ItemMatch.matches(config.target, ItemMatch.Match.CONTAINS, stack);

The three modes

  • ItemMatch.Match.ITEM: the kind of item only. Count and components are ignored: any diamond sword is a diamond sword.
  • ItemMatch.Match.EXACT: vanilla's own stack equality (ItemStack.matches(ItemStack, ItemStack)): the same item, the same count, and exactly the same components. A rule with no components set is a plain item, so an enchanted or renamed one does not match it. The count matters for an item that stacks; one that does not is always one.
  • ItemMatch.Match.CONTAINS: the same item, and at least the components the rule sets; others may be there too, and the count is ignored. A rule with no components set matches any variant of the item. A component the rule removes (!food in /give syntax) must be absent.
Whether an empty rule means "plain" or "any" is the mode's answer, never a guess: EXACT says plain, CONTAINS says any.

Ignoring components, and the count

A rule can leave chosen component types out of the comparison, in EXACT and CONTAINS alike: neither side's value for them is looked at. A lock on "this exact sword" that should hold after the sword takes damage: 
ItemMatch lock = new ItemMatch(sword, ItemMatch.Match.EXACT)
        .ignoring(DataComponents.DAMAGE)   // still this sword once it is worn
        .ignoringCount();                  // and a stack of 3 is still "this item"
ignoringCount() drops the count from EXACT (the count is not a component, so it has its own call; CONTAINS and ITEM never compare it). Both are saved with the rule by CODEC, and a rule saved without them loads ignoring nothing, as before.

CONTAINS compares as vanilla's item predicates do

Each component the rule sets is compared the way an item predicate in a command or a datapack compares it (/clear @s diamond_sword[damage=0], and the partial ~ form where vanilla has one):
  • enchantments and stored_enchantments: the stack has at least the rule's enchantments, each at the rule's level (vanilla's EnchantmentsPredicate); it may have more.
  • custom_data: the rule's tag is contained in the stack's (vanilla's NBT predicate, CustomData.matchedBy(CompoundTag)).
  • Any other component: equal, as DataComponentExactPredicate compares it.

An empty rule (ItemStack.EMPTY, or air) matches nothing, and an empty stack matches no rule: an empty picker slot is not a rule.

Common code: it reads only the stacks, so a mod's server side can use it too. The record copies its stack; treat stack() as read-only. Two rules are equal when their modes are, their stacks match exactly (ItemStack.matches(ItemStack, ItemStack)), and they ignore the same.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    ItemMatch.Match
    How a stack is compared with a rule's.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final com.mojang.serialization.Codec<ItemMatch>
    CODEC
    Saves a rule as {stack: <vanilla's stack>, match: "exact"}, plus ignoring: ["minecraft:damage"] and ignore_count: true when the rule has them (left out when it does not, so a rule saved before they existed loads as it was).

  • Constructor Summary

    Constructors
    Constructor
    Description
    ItemMatch(net.minecraft.world.item.ItemStack stack, ItemMatch.Match match)
    A rule that compares every component, and in EXACT the count.
    ItemMatch(net.minecraft.world.item.ItemStack stack, ItemMatch.Match match, Set<net.minecraft.core.component.DataComponentType<?>> ignored, boolean countIgnored)
    Creates an instance of a ItemMatch record class.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    countIgnored()
    Returns the value of the countIgnored record component.
    boolean
    equals(Object o)
    Indicates whether some other object is "equal to" this one.
    int
    hashCode()
    Returns a hash code value for this object.
    Set<net.minecraft.core.component.DataComponentType<?>>
    ignored()
    Returns the value of the ignored record component.
    ItemMatch
    ignoring(net.minecraft.core.component.DataComponentType<?>... types)
    This rule, also leaving types out of the comparison in EXACT and CONTAINS: neither the rule's value for them nor the candidate's is looked at.
    ItemMatch
    ignoringCount()
    This rule, with EXACT also leaving the count out (the other modes never compare it).
    ItemMatch.Match
    match()
    Returns the value of the match record component.
    boolean
    matches(net.minecraft.world.item.ItemStack candidate)
    Whether candidate matches this rule.
    static boolean
    matches(net.minecraft.world.item.ItemStack rule, ItemMatch.Match match, net.minecraft.world.item.ItemStack candidate)
    Whether candidate matches the rule rule under match: the comparison ItemMatch describes, for a consumer that stores a plain stack and declares the mode itself.
    net.minecraft.world.item.ItemStack
    stack()
    Returns the value of the stack record component.
    String
    toString()
    Returns a string representation of this record class.

    Methods inherited from class Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • CODEC

      public static final com.mojang.serialization.Codec<ItemMatch> CODEC
      Saves a rule as {stack: <vanilla's stack>, match: "exact"}, plus ignoring: ["minecraft:damage"] and ignore_count: true when the rule has them (left out when it does not, so a rule saved before they existed loads as it was). The stack goes through vanilla's ItemStack.OPTIONAL_CODEC, so encode it with the world's registry ops (enchantments are registry entries), as vanilla saves a stack.

  • Constructor Details

    • ItemMatch

      public ItemMatch(net.minecraft.world.item.ItemStack stack, ItemMatch.Match match, Set<net.minecraft.core.component.DataComponentType<?>> ignored, boolean countIgnored)
      Creates an instance of a ItemMatch record class.
      Parameters:
      stack - the value for the stack record component
      match - the value for the match record component
      ignored - the value for the ignored record component
      countIgnored - the value for the countIgnored record component

    • ItemMatch

      public ItemMatch(net.minecraft.world.item.ItemStack stack, ItemMatch.Match match)
      A rule that compares every component, and in EXACT the count.

  • Method Details

    • ignoring

      public ItemMatch ignoring(net.minecraft.core.component.DataComponentType<?>... types)
      This rule, also leaving types out of the comparison in EXACT and CONTAINS: neither the rule's value for them nor the candidate's is looked at. Adds to any already ignored.

    • ignoringCount

      public ItemMatch ignoringCount()
      This rule, with EXACT also leaving the count out (the other modes never compare it).

    • matches

      public boolean matches(net.minecraft.world.item.ItemStack candidate)
      Whether candidate matches this rule.

    • matches

      public static boolean matches(net.minecraft.world.item.ItemStack rule, ItemMatch.Match match, net.minecraft.world.item.ItemStack candidate)
      Whether candidate matches the rule rule under match: the comparison ItemMatch describes, for a consumer that stores a plain stack and declares the mode itself. Ignores nothing; for a rule that does, make an ItemMatch and call ignoring(DataComponentType...) on it.

    • equals

      public boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with Objects::equals(Object,Object); primitive components are compared with the compare method from their corresponding wrapper classes.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • hashCode

      public int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • toString

      public String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • stack

      public net.minecraft.world.item.ItemStack stack()
      Returns the value of the stack record component.
      Returns:
      the value of the stack record component

    • match

      public ItemMatch.Match match()
      Returns the value of the match record component.
      Returns:
      the value of the match record component

    • ignored

      public Set<net.minecraft.core.component.DataComponentType<?>> ignored()
      Returns the value of the ignored record component.
      Returns:
      the value of the ignored record component

    • countIgnored

      public boolean countIgnored()
      Returns the value of the countIgnored record component.
      Returns:
      the value of the countIgnored record component