Predicate

This feature is exclusive to Java Edition.

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 will act 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 of predicate files[]

A predicate file is defined with the JSON format. It contains either the structure of a predicate, or an array with multiple predicates.

Predicate files belong in the following folder of a data pack's structure, highlighted below:

(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…

The root element of a predicate file can be either an object following the predicate structure below, or an array containing multiple predicates.

Invocation[]

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

Invocation from 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.

Invocation from other predicates[]

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

Predicates' 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.

Predicate JSON format[]

This section describes the JSON format of a predicate.

: The root element of the predicate.
- condition: The resource location of the condition type to check.
- Other parts of the predicate, specified below.

The possible values for condition and associated extra contents:

all_of—Evaluates a list of predicates and passes if all of them pass. Invokable from any context.
- terms: The list of predicates to evaluate. A predicate within this array must be a 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.
- terms: The list of predicates to evaluate. A predicate within this array must be a 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.
- block: A block ID. The test fails if the block doesn't match.
- properties: (Optional) A map of block state names to values. Errors if the block doesn't have these properties.
  - name: A block state and a exact value. The value is a string.
  - name: A block state name and a ranged value to match.
    - min: The min value.
    - 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.
- predicate: Predicate applied to the damage source.
  - Tags common to all damage types

entity_properties—Checks properties of an entity. Invokable from any context.
- entity: The entity to check. Specifies an entity from loot context. Can be this, killer, direct_killer, or killer_player.
- predicate: Predicate applied to entity, uses same structure as advancements.
  - All possible conditions for entities

entity_scores—Checks the scoreboard scores of an entity. Requires the specified entity provided by loot context, and always fails if not provided.
- entity: The entity to check. Specifies an entity from loot context. Can be this, killer, direct_killer, or killer_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: A number Provider. Minimum score.
    - max: A 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.

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 there is a killer_player entity provided by loot context. Requires killer_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.
- offsetX: An optional x offset to the location.
- offsetY: An optional y offset to the location.
- offsetZ: An optional z offset to the 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. Requires tool provided by loot context, and always fails if not provided.
- predicate: Predicate applied to item, uses same structure as advancements.
  - All possible conditions for items

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. Requires killer entity provided by loot context, and if not provided, the looting level is regarded as 0.
- 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 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.
- enchantment: Resource location of enchantment.
- 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.
- value: The time to compare the day time against.
  - min: A number Provider. The minimum value.
  - max: A 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 day 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_check—Compares a number against another number or range of numbers. Invokable from any context.
- value: A number Provider. The number to test.
- range: The range of numbers to compare value against.
  - min: A number Provider. The minimum value.
  - max: A 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.
1.16	20w12a	Added fishing_hook sub-predicate into entity predicate to check properties of the fishing hook.
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`.
1.19.3	23w06a	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`.
1.20	23w18a	Added new condition `all_of` that passes only when all sub-conditions pass, with the same syntax as `any_of`.