milestones

Every category is one file in milestones/. The file name (lower-cased, without .yml) is the category id used by /milestones <category>, the admin commands and the placeholders. After adding or editing one, run /milestonesadmin reload.

Two ship by default: blocks.yml (an API category counting block breaks) and playtime.yml (a PLACEHOLDER category reading %statistic_hours_played%). They are only created when the milestones/ folder does not exist yet. A walkthrough is in Creating Categories; this page is the full reference.

Category fields

Enabled: true
Display-Name: "Blocks"
Order: 1

Menu: { ... }
Progress: { ... }
Milestone-Icons: { ... }
Milestones: { ... }

Key	Default	Description
Enabled	true	false hides the category from the menu, /milestones <category> and tab completion, and stops its progress being counted. Stored data is kept.
Display-Name	the id	Shown in the menu and messages as {category}.
Order	file position	Sort key, lowest first. The enabled category with the lowest Order is what /milestones opens. Ties are sorted by id.
Menu	required	The selector icon and its slot.
Progress	required	How progress is measured.
Milestone-Icons	required	The three state icons.
Milestones	required	The numbered track.

Menu

The category’s selector icon in /milestones, plus where it sits. The section is both the slot and the item.

Menu:
  Slot: 2
  Material: COBBLESTONE
  Name: "&b&lBlocks Milestone"
  Lore:
    - "&7Complete milestones and receive rewards"
    - "&7to help you progress through the game."
    - ""
    - "&3 - &bComplete: &a{complete}&8/&c{total}"
    - ""
    - "&e➥ Click to view!"

Slot is a raw menu slot, counting from 0. Give each category its own slot, inside the menu Size and outside Milestone-Slots. The category being viewed glows automatically. Everything else in the section uses the standard item fields.

Clicking another category’s icon switches the menu to it; clicking the one being viewed flashes Already-Selected.

Tokens (each icon shows its own category’s values):

Token	Value
{category}	The category’s Display-Name.
{complete}	Milestones claimed.
{total}	Milestones in the category.
{reached}	Thresholds met, claimed or not.
{progress}	The player’s progress, comma-grouped.
{percent}	Claimed out of total, two decimals, no % sign.
{progress-bar}	Claimed out of total as a bar.

The selector bar measures claims, not raw progress

{percent} and {progress-bar} on a selector icon are claimed out of total - how much of the track is done. On a milestone icon they are progress out of that milestone’s Required. Same tokens, different subject.

Progress

Progress:
  Type: API
  API: BLOCK_BREAK

Progress:
  Type: PLACEHOLDER
  Placeholder: "%statistic_hours_played%"

Key	Description
Type	API or PLACEHOLDER, not case-sensitive. Defaults to API.
API	Required for API. One source name, see below.
Placeholder	Required for PLACEHOLDER. Any numeric PlaceholderAPI placeholder.

API sources

Name	+1 for every
BLOCK_BREAK	Block broken by a player (cancelled breaks ignored).
BLOCK_PLACE	Block placed by a player (cancelled places ignored).
MOB_KILL	Non-player entity killed by a player.
PINNAPRISON	PinnaPrison block mine. Needs PinnaPrison.
EDDUNGEONS	EdDungeons sword swing. Needs EdDungeons.
RIVALHARVESTERHOE	RivalHarvesterHoes block break. Needs RivalHarvesterHoes.

Not case-sensitive, and - counts as _. Each matching event adds exactly +1; there are no amount, chance, world or block filters. Several categories may share a source and each gets its own +1. Events from a player whose data is not loaded are ignored.

PLACEHOLDER parsing

The placeholder is resolved for the player every time progress is read (the menu, the unlock check, claims and the plugin’s own placeholders). Everything from the first . on is dropped, then every non-digit is ignored:

"1,234"     →  1234
"1234.9"    →  1234
"58 hours"  →  58
""          →  0

Without PlaceholderAPI installed, the value is always 0.

Milestone-Icons

Required, with all three states: Locked, Unclaimed and Claimed.

Milestone-Icons:
  Locked:
    Material: RED_STAINED_GLASS_PANE
    Primary: "&c"
    Secondary: "&4"
    Name: "{primary}&lMilestone {secondary}&l{milestone}"
    Lore:
      - "&7You are still working towards"
      - "&7this milestone."
      - ""
      - "{primary}Progress:"
      - "{secondary} - &7Required: &a{progress}&8/&c{required}"
      - "{secondary} - &7{progress-bar} &7({percent}%)"
      - ""
      - "{primary}Rewards:"
      - "{reward-lore}"
      - ""
      - "{primary}&lLOCKED"

State	Shown when
Locked	Progress is below Required.
Unclaimed	Threshold met, not claimed yet.
Claimed	Already claimed.

Icon fields

Each state is a standard item with two extra keys:

Field	Default	Description
Primary	&f	Fills {primary} across the whole icon, including the reward lore.
Secondary	&7	Fills {secondary} the same way.

A lore line holding {reward-lore} is replaced with the milestone’s own Lore list. The stack size is always the milestone number, capped at 64, so Amount has no effect here.

Icon tokens

Token	Value
{category}	The category’s Display-Name.
{milestone}	The milestone number as a Roman numeral (XII). Above 3999 it stays a plain number.
{number}	The milestone number (12).
{progress}	The player’s progress, comma-grouped.
{required}	That milestone’s Required, comma-grouped.
{progress-bar}	Progress towards that milestone, using the Progress-Bar style.
{percent}	Progress out of Required, two decimals (42.50), no % sign.
{primary} / {secondary}	That state’s colors.
{reward-lore}	Expands into the milestone’s Lore.

Because {primary} and {secondary} also resolve inside the expanded reward lore, a reward line written as "{secondary} - &f3x Pearl Key" recolors itself per state.

Milestones

Entries keyed by the milestone number. Keys must be whole numbers, 1 or higher.

Milestones:
  "1":
    Enabled: true
    Required: 1000
    Lore:
      - "{secondary} - &f3x Pearl Key"
    Commands:
      - "crates key give {player} pearl 3"
  "2":
    Enabled: true
    Required: 2500
    Lore:
      - "{secondary} - &f3x Orbs Booster &7(1.25x, 10m)"
    Commands:
      - "booster give {player} orbs 1.25 10"

Key	Default	Description
Enabled	true	false removes the milestone from the track, the menu, the counts and the placeholders. Numbers around it don’t shift, so gaps are fine.
Required	0	Cumulative total progress needed. Negative values count as 0.
Lore	[]	The reward description, shown wherever the state icon has a {reward-lore} line.
Commands	required	Console commands run on claim, with {player} replaced by the player’s name. An empty list fails the load.

Milestones are sorted by number, not by their order in the file. Required should go up with the number. The plugin does not enforce it, but a track that goes backwards reads as already complete.

Claiming

1. Progress is checked against Required. Below it: MILESTONE-LOCKED, the DENY sound and the Locked flash.
2. The claim is recorded. Already claimed: ALREADY-CLAIMED, the DENY sound and the Already-Claimed flash.
3. The claim is saved to the database immediately.
4. Every line in Commands runs from console.
5. MILESTONE-CLAIMED is sent, the CLAIM sound plays and the menu redraws.

Nothing is claimed automatically. MILESTONE-UNLOCKED only tells the player something is waiting.

Validation

Checked on startup and on every reload. These stop the load with an error in the console instead of being skipped:

• A missing Menu, Progress, Milestones or Milestone-Icons section
• A missing Locked, Unclaimed or Claimed icon
• A non-numeric milestone key, or one below 1
• A milestone with an empty Commands list
• Type: API with no API source, or an unknown source name
• Type: PLACEHOLDER with no Placeholder
• An unknown Type
• An invalid Material anywhere