Advancements

Challenge and achievement system with 9 tabbed categories, 36 trigger types, tree-positioned GUIs, toasts, sounds, points, console rewards, and per-player progress stored in the database. Everything is defined in advancement.yml.

How Players Use It

1. Open the GUI: /advancements (aliases: /adv, /achievements, /sdadv). Permission: shyamduels.advancements.use.
2. Pick a category tab (Duels, Ranked, Bed Fight, Bridge, FFA, Kits, Party, Challenges, Secrets) and click through the tree.
3. Play normally. Progress counters fill automatically (for example Win 10 duels shows 4/10).
4. On completion the player gets a toast popup, a chat message, and a sound. Big milestones also broadcast server-wide.

How To Make An Advancement

Work in plugins/ShyamDuels/advancement.yml. The file is versioned (config-version: 2) and missing keys are merged from the built-in defaults on load, so editing never wipes your entries.

1. Decide the category. Use one of the 9 shipped categories or add your own block under categories: (see the category table below). Note its key, for example DUELS.
2. Add an entry under advancements: with a unique id, for example my_first_win:.
3. Wire it into the tree with category: and parent:. Use parent: null for a root node, or the id of the previous advancement to chain it. The GUI position is computed automatically unless you set coords.x / coords.y.
4. Describe it under display: (title, description lines, icon material, frame). See the display table below.
5. Pick a difficulty (EASY to SECRET). It sets the label color and the default point value when rewards.points is omitted.
6. Pick a trigger under trigger: with type: and amount: (how many times the event must fire). Full trigger list is in the trigger table below.
7. Narrow it with conditions (optional) under trigger.conditions:, for example ranked: true or kit: "nethpot". Full condition list is in the condition table below.
8. Set rewards under rewards: (points, console commands, extra message lines). Override announcements per advancement under announcements: if needed.
9. Reload and test: run /advancements reload (or /shyamduels reload-advancements), then /advancements list to confirm your id appears. Grant it to yourself with /advancements grant <player> <id> to preview the toast and rewards. Turn on settings.debug: true and reload if an entry does not show up; unknown trigger types log a warning and never complete.

Minimal Example (Copy And Edit)

yamladvancements:
  my_bridge_debut:
    category: BRIDGE
    parent: "bridge_root"
    display:
      title: "<green>My Bridge Debut"
      description:
        - "<gray>Score your first Bridge goal."
      icon:
        material: "END_PORTAL_FRAME"
      frame: TASK
    difficulty: EASY
    trigger:
      type: BRIDGE_GOAL
      amount: 1
    rewards:
      points: 25
      commands:
        - "give %player% diamond 3"

Placeholders usable in messages, commands, and lore: %player%, %uuid%, %advancement%, %advancement_id%, %category%, %difficulty%, %progress%, %required%, %percentage%, %rewards%.

settings: (7 Keys)

defaults: (Global Fallbacks)

categories: (9 Shipped Tabs)

Shipped tabs and roots: DUELS (duels_root), RANKED (ranked_root), BEDFIGHT (bedfight_root), BRIDGE (bridge_root), FFA (ffa_root), KITS (kits_root), PARTY (party_root), CHALLENGES (challenges_root), SECRETS (secrets_root). Category keys are uppercased on load. An advancement whose category does not exist falls back to the first loaded category.

advancements: (Per-Entry Keys)

Difficulty Tiers And Default Points

When rewards.points is omitted, the tier value is used.

Trigger Types (All 36)

amount counts matching events. Pair a counter trigger with a condition to scope it (for example DUEL_WIN plus ranked: true).

Conditions (Every Key)

Conditions live under trigger.conditions: (or conditions:). Flat keys combine with AND. Use all:, any:, and not: lists for logic, and typed rules (type: plus field: plus value:) for full control. Any other key falls back to generic payload matching: booleans must equal, numbers must be greater than or equal, text must equal ignoring case.

Logic Groups And Typed Rules

yamltrigger:
  type: BOXING_COMBO
  amount: 20
  conditions:
    any:                 # OR: macepvp kit OR mace kit OR mace payload
      - kit: "macepvp"
      - kit: "mace"
      - mace: true

yamltrigger:
  type: DUEL_KILL
  amount: 1
  conditions:
    all:                 # AND group
      - bow_kill: true
      - ranked: true
    not:                 # NOT group
      - kit: "bridge"

Typed rules use type: plus field: plus value:: KIT_EQUALS (kit name equals), NUMERIC_GTE (payload number greater than or equal), NUMERIC_LTE (payload number less than or equal), BOOLEAN_IS (payload flag equals), STRING_EQUALS (payload text equals ignoring case). Example: {type: NUMERIC_GTE, field: elo, value: 2000}.

rewards: (Every Key)

Admin Commands And Permissions

Behind The Scenes

• Storage: progress lives in the player_advancements table (progression, completed flag, timestamp) with a 60-second completed-count cache. Join loads are async; gameplay triggers run on the main thread; saves go through a per-player ordered write queue.
• Events: completion fires AdvancementGrantEvent (player plus advancement, informational, not cancellable). See Events Reference.
• High-frequency guard: rapid triggers such as boxing combos are checked on a throttled path (every 5th event) to protect performance.
• Vanilla: the embedded advancement library renders tabs, nodes, progress bars, and toasts from its own SQLite file (data/advancements.db). disable-vanilla-advancements and suppress-vanilla-in-arena control vanilla behavior.
• Placeholders: %shyamduels_advancements_completed% and related advancements_* variables expose totals. See PlaceholderAPI.