Data component predicate
Data component predicates (known as Item sub-predicates in Java Edition 1.21.4[not in future version]) are used to check conditions about data components. They are used in minecraft:item_predicate
argument type, item modifiers, loot predicates, or advancement criteria. In Java Edition 1.21.5[upcoming] they can also be used in entity and block predicates. They return a pass or fail result to the invoker, who acts differently based on this result.
List of data component predicate types[edit | edit source]
ID | Data type and format | Data components to check |
---|---|---|
attribute_modifiers | [NBT Compound / JSON Object] Object, see below | attribute_modifiers
|
bundle_contents | [NBT Compound / JSON Object] Object, see below | bundle_contents
|
container | [NBT Compound / JSON Object] Object, see below | container
|
custom_data | [String] String or [NBT Compound / JSON Object] Object, see below | custom_data
|
damage | [NBT Compound / JSON Object] Object, see below | damage and max_damage
|
enchantments | [NBT List / JSON Array] Array, see below | enchantments
|
firework_explosion | [NBT Compound / JSON Object] Object, see below | firework_explosion
|
fireworks | [NBT Compound / JSON Object] Object, see below | fireworks
|
jukebox_playable | [NBT Compound / JSON Object] Object,see below | jukebox_playable
|
potion_contents | [String] String or [NBT List / JSON Array] Array, see below | potion_contents
|
stored_enchantments | [NBT List / JSON Array] Array, see below | stored_enchantments
|
trim | [NBT Compound / JSON Object] Object, see below | trim
|
writable_book_content | [NBT Compound / JSON Object] Object, see below | writable_book_content
|
written_book_content | [NBT Compound / JSON Object] Object, see below | written_book_content
|
Formats[edit | edit source]
attribute_modifiers[edit | edit source]
Checks modifiers in the attribute_modifiers
data component.
- [NBT Compound / JSON Object] minecraft:attribute_modifiers
- [NBT Compound / JSON Object] modifiers: (Optional) A collection predicate of attribute modifier.
- [NBT List / JSON Array] contains: (Optional. Can be empty) Checks if there is any attribute modifier passing a test. To succeed, each test must be passed by at least one attribute modifier, but one attribute modifier does not have to pass all the tests.
- [NBT Compound / JSON Object]: A test.
- Predicate of attribute modifier see Template:Nbt inherit/attribute_modifier/template
- [NBT Compound / JSON Object]: A test.
- [Int] size: (Optional) Checks the total number of attribute modifiers. Matches an exact [Int]value, or checks if the value is between a range.
- [NBT Compound / JSON Object] size: (Optional) Another format.
- [Int] max: (Optional) The maximum value.
- [Int] min: (Optional) The minimum value.
- [NBT List / JSON Array] count: (Optional. Can be empty) Checks the number of attribute modifiers that pass a test.
- [NBT Compound / JSON Object]: A test and required number.
- [NBT Compound / JSON Object] test: A test.
- Predicate of attribute modifier see Template:Nbt inherit/attribute_modifier/template
- [Int] count: Matches an exact [Int]value, or checks if the value is between a range.
- [NBT Compound / JSON Object] count: Another format.
- [Int] max: The maximum value.
- [Int] min: The minimum value.
- [NBT Compound / JSON Object] test: A test.
- [NBT Compound / JSON Object]: A test and required number.
- [NBT List / JSON Array] contains: (Optional. Can be empty) Checks if there is any attribute modifier passing a test. To succeed, each test must be passed by at least one attribute modifier, but one attribute modifier does not have to pass all the tests.
- [NBT Compound / JSON Object] modifiers: (Optional) A collection predicate of attribute modifier.
bundle_contents[edit | edit source]
Checks item stacks in the bundle_contents
data component.
- [NBT Compound / JSON Object] minecraft:bundle_contents
- [NBT Compound / JSON Object] items: (Optional) A collection predicate of item stack.
- [NBT List / JSON Array] contains: (Optional. Can be empty) Checks if there is any item stack passing a test. To succeed, each test must be passed by at least one item stack, but one item stack does not have to pass all the tests.
- [NBT Compound / JSON Object]: A test.
- All possible conditions for items see Template:Nbt inherit/conditions/item/template
- [NBT Compound / JSON Object]: A test.
- [Int] size: (Optional) Checks the total number of item stacks. Matches an exact [Int]value, or checks if the value is between a range.
- [NBT Compound / JSON Object] size: (Optional) Another format.
- [Int] max: (Optional) The maximum value.
- [Int] min: (Optional) The minimum value.
- [NBT List / JSON Array] count: (Optional. Can be empty) Checks the number of item stacks that pass a test.
- [NBT Compound / JSON Object]: A test and required number.
- [NBT Compound / JSON Object] test: A test.
- All possible conditions for items see Template:Nbt inherit/conditions/item/template
- [Int] count: Matches an exact [Int]value, or checks if the value is between a range.
- [NBT Compound / JSON Object] count: Another format.
- [Int] max: The maximum value.
- [Int] min: The minimum value.
- [NBT Compound / JSON Object] test: A test.
- [NBT Compound / JSON Object]: A test and required number.
- [NBT List / JSON Array] contains: (Optional. Can be empty) Checks if there is any item stack passing a test. To succeed, each test must be passed by at least one item stack, but one item stack does not have to pass all the tests.
- [NBT Compound / JSON Object] items: (Optional) A collection predicate of item stack.
container[edit | edit source]
Checks item stacks in the container
data component.
- [NBT Compound / JSON Object] minecraft:container
- [NBT Compound / JSON Object] items: (Optional) A collection predicate of item stack.
- [NBT List / JSON Array] contains: (Optional. Can be empty) Checks if there is any item stack passing a test. To succeed, each test must be passed by at least one item stack, but one item stack does not have to pass all the tests.
- [NBT Compound / JSON Object]: A test.
- All possible conditions for items see Template:Nbt inherit/conditions/item/template
- [NBT Compound / JSON Object]: A test.
- [Int] size: (Optional) Checks the total number of item stacks. Matches an exact [Int]value, or checks if the value is between a range.
- [NBT Compound / JSON Object] size: (Optional) Another format.
- [Int] max: (Optional) The maximum value.
- [Int] min: (Optional) The minimum value.
- [NBT List / JSON Array] count: (Optional. Can be empty) Checks the number of item stacks that pass a test.
- [NBT Compound / JSON Object]: A test and required number.
- [NBT Compound / JSON Object] test: A test.
- All possible conditions for items see Template:Nbt inherit/conditions/item/template
- [Int] count: Matches an exact [Int]value, or checks if the value is between a range.
- [NBT Compound / JSON Object] count: Another format.
- [Int] max: The maximum value.
- [Int] min: The minimum value.
- [NBT Compound / JSON Object] test: A test.
- [NBT Compound / JSON Object]: A test and required number.
- [NBT List / JSON Array] contains: (Optional. Can be empty) Checks if there is any item stack passing a test. To succeed, each test must be passed by at least one item stack, but one item stack does not have to pass all the tests.
- [NBT Compound / JSON Object] items: (Optional) A collection predicate of item stack.
custom_data[edit | edit source]
Checks custom_data
data component. See NBT format § Testing NBT tags and NBT format § Conversion from JSON.
Either as a JSON object or an NBT compound tag, or a string. If a string, it is resolved into an NBT compound tag.
- [String][NBT Compound / JSON Object] minecraft:custom_data
damage[edit | edit source]
Checks remaining durability or damage value. Damage value is from the damage
data component; remaining durability is the value max_damage
data component minus damage value.
- [NBT Compound / JSON Object] minecraft:damage
- [Int] damage: (Optional) Checks damage value. Matches an exact [Int]value, or checks if the value is between a range.
- [NBT Compound / JSON Object] damage: (Optional) Another format.
- [Int] max: (Optional) The maximum value.
- [Int] min: (Optional) The minimum value.
- [Int] durability: (Optional) Checks remaining durability. Matches an exact [Int]value, or checks if the value is between a range.
- [NBT Compound / JSON Object] durability: (Optional) Another format.
- [Int] max: (Optional) The maximum value.
- [Int] min: (Optional) The minimum value.
enchantments[edit | edit source]
Checks enchantments on the item (enchantments in the enchantments
data component).
- [NBT List / JSON Array] minecraft:enchantments: Array of conditions. The sub-predicate succeeds when all the conditions succeed.
- [NBT Compound / JSON Object]: A condition.
- [String][NBT List / JSON Array] enchantments: (Optional) Any number of enchantment(s) (an [String] ID, or a [String] tag with
#
, or an [NBT List / JSON Array] array containing [String] IDs). If more than one enchantment is specified, succeeds when any one of them is present. - [Int] levels: (Optional) Checks the level of the specified enchantment. Matches an exact [Int]value, or checks if the value is between a range. If more than one enchantment is specified, succeeds when any one of them matches the level. If [String][NBT List / JSON Array] enchantment is not specified, succeeds when any one of enchantments on the item matches the level.
- [NBT Compound / JSON Object] levels: (Optional) Another format.
- [Int] max: (Optional) The maximum value.
- [Int] min: (Optional) The minimum value.
- [String][NBT List / JSON Array] enchantments: (Optional) Any number of enchantment(s) (an [String] ID, or a [String] tag with
- [NBT Compound / JSON Object]: A condition.
firework_explosion[edit | edit source]
Checks the firework_explosion
data component.
- [NBT Compound / JSON Object] minecraft:firework_explosion
- Predicate of firework explosion effect see Template:Nbt inherit/firework predicate/template
fireworks[edit | edit source]
Checks explosion effects in the fireworks
data component.
- [NBT Compound / JSON Object] minecraft:fireworks
- [NBT Compound / JSON Object] explosions: (Optional) A collection predicate of explosion effect.
- [NBT List / JSON Array] contains: (Optional. Can be empty) Checks if there is any explosion effect passing a test. To succeed, each test must be passed by at least one explosion effect, but one explosion effect does not have to pass all the tests.
- [NBT Compound / JSON Object]: A test.
- Predicate of firework explosion effect see Template:Nbt inherit/firework predicate/template
- [NBT Compound / JSON Object]: A test.
- [Int] size: (Optional) Checks the total number of explosion effects. Matches an exact [Int]value, or checks if the value is between a range.
- [NBT Compound / JSON Object] size: (Optional) Another format.
- [Int] max: (Optional) The maximum value.
- [Int] min: (Optional) The minimum value.
- [NBT List / JSON Array] count: (Optional. Can be empty) Checks the number of explosion effects that pass a test.
- [NBT Compound / JSON Object]: A test and required number.
- [NBT Compound / JSON Object] test: A test.
- Predicate of firework explosion effect see Template:Nbt inherit/firework predicate/template
- [Int] count: Matches an exact [Int]value, or checks if the value is between a range.
- [NBT Compound / JSON Object] count: Another format.
- [Int] max: The maximum value.
- [Int] min: The minimum value.
- [NBT Compound / JSON Object] test: A test.
- [NBT Compound / JSON Object]: A test and required number.
- [NBT List / JSON Array] contains: (Optional. Can be empty) Checks if there is any explosion effect passing a test. To succeed, each test must be passed by at least one explosion effect, but one explosion effect does not have to pass all the tests.
- [Int] flight_duration: (Optional) Checks the flight duration of this firework rocket, i.e. the number of gunpowders used to craft it. Matches an exact [Int]value, or checks if the value is between a range.
- [NBT Compound / JSON Object] flight_duration: (Optional) Another format.
- [Int] max: (Optional) The maximum value.
- [Int] min: (Optional) The minimum value.
- [NBT Compound / JSON Object] explosions: (Optional) A collection predicate of explosion effect.
jukebox_playable[edit | edit source]
Checks jukebox song in the jukebox_playable
data component.
- [NBT Compound / JSON Object] minecraft:jukebox_playable
- [String][NBT List / JSON Array] song: (Optional) Any number of jukebox song(s) (an [String] ID, or a [String] tag with
#
, or an [NBT List / JSON Array] array containing [String] IDs). If more than one jukebox song is specified, succeeds when any one of them matches the testing song.
- [String][NBT List / JSON Array] song: (Optional) Any number of jukebox song(s) (an [String] ID, or a [String] tag with
potion_contents[edit | edit source]
Checks [String] potion field in the potion_contents
data component. Fails if there is no [String] potion field in the component.
- [String][NBT List / JSON Array] minecraft:potion_contents: Any number of potion type(s) (an [String] ID, or a [String] tag with
#
, or an [NBT List / JSON Array] array containing [String] IDs). If more than one potion type is specified, succeeds when any one of them matches the testing [String] potion field.
stored_enchantments[edit | edit source]
Checks enchantments on an enchanted book (enchantments in the stored_enchantments
data component).
- [NBT List / JSON Array] minecraft:stored_enchantments: Array of conditions. The sub-predicate successes when all the conditions success.
- [NBT Compound / JSON Object]: A condition.
- [String][NBT List / JSON Array] enchantments: (Optional) Any number of enchantment(s) (an [String] ID, or a [String] tag with
#
, or an [NBT List / JSON Array] array containing [String] IDs). If more than one enchantment is specified, succeeds when any one of them is present. - [Int] levels: (Optional) Checks the level of the specified enchantment. Matches an exact [Int]value, or checks if the value is between a range. If more than one enchantment is specified, succeeds when any one of them matches the level. If [String][NBT List / JSON Array] enchantment is not specified, succeeds when any one of enchantments on the item matches the level.
- [NBT Compound / JSON Object] levels: (Optional) Another format.
- [Int] max: (Optional) The maximum value.
- [Int] min: (Optional) The minimum value.
- [String][NBT List / JSON Array] enchantments: (Optional) Any number of enchantment(s) (an [String] ID, or a [String] tag with
- [NBT Compound / JSON Object]: A condition.
trim[edit | edit source]
Checks the trim
data component.
- [NBT Compound / JSON Object] minecraft:trim
- [NBT List / JSON Array][String] material: (Optional) Any number of trim material(s) (an [String] ID, or a [String] tag with
#
, or an [NBT List / JSON Array] array containing [String] IDs) If more than one trim material is specified, succeeds when any one of them matches the testing trim material. - [NBT List / JSON Array][String] pattern: (Optional) Any number of trim pattern(s) (an [String] ID, or a [String] tag with
#
, or an [NBT List / JSON Array] array containing [String] IDs) If more than one trim pattern is specified, succeeds when any one of them matches the testing trim pattern.
- [NBT List / JSON Array][String] material: (Optional) Any number of trim material(s) (an [String] ID, or a [String] tag with
writable_book_content[edit | edit source]
Checks pages in the writable_book_content
data component. Raw texts are checked instead of filtered texts.
- [NBT Compound / JSON Object] minecraft:writable_book_content
- [NBT Compound / JSON Object] pages: (Optional) A collection predicate of page.
- [NBT List / JSON Array] contains: (Optional. Can be empty) Checks if there is any page passing a test. To succeed, each test must be passed by at least one page, but one page does not have to pass all the tests.
- [String]: A test. Matches the full string of a page.
- [Int] size: (Optional) Checks the total number of pages. Matches an exact [Int]value, or checks if the value is between a range.
- [NBT Compound / JSON Object] size: (Optional) Another format.
- [Int] max: (Optional) The maximum value.
- [Int] min: (Optional) The minimum value.
- [NBT List / JSON Array] count: (Optional. Can be empty) Checks the number of pages that pass a test.
- [NBT Compound / JSON Object]: A test and required number.
- [String] test: A test. Matches the full string of a page.
- [Int] count: Matches an exact [Int]value, or checks if the value is between a range.
- [NBT Compound / JSON Object] count: Another format.
- [Int] max: The maximum value.
- [Int] min: The minimum value.
- [NBT Compound / JSON Object]: A test and required number.
- [NBT Compound / JSON Object] pages: (Optional) A collection predicate of page.
written_book_content[edit | edit source]
Checks written_book_content
data component.
- [NBT Compound / JSON Object] minecraft:written_book_content
- [NBT Compound / JSON Object] pages: (Optional) A collection predicate of page. Checks the raw texts of pages instead of filtered texts.
- [NBT List / JSON Array] contains: (Optional. Can be empty) Checks if there is any page passing a test. To succeed, each test must be passed by at least one page, but one page does not have to pass all the tests.
- [Undefined]: A test. A text component. Matches the full text of a page.
- [Int] size: (Optional) Checks the total number of pages. Matches an exact [Int]value, or checks if the value is between a range.
- [NBT Compound / JSON Object] size: (Optional) Another format.
- [Int] max: (Optional) The maximum value.
- [Int] min: (Optional) The minimum value.
- [NBT List / JSON Array] count: (Optional. Can be empty) Checks the number of pages that pass a test.
- [NBT Compound / JSON Object]: A test and required number.
- [Undefined] test: A test. A text component. Matches the full text of a page.
- [Int] count: Matches an exact [Int]value, or checks if the value is between a range.
- [NBT Compound / JSON Object] count: Another format.
- [Int] max: The maximum value.
- [Int] min: The minimum value.
- [NBT Compound / JSON Object]: A test and required number.
- [String] author: (Optional) Matches the full string of author.
- [String] title: (Optional) Matches the full string of title. Checks raw title instead of filtered title.
- [Int] generation: (Optional) Checks the number of times this written book has been copied. 0 = original, 1 = copy of original, 2 = copy of copy, 3 = tattered. Matches an exact [Int]value, or checks if the value is between a range.
- [NBT Compound / JSON Object] generation: (Optional) Another format.
- [Int] max: (Optional) The maximum value.
- [Int] min: (Optional) The minimum value.
- [Boolean] resolved: (Optional) Checks whether the JSON text components have already been resolved (the [Boolean] resolved field in the data component is
true
).
- [NBT Compound / JSON Object] pages: (Optional) A collection predicate of page. Checks the raw texts of pages instead of filtered texts.
History[edit | edit source]
Java Edition | |||||||
---|---|---|---|---|---|---|---|
1.20.5 | 24w11a | Added item sub-predicate. | |||||
24w12a | Now item sub-predicate can be used in minecraft:item_predicate argument type.
| ||||||
custom_data now can be defined in JSON object or NBT compound tag. Before, it can only be a quoted string of a SNBT. | |||||||
pre1 | Added 8 new item sub-predicate types: container , bundle_contents , firework_explosion , fireworks , writable_book_content , written_book_content , attribute_modifiers , and trim . | ||||||
1.21 | 24w18a | In enchantments and stored_enchantments , enchantment field is replaced by enchantments , and now can specify multiple enchantments. | |||||
24w21a | Added a new item sub_predicate type jukebox_playable .
| ||||||
In attribute_modifiers , name , and uuid fields are replaced by id . | |||||||
Upcoming Java Edition | |||||||
1.21.5 | 25w04a | renamed item sub-predicate to "data component predicate" | |||||
25w10a | data component predicates are now usable from block and entity predicates. |