Predicates are data pack files, invoked with various means to check conditions within the world. They return a pass or fail result to the invoker, who will act differently based on this result.
This page describes how predicates are defined and invoked. Also described here is the JSON structure of a predicate condition, the primary JSON structure used within predicates.
Within this article, the term "predicate condition" may be referred to by the short form "condition."
Definition[]
A predicate is defined with the JSON format. It contains either the structure of a condition, or an array with multiple conditions.
- (data pack name)
- pack.mcmeta
- pack.png
- data
- (namespace)
- advancements
- (advancement).json
- functions
- (function).mcfunction
- item_modifiers
- (modifier).json
- loot_tables
- (loot table).json
- predicates
- (predicate).json
- Further folders…
- advancements
- (namespace)
The root element of a predicate can be either an object, following the structure of a condition below, or an array containing multiple conditions.
Invocation[]
Predicates can be invoked in several different manners from other data pack files:
Invocation from commands[]
Commands or functions can invoke predicates in two ways:
- Target selectors: The selector argument
predicate=
checks predicates as a filter for entity selection. The predicate 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 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.
Invocation from other conditions[]
The condition type minecraft:reference
invokes a predicate file and returns the result to the invoker.
Predicate conditions' presence in other files[]
In addition to predicates, the JSON structure of predicate conditions, described below, is used in other locations within other data pack files such as advancements and loot tables.
Predicate condition JSON format[]
This section describes the JSON format of a single predicate condition. Multiple conditions may be entered into a single predicate by placing them into a JSON array.
- : The root element of the condition.
- condition: The resource location of the condition type to check.
- Other parts of the condition, specified below.
The possible values for condition and associated extra contents:
- alternative—Evaluates a list of conditions and passes if any one of them passes. Invokable from any context.
- terms: The list of conditions to evaluate. Conditinons within this array must be objects, they cannot themselves be arrays.
- A condition, following this structure recursively.
- terms: The list of conditions to evaluate. Conditinons within this array must be objects, they cannot themselves be arrays.
- block_state_property—Checks the mined block and its block states. Invokable from loot tables, and always fails when invoked from anything else.
- block: A block ID. The test fails if the block doesn't match.
- properties: (Optional) A map of block property names to values. All values are strings. The test fails if the block doesn't match.
- damage_source_properties—Checks properties of damage source. Invokable from loot tables, and fails when invoked from anything else.
- predicate: Predicate applied to the damage source.
- Tags common to all damage types
- predicate: Predicate applied to the damage source.
- entity_properties—Checks properties of an entity. Invokable from any context.
- entity: The entity to check. Set to
this
to use the entity that invoked this condition,killer
for the killer of thethis
entity, orkiller_player
to only select the killer if they are a player. - predicate: Predicate applied to entity, uses same structure as advancements.
- All possible conditions for entities
- entity: The entity to check. Set to
- entity_scores—Checks the scoreboard scores of an entity. May be invoked from any context.
- entity: The entity to check. Set to
this
to use the entity that invoked this condition,killer
for the killer of thethis
entity, orkiller_player
to only select the killer if they are a player. - scores: Scores to check. All specified scores must pass for the condition to pass.
- A score: Key name is the objective while the value specifies a range of score values required for the condition to pass.
- min: Number Provider. Minimum score.
- max: Number Provider. Maximum score.
- 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.
- A score: Key name is the objective while the value specifies a range of score values required for the condition to pass.
- entity: The entity to check. Set to
- inverted—Inverts another loot table condition. Invokable from any context.
- term: The condition to be negated, following the same structure as outlined here, recursively.
- killed_by_player—Checks if a
killer_player
entity exists. Invokable from loot tables, and fails when invoked from anything else.- inverse: If true, the condition passes if
killer_player
is not available.
- inverse: If true, the condition passes if
- location_check—Checks the current location against location criteria. Invokable from any context.
- offsetX - optional offsets to location
- offsetY - optional offsets to location
- offsetZ - optional offsets to location
- predicate: Predicate applied to location, uses same structure as advancements.
- Tags common to all locations
- match_tool—Checks tool used to mine the block. Invokable from loot tables, and fails when invoked from anything else.
- predicate: Predicate applied to item, uses same structure as advancements.
- All possible conditions for items
- predicate: Predicate applied to item, uses same structure as advancements.
- 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.
- chance: Success rate as a number 0.0–1.0.
- random_chance_with_looting—Generates a random number between 0.0 and 1.0, and checks if it is less than a specified value which has been affected by the level of Looting on the
killer
entity. Invokable from advancements and loot tables, and fails[verify] when invoked from anything else.- chance: Base success rate.
- looting_multiplier: Looting adjustment to the base success rate. Formula is
chance + (looting_level * looting_multiplier)
.
- reference—Invokes a predicate file and returns its result. Invokable from any context.
- name: The resource location of the predicate to invoke. A cyclic reference causes a parsing failure.
- survives_explosion—Returns true with
1 ÷ explosion radius
probability. Invokable only from loot tables, and fails[verify] when invoked from anything else.
- table_bonus—Passes with probability picked from table, indexed by enchantment level. Invokable from any context.
- enchantment: Resource location of enchantment.
- chances: List of probabilities for enchantment level, indexed from 0.
- time_check—Compares the current game time (the age of the world in game ticks) against given values. Invokable from any context.
- value: The time to compare the game time against.
- min: Number Provider. The minimum value.
- max: Number Provider. The maximum value.
- value: Shorthand version of value above, used to check for a single value only. Number providers cannot be used in this shorthand form.
- period: If present, the game time is first reduced modulo the given number before being checked against value. For example, setting this to 24000 causes the checked time to be equal to the current daytime.
- value: The time to compare the game time against.
- value_check—Compares a number against another number or range of numbers. Invokable from any context.
- value: Number Provider. The number to test.
- range: The range of numbers to compare value against.
- min: Number Provider. The minimum value.
- max: Number Provider. The maximum value.
- range: Shorthand version of range above, used to compare 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.
- raining: If true, the condition passes only if it is raining or thundering.
- thundering: If true, the condition passes only if it is thundering.
History[]
Java Edition | |||||
---|---|---|---|---|---|
1.15 | 19w38a | Added predicates to data packs. |
Components |
|
---|---|
Data packs | |
Tutorials |