Configuration Reference

Every advancement entry lives under the top-level advancements key in any ItemsAdder content file. IAA picks up files that contain this key automatically.

info:
  namespace: my_pack

advancements:
  <advancement_id>:
    # ... options below

Top-level options

Key	Type	Default	Description
`enabled`	boolean	`true`	Set to `false` to skip this advancement without removing it from the file.
`parent`	string	(none)	Parent advancement ID. Omit to make this a root (tab) advancement. See Parent.
`display`	section	(required)	Visual settings. See Display.
`criteria`	section	(none)	Conditions that must be met to complete the advancement. Each criterion has one trigger, trigger-specific conditions, and an optional `conditions.player` predicate. See Triggers and Player predicates.
`rewards`	section	(none)	Experience, loot tables, and recipe unlocks. See Rewards.
`on_complete`	section	(none)	Actions run when the advancement is fully completed. See Completion actions.

Parent

parent: root              # same namespace as this file, resolves to my_pack:root
parent: otherns:someroot  # explicit namespace

If parent contains no colon, the file's namespace is prepended. If parent is omitted entirely, this advancement becomes a root and creates a new tab in the advancements screen.

Display

display:
  title: "<gold>First Ruby Sword"
  description: "<gray>Obtain your first custom sword."
  icon: my_pack:ruby_sword
  frame: task
  background: "minecraft:gui/advancements/backgrounds/adventure"
  show_toast: true
  announce_to_chat: true
  hidden: false

Key	Type	Default	Description
`title`	string	(required)	Advancement title. Supports MiniMessage.
`description`	string	`""`	Tooltip description. Supports MiniMessage.
`icon`	`namespace:id`	`minecraft:barrier`	Item shown as the icon. Accepts ItemsAdder item IDs, MMOItems IDs, or vanilla material IDs. Tags are not supported because the icon must resolve to one concrete item. See IDs.
`frame`	string	`task`	Shape of the icon border: `task`, `goal`, or `challenge`.
`background`	string	(none)	Root advancements only. Texture path for the tab background (e.g. `minecraft:gui/advancements/backgrounds/adventure`).
`show_toast`	boolean	`true`	Show a toast notification when completed.
`announce_to_chat`	boolean	`true`	Broadcast completion to all players in chat.
`hidden`	boolean	`false`	Hide this advancement until it is completed.

background is what makes an advancement create a new tab. It is only used on root advancements (no parent).

Each criterion has a trigger and an optional conditions section. Trigger-specific options live directly under conditions. You can also add a player predicate to any runtime trigger to require an extra player state check before the criterion is awarded.

criteria:
  sneaky_sleep:
    trigger: slept_in_bed
    conditions:
      player:
        flags:
          is_sneaking: true

  high_fall:
    trigger: fall_from_height
    conditions:
      distance:
        y:
          min: 30

Key	Type	Default	Description
`trigger`	string	`impossible`	Trigger type for this criterion. See the full trigger reference.
`conditions`	section	(none)	Trigger-specific options, plus optional `player` predicates.
`conditions.player`	section or list	(any player)	Extra player predicate checked when the criterion is about to be awarded. Ignored by the `impossible` trigger. See Player predicates.

Child advancements need at least one valid criterion. Root advancements can omit criteria; IAA creates an internal root criterion and grants it automatically so the advancement tab appears.

Rewards

rewards:
  experience: 50
  loot:
    - minecraft:chests/simple_dungeon
  recipes:
    - my_pack:ruby_sword_recipe
    - minecraft:golden_apple

Key	Type	Default	Description
`experience`	integer	`0`	Experience points awarded on completion.
`loot`	list of strings	`[]`	Loot table keys to roll on completion.
`recipes`	list of strings	`[]`	Recipe keys to unlock. Accepts `namespace:id` or a bare `id` (uses the file namespace).

Full example

info:
  namespace: my_pack

advancements:

  root:
    display:
      title: "My Server"
      description: "Custom achievements for My Server."
      icon: minecraft:nether_star
      background: "minecraft:gui/advancements/backgrounds/adventure"
      show_toast: false
      announce_to_chat: false
      frame: task

  first_ruby_sword:
    parent: root
    display:
      title: "First Ruby Sword"
      description: "Obtain your first custom sword."
      icon: my_pack:ruby_sword
      frame: task
      show_toast: true
      announce_to_chat: true
    criteria:
      obtain:
        trigger: obtain_item
        conditions:
          items:
            - my_pack:ruby_sword
          amount: 1
    on_complete:
      sound:
        name: minecraft:entity.player.levelup
      title:
        title: "<gold>Achievement!"
        subtitle: "<gray>First Ruby Sword obtained."
      commands:
        reward:
          command: "give {player} gold_ingot 4"
          as_console: true

  master_crafter:
    parent: my_pack:root
    display:
      title: "Master Crafter"
      description: "Craft the sword, the shield, and the potion."
      icon: minecraft:crafting_table
      frame: goal
    criteria:
      craft_sword:
        trigger: craft_recipe
        conditions:
          recipe: my_pack:ruby_sword_recipe
      craft_shield:
        trigger: craft_recipe
        conditions:
          recipe: my_pack:ruby_shield_recipe
      craft_potion:
        trigger: craft_recipe
        conditions:
          recipe: my_pack:ruby_potion_recipe
    rewards:
      experience: 100
      loot:
        - minecraft:chests/simple_dungeon

Multi-criteria advancements (like master_crafter above) require all criteria to be completed. Each criterion is tracked independently; progress is saved by vanilla and survives reloads.

Top-level options

Parent

Display

Criteria

Rewards

Full example

On this page