Get Started: Create Your First Custom Advancement Tree

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.

Install the mod

Follow the Installation guide to add Custom Advancements and its dependencies to your Fabric or NeoForge instance for Minecraft 1.21.1.

Launch the game once

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

Create the advancement namespace folder

Inside the customadvancements/ folder that was just created, make a subfolder named customadvancements:

<game directory>/
└── customadvancements/
    └── customadvancements/    ← create this folder

The name of this subfolder must exactly match a loaded mod ID. The mod validates every subfolder name against the list of loaded mods and skips any folder whose name does not correspond to a known mod. Using customadvancements (the mod’s own ID) is always safe and is the recommended namespace when you are creating original advancements rather than overriding another mod’s trees.

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": {
      "id": "minecraft:diamond_block"
    },
    "title": {
      "translate": "customadvancements.advancements.example_root.title"
    },
    "description": {
      "translate": "customadvancements.advancements.example_root.description"
    },
    "background": {
      "type": "IMAGE",
      "location": "customadvancements:textures/screenshot.png",
      "object_fit": "COVER"
    },
    "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 can define in a lang file, or replace them with {"text": "Your Title"} for a hardcoded string.
display.background — sets a custom background image for this tab. Remove this field entirely to use the default stone texture, or see Background Types for all options.
criteria — root advancements are granted automatically via the minecraft:tick trigger; the player earns it on the first game tick.

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": {
      "id": "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": [
          {
            "id": "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 you created in 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 of the advancement icon in the screen. Valid values are task, goal, and challenge.
criteria — this advancement is granted when the player picks up dirt. Replace the trigger and conditions to match whatever goal you have in mind.

See the Advancement JSON Reference for the full list of fields, triggers, and conditions.

Load the game and open advancements

Launch Minecraft (or, if the game is already running on a server, run the vanilla /reload command to pick up changes to the customadvancements/ folder without restarting). Once in a world, press L to open the advancements screen. A new tab labelled with your root advancement’s title should appear alongside the vanilla tabs.

Want to customize or override existing vanilla advancements? Run /ca/generate/advancement/all in-game. The mod will export every currently loaded advancement as an editable JSON file into customadvancements/ and then automatically reload the server, registering them as custom advancements under your control. See the Commands overview for the full list of available commands.

If the tab does not appear, check the game log for lines beginning with [Custom Advancements] — the most common causes are a misspelled folder name (not matching a loaded mod ID) or 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]

Getting Started

Creating Advancements

Configuration

Commands

Localization & Textures

Troubleshooting

Get Started: Create Your First Custom Advancement Tree