Total XP Rewards

A powerful and lightweight Paper plugin that tracks each player's lifetime XP and executes custom rewards when XP milestones are reached. Fully configurable, translation-ready, and built for modern Paper servers (1.21+).

---

✨ Features

• Global Total XP Tracking 📈
  • Tracks XP from killing mobs, mining, and vanilla commands (/xp, /experience).
  • Never resets, even after death.
  • Async Caching: High-performance data handling prevents server lag.
• BossBar Progress System 📊
  • Displays a customizable BossBar showing progress to the next rank.
  • Dynamic Mode: Auto-hides the bar when not gaining XP.
  • Rich Text support: Supports MiniMessage (Gradients, RGB) AND Legacy Color Codes (&a) simultaneously!
• Reward System 🎁
  • Execute multiple commands when reaching a threshold.
  • Send custom broadcast messages.
  • Supports Minecraft Target Selectors in commands (e.g., @a, @p).
• Full Customization 🛠️
  • PlaceholderAPI support.
  • Complete language control via lang.yml (including "Max Rank" text).
  • SQLite storage with automatic schema migration (external apps can read current_rank).

---

📥 Installation

1. Download the latest release from the Releases page.
2. Drop the .jar file into your server's plugins folder.
3. Start the server to generate config files.
4. Adjust config.yml and lang.yml to your liking.
5. Restart or run:

   /txp reload
   

---

⚙️ Configuration

config.yml (example)

bossbar:
  enabled: true
  # Hybrid Support: Mix Legacy (&) and MiniMessage (<gradient>)!
  title: "&bCurrent Rank: &e%current_rank% &7| <gradient:blue:aqua>Next: %next_rank%</gradient> &7(&a%xp%&7/&c%required_xp%&7)"
  color: BLUE
  style: SOLID
  dynamic-mode: true # Bar appears on XP gain and hides after timeout
  timeout: 10

rewards:
  "1000":
    name: "<gradient:#2486B5:#3A816A>Novice</gradient>"
    commands:
      - "give %player% diamond 1"
      - "eco give %player% 250"
    broadcast: "&a%player% reached %threshold% XP (Novice)!"

  "50000":
    name: "Master"
    commands:
      - "give %player% netherite_ingot 1"
    broadcast: "&6%player% is now a Master!"

---

🧩 Placeholders

Available for use in Chat, Broadcasts, and BossBar:

Placeholder	Description
%player%	Player's name
%xp%	Player's total lifetime XP
%current_rank%	Name of the current rank (e.g. "Novice")
%next_rank%	Name of the next rank (e.g. "Master")
%required_xp%	XP required for the next rank
%threshold%	The specific threshold reached (Rewards only)

---

🔧 Commands

Command	Description	Permission
/txp get <player>	View a player’s total XP	totalxp.view
/txp show	Show your BossBar	totalxp.use
/txp hide	Hide your BossBar	totalxp.use
/txp set <player> <amount>	Set a player’s XP	totalxp.admin
/txp reset <player>	Reset player XP & history	totalxp.admin
/txp reload	Reload config & language	totalxp.admin

---

💾 Storage

XP and reward history are stored via SQLite, located in: plugins/TotalXPRewards/database.db

External Access: The database now includes a current_rank and username column, making it easy to integrate with web leaderboards (e.g. Node.js apps).

---

🧩 Plugin Support

• LuckPerms (for rank rewards)
• Vault (for economy)
• PlaceholderAPI (for extra placeholders)

The plugin does not depend on them but integrates automatically if installed.

---

🛡️ Disclaimer

This plugin was developed with the assistance of Google DeepMind's AI. All code and design decisions were reviewed and finalized manually.

---

📄 License

This project is licensed under the MIT License. You are free to use, modify, and contribute.

---

🤝 Contributing

Pull requests and feature suggestions are welcome! Feel free to open an issue if you encounter bugs or have ideas.

---

⭐ Support the Project

If you enjoy this plugin, consider leaving a star on GitHub — it helps a lot!