Predicate

Predicates are JSON structures found in multiple different locations within data packs. They are invoked with various means to check conditions within the world. They return a pass or fail result to the invoker, who acts differently based on this result.

Predicate files are standalone data pack files that contain one or more predicates. Predicates can also be defined in other ways.

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

Definition

A predicate file is defined with the JSON format.

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

•  data pack name.zip or  data pack name
  •  pack.mcmeta
  •  data
    •  namespace
      •  predicate
        •  <name>.json
      • More directories…

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.

Usage

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

Commands

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 to either return a result or to decide whether to continue with a subcommand chain. The predicate file is invoked once at the current contextual position of execution.

Other predicates

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

Presence in other files

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

JSON format

This section describes the JSON format of a predicate.

• [NBT Compound / JSON Object]: The root element of the predicate.
  • [String] condition: The resource location of the condition type to check.
  • Other parts of the predicate, specified below.

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

• all_of—Evaluates a list of predicates and passes if all of them pass. Invokable from any context.
  • [NBT List / JSON Array] terms: The list of predicates to evaluate. A predicate within this array must be a [NBT Compound / JSON Object] object.
    • [NBT Compound / JSON Object] A predicate, following this structure recursively.

• any_of—Evaluates a list of predicates and passes if any one of them passes. Invokable from any context.
  • [NBT List / JSON Array] terms: The list of predicates to evaluate. A predicate within this array must be a [NBT Compound / JSON Object] object.
    • [NBT Compound / JSON Object] A predicate, following this structure recursively.

• block_state_property—Checks the mined block and its block states. Requires block state provided by loot context, and always fails if not provided.
  • [String] block: A block ID. The test fails if the block doesn't match.
  • [NBT Compound / JSON Object] properties: (Optional) A map of block state names to values. Errors if the block doesn't have these properties.
    • [String] name: A block state and a exact value. The value is a string.
    • [NBT Compound / JSON Object] name: A block state name and a ranged value to match.
      • [String] min: The min value.
      • [String] max: The max value.

• damage_source_properties—Checks properties of the damage source. Requires origin and damage source provided by loot context, and always fails if not provided.
  • [NBT Compound / JSON Object] predicate: Predicate applied to the damage source.
    • Tags common to all damage types see Template:Nbt inherit/conditions/damage_type/template

• enchantment_active_check—Checks if the enchantment has been active. Requires enchantment active status provided by loot context, and always fails if not provided. It is therefore only usable from the enchanted_location loot context.
  • [Boolean] active: Whether to check for an active (true) or inactive (false) enchantment.

• entity_properties—Checks properties of an entity. Invokable from any context.
  • [String] entity: The entity to check. Specifies an entity from loot context. Can be this, attacker, direct_attacker, or attacking_player.
  • [NBT Compound / JSON Object] predicate: Predicate applied to entity, uses same structure as advancements.
    • All possible conditions for entities see Template:Nbt inherit/conditions/entity/template

• entity_scores—Checks the scoreboard scores of an entity. Requires the specified entity provided by loot context, and always fails if not provided.
  • [String] entity: The entity to check. Specifies an entity from loot context. Can be this, attacker, direct_attacker, or attacking_player.
  • [NBT Compound / JSON Object] scores: Scores to check. All specified scores must pass for the condition to pass.
    • [NBT Compound / JSON Object] A score: Key name is the objective while the value specifies a range of score values required for the condition to pass.
      • [Int][NBT Compound / JSON Object] min: A number provider. Minimum score. Optional.
      • [Int][NBT Compound / JSON Object] max: A number provider. Maximum score. Optional.
    • [Int] A score: Shorthand version of the other syntax above, to check the score against a single number only. Key name is the objective while the value is the required score.

• inverted—Inverts another predicate condition. Invokable from any context.
  • [NBT Compound / JSON Object] term: The condition to be negated, following the same structure as outlined here, recursively.

• killed_by_player—Checks if there is a attacking_player entity provided by loot context. Requires attacking_player entity provided by loot context, and always fails if not provided.

• location_check—Checks the current location against location criteria. Requires origin provided by loot context, and always fails if not provided.
  • [Int] offsetX: An optional x offset to the location.
  • [Int] offsetY: An optional y offset to the location.
  • [Int] offsetZ: An optional z offset to the location.
  • [NBT Compound / JSON Object] predicate: Predicate applied to location, uses same structure as advancements.
    • Tags common to all locations see Template:Nbt inherit/conditions/location/template

• match_tool—Checks tool used to mine the block. Requires tool provided by loot context, and always fails if not provided.
  • [NBT Compound / JSON Object] predicate: Predicate applied to item, uses same structure as advancements.
    • All possible conditions for items see Template:Nbt inherit/conditions/item/template

• random_chance—Generates a random number between 0.0 and 1.0, and checks if it is less than a specified value. Invokable from any context.
  • [Float][NBT Compound / JSON Object] chance: A number provider. Success rate as a number 0.0–1.0.

• random_chance_with_enchanted_bonus—Generates a random number between 0.0 and 1.0, and checks if it is less than the value determined using the level of a given enchantment. Requires attacker entity provided by loot context, and if not provided, the enchantment level is regarded as 0.
  • [Float] unenchanted_chance: The success rate to use when the enchantment is not present; 0.0–1.0.
  • [Float][NBT Compound / JSON Object] enchanted_chance: level-based value. The success rate based on the level when then enchantment is present; 0.0–1.0.
  • [String] enchantment: One enchantment (an [String] ID). The enchantment whose level to use for the chance calculation. If the enchantment is not present, uses 0 as level.

• reference—Invokes a predicate file and returns its result. Invokable from any context.
  • [String] name: The resource location of the predicate to invoke. A cyclic reference causes a parsing failure.

• survives_explosion—Returns success with 1 ÷ explosion radius probability. Requires explosion radius provided by loot context, and always success if not provided.

• table_bonus—Passes with probability picked from a list, indexed by enchantment power. Requires tool provided by loot context. If not provided, the enchantment level is regarded as 0.
  • [String] enchantment: Resource location of enchantment.
  • [NBT List / JSON Array] chances: List of probabilities for enchantment power, indexed from 0.

• time_check—Compares the current day time (or rather, 24000 * day count + day time) against given values. Invokable from any context.
  • [NBT Compound / JSON Object] value: The time to compare the day time against.
    • [Int][NBT Compound / JSON Object] min: A number provider. The minimum value.
    • [Int][NBT Compound / JSON Object] max: A number provider. The maximum value.
  • [Int] value: Shorthand version of [NBT Compound / JSON Object] value above, used to check for a single value only. Number providers cannot be used in this shorthand form.
  • [Int] period: If present, the day time is first reduced modulo the given number before being checked against [NBT Compound / JSON Object][Int] value. For example, setting this to 24000 causes the checked time to be equal to the current daytime.

• value_check—Compares a number against another number or range of numbers. Invokable from any context.
  • [Int][NBT Compound / JSON Object] value: A number provider. The number to test.
  • [NBT Compound / JSON Object] range: The range of numbers to compare [Int][NBT Compound / JSON Object] value against.
    • [Int][NBT Compound / JSON Object] min: A number provider. The minimum value.
    • [Int][NBT Compound / JSON Object] max: A number provider. The maximum value.
  • [Int] range: Shorthand version of [NBT Compound / JSON Object] range above, used to compare [Int][NBT Compound / JSON Object] value against a single number only. Number providers cannot be used in this shorthand form.

• weather_check—Checks the current game weather. Invokable from any context.
  • [Boolean] raining: If true, the condition passes only if it is raining or thundering.
  • [Boolean] thundering: If true, the condition passes only if it is thundering.

History

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.

External links

• Predicate Generator on misode.github.io