Advancement/JSON format

From Minecraft Wiki
Jump to: navigation, search

Custom advancements in data packs of a Minecraft world store the advancement data for that world as separate JSON files.

Contents

File format[edit]

All advancement JSON files are structured according to the following format:

  • The root tag.
    •  display: The optional display data.
      •  icon: The data for the icon.
        •  item: The item id.
        •  nbt: The nbt data of the item.
      •  title: The title for this advancement.
      •  title: A JSON text component (containing text and formatting like used in /tellraw and various other commands. Also translate tag can be used here).
      •  frame: The optional type of frame for the icon. challenge for a tile with a more fancy spiked border as it is used for the kill all mobs advancement, goal for a tile with a rounded border as it is used for the full beacon advancement, task for a normal tile (default.)
      •  background: The optional directory for the background to use in this advancement tab (used only for the root advancement).
      •  description: The description of the advancement.
      •  description: A JSON text component (containing text and formatting like used in /tellraw and various other commands. Also translate tag can be used here).
      •  show_toast: Can be true or false. Whether or not to show the toast pop up after completing this advancement. Defaults to true.
      •  announce_to_chat: Can be true or false. Whether or not to announce in the chat when this advancement has been completed. Defaults to true.
      •  hidden: Can be true or false. Whether or not to hide this advancement and all its children from the advancement screen until this advancement have been completed. Has no effect on root advancements themselves, but still affects all their children. Defaults to false.
    •  parent: The optional parent advancement directory of this advancement. If this field is absent, this advancement is a root advancement. Circular references cause a loading failure.
    •  criteria: The required criteria that have to be met.
      •  <criterionName>: A name given to the criterion (can be any string, must be unique).
        •  trigger: The trigger for this advancement; specifies what the game should check for the advancement.
        •  conditions: All the conditions that need to be met when the trigger gets activated.
    •  requirements: An optional list of requirements (all the <criteriaNames>). If all criteria are required, this may be omitted. With multiple criteria: requirements contains a list of lists with criteria (all criteria need to be mentioned). If all of the lists each have any criteria met, the advancement is complete. (basically AND grouping of OR groups)
    •  rewards: An optional object representing the rewards provided when this advancement is obtained.

Display[edit]

Within the root tag of an advancement JSON object, the  display field and the  parent field, both optional, are related to the display of the advancement.

If the  display tag is present, it must have both the  title and  description fields present in order to be a valid advancement display data.

The  parent field, albeit not directly associated with the display data of an advancement, affects only the display data effectively. When an advancement does not have a display data and none of its children has a display data, the parent of the advancement only affects /advancement ... through|from|until usage.

Tab creation[edit]

To create a tab in the advancement menu, define a root advancement (an advancement without a parent) with a display. When the data pack containing the advancement is loaded, the root advancement shows a tab in the advancement menu when any advancement in its advancement tree is granted to the player viewing the menu.

When a background is not specified for a root advancement, the tab is still created, but with the tab background appearing as the missing texture.

Presence[edit]

For a non-root advancement (i.e. an advancement with a parent defined), these conditions must be met in order to have it displayed in a tab when unlocked:

  1. Its root advancement must be a valid tab.
  2. It must have a display.

Position[edit]

The game automatically arranges advancements, position them when it loads advancements from data packs, and sends the arrangement to the client. Each advancement has an arrow from its closest visible ancestor (i.e. if its parent does not have a display, it has a link from its grandparent, and so on). The root advancement appears on the leftmost column while each arrow points to an advancement in the next column. The arrangement of advancements within a column is based on file name.

Lack of display[edit]

Some advancements, such as the vanilla recipe unlocking advancements, may lack a display so that they can utilize triggers and rewards instead of excessive commands or functions for more functionalities and a more flexible control. These advancements should not have the  display field defined in order to hide from users and enjoy a better loading performance.

List of triggers[edit]

minecraft:bee_nest_destroyed[edit]

Triggers when the player breaks a bee nest or beehive. Available conditions:

  •  conditions:
    •  block: The block that was destroyed. Accepts block IDs.
    •  item: The item used to break the block.
      • Tags common to all items
    •  num_bees_inside: The number of bees that were inside the bee nest/beehive before it was broken.
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:bred_animals[edit]

Triggers after the player breeds 2 animals. Available conditions:

  •  conditions:
    •  child: The child that results from the breeding. May also be a list of predicates that must pass in order for the trigger to activate.
      • Tags common to all entities
    •  parent: The parent. May also be a list of predicates that must pass in order for the trigger to activate.
      • Tags common to all entities
    •  partner: The partner. (The entity the parent was bred with) May also be a list of predicates that must pass in order for the trigger to activate.
      • Tags common to all entities
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:brewed_potion[edit]

Triggers after the player takes any item out of a brewing stand. Available conditions:

  •  conditions:
    •  potion: A brewed potion ID.
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:changed_dimension[edit]

Triggers after the player travels between two dimensions. Available conditions:

  •  conditions:
    •  from: The dimension the entity traveled from. Accepts these 3 values.
    •  to: The dimension the entity traveled to. Same accepted values as above.
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:channeled_lightning[edit]

Triggers after the player successfully uses the Channeling enchantment on an entity. Available conditions:

  •  conditions:
    •  victims: The victims hit by the lightning summoned by the Channeling enchantment. All entities in this list must be hit. Each entry may also be a list of predicates that must pass in order for the trigger to activate. The checks are applied to the victim hit by the enchanted trident.
      • : A victim.
        • Tags common to all entities
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:construct_beacon[edit]

Triggers after the player changes the structure of a beacon. (When the beacon updates itself). Available conditions:

  •  conditions:
    •  level: The tier of the updated beacon structure.
    •  level:
      •  max: The maximum value.
      •  min: The minimum value.
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:consume_item[edit]

Triggers when the player consumes an item. Available conditions:

  •  conditions:
    •  item: The item that was consumed
      • Tags common to all items
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:cured_zombie_villager[edit]

Triggers when the player cures a zombie villager. Available conditions:

  •  conditions:
    •  villager: The villager that is the result of the conversion. The 'type' tag is redundant since it will always be "villager". May also be a list of predicates that must pass in order for the trigger to activate.
      • Tags common to all entities
    •  zombie: The zombie villager right before the conversion is complete (not when it is initiated). The 'type' tag is redundant since it will always be "zombie_villager". May also be a list of predicates that must pass in order for the trigger to activate.
      • Tags common to all entities
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:effects_changed[edit]

Triggers after the player gets a status effect applied or taken from them. Available conditions:

  •  conditions:
    •  effects: A list of status effects the player has.
      •  <minecraft:effect_name>: A status effect with the key name being the status effect name.
        •  amplifier: The effect amplifier.
        •  amplifier:
          •  max: The maximum value.
          •  min: The minimum value.
        •  duration: The effect duration in ticks.
        •  duration:
          •  max: The maximum value.
          •  min: The minimum value.
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:enchanted_item[edit]

Triggers after the player enchants an item through an enchanting table (does not get triggered through an anvil, or through commands). Available conditions:

  •  conditions:
    •  item: The item after it has been enchanted.
      • Tags common to all items
    •  levels: The levels spent by the player on the enchantment.
    •  levels:
      •  max: The maximum value.
      •  min: The minimum value.
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:enter_block[edit]

Triggers when the player stands in a block. Checks every tick and will try to trigger for each successful match (up to 8 times, the maximum amount of blocks a player can stand in), which only works if the advancement is revoked from within the advancement using a function reward. Available conditions:

  •  conditions:
    •  block: The block that the player is standing in. Accepts block IDs.
    •  state: The block states of the block.
      •  <state_name>: A single block state, with the key name being the state name and the value being the required value of that state.
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:entity_hurt_player[edit]

Triggers after a player gets hurt. It also triggers after player hurts without a source entity. Available conditions:

  •  conditions:
    •  damage: Checks the damage done to the player. Missing corresponding list of predicates.
      • Damage tags
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:entity_killed_player[edit]

Triggers after an entity kills a player. Available conditions:

  •  conditions:
    •  entity: Checks the entity that was the source of the damage that killed the player (for example: The skeleton that shot the arrow). May also be a list of predicates that must pass in order for the trigger to activate.
      • Tags common to all entities
    •  killing_blow: Checks the type of damage that killed the player. Missing corresponding list of predicates for the direct entity.
      • Tags common to all damage types
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:filled_bucket[edit]

Triggers after the player fills a bucket. Available conditions:

  •  conditions:
    •  item: The item resulting from filling the bucket.
      • Tags common to all items
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:fishing_rod_hooked[edit]

Triggers after the player successfully catches an item with a fishing rod or pulls an entity with a fishing rod. Available conditions:

  •  conditions:
    •  entity: The entity that was pulled. May also be a list of predicates that must pass in order for the trigger to activate.
      • Tags common to all entities
    •  item: The item that was caught.
      • Tags common to all items
    •  rod: The fishing rod used.
      • Tags common to all items
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:hero_of_the_village[edit]

Triggers when the player defeats a raid and checks where the player is. Available conditions:

  •  conditions:
    •  location: The location of the player.
      • Tags common to all locations
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:impossible[edit]

Triggers only using commands.

minecraft:inventory_changed[edit]

Triggers after any changes happen to the player's inventory. Available conditions:

  •  conditions:
    •  items: A list of items in the player's inventory. All items in the list must be in the player's inventory, but not all items in the player's inventory have to be in this list.
      • :
        • Tags common to all items
    •  slots:
      •  empty: The amount of slots empty in the inventory.
      •  empty:
        •  max: The maximum value.
        •  min: The minimum value.
      •  full: The amount of slots completely filled (stacksize) in the inventory.
      •  full:
        •  max: The maximum value.
        •  min: The minimum value.
      •  occupied: The amount of slots occupied in the inventory.
      •  occupied:
        •  max: The maximum value.
        •  min: The minimum value.
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:item_durability_changed[edit]

Triggers after any item in the inventory has been damaged in any form. Available conditions:

  •  conditions:
    •  delta: The change in durability (negative numbers are used to indicate a decrease in durability).
    •  delta:
      •  max: The maximum value.
      •  min: The minimum value.
    •  durability: The remaining durability of the item.
    •  durability:
      •  max: The maximum value.
      •  min: The minimum value.
    •  item: The item before it was damaged, allows you to check the durability before the item was damaged.
      • Tags common to all items
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:item_used_on_block[edit]

Triggers when the player uses their hand or an item on a block. Available conditions:

  •  conditions:
    •  location: The location at the center of the block the item was used on.
      • Tags common to all locations
    •  item: The item used on the block.
      • Tags common to all items
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:killed_by_crossbow[edit]

Triggers after the player kills a mob or player using a crossbow in ranged combat. Available conditions:

  •  conditions:
    •  unique_entity_types: The exact count of types of entities killed.
    •  unique_entity_types: The acceptable range of count of types of entities killed.
      •  max: The maximum value.
      •  min: The minimum value.
    •  victims: A predicate for any of the killed entities.
      • Tags common to all entities
    •  victims: A list of predicates for any of the killed entities. All of the predicates must be matched, and one killed entity may match only one predicate.
      • : A predicate for any of the killed entities. May also be a list of predicates that must pass in order for the trigger to activate.
        • Tags common to all entities
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:levitation[edit]

Triggers when the player has the levitation status effect. Available conditions:

  •  conditions:
    •  distance:
      •  absolute:
        •  max: The maximum value.
        •  min: The minimum value.
      •  horizontal:
        •  max: The maximum value.
        •  min: The minimum value.
      •  x:
        •  max: The maximum value.
        •  min: The minimum value.
      •  y:
        •  max: The maximum value.
        •  min: The minimum value.
      •  z:
        •  max: The maximum value.
        •  min: The minimum value.
    •  duration: The duration of the levitation in ticks.
    •  duration:
      •  max: The maximum value.
      •  min: The minimum value.
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:location[edit]

Triggers every 20 ticks (1 second) and checks where the player is. Available conditions:

  •  conditions:
    •  location: The location of the player.
      • Tags common to all locations
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:nether_travel[edit]

Triggers when the player travels to the Nether and then returns to the Overworld. Available conditions:

  •  conditions:
    •  entered: The location where the player entered the Nether.
      • Tags common to all locations
    •  exited: The location where the player exited the Nether.
      • Tags common to all locations
    •  distance: The overworld distance between where the player entered the Nether and where the player exited the Nether.
      •  absolute:
        •  max: The maximum value.
        •  min: The minimum value.
      •  horizontal:
        •  max: The maximum value.
        •  min: The minimum value.
      •  x:
        •  max: The maximum value.
        •  min: The minimum value.
      •  y:
        •  max: The maximum value.
        •  min: The minimum value.
      •  z:
        •  max: The maximum value.
        •  min: The minimum value.
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:placed_block[edit]

Triggers when the player places a block. Available conditions:

  •  conditions:
    •  block: The block that was placed. Accepts block IDs.
    •  item: The item that was used to place the block before the item was consumed.
      • Tags common to all items
    •  location: The location of the block that was placed.
      • Tags common to all locations
    •  state: The block states of the block.
      •  <state_name>: A single block state, with the key name being the state name and the value being the required value of that state.
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:player_generates_container_loot[edit]

Triggers when the player generates the contents of a container with a loot table set. Available conditions:

  •  conditions:
    •  loot_table: The resource location of the generated loot table.
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:player_hurt_entity[edit]

Triggers after the player hurts a mob or player. Available conditions:

  •  conditions:
    •  damage: The damage that was dealt. Missing corresponding list of predicates for the direct entity.
      • Damage tags
    •  entity: The entity that was damaged. May be a list of predicates that must pass in order for the trigger to activate.
      • Tags common to all entities
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:player_interacted_with_entity[edit]

Triggers when the player interacts with an entity. Available conditions:

  •  conditions:
    •  item: The item which was in the player's hand during interaction.
      • Tags common to all items
    •  entity: The entity which was interacted with. May be a list of predicates that must pass in order for the trigger to activate.
      • Tags common to all entities
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:player_killed_entity[edit]

Triggers after a player is the source of a mob or player being killed. Available conditions:

  •  conditions:
    •  entity: The entity that was killed. May be a list of predicates that must pass in order for the trigger to activate.
      • Tags common to all entities
    •  killing_blow: The type of damage that killed an entity. Missing corresponding list of predicates for the direct entity.
      • Tags common to all damage types
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:recipe_unlocked[edit]

Triggers after the player unlocks a recipe (using a knowledge book for example). Available conditions:

  •  conditions:
    •  recipe: The recipe that was unlocked.
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:shot_crossbow[edit]

Triggers when the player shoots a crossbow. Available conditions:

  •  conditions:
    •  item: The item that was used.
      • Tags common to all items
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:slept_in_bed[edit]

Triggers when the player enters a bed. Available conditions:

  •  conditions:
    •  location: The location of the player.
      • Tags common to all locations
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:slide_down_block[edit]

Triggers when the player slides down a block. Available conditions:

  •  conditions:
    •  block: The block that the player slid on.
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:summoned_entity[edit]

Triggers after an entity has been summoned. Works with iron golems (pumpkin and iron blocks), snow golems (pumpkin and snow blocks), the ender dragon (end crystals) and the wither (wither skulls and soul sand/soul soil). Using dispensers to place the wither skulls or pumpkins will still activate this trigger. Spawn eggs, commands and mob spawners will not work however. Available conditions:

  •  conditions:
    •  entity: The summoned entity. May be a list of predicates that must pass in order for the trigger to activate.
      • Tags common to all entities
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:tame_animal[edit]

Triggers after the player tames an animal. Available conditions:

  •  conditions:
    •  entity: Checks the entity that was tamed. May be a list of predicates that must pass in order for the trigger to activate.
      • Tags common to all entities
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:target_hit[edit]

Triggers when the player shoots a target block. Available conditions:

  •  conditions:
    •  signal_strength: The redstone signal that will come out of the target block.
    •  projectile: The projectile used to hit the target block.
    •  shooter: Entity predicate for the player who shot or threw the projectile. May be a list of loot table conditions that must pass in order for the trigger to activate.
      • Tags common to all entities
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:thrown_item_picked_up_by_entity[edit]

Triggers after the player throws an item and another entity picks it up. Available conditions:

  •  conditions:
    •  item: The thrown item which was picked up.
      • Tags common to all items
    •  entity: The entity which picked up the item. May be a list of predicates that must pass in order for the trigger to activate.
      • Tags common to all entities
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:tick[edit]

Triggers every tick (20 times a second). Available conditions:

  •  conditions:
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:used_ender_eye[edit]

Triggers when the player uses an eye of ender (in a world where strongholds generate). Available conditions:

  •  conditions:
    •  distance: The horizontal distance between the player and the stronghold.
    •  distance:
      •  max: A maximum value.
      •  min: A minimum value.
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:used_totem[edit]

Triggers when the player uses a totem. Available conditions:

  •  conditions:
    •  item: The item, only works with totem items.
      • Tags common to all items
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:villager_trade[edit]

Triggers after the player trades with a villager or a wandering trader. Available conditions:

  •  conditions:
    •  item: The item that was purchased. The "count" tag checks the count from one trade, not multiple.
      • Tags common to all items
    •  villager: The villager the item was purchased from. May be a list of predicates that must pass in order for the trigger to activate.
      • Tags common to all entities
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

minecraft:voluntary_exile[edit]

Triggers when the player causes a raid and checks where the player is. Available conditions:

  •  conditions:
    •  location: The location of the player.
      • Tags common to all locations
    •  player: A list of predicates that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

Removed triggers[edit]

minecraft:arbitrary_player_tick[edit]

Triggers every tick for one player only.

Removed in 1.12-pre1.

minecraft:player_damaged[edit]

Triggers when the player receives damage. Available conditions:

  •  conditions:
    •  blocked: Checks whether the damage was blocked.
    •  is_projectile: Checks if the damage was caused by a projectile.

This trigger had these two conditions only because it was made just for the Deflect Arrow advancement. Removed in 17w14a.

minecraft:safely_harvest_honey[edit]

Triggers when the player harvests honey from a bee nest/beehive with a campfire below it. Available conditions:

  •  conditions:
    •  block: The block that the player harvested the honey from.
      •  block: A block ID.
      •  tag: A block tag.
    •  item: The item that the player used to harvest the honey.
      • Tags common to all items
    •  player: A list of loot table conditions that must pass in order for the trigger to activate. The checks are applied to the player that would get the advancement.

This trigger was made redundant by the item_used_on_block trigger. Removed in 20w20a.