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.

Features

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

Shard Economy

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.

Economy Operations

• Add shards
• Remove shards
• Set balances
• Transfer shards between players
• Apply configurable transfer tax
• Enforce a configurable maximum balance
• Prevent negative balances
• Protect against numeric overflow

Player Transfers

Players can transfer shards directly to other players.

Transfers are handled atomically so the debit and credit operations are treated as one transaction.

Transfer Features

• Player-to-player shard payments
• Configurable transfer tax
• Atomic balance updates
• Negative-balance protection
• Overflow protection
• Transaction history
• Idempotent transaction keys

Transaction Ledger

DonutShards stores economy activity in a persistent SQL-backed transaction system.

The transaction foundation includes:

• Persistent player balances
• Transaction history storage
• Idempotent transaction keys
• Atomic economy operations
• SQL-backed durability

Idempotent transaction keys help prevent the same logical transaction from being applied multiple times when an operation is retried.

Storage

DonutShards supports multiple SQL storage options.

SQLite

SQLite is the default option and works without additional database infrastructure.

It is suitable for:

• Standalone servers
• Simple installations
• Development environments
• Servers that do not require an external database

MariaDB & MySQL

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.

Recurring Rewards

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.

Cosmic Confection Exchange

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.

Performance & Safety

DonutShards is designed around asynchronous database operations and modern Minecraft scheduling requirements.

The plugin includes:

• Asynchronous economy operations
• Asynchronous public Java API
• HikariCP connection pooling
• Paper scheduler abstraction
• Genuine Folia scheduler abstraction
• Region-safe player-facing Bukkit interactions
• Atomic transfer handling
• Balance overflow protection
• Negative-balance protection
• Idempotent transaction processing

Commands

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
• /dshards

Java API

DonutShards 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.

Configuration

Current configuration supports:

• Maximum shard balance
• Player transfer tax
• SQLite storage
• MariaDB/MySQL storage
• Database connection settings
• Recurring reward behavior
• MiniMessage-formatted messages

MariaDB/MySQL installations should configure a dedicated, least-privilege database account in database.yml.

Installation

1. Download the DonutShards JAR.
2. Place it inside the server's plugins/ directory.
3. Start the server and wait for the database-ready message.
4. Stop the server before editing generated configuration files.
5. Configure the desired database and economy settings.
6. Restart the server.
7. Verify that the selected database connection initializes successfully.

SQLite works without additional setup.

Compatibility

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.

Release Status

DonutShards 1.0.0 is an early functional foundation.

The following advanced functionality is planned but not complete in this build:

• Advanced AFK-zone management
• Persistent shop delivery reconciliation
• Transaction rollback commands
• Leaderboards
• Vault hooks
• PlaceholderAPI hooks
• Migration tools
• Administration editors

Why Choose DonutShards?

1. Dedicated Shard Economy — Adds an independent virtual currency for custom progression and rewards.
2. Durable Transactions — SQL-backed balances, transaction history, and idempotent keys provide a reliable foundation.
3. Safe Transfers — Atomic transfers, balance protection, overflow protection, and configurable taxation protect currency operations.
4. Flexible Storage — Use SQLite out of the box or connect to MariaDB/MySQL.
5. Modern Performance — Economy and database operations are asynchronous and designed around Paper/Folia scheduling.
6. Developer Friendly — An asynchronous public Java API provides a foundation for integrations.
7. Expandable Foundation — The 1.0.0 release establishes core systems for future shops, rewards, leaderboards, hooks, and administration features.

Support & Bug Reports

When reporting a problem, include:

• DonutShards version
• Paper or Folia version
• Minecraft version
• Java version
• Sanitized relevant console logs
• Exact reproduction steps

Never publish database passwords, private network addresses, or the contents of a production database.

Community & Support

• Discord: https://discord.gg/TJc3CxR4jK
• GitHub: https://github.com/MeherBenSalem
• Website: https://nightbeam.dev
• Store: https://nightbeam.dev/store
• CurseForge: https://www.curseforge.com/members/nightbeamstudio/projects
• Modrinth: https://modrinth.com/organization/nightbeam

If you encounter a bug or have a feature request, please join the Discord community or report it through the appropriate project page.

License

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.