Описание
# 🍩 DonutShard
> A feature-rich **custom currency plugin** for PaperMC servers — earn Shards by killing, AFK farming, and spending them in a configurable shop.
[](CHANGELOG.md)
[](https://papermc.io)
[](https://adoptium.net)
[](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: "⭐ My Category"
items:
- id: DIAMOND
name: "💎 Diamond"
price: 100
slot: 10
quantity: 1
lore:
- "Shiny and expensive"
- id: SPAWNER
name: "🔥 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: "My Category"
slot: 4
lore:
- "Buy diamonds and spawners"
```
3. Run `/shard reload`. No restart needed!
---
## 💬 Commands
| Command | Description | Permission |
|---|---|---|
| `/shard balance [player]` | View Shard balance | `donutshard.balance` |
| `/shard give ` | Give Shards | `donutshard.give` |
| `/shard take ` | Take Shards | `donutshard.take` |
| `/shard set ` | Set Shards | `donutshard.set` |
| `/shard top [page]` | View leaderboard | `donutshard.top` |
| `/shard reload` | Reload config | `donutshard.reload` |
| `/shard set-afk-warp ` | Set AFK warp to a world | `donutshard.admin` |
| `/shard remove-afk-warp ` | Remove AFK warp | `donutshard.admin` |
| `/shard list-afk-warp` | List all AFK warps | `donutshard.admin` |
| `/shard language ` | Change language | `donutshard.language` |
| `/afk [warpname]` | 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` |
| `donutshard.balance.others` | Check other's balance | `op` |
| `donutshard.give` | Give Shards to others | `op` |
| `donutshard.take` | Take Shards from others | `op` |
| `donutshard.set` | Set Shard balance | `op` |
| `donutshard.top` | View leaderboard | `true` |
| `donutshard.reload` | Reload plugin | `op` |
| `donutshard.admin` | All admin commands | `op` |
| `donutshard.afk` | Use /afk command | `true` |
| `donutshard.afk.admin` | Manage AFK settings | `op` |
| `donutshard.shop` | Open Shard shop | `true` |
| `donutshard.kill.bypass` | This player's deaths give no Shards | `false` |
| `donutshard.zone.bypass` | Bypass zone protection | `op` |
| `donutshard.language` | Change language | `true` |
---
## 📊 PlaceholderAPI
Register these placeholders in any compatible plugin:
| Placeholder | Returns |
|---|---|
| `%donutshard_balance%` | Player's Shard balance |
| `%donutshard_rank%` | Player's leaderboard rank |
| `%donutshard_top_1%` to `%donutshard_top_10%` | Top player name at rank N |
| `%donutshard_top_balance_1%` | Top player balance at rank N |
---
## 🔌 Developer API
Add DonutShard as a dependency in your plugin:
```java
// Check availability
if (DonutShardAPI.isAvailable()) {
// Get balance
long balance = DonutShardAPI.getBalance(player);
// Give Shards with a reason
DonutShardAPI.give(player, 100, "Quest reward");
// Take Shards (returns false if insufficient)
boolean success = DonutShardAPI.take(player, 50);
// Listen to Shard events
DonutShardAPI.registerHook(new ShardEventHook() {
@Override
public void onShardEarned(UUID uuid, long amount, String reason) {
// ...
}
@Override
public void onShardSpent(UUID uuid, long amount, String reason, long newBalance) {
// ...
}
});
}
```
---
## 🔨 Building from Source
```bash
git clone https://github.com/duong2012g/DonutShard.git
cd DonutShard
mvn clean package
# Output: target/DonutShard-1.0.0.jar
```
**Requirements:** Java 21, Maven 3.8+
---
## 📝 License
MIT — free to use, modify, and redistribute with attribution.
---
*Made with ❤️ by duong2012g*