Minecraft: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 Minecraft: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 Minecraft:data packs, or they can be directly defined "in-line" in various places. They can be used throughout the game such as in commands, Minecraft:loot tables, and Minecraft: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 Minecraft:JSON files in data packs containing the definition for a predicate. The file path indicates the Minecraft:namespaced identifier used to reference it.

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 Minecraft: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 Template:Nbt following the predicate structure below, or an Template:Nbt containing multiple predicates. In the latter case all predicates must evaluate to true.

Usage

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

Commands

Minecraft:Commands or functions can invoke predicate files in two ways:

• Minecraft: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.
• Template:Cmd: 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.

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.

Examples

Below are a few simple predicate examples for context.

Example 1: Check if player is holding a diamond sword

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

Example 2: Only run if it’s daytime

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

Example 3: Nested example using any_of

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

These snippets can be placed inside Template:Cd within a data pack, then referenced using commands such as:

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

JSON format

This section describes the JSON format of a predicate.

• Template:NbtTemplate:Nbt: The root element of the predicate.
  • Template:NbtTemplate:Until / Template:NbtTemplate:Upcoming: The Minecraft:resource location of the condition type to check.
  • Other parts of the predicate, specified below. In lists each element must evaluate to true for the predicate to pass.

The possible values for Template:Nbt and associated extra contents:

• all_of — Evaluates a list of predicates and passes if all of them pass. Invokable from any context.
  • Template:Nbt: The list of predicates to evaluate.Template:Until / an inline value, a single namespaced ID, a list of namespaced IDs, a list of inline values, or a hash-prefixed tag ID of a Template:Cd type.Template:Upcoming
    • Template:NbtTemplate:Nbt 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.
  • Template:Nbt: The list of predicates to evaluate.Template:Until / an inline value, a single namespaced ID, a list of namespaced IDs, a list of inline values, or a hash-prefixed tag ID of a Template:Cd type.Template:Upcoming
    • Template:NbtTemplate:Nbt A predicate, following this structure recursively. Note that any_of only applies to Template:Nbt, nested lists are all_of.

• block_state_propertyTemplate:Until — Checks the mined block and its Minecraft:block states. Requires block state provided by Minecraft:loot context, and always fails if not provided.
  • Template:Nbt: A block ID. The test fails if the block doesn't match.
  • Template:Nbt: (Optional) A map of block state names to values. Errors if the block doesn't have these properties.
    • Template:Nbt: A block state and an exact value. The value is a string.
    • Template:Nbt: A block state name and a ranged value to match.
      • Template:Nbt: The min value.
      • Template:Nbt: The max value.

• damage_source_properties — Checks properties of the damage source. Requires origin and damage source provided by Minecraft:loot context, and always fails if not provided.
  • Template:Nbt: Predicate applied to the damage source.
    • Template:Nbt inherit/conditions/damage type

• enchantment_active_check — Checks if the enchantment has been active. Requires enchantment active status provided by Minecraft:loot context, and always fails if not provided. It is therefore only usable from the Template:Cd loot context.
  • Template:Nbt: Whether to check for an active (Template:Cd) or inactive (Template:Cd) enchantment.

• entity_properties — Checks properties of an entity. Invokable from any context.
  • Template:Nbt: The entity to check. Specifies an entity from Minecraft:loot context. Can be Template:Loot entity target.
  • Template:Nbt: Predicate applied to entity, uses same structure as advancements.
    • Template:Nbt inherit/conditions/entity

• entity_scores — Checks the Minecraft:scoreboard scores of an entity. Requires the specified entity provided by Minecraft:loot context, and always fails if not provided.
  • Template:Nbt: The entity to check. Specifies an entity from Minecraft:loot context. Can be Template:Loot entity target.
  • Template:Nbt: Scores to check. All specified scores must pass for the condition to pass.
    • Template:Nbt: Key name is the objective while the value specifies a range of score values required for the condition to pass.
      • Template:NbtTemplate:Nbt: A number provider.Template:Until / an inline value or a namespaced ID of a Template:Cd type.Template:Upcoming Minimum score. Optional.
      • Template:NbtTemplate:Nbt: A number provider.Template:Until / an inline value or a namespaced ID of a Template:Cd type.Template:Upcoming Maximum score. Optional.
    • Template:Nbt: 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.
  • Template:Nbt: The condition to be negated, following the same structure as outlined here, recursively.Template:Until / an inline value or a namespaced ID of a Template:Cd type.Template:Upcoming

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

• location_check — Checks the current location against location criteria. Requires origin provided by Minecraft:loot context, and always fails if not provided.
  • Template:Nbt: An optional x offset to the location.
  • Template:Nbt: An optional y offset to the location.
  • Template:Nbt: An optional z offset to the location.
  • Template:Nbt: Predicate applied to location, uses same structure as advancements.
    • Template:Nbt inherit/conditions/location

• match_blockTemplate:Upcoming — Matches block state and optionally block entity data and components (if present).
  • Template:NbtTemplate:Nbt: Optional; Can be a single block ID, a list of namespaced block IDs, or a hash-prefixed block tag to match.
    • • Template:Nbt: Optional; The block state property keys to values to match.
      • Template:Nbt: Optional; Minecraft:Block entity NBT to match. See Minecraft:Block entity format. Match will fail if the field is present, but the block entity is not available in context.
      • Template:Nbt: Optional; Map of exact components to match. Match will fail if the field is present, but the block entity is not available in context.
      • Template:Nbt: Optional; Map of component predicates to match. Match will fail if the field is present, but the block entity is not available in context.

• match_tool — Checks tool used to mine the block. Requires tool provided by Minecraft:loot context, and always fails if not provided.
  • Template:Nbt: Predicate applied to item, uses same structure as advancements.
    • Template:Nbt inherit/conditions/item

• 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.
  • Template:NbtTemplate:Nbt: A number provider.Template:Until / an inline value or a namespaced ID of a Template:Cd type.Template:Upcoming 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 Minecraft:loot context, and if not provided, the enchantment level is regarded as 0.
  • Template:Nbt: The success rate to use when the enchantment is not present; 0.0–1.0.
  • Template:NbtTemplate:Nbt: Minecraft:level-based value. The success rate based on the level when then enchantment is present; 0.0–1.0.
  • Template:Nbt: Template:Json ref/enchantment. The enchantment whose level to use for the chance calculation. If the enchantment is not present, uses Template:Cd as level.

• referenceTemplate:Until — Invokes a predicate file and returns its result. Invokable from any context. Cannot be used in enchantment definitions.
  • Template:Nbt: The Minecraft:resource location of the predicate to invoke. A cyclic reference causes a parsing failure.

• survives_explosion — Returns success with Template:Cd probability. Requires explosion radius provided by Minecraft: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 Minecraft:loot context. If not provided, the enchantment level is regarded as 0.
  • Template:Nbt: Minecraft:Resource location of enchantment.
  • Template:Nbt: 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.
  • Template:Nbt: Template:Json ref to check the time of.
  • Template:Nbt: The time to compare the day time against.
    • Template:NbtTemplate:Nbt: A number provider.Template:Until / an inline value or a namespaced ID of a Template:Cd type.Template:Upcoming The minimum value.
    • Template:NbtTemplate:Nbt: A number provider.Template:Until / an inline value or a namespaced ID of a Template:Cd type.Template:Upcoming The maximum value.
  • Template:Nbt: Shorthand version of Template:Nbt above, used to check for a single value only. Number providers cannot be used in this shorthand form.
  • Template:Nbt: If present, the day time is first reduced modulo the given number before being checked against Template:NbtTemplate:Nbt. 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.
  • Template:NbtTemplate:Nbt: A number provider.Template:Until / an inline value or a namespaced ID of a Template:Cd type.Template:Upcoming The number to test.
  • Template:Nbt: The range of numbers to compare Template:NbtTemplate:Nbt against.
    • Template:NbtTemplate:Nbt: A number provider.Template:Until / an inline value or a namespaced ID of a Template:Cd type.Template:Upcoming The minimum value.
    • Template:NbtTemplate:Nbt: A number provider.Template:Until / an inline value or a namespaced ID of a Template:Cd type.Template:Upcoming The maximum value.
  • Template:Nbt: Shorthand version of Template:Nbt above, used to compare Template:NbtTemplate:Nbt 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.
  • Template:Nbt: If true, the condition passes only if it is raining or thundering.
  • Template:Nbt: If true, the condition passes only if it is thundering.

See also

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

External links

• Predicate Generator on misode.github.io