Item Predicates

An ItemPredicate is a filter used to evaluate ItemStack instances. Instead of manually checking item types and component data, Item Predicates allow you to construct rules that check an item's identity, the presence or absence of data components, exact component values, and nested sub-predicates.

Because Item Predicates support the Condition logical tree, you can natively implement AND (all_of) and OR (any_of) gates into your checks.

Creating a Predicate

To construct an Item Predicate in Java, use ItemPredicate.builder().

The builder provides a fluent API to define your requirements. You can evaluate the predicate at any time by passing an ItemStack into its test() method.

public final class PredicateExample {

    public static final ItemPredicate PRISTINE_SWORD = ItemPredicate.builder()
        // 1. Must be a Diamond Sword
        .material(Material.DIAMOND_SWORD)
        
        // 2. Must have Custom Model Data applied
        .with(Key.key("minecraft:custom_model_data"))
        
        // 3. Must NOT have the Unbreakable component
        .without(Key.key("minecraft:unbreakable"))
        
        // 4. Must have EXACTLY 0 damage
        .value(new Durability(0))
        
        // 5. Logical OR: Must have either enchantments or stored enchantments
        .withAny(Key.key("minecraft:enchantments"), Key.key("minecraft:stored_enchantments"))
        
        .build();

    public static void checkItem(Player player, ItemStack item) {
        if (PRISTINE_SWORD.test(item)) {
            player.sendMessage("Item matches the predicate.");
        }
    }
}

Builder Methods

Method	Description
`id(Key)`/`material(Material)`	Mandates that the item matches a specific base Key or vanilla Material.
`with(Key)`	Requires the presence of a specific component Key on the item.
`without(Key)`	Requires the absence of a specific component Key on the item.
`value(DataComponent<?>)`	Requires an exact value match against the provided data component.
`check(ItemPredicate)`	Evaluates an entire nested sub-predicate against the item.
`withAny(...)`/`valueAny(...)`	Logical `OR`. Requires the item to satisfy at least one of the provided rules.

Creating a Predicate

Predicates are inherently data-driven and can be loaded directly from configuration files.

To create a predicate using YAML, create a file at plugins/AbyssalLib/predicates/item/<namespace>/<id>.yml. For this example, we will recreate the "Pristine Sword" predicate at abyssallib_example/pristine_sword.yml.

# 1. Must be a Diamond Sword
id: "minecraft:diamond_sword"

# 2. Must have Custom Model Data applied, AND
# 5. Logical OR: Must have either enchantments or stored enchantments
with:
  - "minecraft:custom_model_data"
  - any_of:
      - "minecraft:enchantments"
      - "minecraft:stored_enchantments"

# 3. Must NOT have the Unbreakable component
without:
  - "minecraft:unbreakable"

# 4. Must have EXACTLY 0 damage
components:
  - "minecraft:damage": 0

Utilizing Loaded Predicates

During server startup, AbyssalLib automatically parses YAML definitions in the predicates folder and registers them under the Registries.ITEM_PREDICATES registry.

You can retrieve and use the predicate in your code using its namespaced key:

public void checkLoadedItem(ItemStack item) {
    // Fetch the predicate using the namespace (folder name) and filename
    ItemPredicate predicate = Registries.ITEM_PREDICATES.get("abyssallib_example:pristine_sword");
    
    if (predicate != null && predicate.test(item)) {
        // The item matches the YAML definition.
    }
}

05 June 2026