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.
- Write the advancement JSON with a display and a criterion.
- Set the parent: minecraft:story/root puts it in the Minecraft tab.
- Add the title and description to the lang file (the how-to does this).
- Get the item in survival and watch for the toast; /advancement revoke resets it.
What you can change
Section titled “What you can change”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. |
For each loader and version
Section titled “For each loader and version”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_changedminecraft:story/rootAdvancementHolder
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."}Fabric and NeoForge 1.20.5 to 1.20.6
Section titled “Fabric and NeoForge 1.20.5 to 1.20.6”Uses:
minecraft:inventory_changedminecraft:story/rootAdvancementHolder
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_changedminecraft:story/rootAdvancementHolder
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."}Forge 1.17.1 to 1.20.1
Section titled “Forge 1.17.1 to 1.20.1”Uses:
minecraft:inventory_changedminecraft:story/rootAdvancementHolder
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."}Fabric 1.16.5
Section titled “Fabric 1.16.5”Uses:
minecraft:inventory_changedminecraft:story/rootAdvancementHolder
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."}Forge 1.16.5
Section titled “Forge 1.16.5”Uses:
minecraft:inventory_changedminecraft: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."}Forge 1.12.2
Section titled “Forge 1.12.2”Uses:
minecraft:inventory_changedminecraft: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."}Sources
Section titled “Sources”- https://docs.neoforged.net/docs/1.21.1/resources/server/advancements
- https://docs.neoforged.net/docs/1.21.1/resources/server/
- https://docs.fabricmc.net/develop/
Related how-tos
Section titled “Related how-tos”In Linen
Section titled “In Linen”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.