AdvancementRewards

Reward your players for completing advancements — with money, items, or both.

NOTE:

• Custom items are work in progress.

Overview:

AdvancementRewards is a customizable Minecraft plugin that rewards players with money, items, or both for completing advancements — vanilla, datapack, or mod/plugin-added alike. Money payouts use Vault (EssentialsX, CMI, and other providers); item-only setups need no dependencies. Configure rewards from config.yml, with in-game commands, or visually in the drag-and-drop web editor (/ar config) — giving you full control over the progression system.

---

📋 Features:

• Money & item rewards: Grant in-game currency, items (with custom names & lore), or both for any advancement.
• Any advancement: Vanilla, datapack, or mod/plugin-added — all supported.
• Web editor: Edit rewards from a drag-and-drop browser UI with /ar config — no YAML required.
• In-game commands: Add, remove, list, and browse advancements without touching files.
• Vault economy: Works with any Vault provider (EssentialsX, CMI, …); pick the provider in config.
• Item-only mode: Runs without Vault if you only hand out items.

---

🎮 How It Works:

1. Players complete advancements.
2. If the advancement is listed in the config, they receive a reward.
3. AdvancementRewards checks if the player has already claimed the reward. If not, they are awarded.
4. If a reward has already been claimed, no additional rewards are given.

---

⚙️ Configuration:

The plugin generates a config.yml that allows you to define which advancements reward players and what they receive (money, items, or both).

Example config.yml:

# Set rewards for specific advancements
advancement-rewards:
  minecraft:story/mine_diamond: 500.0
  minecraft:story/enter_the_nether: 300.0
  minecraft:end/kill_dragon: 1000.0
  minecraft:adventure/hero_of_the_village: 700.0
  minecraft:nether/summon_wither: 1000.0

• advancement-rewards: Define which advancements give rewards and set the amount of in-game currency for each.

Adding New Advancements:

To add a new advancement, simply edit the config.yml:

minecraft:adventure/adventuring_time: 300.0

Item & combined rewards (rich form):

A reward can also be a section with optional money and an items list. Items support an amount, a name, and lore (both accept & colour codes):

advancement-rewards:
  # money only (simple form)
  minecraft:story/mine_diamond: 500.0

  # money + items
  minecraft:end/kill_dragon:
    money: 1000.0
    items:
      - material: DRAGON_HEAD
        amount: 1
        name: "&5Dragon Slayer's Trophy"
        lore:
          - "&7Proof you bested the Ender Dragon"
      - material: DIAMOND
        amount: 5

The economy provider and update notifications are also configurable:

economy:
  provider: auto      # auto | Essentials | CMI | <custom Vault provider>
notify-update: true

Storage (config.yml only):

Claim data (which advancements each player already redeemed) is stored in SQLite by default; switch to MariaDB for shared/multi-server setups. Configured here only — never via the web editor. Legacy playerdata/*.yml files are imported automatically on first start.

storage:
  type: sqlite        # sqlite | mariadb
  mariadb:            # used only when type: mariadb
    host: localhost
    port: 3306
    database: advancementrewards
    username: root
    password: ""

---

🚀 Installation:

1. Download the AdvancementRewards.jar and place it in your server's plugins folder.
2. Restart your server to generate the default config.yml.
3. Modify the config.yml to customize advancement rewards.
4. Restart your server or reload the plugin with /ar reload.

---

🛠 Commands:

All under /ar:

• /ar config: Open the drag-and-drop web editor (gives you a personal link).
• /ar list [page]: List configured advancement rewards.
• /ar advancements [filter] [page]: Browse every advancement on the server (vanilla/datapack/mod).
• /ar add <advancement> money <amount>: Add a money reward.
• /ar add <advancement> item <material> [amount]: Add an item reward.
• /ar remove <advancement>: Remove an advancement's rewards.
• /ar reload: Reload the configuration and messages.

---

🖱 Web Editor:

Run /ar config in-game to get a personal link to a drag-and-drop editor at ar.venle.website. Arrange money and item rewards visually, then hit Push to server — changes are re-validated server-side and applied live. The session ends when you close the tab.

• The link is personal and short-lived — don't share it.
• Your server is identified by an auto-generated plugins/AdvancementRewards/identity.yml — a private key. Keep it; delete it only to reset to a new identity.
• A backup is written to config.yml.bak before every web apply, so a push is always reversible.

---

🛡 Permissions:

Permission	Description	Default
ar.reload	Reload the configuration and messages	op
ar.edit	View, query, and edit rewards (commands + web editor)	op
ar.admin	Receive update notifications on join	op

---

💾 Data Storage:

Claim history (which advancements each player has already redeemed) is kept in a database so rewards can never be claimed twice. SQLite is used by default — zero setup — and MariaDB is supported for shared or multi-server networks (set in config.yml). Upgrading from an older version? Your existing playerdata/*.yml files are imported automatically on first start.

---

💡 Use Cases:

• Survival Servers: Reward players for key milestones like mining diamonds or entering the Nether.
• RPG or Progression Servers: Integrate rewards for advancement milestones to enhance gameplay progression.
• Event Servers: Track player progress during events and reward them based on specific achievements.

---

🔧 Compatibility:

• Platforms: Paper, Purpur, Spigot, Bukkit, and Folia — one jar, no extra setup. Folia's regionised scheduler is used automatically where present.
• Minecraft Version: 1.18 – 26.1.2 (runs on whatever Java your server uses — 17 and up). On older versions the /ar advancements browser falls back to plain advancement names where the server doesn't expose icons/titles — everything still works.
• Dependencies: Vault + an economy plugin (EssentialsX/CMI) for money rewards. Item-only setups need no dependencies. The database drivers are bundled in — nothing to install.

---

📥 Download Now:

Start enhancing your server's advancement system with AdvancementRewards today.

---