# :icon-code: Advancement Format

* * *

####   

**YAML File Structure**

Each `.yml` file in the `Advancements/` folder defines one tab. The file has three sections: `tab`, `root`, and
`advancements`.

### Full Structure

```yaml
# ============================================
#   Tab Configuration
# ============================================
tab:
  namespace: "survival"           # Unique ID, lowercase + underscores
  tabOrder: 10                    # Display order in tab selector (default 999 for custom tabs)

root:
  icon: "NETHER_STAR"             # Material for the root icon
  iconCustomModelData: -1         # Custom model data for root icon (ItemsAdder/Oraxen), -1 = none
  title: "&6Survival"             # Tab display name (& for colors)
  description: "Survival challenges"
  background: "textures/block/stone.png"

# ============================================
#   Advancements
# ============================================
advancements:
  first_join:
    title: "&aWelcome!"
    description: "Join the server for the first time"
    icon: NETHER_STAR
    trigger: JOIN
    hasReward: true
    rewards:
      - give %player% diamond 1
    display:
      x: 1.0
      y: 4.0
      frame: TASK
      showToast: true
      announceChat: false
      showActionBar: true
    sound:
      enabled: true
      type: UI.TOAST.CHALLENGE_COMPLETE
      volume: 1.0
      pitch: 1.0
    money:
      enabled: true
      amount: 100.0
    connection:
      target: first_join

  stone_breaker:
    title: "Stone Breaker"
    description: "Break 50 stone blocks"
    icon: STONE_PICKAXE
    trigger: BREAK_BLOCK
    block: STONE
    amount: 50
    hasReward: true
    rewards:
      - give %player% iron_pickaxe 1
    display:
      x: 2.0
      y: 4.0
      frame: TASK
      showToast: true
      announceChat: false
      showActionBar: true
    connection:
      target: first_join
```

* * *

####   

**Required Fields**

| Field         | Type   | Description                                                  |
|---------------|--------|--------------------------------------------------------------|
| `title`       | String | Display name. Supports all color formats (see below).        |
| `description` | String | Tooltip description. Supports all color formats (see below). |
| `icon`        | String | Valid Minecraft material name (e.g. DIAMOND, NETHER_STAR).   |
| `trigger`     | String | One of the 40+ trigger types.                                |

### Title & Description Color Formats

Titles and descriptions support all three color code systems. They work in-game (L menu, GUIs, broadcasts, commands) AND
in the web editor live preview.

| Format            | Example                                                                            | Notes                                                                |
|-------------------|------------------------------------------------------------------------------------|----------------------------------------------------------------------|
| Legacy `&` codes  | `&6Gold &lBold`                                                                    | Standard Minecraft color codes                                       |
| Hex               | `&#FFAA00Gold!`                                                                    | Per-character RGB hex colors                                         |
| Named tags        | `<red>Text`, `<light_purple>Text`                                                  | MiniMessage named colors                                             |
| Format tags       | `<bold>`, `<italic>`, `<underlined>`, `<strikethrough>`, `<obfuscated>`, `<reset>` | MiniMessage formatting                                               |
| `<color:#RRGGBB>` | `<color:#FFAA00>Text`                                                              | MiniMessage hex color tag                                            |
| `<color:name>`    | `<color:gold>Text`                                                                 | MiniMessage named color tag                                          |
| Gradient          | `<gradient:gold:yellow>Text</gradient>`                                            | Per-character color interpolation. Works with or without closing tag |
| Rainbow           | `<rainbow>Text</rainbow>`                                                          | Per-character HSL hue cycling. Works with or without closing tag     |

> **Note:** `</gradient>` and `</rainbow>` reset the color back to default after the closing tag. Formatted tags inside
> gradients/rainbows are preserved (e.g. `<gradient:red:blue>Hello <bold>World</bold></gradient>` works as expected).

* * *

####   

**Display Options**

| Field                   | Type    | Default | Description                                                 |
|-------------------------|---------|---------|-------------------------------------------------------------|
| `display.x`             | float   | 1.0     | X coordinate in the advancement tree                        |
| `display.y`             | float   | 1.0     | Y coordinate in the advancement tree                        |
| `display.frame`         | String  | TASK    | Frame type: TASK (square), GOAL (rounded), CHALLENGE (star) |
| `display.showToast`     | boolean | true    | Show popup notification on unlock                           |
| `display.announceChat`  | boolean | false   | Announce in chat on unlock                                  |
| `display.showActionBar` | boolean | true    | Show progress in action bar                                 |

* * *

####   

**Sound**

| Field           | Type    | Default                     | Description              |
|-----------------|---------|-----------------------------|--------------------------|
| `sound.enabled` | boolean | true                        | Play sound on completion |
| `sound.type`    | String  | UI_TOAST_CHALLENGE_COMPLETE | Sound name               |
| `sound.volume`  | float   | 1.0                         | Sound volume             |
| `sound.pitch`   | float   | 1.0                         | Sound pitch              |

* * *

####   

**Trigger Configuration Fields**

| Field                 | Type          | Applies to                                                                                                 | Description                              |
|-----------------------|---------------|------------------------------------------------------------------------------------------------------------|------------------------------------------|
| `amount`              | int           | All counter-based triggers                                                                                 | Required amount (default: 1)             |
| `block`               | String / List | BREAK_BLOCK, PLACE_BLOCK, HARVEST, SNIFF, CHOP_TREE                                                        | Block material(s)                        |
| `itemType`            | String / List | OBTAIN_ITEM, CRAFT_ITEM, SMELT_ITEM, FISH, CONSUME, EAT, DROP_ITEM, ARMOR_EQUIP, FILL_BUCKET, EMPTY_BUCKET | Item material(s)                         |
| `item`                | String / List | Same as itemType                                                                                           | Legacy alias for itemType                |
| `entity`              | String / List | KILL, BREED, TAME, SHEAR, MILK                                                                             | Entity type(s)                           |
| `inputItem`           | String / List | ANVIL_USE, GRINDSTONE_USE                                                                                  | Input material(s)                        |
| `outputItem`          | String / List | ANVIL_USE, GRINDSTONE_USE, SMELT_ITEM                                                                      | Output material(s)                       |
| `dimension`           | String        | ENTER_DIMENSION                                                                                            | NORMAL, NETHER, or THE_END               |
| `travelMode`          | String        | TRAVEL_DISTANCE                                                                                            | TOTAL, WALKING, or BOAT                  |
| `distanceRequired`    | double        | TRAVEL_DISTANCE                                                                                            | Distance in blocks                       |
| `enchantmentType`     | String        | ENCHANT                                                                                                    | Enchantment name (e.g. SHARPNESS)        |
| `minimumLevel`        | int           | ENCHANT                                                                                                    | Minimum enchantment level                |
| `villagerProfession`  | String        | TRADE                                                                                                      | Profession name (e.g. FARMER, LIBRARIAN) |
| `potionEffectType`    | String        | POTION_EFFECT                                                                                              | Effect name (e.g. SPEED, STRENGTH)       |
| `minimumAmplifier`    | int           | POTION_EFFECT                                                                                              | Minimum amplifier (0 = level I)          |
| `deathCause`          | String        | DEATH                                                                                                      | any DamageCause or entity type (e.g. FALL, LAVA, PVP, MOB, DROWNING, EXPLOSION, ZOMBIE - null = any) |
| `sheepColor`          | String        | SHEAR                                                                                                      | Wool color (e.g. WHITE, PINK)            |
| `bedColor`            | String        | SLEEP                                                                                                      | Bed color (e.g. RED, BLUE)               |
| `placeholder`         | String        | PLACEHOLDER                                                                                                | PlaceholderAPI placeholder to check      |
| `placeholderOperator` | String        | PLACEHOLDER                                                                                                | Operator: ==, !=, >, >=, <, <=, contains |
| `placeholderValue`    | String        | PLACEHOLDER                                                                                                | Value to compare against                 |

* * *

####   

**Custom Model Data**

| Field                 | Type | Description                                                                                                                                     |
|-----------------------|------|-------------------------------------------------------------------------------------------------------------------------------------------------|
| `iconCustomModelData` | int  | Custom model data for the advancement **icon** in the tree view (ItemsAdder/Oraxen). Requires plugin v2.1+.                                     |
| `customModelData`     | int  | Custom model data for **item type** matching in triggers (e.g., `OBTAIN_ITEM`, `CRAFT_ITEM`). Filters items by their `CustomModelData` NBT tag. |

For tab-level root icon customization, use `root.iconCustomModelData` in the tab section.

* * *

####   

**Connections & Dependencies**

| Field               | Type          | Description                                            |
|---------------------|---------------|--------------------------------------------------------|
| `connection.target` | String        | Visual parent advancement ID                           |
| `requires`          | String / List | Prerequisite advancement ID(s)                         |
| `hidden`            | boolean       | Hide until prerequisites are met (requires `requires`) |

* * *

####   

**Conditions**

| Field                   | Type   | Description              |
|-------------------------|--------|--------------------------|
| `conditions.worlds`     | List   | Allowed world names      |
| `conditions.permission` | String | Required permission node |

* * *

####   

**Reward Fields**

| Field                        | Type    | Description                          |
|------------------------------|---------|--------------------------------------|
| `hasReward`                  | boolean | Enable command rewards               |
| `rewards`                    | List    | Command strings to execute           |
| `money.enabled`              | boolean | Enable money reward                  |
| `money.amount`               | double  | Money amount                         |
| `rewards-items`              | Map     | Item rewards (indexed by string key) |
| `rewards-permissions`        | List    | Permission nodes to grant            |
| `rewards-permission-enabled` | boolean | Enable permission rewards            |
| `rewards-playerpoints`       | int     | PlayerPoints to give                 |
| `rewards-pools`              | Map     | Random reward pools                  |
| `broadcast.enabled`          | boolean | Enable broadcast on completion       |
| `broadcast.message`          | String  | Broadcast message                    |
| `webhook-enabled`            | boolean | Send Discord webhook                 |

* * *

####   

**Tab System**

### Overview

Each `.yml` file in `Advancements/` creates one tab in the Minecraft advancement menu (L key). Tabs are managed
independently but share a global advancement ID pool.

### Tab Rules

- `tab.namespace` must be unique across ALL files in `Advancements/`
- Advancement IDs (e.g. `first_join`) must be unique GLOBALLY across all tabs
- The tab display name is the `root.title` value (supports all color formats — see Color Formats section above)
- `tab.tabOrder` controls the display order in the tab selector GUI (lower = first). Vanilla tabs use
  `vanilla-tab-order` in `config.yml` instead.
- `root.iconCustomModelData` sets a custom model data for the tab root icon (for ItemsAdder/Oraxen custom textures)

### Available Background Textures

Any valid Minecraft vanilla texture path works. Examples:

```
textures/block/stone.png
textures/block/cobblestone.png
textures/block/dirt.png
textures/block/oak_planks.png
textures/block/gold_block.png
textures/block/diamond_block.png
textures/block/emerald_block.png
textures/block/netherrack.png
textures/block/end_stone.png
textures/block/prismarine.png
textures/block/red_sand.png
textures/block/sandstone.png
```

**Custom resource pack textures** are also fully supported, just use the path from your pack (e.g.
`textures/block/my_custom_block.png`).

### Creating a Tab

**Via web editor:** Run `/padv editor`, click "+" next to the tab dropdown, enter a namespace.

**Manually:** Create a new `.yml` file in the `Advancements/` folder with the required `tab`, `root`, and `advancements`
sections. Run `/padv reload` to apply.

**Via in-game GUI:** Not directly supported. Use the web editor or manual YAML editing.

### Deleting a Tab

- Delete the `.yml` file from `Advancements/`
- Run `/padv reload`
- Ensure no advancements reference IDs from the deleted tab