Get Started: Create Your First Custom Advancement Tree

Create your first custom advancement JSON file and see it appear in the Minecraft advancements screen in under five minutes with Custom Advancements.

This guide walks you through creating your first custom advancement tree from scratch. By the end you will have a root tab and a child advancement visible in the Minecraft advancements screen, built entirely from JSON files — no coding required. The whole process takes under five minutes once the mod is installed.

1. Install the mod

   Follow the Installation guide to add Custom Advancements to your Forge 1.16.5 instance.

2. Launch the game once

   Start Minecraft at least once with the mod installed. Custom Advancements creates the customadvancements/ folder inside your game directory on the first run and fills it with example files. You can close the game again after reaching the main menu.

3. Open the advancements folder

   Your own advancement files belong in the inner customadvancements folder:

   <game directory>/
   └── customadvancements/
       └── customadvancements/    ← your advancement JSON files go here
   

   The outer folder is the mod’s data directory; the inner folder is the customadvancements namespace. Every .json file in the inner folder — including files in any subfolder — is loaded as one of your own advancements. Files placed directly in the outer folder are not loaded as custom advancements.

4. Create the root advancement

   A root advancement defines a new tab in the advancements screen. Create the file root.json inside the customadvancements/customadvancements/ folder with the following content:

   root.json

   {
     "display": {
       "icon": {
         "item": "minecraft:diamond_block"
       },
       "title": {
         "translate": "customadvancements.advancements.example_root.title"
       },
       "description": {
         "translate": "customadvancements.advancements.example_root.description"
       },
       "background": "customadvancements:textures/logo.png",
       "show_toast": false,
       "announce_to_chat": false,
       "hidden": false
     },
     "criteria": {
       "requirement": {
         "trigger": "minecraft:tick"
       }
     }
   }
   

   Key fields to note:

   • display.icon — the item shown on the tab header. Any valid item ID works.
   • display.title / display.description — use translate keys that you define in a language file, or replace them with plain strings such as "My Tab" for hardcoded text.
   • display.background — required on every root advancement. A file without it is rejected by the loader. logo.png ships with the mod in customadvancements/data/textures/; see Background Types for the other options.
   • criteria — root advancements are granted automatically via the minecraft:tick trigger; the player earns it on the first game tick.
5. Create a child advancement

   Child advancements appear as nodes branching off the root inside its tab. Create the file example.json in the same folder:

   example.json

   {
     "display": {
       "icon": {
         "item": "minecraft:dirt"
       },
       "title": {
         "translate": "customadvancements.advancements.example_example.title"
       },
       "description": {
         "translate": "customadvancements.advancements.example_example.description"
       },
       "frame": "task",
       "show_toast": true,
       "announce_to_chat": true
     },
     "parent": "customadvancements:root",
     "criteria": {
       "requirement": {
         "trigger": "minecraft:inventory_changed",
         "conditions": {
           "items": [
             {
               "item": "minecraft:dirt"
             }
           ]
         }
       }
     }
   }
   

   Key fields to note:

   • parent — the resource location of the advancement this node connects to. Here customadvancements:root refers to the root.json file from the previous step. The format is <namespace>:<path>, where the path mirrors the file path relative to the namespace folder, without the .json extension.
   • frame — controls the border shape around the icon. Valid values are task, goal, and challenge.
   • criteria — this advancement is granted when dirt appears in the player’s inventory. Replace the trigger and conditions to match whatever goal you have in mind.

   Every child advancement must define parent, criteria, and display. A file missing any of the three is rejected with a does not match the required '.json' format! line in the log. See Structure for the full field reference.

6. Reload and open the advancements screen

   Load a world and run the reload command in chat:

   /ca reload
   

   The mod re-reads every JSON file in customadvancements/, reloads your textures and language files, and rebuilds the advancement data for everyone online — no restart needed. Then press L (the default keybind) to open the advancements screen. A new tab with your root advancement’s title appears alongside the vanilla tabs, with the example node branching off it. Pick up a piece of dirt to complete the child advancement and watch the toast appear.

   Want to customize or override existing vanilla advancements? Run /ca generate advancement all in-game. The mod exports every currently loaded advancement as an editable JSON file into customadvancements/<namespace>/… and reloads automatically. See the Commands overview for the full list of available commands.

   If the tab does not appear, check latest.log for lines from Custom Advancements — the most common causes are a missing background on the root advancement and malformed JSON syntax in one of your files. See Common Issues for more.

   [INSERT IMAGE: The new root advancement tab visible in the advancements screen, next to the vanilla tabs]