DonutShards

# 🍩 DonutShard > A feature-rich **custom currency plugin** for PaperMC servers — earn Shards by killing, AFK farming, and spending them in a configurable shop. (https://img.shields.io/badge/version-1.0.0-gold)](CHANGELOG.md) (https://img.shields.io/badge/PaperMC-1.21.x-green)](https://papermc.io) (https://img.shields.io/badge/Java-21-blue)](https://adoptium.net) (https://img.shields.io/badge/license-MIT-lightgrey)](LICENSE) --- ## ✨ Features | Feature | Description | |---|---| | 💰 **Shard Currency** | Custom economy currency with leaderboard, balance commands | | ⚔️ **Kill Rewards** | Earn Shards for PvP kills with cooldown and bonus multiplier | | 🌙 **AFK System** | Earn Shards passively while AFK in designated warp zones | | 🛡️ **Zone Protection** | WorldGuard-like protection for AFK zones (no WorldGuard required) | | 🏪 **Shard Shop** | Multi-category GUI shop — buy items with Shards | | 🌐 **Multi-language** | 5 built-in languages: `vi` `en` `zh` `es` `fr` | | 📊 **Leaderboard** | `/shard top` with PlaceholderAPI support | | 🔌 **Developer API** | Hook into Shard events from other plugins | | 💾 **Dual Storage** | YAML or SQLite, with WAL-mode async writes | --- ## 📦 Requirements | Requirement | Version | |---|---| | **PaperMC** | 1.21.x | | **Java** | 21+ | | **PlaceholderAPI** | 2.11+ *(optional)* | --- ## ⚙️ Installation 1. Download `DonutShard-1.0.0.jar` and drop it into your `/plugins` folder. 2. Start the server — config files generate automatically. 3. Edit `plugins/DonutShard/config.yml` to your liking. 4. Run `/shard reload` in-game to apply changes without restarting. --- ## 🗂️ File Structure ``` plugins/DonutShard/ ├── config.yml # Main config (kill reward, storage, leaderboard) ├── afk.yml # AFK zones, protection rules, earn rates ├── shop.yml # Shop categories & GUI layout ├── shops/ │ ├── Spawners.yml # Spawner items │ ├── Ores.yml # Ore blocks │ └── Farm.yml # Farming items ├── languages/ │ ├── en.yml │ ├── vi.yml │ ├── zh.yml │ ├── es.yml │ └── fr.yml └── data/ # YAML storage files (if YAML mode) ├── balances.yml ├── afk_sessions.yml ├── afk_warps.yml └── daily_earnings.yml ``` --- ## 🔧 Configuration ### `config.yml` — Quick Reference ```yaml language: en # Active language (en/vi/zh/es/fr) kill-reward: enabled: true shards-per-kill: 10 kill-cooldown: 30 # seconds before same kill gives reward again ignore-afk-victims: false bonus-multiplier: enabled: false threshold: 1000 # if victim has >= this many Shards multiplier: 1.5 storage: type: SQLITE # YAML or SQLITE auto-save-interval: 5 # minutes leaderboard: size: 10 ``` ### `afk.yml` — AFK System ```yaml enabled: true shards-per-minute: 1 daily-limit: 100 # 0 = unlimited teleport-cooldown: 5 # seconds between /afk uses auto-detect-afk: true # auto-detect players already in AFK world protection: default: no-damage: true no-hunger: true no-pvp: true no-mob-spawn: true no-item-drop: true restore-health-on-enter: true clear-effects-on-enter: true ``` ### Adding a Shop Category 1. Create `plugins/DonutShard/shops/MyCategory.yml`: ```yaml gui-title: "<gold>⭐ My Category" items: - id: DIAMOND name: "<aqua>💎 Diamond" price: 100 slot: 10 quantity: 1 lore: - "<gray>Shiny and expensive" - id: SPAWNER name: "<red>🔥 Blaze Spawner" spawnertype: BLAZE price: 5000 slot: 11 quantity: 1 ``` 2. Add the category to `shop.yml` under `categories`: ```yaml categories: MyCategory: icon: DIAMOND name: "<aqua>My Category" slot: 4 lore: - "<gray>Buy diamonds and spawners" ``` 3. Run `/shard reload`. No restart needed! --- ## 💬 Commands | Command | Description | Permission | |---|---|---| | `/shard balance ` | View Shard balance | `donutshard.balance` | | `/shard give <player> <amount>` | Give Shards | `donutshard.give` | | `/shard take <player> <amount>` | Take Shards | `donutshard.take` | | `/shard set <player> <amount>` | Set Shards | `donutshard.set` | | `/shard top ` | View leaderboard | `donutshard.top` | | `/shard reload` | Reload config | `donutshard.reload` | | `/shard set-afk-warp <name>` | Set AFK warp to a world | `donutshard.admin` | | `/shard remove-afk-warp <name>` | Remove AFK warp | `donutshard.admin` | | `/shard list-afk-warp` | List all AFK warps | `donutshard.admin` | | `/shard language <code>` | Change language | `donutshard.language` | | `/afk ` | Enter an AFK zone | `donutshard.afk` | | `/afk-setting` | Manage AFK zone settings | `donutshard.afk.admin` | | `/shardshop` | Open the Shard Shop | `donutshard.shop` | **Aliases:** `/shard` → `/donutshard`, `/ds` --- ## 🛡️ Permissions | Permission | Description | Default | |---|---|---| | `donutshard.balance` | Check own balance | `true`