Predicate

A predicate (also known as a loot condition) is a data structure commonly used throughout data packs and commands, invoked to check boolean conditions either in the world or within a given loot context. Predicates do not change data or affect the world, they only check information (that they have access to) and return either a pass or a fail. They can be defined and registered in data packs, or they can be directly defined "in-line" in various places. They can be used throughout the game such as in commands, loot tables, and advancements. In practical terms, predicates are a flexible way for data packs to encode "if this, then that" logic without needing custom code.

Predicate files are standalone JSON files in data packs containing the definition for a predicate. The file path indicates the namespaced identifier used to reference it.

This article describes how predicates are defined and invoked, and also describes the JSON structure of a predicate.

A predicate file is defined with the JSON format.

Predicate files are part of the data pack directory structure, highlighted below:

The root element of a predicate file can be either an [NBT Compound / JSON Object] object following the predicate structure below, or an [NBT List / JSON Array] array containing multiple predicates. In the latter case all predicates must evaluate to true.

Predicates and predicate files can be invoked in several different manners from other data pack files:

Commands or functions can invoke predicate files in two ways:

• Target selectors: The selector argument predicate= checks predicate files as a filter for entity selection. The predicate file is invoked once per entity that needs filtering, each time being at the entity's location.
• /execute: A subcommand, /execute if predicate, can invoke a predicate file or an in-line predicate definition to either return a result or to decide whether to continue with a subcommand chain. The predicate is invoked once at the current contextual position of execution.

The condition type minecraft:reference invokes a predicate file and returns the result to the invoker.

In addition to predicate files, predicates themselves are used in other locations within other data pack files such as advancements and loot tables.

Below are a few simple predicate examples for context.

{
  "condition": "minecraft:entity_properties",
  "entity": "this",
  "predicate": {
    "equipment": {
      "mainhand": {
        "items": ["minecraft:diamond_sword"]
      }
    }
  }
}

{
  "condition": "minecraft:time_check",
  "value": { "min": 0, "max": 12000 },
  "period": 24000
}

{
  "condition": "minecraft:any_of",
  "terms": [
    { "condition": "minecraft:random_chance", "chance": 0.25 },
    { "condition": "minecraft:weather_check", "raining": true }
  ]
}

These snippets can be placed inside data/<namespace>/predicate/ within a data pack, then referenced using commands such as:

/execute if predicate my_pack:daytime_check run say Good morning!

This section describes the JSON format of a predicate.

The possible values for [String] condition and associated extra contents:

Java Edition
1.15			19w38a				Added predicates to data packs.
1.16			20w12a				Added fishing_hook sub-predicate into entity predicate to check properties of the fishing hook.
1.19			22w14a				player, fishing_hook, lightning_bolt, and catType fields have been replaced with type_specific. type_specific has field type (one of player, fishing_hook, lightning_bolt, or cat) and same sub-fields as removed fields.
1.19.3			23w06a				Removed is_projectile, is_explosion, bypasses_armor, bypasses_invulnerability, bypasses_magic, is_fire, is_magic, and is_lightning fields from damage_source_properties.
							A new tags array has been added to damage_source_properties. Each entry has two fields: id: The ID of a damage type tag. expected: Whether the damage is expected to have or not have the tag for the predicate to match.
1.20			23w18a				Condition alternative has been renamed to any_of.
							Added new condition all_of that passes only when all sub-conditions pass, with the same syntax as any_of.
1.20.5			24w09a				Item predicate format has been updated: tag field has been removed. items field now supports a single entry, hash-prefixed item tag, or list of items. potion renamed to potions, and supports a single entry, hash-prefixed potion tag, or list of potions. nbt predicate has been renamed to custom_data and now matches minecraft:custom_data component. A new optional components field matches exact components.
							Block predicate format has been updated: tag field has been removed. blocks field now supports a single entry, hash-prefixed block tag, or list of blocks.
							Fluid predicate format has been updated: tag field has been removed. fluid renamed to fluids, and supports a single entry, hash-prefixed fluid tag, or list of fluids.
							Entity predicate format has been updated: type field now supports a single entry, hash-prefixed entity type tag, or list of entity types.
							Location predicate format has been updated: biome renamed to biomes, and supports a single entry, hash-prefixed biome tag, or list of biomes. structure renamed to structures, and supports a single entry, hash-prefixed structure tag, or list of structures.
			24w10a				Added entity sub-predicate slots, used to check single or multiple slots on any entity.
			24w11a				Removed entity sub-predicate any Component-specific item predicate properties have been moved to separate field predicates
							Item sub-predicate format has been updated: Some fields from item predicate have been moved to a map in an optional field predicates. enchantments, stored_enchantments, potions, custom_data fields have been moved to minecraft:enchantments, minecraft:stored_enchantments, minecraft:potion_contents, minecraft:custom_data sub-predicates respectively. durability field has been expanded to minecraft:damage predicate. Predicates minecraft:enchantments, minecraft:stored_enchantments, minecraft:potion_contents, minecraft:damage now require matching component to exist on them.
1.21			24w18a				Renamed random_chance_with_looting to random_chance_with_enchanted_bonus, changing the chance field from a float to a level-based value, removing the looting_multiplier field, and adding a enchantment field.
							Changed the chance field of random_chance from a float into a number provider.
							Added a can_see_sky field to location predicates.
							Renamed enchantment to enchantments in the minecraft:enchantments item sub-predicate; now accepting multiple possible enchantments, or tags.
							Changes to the entity predicate: added is_on_ground and is_flying flags to flags sub-predicate. added movement sub-predicate. added periodic_ticks sub-predicate.
							Renamed loot context entities: killer renamed to attacker; direct_killer renamed to direct_attacker; killer_player renamed to attacking_player.
			24w19a				Added is_direct field to damage type predicates.
			24w21a				Added jukebox_playable item predicate.
							The gamemode field of the player predicate now accepts a list of gamemodes rather than a single string.
			pre1				Split chance into unenchanted_chance and enchanted_chance in the random_chance_with_enchanted_bonus condition.
1.21.2			24w35a				New entity sub-predicate for testing sheep wool. Fields: sheared and color.
			24w36a				New entity sub-predicate for testing player input. Available inputs to test are forward, backward left, right, jump, sneak, and sprint.
			24w37a				New entity sub-predicate for salmon. Fields: variant.
			24w39a				Removed the minecraft:boat entity sub-predicate, since boats no longer have variants.
1.21.5			25w03a				A new optional field was added to entity predicate: components.
							Several entity sub-predicates have been removed and replaced with combination of components predicate and variant entity components.
							The field color has been removed from minecraft:sheep sub-predicate.
			25w07a				The stepping_on entity predicate can only evaluate to true if the entity is on ground.
			25w10a				New optional fields have been added to block predicates: components and predicates.
							A new optional field has been added to entity predicates: predicates.
1.21.11			25w41a				Component predicates (predicates field in block, item and entity predicates) now include predicates for checking existence of every component type.
							The flags entity predicate now supports new values.
26.1			snap1				player Sub-Predicate has a new optional field: food.
			snap3				minecraft:time_check loot predicate: added clock field.
			pre1				Added the minecraft:environment_attribute_check loot predicate.
26.2			snap3				The entity predicate format has changed from a structure with multiple optional fields to one similar to data component maps.
							Added minecraft:entity_tags entity sub-predicate.
			snap4				The entity sub-predicate slime has been renamed to cube_mob.
Upcoming Java Edition
26.3			snap3				New entries added to previously empty minecraft:predicate: minecraft:tool/can_silk_touch, minecraft:tool/can_shear.
							The minecraft:potion_contents data component predicate has been changed to allow matching on specific potion effects.
			snap4				Added the match_block condition type.
							The condition field has been renamed to type.
							Numerous fields in predicates now accept an inline value or a namespaced ID of a corresponding type.
							Removed the reference condition type.
							Removed the block_state_property condition type. It has been fully replaced by match_block.

• Data pack – where predicates are defined and stored
• Loot table – one of the most common predicate users
• Advancement – another system that embeds predicates
• Execute – command subcomponent that can run predicates

• Predicate Generator on misode.github.io

v t e Java Edition technical
General Concepts Block entity Coordinates Crashes Loot context Mob AI Point of Interest Identifier Screenshot Statistics Telemetry Tick Random Tick UUID JSON General format Data values Classic Remake Indev Pre-flattening Data component format Predicate Entity format Block entity format Map item format NBT Format Particle format Text component format § Formatting codes Key codes Random sequence Structure file format Schematic file format World Heightmap Seed Anomalous Data version Legacy Spawn chunk Level format Anvil file format Chunk format Player format Point of Interest format raids.dat format Command storage format Scoreboard format Legacy Classic level format Classic server protocol Indev level format Alpha level format Zone file format Region file format server_level.dat format villages.dat format Generated structures format .minecraft client.jar version.json client.json command_history.txt launcher_profiles.json launcher_settings.json options.txt version_manifest.json hotbar.nbt format Server list format Tools F3 Debug screen hotkey renderer Developer Tools GameTest DataFixerUpper Debug properties Legacy Obfuscation map Sound Block sound type Closed captions sounds.json Commands Brigadier Functions All commands Launching Mojang API Microsoft authentication Quick Play Legacy Legacy Minecraft authentication Yggdrasil Protocol Protocol version Packets Data types Encryption Server server.jar server.properties Server requirements Whitelist Operator list Code of conduct Protocols Query RCON Server Management Protocol Legacy al_version Item format
Data pack Components pack.mcmeta Pack format Advancements Functions Item modifier Loot tables Predicate Recipe Damage type Chat type Enchantment Enchantment provider Painting variant Banner pattern Instrument Jukebox song Trial spawner configuration Mob variants Dialog Armor trim Timeline Villager trade Trade set World clock Sulfur cube archetype Slot sources​[upcoming: JE 26.3] Decorated pot pattern​[upcoming: JE 26.3] Number provider Block transformer​[upcoming: JE 26.3] Tag Block Item Function Fluid Entity type Game event Biome Flat level generator preset World preset Structure Point of interest type Painting variant Banner pattern Instrument Damage type Enchantment Dialog Timeline Potion Villager trade Configured feature GameTest Test environment Test instance World generation Dimension Dimension type World preset Biomes Carver Configured feature Tree Placed feature Environment attribute Noise settings Noise router Density function Noises Surface rule Structures Structure set Template pool Processor list Structure templates Removed Configured surface builder Data packs Caves & Cliffs Prototype Data Pack Phantom Frames Tutorials Importing Creating Optimizing Command blocks and functions Repairing a world corrupted by a data pack Content Custom enchantments Custom paintings Custom trims World generation New dimension Custom structures
Resource pack Components pack.mcmeta Pack format Language Models Blockstates Items Sounds (sounds.json) Shaders Textures Atlases Aa Fonts Colormaps Texts Waypoint styles regional_compliancies.json Equipment Debug Missing font character Missing model Missing texture Tools Slicer Legacy Texture Ender Unstitcher Tutorials Creating Loading Models Sound directory