Skip to content

How to add an advancement in a Minecraft mod

An advancement is one data file in data/<modid>/advancement (advancements before 1.21). It has a display (icon, title, description, frame, toast), a parent to hang under, criteria that say what the player must do (each has a trigger such as minecraft:inventory_changed), and requirements that say which criteria are needed (a list of lists: the outer list is AND, the inner list is OR). Names go in the lang file as translation keys. A rewards block can give XP, loot or run a function.

Works on Minecraft 1.20.1 to 26.3 on NeoForge; Minecraft 1.16.5 to 26.3 on Fabric; Minecraft 1.16.5 to 1.20.1 on Forge; Minecraft 1.12.2 on Forge. Each example was compiled against its loader and version before it shipped in Linen.

  1. Write the advancement JSON with a display and a criterion.
  2. Set the parent: minecraft:story/root puts it in the Minecraft tab.
  3. Add the title and description to the lang file (the how-to does this).
  4. Get the item in survival and watch for the toast; /advancement revoke resets it.

The example uses these values. Change them in the code.

Setting In the example What it does
item minecraft:diamond The id of the item that earns it.

The example mod is examplemod in the package com.example.examplemod. Use your own mod id and package.

Fabric and NeoForge 1.20.1 to 1.20.4, Fabric 1.17 to 1.20

Section titled “Fabric and NeoForge 1.20.1 to 1.20.4, Fabric 1.17 to 1.20”

Uses:

  • minecraft:inventory_changed
  • minecraft:story/root
  • AdvancementHolder

src/main/resources/data/examplemod/advancements/got_diamond.json

{
"parent": "minecraft:story/root",
"display": {
"icon": { "item": "minecraft:diamond" },
"title": { "translate": "advancement.examplemod.got_diamond.title" },
"description": { "translate": "advancement.examplemod.got_diamond.description" },
"frame": "task",
"show_toast": true,
"announce_to_chat": true,
"hidden": false
},
"criteria": {
"has_item": {
"trigger": "minecraft:inventory_changed",
"conditions": {
"items": [ { "items": [ "minecraft:diamond" ] } ]
}
}
},
"requirements": [ [ "has_item" ] ]
}

In src/main/resources/assets/examplemod/lang/en_us.json:

{
"advancement.examplemod.got_diamond.title": "Got Diamond",
"advancement.examplemod.got_diamond.description": "Pick up the item."
}

Uses:

  • minecraft:inventory_changed
  • minecraft:story/root
  • AdvancementHolder

src/main/resources/data/examplemod/advancements/got_diamond.json

{
"parent": "minecraft:story/root",
"display": {
"icon": { "id": "minecraft:diamond" },
"title": { "translate": "advancement.examplemod.got_diamond.title" },
"description": { "translate": "advancement.examplemod.got_diamond.description" },
"frame": "task",
"show_toast": true,
"announce_to_chat": true,
"hidden": false
},
"criteria": {
"has_item": {
"trigger": "minecraft:inventory_changed",
"conditions": {
"items": [ { "items": "minecraft:diamond" } ]
}
}
},
"requirements": [ [ "has_item" ] ]
}

In src/main/resources/assets/examplemod/lang/en_us.json:

{
"advancement.examplemod.got_diamond.title": "Got Diamond",
"advancement.examplemod.got_diamond.description": "Pick up the item."
}

Fabric and NeoForge 1.21 to 1.21.1, Fabric and NeoForge 1.21.2 to 26.3

Section titled “Fabric and NeoForge 1.21 to 1.21.1, Fabric and NeoForge 1.21.2 to 26.3”

Uses:

  • minecraft:inventory_changed
  • minecraft:story/root
  • AdvancementHolder

src/main/resources/data/examplemod/advancement/got_diamond.json

{
"parent": "minecraft:story/root",
"display": {
"icon": { "id": "minecraft:diamond" },
"title": { "translate": "advancement.examplemod.got_diamond.title" },
"description": { "translate": "advancement.examplemod.got_diamond.description" },
"frame": "task",
"show_toast": true,
"announce_to_chat": true,
"hidden": false
},
"criteria": {
"has_item": {
"trigger": "minecraft:inventory_changed",
"conditions": {
"items": [ { "items": "minecraft:diamond" } ]
}
}
},
"requirements": [ [ "has_item" ] ]
}

In src/main/resources/assets/examplemod/lang/en_us.json:

{
"advancement.examplemod.got_diamond.title": "Got Diamond",
"advancement.examplemod.got_diamond.description": "Pick up the item."
}

Uses:

  • minecraft:inventory_changed
  • minecraft:story/root
  • AdvancementHolder

src/main/resources/data/examplemod/advancements/got_diamond.json

{
"parent": "minecraft:story/root",
"display": {
"icon": { "item": "minecraft:diamond" },
"title": { "translate": "advancement.examplemod.got_diamond.title" },
"description": { "translate": "advancement.examplemod.got_diamond.description" },
"frame": "task",
"show_toast": true,
"announce_to_chat": true,
"hidden": false
},
"criteria": {
"has_item": {
"trigger": "minecraft:inventory_changed",
"conditions": {
"items": [ { "items": [ "minecraft:diamond" ] } ]
}
}
},
"requirements": [ [ "has_item" ] ]
}

In src/main/resources/assets/examplemod/lang/en_us.json:

{
"advancement.examplemod.got_diamond.title": "Got Diamond",
"advancement.examplemod.got_diamond.description": "Pick up the item."
}

Uses:

  • minecraft:inventory_changed
  • minecraft:story/root
  • AdvancementHolder

src/main/resources/data/examplemod/advancements/got_diamond.json

{
"parent": "minecraft:story/root",
"display": {
"icon": { "item": "minecraft:diamond" },
"title": { "translate": "advancement.examplemod.got_diamond.title" },
"description": { "translate": "advancement.examplemod.got_diamond.description" },
"frame": "task",
"show_toast": true,
"announce_to_chat": true,
"hidden": false
},
"criteria": {
"has_item": {
"trigger": "minecraft:inventory_changed",
"conditions": {
"items": [ { "item": "minecraft:diamond" } ]
}
}
},
"requirements": [ [ "has_item" ] ]
}

In src/main/resources/assets/examplemod/lang/en_us.json:

{
"advancement.examplemod.got_diamond.title": "Got Diamond",
"advancement.examplemod.got_diamond.description": "Pick up the item."
}

Uses:

  • minecraft:inventory_changed
  • minecraft:story/root

src/main/resources/data/examplemod/advancements/got_diamond.json

{
"parent": "minecraft:story/root",
"display": {
"icon": { "item": "minecraft:diamond" },
"title": { "translate": "advancement.examplemod.got_diamond.title" },
"description": { "translate": "advancement.examplemod.got_diamond.description" },
"frame": "task",
"show_toast": true,
"announce_to_chat": true,
"hidden": false
},
"criteria": {
"has_item": {
"trigger": "minecraft:inventory_changed",
"conditions": {
"items": [ { "item": "minecraft:diamond" } ]
}
}
},
"requirements": [ [ "has_item" ] ]
}

In src/main/resources/assets/examplemod/lang/en_us.json:

{
"advancement.examplemod.got_diamond.title": "Got Diamond",
"advancement.examplemod.got_diamond.description": "Pick up the item."
}

Uses:

  • minecraft:inventory_changed
  • minecraft:story/root

In 1.12.2 a mod’s advancements are files in assets/<modid>/advancements, not in a data pack.

src/main/resources/assets/examplemod/advancements/got_diamond.json

{
"parent": "minecraft:story/root",
"display": {
"icon": { "item": "minecraft:diamond" },
"title": { "translate": "advancement.examplemod.got_diamond.title" },
"description": { "translate": "advancement.examplemod.got_diamond.description" },
"frame": "task",
"show_toast": true,
"announce_to_chat": true,
"hidden": false
},
"criteria": {
"has_item": {
"trigger": "minecraft:inventory_changed",
"conditions": {
"items": [ { "item": "minecraft:diamond" } ]
}
}
},
"requirements": [ [ "has_item" ] ]
}

In src/main/resources/assets/examplemod/lang/en_us.json:

{
"advancement.examplemod.got_diamond.title": "Got Diamond",
"advancement.examplemod.got_diamond.description": "Pick up the item."
}

Linen’s How-tos library has this page too, with the example for your own mod’s loader and Minecraft version. Hover a name in your code and Linen points to the how-tos that explain it. Both are free. Download Linen.