Predicates
A predicate is a reusable JSON condition — the exact same system as loot-table conditions — that you reference from loot tables, advancements, item modifiers and the /execute if predicate command to test complex entity, item, location and world state.
- File location & structure
- One system: conditions == predicates
- Condition types (full list)
- Entity sub-predicate
- Item sub-predicate
- Data-component predicate types
- Location, block & fluid sub-predicates
- Damage-source sub-predicate
- Using predicates
- Worked examples
- Tricks & best practices
- Version differences
- Sources
File location & structure
Each predicate is one JSON file under the singular 1.21+ folder:
data/<namespace>/predicate/<path>.json
data/mypack/predicate/holding_diamond_sword.json → referenced as mypack:holding_diamond_sword
The file's root is either a single condition object or an array of conditions (ALL must pass — an implicit all_of). It is referenced by namespace:path.
One system: conditions == predicates
There is no separate "predicate language". A predicate file contains the very same condition objects that appear inline in a loot table's conditions array. The full list below is identical to the loot-condition list on the loot tables page — the difference is only where the condition lives (a standalone file vs. inline). Anything you can write in a loot pool's conditions, you can save as a predicate and pull back in with reference.
Factor shared logic into one predicate file and reference it everywhere with {"condition":"minecraft:reference","name":"mypack:x"} — inside loot tables, advancements and other predicates. One canonical definition, many call sites.
Condition types (full list)
Logical
| Condition | Fields |
|---|---|
minecraft:all_of | terms (array of conditions) — passes if all pass. |
minecraft:any_of | terms (array) — passes if any pass. |
minecraft:inverted | term (single condition) — negates it. |
Entity / scores
| Condition | Fields |
|---|---|
minecraft:entity_properties | entity (context ref: this, attacker, direct_attacker, attacking_player, target_entity, …), predicate (entity sub-predicate). |
minecraft:entity_scores | entity (context ref), scores (map objective → int range or single value). |
minecraft:killed_by_player | No fields; requires attacking_player in context. |
Items / tools
| Condition | Fields |
|---|---|
minecraft:match_tool | predicate (item sub-predicate). In loot context checks the mining tool; in other contexts the relevant tool. |
Location / world
| Condition | Fields |
|---|---|
minecraft:location_check | predicate (location sub-predicate), optional integer offsetX / offsetY / offsetZ. |
minecraft:block_state_property | block (block ID), properties (map of state → exact value string or {min,max} range). |
minecraft:weather_check | raining (bool, optional), thundering (bool, optional). |
minecraft:time_check | value (number provider / range to test), period (int, optional modulo — e.g. 24000 to test time-of-day cyclically). |
Randomness
| Condition | Fields |
|---|---|
minecraft:random_chance | chance (float 0–1; a number provider since 1.21). |
minecraft:random_chance_with_enchanted_bonus | unenchanted_chance (float), enchanted_chance (level-based number provider), enchantment (enchantment ID). 1.21 restructure of the old looting-based random chance. |
minecraft:table_bonus | enchantment (ID), chances (array of floats indexed by enchantment level). |
minecraft:survives_explosion | No fields; passes with probability 1 / explosion_radius. |
Damage / enchantment
| Condition | Fields |
|---|---|
minecraft:damage_source_properties | predicate (damage-source sub-predicate: tags, source_entity, direct_entity, is_direct, …). |
minecraft:enchantment_active_check | active (bool); used inside enchantment-provided effects to test whether the enchantment is currently active. |
Misc
| Condition | Fields |
|---|---|
minecraft:value_check | value (number provider), range (int range / single value to compare against). |
minecraft:reference | name (resource location of another predicate file). |
Entity sub-predicate
Used by entity_properties (and reused by advancement triggers). All fields are optional; a missing field is not tested.
| Field | Checks |
|---|---|
type | Entity type: ID, #tag, or array. |
type_specific | Type-scoped props: { "type": "player"|"raider"|"sheep"|"fishing_hook"|"lightning"|"cat"|"frog"|"axolotl"|"slime"/"cube_mob"|…, …props }. E.g. player: gamemode, level, stats, recipes, advancements, look_at. |
nbt | Partial SNBT match (slowest — evaluated last). |
team | Scoreboard team name. |
location | Location sub-predicate (where the entity is). |
stepping_on | Block predicate for the block being stood on. |
movement_affected_by | Block predicate ~0.5 below the feet. |
distance | { absolute|horizontal|x|y|z : float range } to context origin. |
movement | Velocity: { x|y|z|speed|horizontal_speed|vertical_speed|fall_distance : range }. |
flags | Booleans: is_on_fire, is_sneaking, is_sprinting, is_swimming, is_baby, is_on_ground, is_flying, is_fall_flying. |
equipment | Per-slot item sub-predicates: mainhand, offhand, head, chest, legs, feet, body. |
slots | Item sub-predicates keyed by slot range (e.g. container.5, hotbar.0, weapon.mainhand). |
effects | Map effect ID → { amplifier(range), duration(range), ambient(bool), visible(bool) }. |
vehicle | Entity sub-predicate for the ridden entity. |
passenger | Entity sub-predicate for a direct passenger. |
targeted_entity | Entity sub-predicate for the mob's AI target. |
periodic_tick | Int; passes when entity age is divisible by it. |
Item sub-predicate 1.20.5+
Used by match_tool, equipment/slots, and advancement item triggers. Since 1.20.5 it is component-based (see data components).
| Field | Checks |
|---|---|
items | Item ID, #tag, or array of IDs (type match). |
count | Int, or { min, max } range (stack size). |
components | EXACT component match: { "minecraft:<component>": <value>, … } — the item must have exactly this component value. |
predicates | LOOSER component checks (partial / ranged). Keys are data-component predicate types (below). |
Data-component predicate types
These are the keys usable inside the item sub-predicate's predicates field — structured, partial or ranged checks against individual components.
| Predicate | Checks |
|---|---|
minecraft:damage | Remaining durability / damage value (ranges). |
minecraft:enchantments | Enchantments on the item (ID + level range). |
minecraft:stored_enchantments | Enchantments stored on an enchanted book. |
minecraft:potion_contents | The potion field of potion_contents. |
minecraft:custom_data | The custom_data component (partial SNBT). |
minecraft:container | Item stacks inside container. |
minecraft:bundle_contents | Item stacks inside bundle_contents. |
minecraft:firework_explosion | The firework_explosion component. |
minecraft:fireworks | Explosions in the fireworks component. |
minecraft:writable_book_content | Pages in writable_book_content. |
minecraft:written_book_content | The written_book_content component. |
minecraft:trim | The trim component. |
minecraft:jukebox_playable | Song in jukebox_playable. |
minecraft:attribute_modifiers | Modifiers in attribute_modifiers. |
Location, block & fluid sub-predicates
Used by location_check and by the entity sub-predicate's location / stepping_on / movement_affected_by fields. All fields optional.
| Location field | Type / checks |
|---|---|
biomes | Biome ID, #tag, or array of IDs. |
dimension | Dimension ID (e.g. minecraft:the_nether). |
structures | Structure ID, #tag, or array of IDs. |
position | { x, y, z }, each a float range. |
light | { light: <int range> } — the light level at the position. |
smokey | Boolean — whether the position is above a campfire (smoke). |
can_see_sky | Boolean — sky visibility at the position. |
block | Block sub-predicate (below). |
fluid | Fluid sub-predicate (below). |
| Block sub-predicate field | Checks |
|---|---|
blocks | Block ID, #tag, or array of IDs (type match). |
state | Map of block-state property → exact value or {min,max} range. |
nbt | Partial block-entity SNBT match. |
components / predicates | Exact / looser component checks on the block item (optional). |
| Fluid sub-predicate field | Checks |
|---|---|
fluids | Fluid ID, #tag, or array of IDs. |
state | Map of fluid-state property → exact value or range (e.g. level, falling). |
Damage-source sub-predicate
Used by damage_source_properties to test how the damage was dealt.
| Field | Checks |
|---|---|
tags | Damage-type tags (e.g. #minecraft:is_fire), each with an expected boolean. |
source_entity | Entity sub-predicate for the logical source (e.g. the shooter of an arrow). |
direct_entity | Entity sub-predicate for the immediate cause (e.g. the arrow itself). |
is_direct | Boolean — whether the direct entity is also the source. |
Using predicates
In commands — /execute if predicate
The cleanest way to test complex entity state (equipment, effects, scores, location, NBT) without long selector arguments:
execute as @a if predicate mypack:holding_diamond_sword run say I am armed
execute if predicate mypack:night_and_sneaking run function mypack:stealth/tick
In loot tables, item modifiers & advancements
- Loot tables / item modifiers: pull a predicate into any
conditionsarray with{"condition":"minecraft:reference","name":"mypack:x"}. - Advancements: triggers embed these same sub-predicates in their
conditions(player,location,itemsub-predicates) — the schemas above apply unchanged.
Worked examples
Detect sneaking at night (array = all must pass)
data/mypack/predicate/night_and_sneaking.json
[
{ "condition": "minecraft:time_check", "value": { "min": 13000, "max": 23000 }, "period": 24000 },
{ "condition": "minecraft:entity_properties", "entity": "this",
"predicate": { "flags": { "is_sneaking": true } } }
]
Use: execute as @a if predicate mypack:night_and_sneaking run …
Holding a custom item via custom_data
data/mypack/predicate/holding_magic_wand.json
{
"condition": "minecraft:entity_properties",
"entity": "this",
"predicate": {
"equipment": {
"mainhand": {
"items": "minecraft:stick",
"predicates": {
"minecraft:custom_data": "{magic_wand:1b}"
}
}
}
}
}
This matches any player holding a stick whose custom_data component contains magic_wand:1b — the standard way to identify a datapack "custom item".
Biome check
data/mypack/predicate/in_desert.json
{
"condition": "minecraft:location_check",
"predicate": {
"biomes": "minecraft:desert",
"can_see_sky": true
}
}
Use: execute as @a at @s if predicate mypack:in_desert run …. Note location_check tests the context origin — with at @s that is the entity's position; add offsetX/Y/Z to test a nearby block instead.
Holding a diamond sword (simple item match)
data/mypack/predicate/holding_diamond_sword.json
{
"condition": "minecraft:entity_properties",
"entity": "this",
"predicate": {
"equipment": {
"mainhand": { "items": "minecraft:diamond_sword" }
}
}
}
Tricks & best practices
/execute if predicate is the cleanest way to test complex entity state without long, brittle target-selector arguments — reach for a predicate whenever a selector's [...] arguments start to sprawl.
The nbt field is slow — it is evaluated last and matches raw SNBT. Always constrain with type, flags or components/predicates first, and put nbt last so the fast checks short-circuit it.
Because predicates and loot conditions are one system, you can prototype a gate inline in a loot table, then lift it verbatim into a predicate/ file and share it across advancements, item modifiers and /execute — no translation needed.
Version differences
- Since 1.20.5 (pack_format 41): the item sub-predicate became component-based. The old
item,tag,nbt,durability,enchantments,potionfields collapsed intoitemspluscomponents(exact) andpredicates(structured/ranged). See data components. - Since 1.21 (pack_format 48): the folder
predicateswas singularised topredicate. - Since 1.21:
random_chance_with_enchanted_bonusreplaced the old looting-based random-chance condition, and its (andrandom_chance's)chancefields became number providers. - Since 1.21: entity context refs renamed:
killer→attacker,direct_killer→direct_attacker,killer_player→attacking_player.