DonutShards is a configurable shard economy and reward foundation for modern Paper and Folia servers. It introduces an original donut-and-cosmic virtual currency system backed by a durable SQL ledger, asynchronous economy operations, safe player transfers, recurring rewards, and a Cosmic Confection Exchange GUI.
| Feature | Description |
|---|---|
| Virtual Shard Economy | Player shard balances stored as 64-bit integers |
| Economy Operations | Add, remove, set, and transfer shard balances |
| Atomic Transfers | Taxed player transfers processed atomically |
| Balance Protection | Negative-balance and overflow protection |
| Transaction Ledger | Transaction history with idempotent transaction keys |
| SQLite Storage | Local SQLite database supported by default |
| MariaDB & MySQL | Optional MariaDB and compatible MySQL storage |
| HikariCP Pooling | Efficient SQL connection pooling |
| Recurring Rewards | Basic recurring shard reward functionality |
| Cosmic Confection Exchange | Original inventory GUI for shard-based interactions |
| MiniMessage Support | MiniMessage-formatted player-facing messages |
| Async Java API | Asynchronous public API for plugin integrations |
| Paper & Folia Support | Region-safe scheduler abstraction for both platforms |
| Configurable Economy | Configurable maximum balance and transfer tax |
DonutShards provides a dedicated virtual currency that can serve as the foundation for rewards, shops, progression systems, and custom server mechanics.
Balances are stored as 64-bit integers in a durable SQL-backed ledger.
Players can transfer shards directly to other players.
Transfers are handled atomically so the debit and credit operations are treated as one transaction.
DonutShards stores economy activity in a persistent SQL-backed transaction system.
The transaction foundation includes:
Idempotent transaction keys help prevent the same logical transaction from being applied multiple times when an operation is retried.
DonutShards supports multiple SQL storage options.
SQLite is the default option and works without additional database infrastructure.
It is suitable for:
MariaDB and compatible MySQL storage can be used when an external database is preferred.
Database connections use HikariCP connection pooling.
Production installations should use a dedicated, least-privilege database account.
DonutShards includes basic recurring shard rewards, providing a foundation for periodically rewarding players as part of a server economy or progression system.
Advanced AFK-zone management is planned but is not complete in version 1.0.0.
DonutShards includes the original Cosmic Confection Exchange inventory GUI.
The interface provides a foundation for shard-based shop and reward interactions using Minecraft's familiar inventory system.
Persistent shop delivery reconciliation and advanced administration editors are planned but are not complete in version 1.0.0.
DonutShards is designed around asynchronous database operations and modern Minecraft scheduling requirements.
The plugin includes:
| Command | Description |
|---|---|
/shards balance [player] |
View a shard balance |
/shards pay <player> <amount> |
Transfer shards to another player |
/shardshop |
Open the shard shop |
/afk leave |
Leave the current AFK interaction |
/shardmanager give <player> <amount> |
Give shards to a player |
/shardmanager take <player> <amount> |
Remove shards from a player |
/shardmanager set <player> <amount> |
Set a player's shard balance |
Aliases for /shards:
/donutshards/dshardsDonutShards exposes an asynchronous public Java API for integrations with other plugins.
The API is designed around asynchronous economy operations so integrations do not need to perform SQL work directly on server or region threads.
Current configuration supports:
MariaDB/MySQL installations should configure a dedicated, least-privilege database account in database.yml.
plugins/ directory.SQLite works without additional setup.
| Requirement | Version |
|---|---|
| Server Software | Paper & Folia |
| Minecraft | 1.20.1 through 26.1.2 |
| Plugin Bytecode | Java 21 |
| Minecraft 26.1.2 Runtime | Java 25 |
Minecraft 26.2 is not currently claimed because a stable dual-platform Paper/Folia release was not available when this build was produced.
DonutShards 1.0.0 is an early functional foundation.
The following advanced functionality is planned but not complete in this build:
When reporting a problem, include:
Never publish database passwords, private network addresses, or the contents of a production database.
If you encounter a bug or have a feature request, please join the Discord community or report it through the appropriate project page.
DonutShards is licensed under the Apache License 2.0.
You are free to use, modify, and redistribute DonutShards in accordance with the terms of the Apache License 2.0.
