> ## Documentation Index
> Fetch the complete documentation index at: https://customadvancements-wiki.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Steps>
  <Step title="Install the mod">
    Follow the [Installation guide](/installation) to add Custom Advancements to your Forge 1.16.5 instance.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Open the advancements folder">
    Your own advancement files belong in the inner `customadvancements` folder:

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

    <Note>
      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.
    </Note>
  </Step>

  <Step title="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:

    ```json root.json theme={null}
    {
      "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](/advancements/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.
  </Step>

  <Step title="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:

    ```json example.json theme={null}
    {
      "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](/advancements/structure) for the full field reference.
  </Step>

  <Step title="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.

    <Tip>
      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](/commands/overview) for the full list of available commands.
    </Tip>

    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](/troubleshooting/common-issues) for more.

    <Frame>
      \[INSERT IMAGE: The new root advancement tab visible in the advancements screen, next to the vanilla tabs]
    </Frame>
  </Step>
</Steps>