VOOZH about

URL: https://minecraft.wiki/w/Predicate

⇱ Predicate – Minecraft Wiki

Predicate

From Minecraft Wiki
Jump to navigation Jump to search
👁 Image
 For predicates inside models, see Tutorial:Models § Item predicates.
This feature is exclusive to Java Edition.
 

Predicates are JSON structures invoked to check conditions within the world. They return a pass or fail result to the invoker, which acts differently based on the result. They can be defined and invoked by data packs or by commands. 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 data pack files containing one or more predicates.

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

Contents

Definition

[edit | edit source]

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.

Usage

[edit | edit source]

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

Commands

[edit | edit source]

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.

Other predicates

[edit | edit source]

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

Presence in other files

[edit | edit source]

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

Examples

[edit | edit source]

Below are a few simple predicate examples for context.

Example 1: Check if player is holding a diamond sword

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

Example 2: Only run if it’s daytime

[edit | edit source]
{
 "condition": "minecraft:time_check",
 "value": { "min": 0, "max": 12000 },
 "period": 24000
}

Example 3: Nested example using any_of

[edit | edit source]
{
 "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!

JSON format

[edit | edit source]

This section describes the JSON format of a predicate.

  • [NBT List / JSON Array][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. In lists each element must evaluate to true for the predicate to pass.

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.
      • [NBT List / JSON Array][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.
      • [NBT List / JSON Array][NBT Compound / JSON Object] A predicate, following this structure recursively. Note that any_of only applies to [NBT List / JSON Array] terms, nested lists are all_of.
  • 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 an 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.
  • 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, attacking_player, target_entity, or interacting_entity..
    • [NBT Compound / JSON Object] predicate: Predicate applied to entity, uses same structure as advancements.
  • 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, attacking_player, target_entity, or interacting_entity..
    • [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.
  • match_tool—Checks tool used to mine the block. Requires tool provided by loot context, and always fails if not provided.
  • 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. Cannot be used in enchantment definitions.
    • [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.
    • [String] clock: One world clock (an [String] ID) to check the time of.
    • [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

[edit | edit source]
Java Edition
1.1519w38aAdded predicates to data packs.
1.1620w12aAdded fishing_hook sub-predicate into entity predicate to check properties of the fishing hook.
1.1922w14aplayer, 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.323w06aRemoved 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.2023w18aCondition 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.524w09aItem 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.
24w10aAdded entity sub-predicate slots, used to check single or multiple slots on any entity.
24w11aRemoved 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.2124w18aRenamed 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.
24w19aAdded is_direct field to damage type predicates.
24w21aAdded jukebox_playable item predicate.
The gamemode field of the player predicate now accepts a list of gamemodes rather than a single string.
pre1Split chance into unenchanted_chance and enchanted_chance in the random_chance_with_enchanted_bonus condition.
1.21.224w35aNew entity sub-predicate for testing sheep wool. Fields: sheared and color.
24w36aNew entity sub-predicate for testing player input. Available inputs to test are forward, backward left, right, jump, sneak, and sprint.
24w37aNew entity sub-predicate for salmon. Fields: variant.
24w39aRemoved the minecraft:boat entity sub-predicate, since boats no longer have variants.
1.21.525w03aA 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.
25w07aThe stepping_on entity predicate can only evaluate to true if the entity is on ground.
25w10aNew optional fields have been added to block predicates: components and predicates.
A new optional field has been added to entity predicates: predicates.
1.21.1125w41aComponent 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.1snap1player Sub-Predicate has a new optional field: food.
snap3minecraft:time_check loot predicate: added clock field.
pre1Added the minecraft:environment_attribute_check loot predicate.
26.2snap3The 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.
snap4The entity sub-predicate slime has been renamed to cube_mob.

See also

[edit | edit source]
  • 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

External links

[edit | edit source]

Navigation

[edit | edit source]
Java Edition technical
General
Concepts
General format
World
Legacy
Level format
Legacy
.minecraft
Tools
Legacy
Sound
Commands

All commands

Launching
Legacy
Protocol
Server
Protocols
Legacy
Data pack
Components
Tag
GameTest
World generation
Noise settings
Structures
Removed
Data packs
Tutorials
Content
World generation
Retrieved from "https://minecraft.wiki/w/Predicate?oldid=3630183"
Categories:

Navigation menu