# 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

# ============================================
#   Tab Configuration
# ============================================
tab:
  namespace: "survival"           # Unique ID, lowercase + underscores

root:
  icon: "NETHER_STAR"             # Material for the root icon
  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 & color codes.
`description`	String	Tooltip description. Supports & color codes.
`icon`	String	Valid Minecraft material name (e.g. DIAMOND, NETHER_STAR).
`trigger`	String	One of the 40+ trigger types.

#

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	FALL, LAVA, PVP, MOB (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 icon (ItemsAdder/Oraxen)
`customModelData`	int	Custom model data for items (ItemsAdder/Oraxen)

#

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 & color codes)

# Available Background Textures

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

# 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