DonutShards

DonutShards - это плагин для серверов Minecraft на PaperMC, который вводит собственную валюту - Shards (осколки). Если стандартная экономика на "алмазах" или "монетах" приелась, или хочется чего-то более гибкого и тематического - DonutShards отличный вариант. Он решает сразу несколько проблем: даёт игрокам дополнительную мотивацию для PvP и просто времяпровождения на сервере, а админам - мощный инструмент для создания своей экономики без костылей.

Что это и зачем нужно

В ванильном Minecraft нет никакой встроенной экономики. Всё держится на плагинах. DonutShards - это не очередной "ещё один экономический плагин", а полноценная система со своей валютой, магазином, AFK-зоной и топом. Он подходит для серверов, где хотят:

• Поощрять PvP - за каждое убийство игрок получает Shards
• Дать возможность зарабатывать пассивно - AFK-зоны с защитой
• Создать магазин с красивым GUI и категориями
• Иметь топ игроков по балансу
• Всё это без танцев с бубном и кучи зависимостей

Основные фишки

• Своя валюта - Shards, со своими командами баланса, топа и выдачи
• Награды за убийства - настраиваемое количество Shards за PvP-килл, с кулдауном и множителем
• AFK-система - игроки получают Shards, просто находясь в специальной AFK-зоне. Можно настроить защиту зоны (без WorldGuard)
• Магазин - многостраничный GUI-магазин с категориями. Покупай предметы за Shards
• Мультиязычность - 5 языков: английский, вьетнамский, китайский, испанский, французский
• Топ - /shard top показывает лучших игроков по балансу
• API для разработчиков - можно интегрировать свои плагины с DonutShards
• Два типа хранения - YAML или SQLite (с WAL-режимом для асинхронной записи)

Требования

• PaperMC 1.21.x
• Java 21+
• PlaceholderAPI 2.11+ (опционально, для плейсхолдеров)

Установка

1. Скачай DonutShard-1.0.0.jar и кинь в папку /plugins
2. Запусти сервер - конфиги сгенерируются автоматически
3. Отредактируй plugins/DonutShard/config.yml под себя
4. Выполни /shard reload в игре, чтобы применить изменения без перезапуска

Структура файлов

plugins/DonutShard/
├── config.yml          # Главный конфиг (награды за убийства, хранилище, топ)
├── afk.yml             # AFK-зоны, правила защиты, скорость заработка
├── shop.yml            # Категории магазина и расположение в GUI
├── shops/
│   ├── Spawners.yml    # Предметы спавнеров
│   ├── Ores.yml        # Руды
│   └── Farm.yml        # Фермерские предметы
├── languages/
│   ├── en.yml
│   ├── vi.yml
│   ├── zh.yml
│   ├── es.yml
│   └── fr.yml
└── data/               # Файлы YAML-хранилища (если выбран YAML)
    ├── balances.yml
    ├── afk_sessions.yml
    ├── afk_warps.yml
    └── daily_earnings.yml

Настройка

config.yml - основные параметры

language: en           # Активный язык (en/vi/zh/es/fr)

kill-reward:
  enabled: true
  shards-per-kill: 10
  kill-cooldown: 30    # секунд до повторной награды за того же игрока
  ignore-afk-victims: false
  bonus-multiplier:
    enabled: false
    threshold: 1000    # если у жертвы >= этого количества Shards
    multiplier: 1.5

storage:
  type: SQLITE         # YAML или SQLITE
  auto-save-interval: 5  # минут

leaderboard:
  size: 10

afk.yml - AFK-система

enabled: true
shards-per-minute: 1
daily-limit: 100       # 0 = безлимит
teleport-cooldown: 5   # секунд между использованиями /afk
auto-detect-afk: true  # автоопределение игроков в AFK-мире

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

Добавление категории в магазин

1. Создай plugins/DonutShard/shops/MyCategory.yml:

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. Добавь категорию в shop.yml в раздел categories:

categories:
  MyCategory:
    icon: DIAMOND
    name: "<aqua>My Category"
    slot: 4
    lore:
      - "<gray>Buy diamonds and spawners"

3. Выполни /shard reload. Перезапуск не нужен!

Команды

Команда	Описание	Право
/shard balance [player]	Посмотреть баланс Shards	donutshard.balance
/shard give <player> <amount>	Выдать Shards	donutshard.give
/shard take <player> <amount>	Забрать Shards	donutshard.take
/shard set <player> <amount>	Установить Shards	donutshard.set
/shard top [page]	Посмотреть топ	donutshard.top
/shard reload	Перезагрузить конфиг	donutshard.reload
/shard set-afk-warp <name>	Установить AFK-варп	donutshard.admin
/shard remove-afk-warp <name>	Удалить AFK-варп	donutshard.admin
/shard list-afk-warp	Список AFK-варпов	donutshard.admin
/shard language <code>	Сменить язык	donutshard.language
/afk [warpname]	Войти в AFK-зону	donutshard.afk
/afk-setting	Настройки AFK-зоны	donutshard.afk.admin
/shardshop	Открыть магазин Shards	donutshard.shop

Алиасы: /shard -> /donutshard, /ds

Права доступа

Право	Описание	По умолчанию
donutshard.balance	Проверить свой баланс	true
donutshard.balance.others	Проверить баланс других	op
donutshard.give	Выдать Shards другим	op
donutshard.take	Забрать Shards у других	op
donutshard.set	Установить баланс Shards	op
donutshard.top	Посмотреть топ	true
donutshard.reload	Перезагрузить плагин	op
donutshard.admin	Все админские команды	op
donutshard.afk	Использовать /afk	true
donutshard.afk.admin	Управлять AFK-настройками	op
donutshard.shop	Открыть магазин Shards	true
donutshard.kill.bypass	Смерть этого игрока не даёт Shards	false
donutshard.zone.bypass	Игнорировать защиту зоны	op
donutshard.language	Сменить язык	true

PlaceholderAPI плейсхолдеры

Если у тебя стоит PlaceholderAPI, можно использовать эти плейсхолдеры в любом совместимом плагине:

Плейсхолдер	Возвращает
%donutshard_balance%	Баланс Shards игрока
%donutshard_rank%	Место игрока в топе
%donutshard_top_1% до %donutshard_top_10%	Имя игрока на N месте топа
%donutshard_top_balance_1% до %donutshard_top_balance_10%	Баланс игрока на N месте топа

API для разработчиков

Если ты разрабатываешь свой плагин и хочешь интегрировать его с DonutShards, вот пример:

// Проверка доступности API
if (DonutShardAPI.isAvailable()) {

    // Получить баланс
    long balance = DonutShardAPI.getBalance(player);

    // Выдать Shards с причиной
    DonutShardAPI.give(player, 100, "Награда за квест");

    // Забрать Shards (вернёт false, если недостаточно)
    boolean success = DonutShardAPI.take(player, 50);

    // Слушать события Shards
    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) {
            // ...
        }
    });
}

Сборка из исходников

git clone https://github.com/duong2012g/DonutShard.git
cd DonutShard
mvn clean package
# Результат: target/DonutShard-1.0.0.jar

Требования: Java 21, Maven 3.8+

Лицензия

MIT - можно свободно использовать, модифицировать и распространять с указанием авторства.