SMP Shards - AFK & Shop v1.1.1

What is SMP Shards?

SMP Shards is a standalone progression-currency plugin designed for survival, Lifesteal, Box, PvP, economy, and competitive SMP servers.

Players can earn shards by remaining inside configured generation regions, defeating other players, receiving administrative rewards, or collecting payments from other players. They can then spend those shards through a configurable inventory shop containing normal Minecraft resources, equipment, special items, spawners, crate keys, and custom SMP weapons.

The plugin includes its own account system, SQLite and MySQL persistence, shop engine, leaderboard interface, AFK teleport flow, PlaceholderAPI expansion, MiniMessage presentation, configurable sounds, public API, and cancellable gain/loss events.

Vault is not required. The shard economy is independent, its gameplay modules can be enabled or disabled, and its currency names and balance model can be configured without replacing the server's normal money economy.

Built for Modern SMP Progression

• Create a second progression currency — run shards beside an existing Vault economy without replacing normal money.
• Reward controlled activity — grant shards inside selected WorldGuard or SMP Regions zones.
• Reward competitive PvP — give configurable shard amounts for legitimate player kills.
• Reduce kill farming — prevent repeated consecutive rewards from the same victim.
• Scale rewards through permissions — ranks can receive the single highest configured generation or kill bonus.
• Give players spending goals — use the bundled shop catalog or define your own products and prices.
• Connect ArkFlame products — configure command delivery for SMP Spawners, SMP Crates, and SMP Weapons.
• Encourage AFK-area usage — provide a movement-cancelled teleport countdown to the configured AFK destination.
• Create visible competition — display cached shard rankings through a paginated player-head leaderboard.
• Operate safely on Folia — player, global, and asynchronous work is routed through ownership-aware schedulers.

Core Features

• Independent shard economy — no mandatory Vault dependency.
• 64-bit balances — shard accounts use Java long values.
• Non-negative balance protection — accounts cannot intentionally persist negative balances.
• Overflow-safe addition — additions use exact arithmetic instead of silently wrapping.
• Atomic subtraction — concurrent balance deductions cannot overdraw the same account.
• Custom currency naming — configure singular and plural currency names.
• Compact number formatting — configurable decimals and suffixes such as K, M, B, T, and Q.
• Region-based passive generation — players earn shards while remaining inside selected regions.
• WorldGuard support — use existing WorldGuard region identifiers.
• SMP Regions support — use ArkFlame SMP Regions through its public region API.
• Composite AUTO mode — accept matching regions from either available provider.
• Movement-query optimization — optionally recheck regions only when block coordinates change.
• Configurable generation interval — control how frequently players earn shards.
• Configurable base generation amount — define the normal reward per cycle.
• Permission generation bonuses — configure any permission node and bonus value.
• Highest-bonus resolution — overlapping rank permissions do not stack uncontrollably.
• Zone entry presentation — configurable chat, title, subtitle, action bar, and sound feedback.
• Live generation countdown — action bar timer shows the next reward time.
• Player-kill rewards — reward killers with configurable shard amounts.
• Kill permission bonuses — provide larger rewards to selected ranks.
• Consecutive-victim anti-farm — repeated kills against the same victim can be ignored.
• Cancellable gain events — other plugins can cancel or modify shard gains.
• Cancellable loss events — other plugins can cancel or modify shard deductions.
• Player payments — online players can transfer shards directly.
• Payment rollback — failed receiver delivery restores the sender's debit.
• Self-payment protection — players cannot transfer shards to themselves.
• Multi-category inventory shop — browse products through configurable YAML menus.
• 215 bundled product definitions — ten categories are included.
• 167 normal Minecraft product definitions — blocks, resources, farming, weapons, armor, tools, and special items.
• 48 optional ecosystem product definitions — spawners, crate keys, and SMP weapons.
• Configurable product prices — every listing controls its own shard cost.
• Configurable product amounts — sell single items, bundles, equipment, or command-delivered products.
• Configurable pages and slots — place each product exactly where it belongs.
• Category permissions — restrict complete categories when required.
• Unavailable-product filtering — products without a valid delivery route are hidden.
• Inventory-capacity preflight — direct-item purchases can require enough storage before debit.
• Command-delivery support — dispatch configured console commands for external products.
• Alternative delivery branches — select the first available action using :R::.
• Safe refund states — known pre-delivery failures can restore the debited shards.
• Paginated leaderboard GUI — display cached rankings with player heads.
• Asynchronous leaderboard refresh — rankings are queried away from player-owned execution.
• Dynamic top placeholders — expose any cached rank through PlaceholderAPI.
• Movement-cancelled AFK teleport — teleport only after the player remains within the configured threshold.
• Asynchronous teleport completion — uses modern Paper teleport behavior.
• SQLite persistence — works immediately without an external database.
• MySQL persistence — configurable remote database and HikariCP pool.
• Asynchronous database executor — JDBC account operations do not run on player threads.
• Batched dirty-account flushing — changed balances are saved together at a configurable interval.
• Final shutdown flush — loaded accounts are persisted before the repository closes.
• MiniMessage support — gradients, hexadecimal colors, decorations, and modern components.
• Legacy ampersand formatting — existing & color strings remain usable.
• Configurable accent tag — change every <accent> component through one branding value.
• Configurable sounds — generation, zone entry, kills, purchases, errors, and AFK actions.
• PlaceholderAPI expansion — balances, ranks, generation timers, AFK state, and global settings.
• Public read API — inspect accounts, balances, leaderboards, and feature state.
• Safe YAML default merging — missing bundled keys are inserted without replacing existing values.
• Atomic YAML writes — mutable configuration snapshots use temporary files and atomic moves where supported.
• Asynchronous reload preparation — configuration and menu files reload away from player-owned operations.
• Folia-native scheduling — global, player, and asynchronous work uses Paper's ownership schedulers.

Independent Shard Currency

SMP Shards stores one account per player UUID and keeps the player's last known username for administrative lookup and leaderboard display.

• UUID identity — name changes do not create a second balance.
• Last-known-name lookup — administrative commands can find persisted accounts by username.
• 64-bit balance range — supports large long-term economies.
• Zero-floor protection — negative initial or assigned values are clamped to zero.
• Exact overflow detection — invalid additions fail instead of corrupting the account.
• Atomic compare-and-set deductions — simultaneous losses cannot spend the same shards twice.
• Dirty-state tracking — only changed cached accounts enter normal periodic persistence batches.

Currency names are configurable:


Number formatting is also configurable:


This can render values such as 1.5K, 2M, or the exact raw amount when compact formatting is disabled.

Region-Based Passive Generation

Players can earn shards by remaining inside one of the configured generation regions.

Default behavior:

• Reward interval — 15 seconds.
• Base reward — 1 shard.
• Generation regions — afk and afk_zone.
• Permission bonus resolution — only the highest matching bonus is added.
• Entry feedback — chat message, title, subtitle, and sound.
• Countdown feedback — live action bar until the next reward.
• Reward feedback — chat, title, subtitle, sound, and refreshed countdown.
• Exit feedback — leave message and action-bar cleanup.

The effective reward formula is:


Configured bonuses are not all added together. A player holding multiple generation bonus permissions receives the single highest value, preventing accidental rank-stack inflation.

Default generation configuration:


WorldGuard and SMP Regions Support

SMP Shards does not hard-depend on one region plugin. The provider mode determines where generation-zone matches are read from.

• AUTO — query every available provider and accept a match from WorldGuard or SMP Regions.
• WORLDGUARD — query only WorldGuard.
• SMP_REGIONS — query only SMP Regions.

Default provider configuration:


Provider mode aliases are normalized, so values such as smp-regions, smp regions, and SMP_REGIONS resolve to the same mode.

Region names are compared case-insensitively. In AUTO mode, matching identifiers returned by either provider are combined into one effective region set.

Movement Query Optimization

Region membership normally only needs to change after crossing a block boundary.

With the default option enabled, head rotation and small movement inside the same block do not trigger another region-provider query.

• Lower region-query frequency — yaw, pitch, and sub-block movement are ignored.
• Immediate block transition checks — crossing X, Y, Z, world, or teleport boundaries refreshes state.
• Per-player reward ticking — tracked generation state is evaluated on the player's entity scheduler.
• One-second presentation cadence — timers remain readable without per-tick message spam.

Permission-Based Reward Bonuses

Generation and kill rewards have independent permission-bonus maps.

Example:


A player with all three permissions receives only the highest bonus, 10. This makes the system compatible with inherited permission groups without multiplying every inherited reward.

Permission nodes and values are not hardcoded. Server owners can create any rank structure required by their network.

Player-Kill Rewards

When a player is killed by another player, the killer can receive a shard reward.

• Configurable base amount — default 15 shards.
• Configurable rank bonuses — add the highest matching kill bonus.
• Real player killer required — environmental deaths do not create rewards.
• Self-kill protection — a player cannot reward themselves.
• Consecutive-victim protection — repeatedly killing the same player can stop producing rewards.
• Different-victim reset — defeating another player changes the tracked victim for that killer.
• Mutable gain event — integrations can change or cancel the final reward.
• Configurable message and sound — successful rewards provide immediate feedback.

Default configuration:


Player-to-Player Payments

Players can transfer shards to another online player through /shards pay.

• Positive whole amounts only — invalid or negative amounts are rejected.
• Online exact-name target — payments resolve the current online player.
• Self-payment denial — sender and receiver must be different players.
• Balance verification — insufficient funds are rejected before receiver credit.
• Loss event — the sender debit can be cancelled or adjusted.
• Gain event — the receiver credit can be cancelled or adjusted.
• Receiver-owned delivery — credit execution is routed through the target player's scheduler.
• Automatic rollback — failed credit or scheduler rejection restores the sender's debited amount.
• Separate sender and receiver messages — both players receive the applied transfer amount.

Configurable Multi-Category Shop

SMP Shards includes a YAML-driven inventory shop that can operate as a category selector or open one default category directly.

The bundled main menu contains ten category definitions:

• Blocks — 24 products.
• Resources — 24 products.
• Farming — 24 products.
• Weaponry — 24 products.
• Armory — 26 products.
• Tools — 22 products.
• Special — 23 products.
• Spawners — 20 optional SMP Spawners products.
• Crate Keys — 7 optional SMP Crates products.
• SMP Weapons — 21 optional SMP Weapons products.

Total bundled catalog definitions: 215.

Every category can configure:

• Inventory title.
• Inventory size.
• Total page count.
• Category permission.
• Next-page item.
• Previous-page item.
• Back item.
• Filler item.
• Product page.
• Product slot.
• Product price.
• Product amount.
• Display material.
• Display name.
• Display lore.
• Glow state.
• Custom model data.
• Spawner type metadata.
• Direct-item or command-based delivery.

167 Bundled Minecraft Products

The normal catalog definitions cover building, farming, combat, progression, and end-game supplies.

• Blocks — stone, cobblestone, wood planks, logs, glass, bricks, sandstone, Nether bricks, End stone, quartz, terracotta, obsidian, glowstone, sea lanterns, prismarine, and End stone bricks.
• Resources — coal, iron, gold, copper, redstone, lapis, quartz, diamonds, emeralds, Netherite, amethyst, echo shards, prismarine materials, blaze rods, pearls, slime, magma cream, ghast tears, nautilus shells, Heart of the Sea, Nether Stars, and Totems of Undying.
• Farming — crops, melons, sugar cane, cactus, bamboo, kelp, cocoa, Nether wart, chorus fruit, apples, golden carrots, bone meal, saplings, bee nests, honey blocks, sponges, eggs, and turtle eggs.
• Weaponry — swords, bows, crossbows, arrows, spectral arrows, tipped arrows, maces, tridents, shields, axes, enchanted books, and End Crystals.
• Armory — leather, chainmail, iron, gold, diamond, and Netherite armor pieces, Turtle Shells, and Elytra.
• Tools — pickaxes, axes, shovels, and hoes across multiple material tiers.
• Special — golden apples, enchanted golden apples, pearls, Eyes of Ender, experience bottles, saddles, name tags, leads, spyglasses, brushes, Elytra, fireworks, enchanted books, Shulker Shells, Dragon Heads, conduits, End Crystals, Respawn Anchors, lodestones, enchanting tables, and anvils.

Prices, quantities, pages, display names, and positions are fully editable. The bundled values are starting examples rather than a mandatory economy balance.

20 SMP Spawner Listings

The bundled SMP Spawners category contains:

Pig, Cow, Sheep, Chicken, Rabbit, Squid, Dolphin, Turtle, Wolf, Cat, Ocelot, Fox, Horse, Donkey, Llama, Mooshroom, Bee, Panda, Polar Bear, and Parrot spawners.

These products use command delivery and can be shown only when their configured integration route is available.

7 SMP Crate Key Listings

The bundled SMP Crates category contains:

Common, Uncommon, Rare, Epic, Legendary, Mythic, and Vote crate keys.

Each product can define its own shard price and external key identifier.

21 SMP Weapon Listings

The bundled SMP Weapons category contains:

Excalibur, Soul Reaper, Thunder Fury, Ice Breaker, Dragon Bow, Inferno Blade, Crystal Staff, Void Hammer, Shadow Dagger, Storm Bow, Titan Axe, Frost Sword, Phoenix Bow, Venom Strike, Thunder Axe, Light Sword, Earth Shaker, Wind Blade, Magma Staff, Celestial Blade, and Death Scythe.

Every listing can map its display icon to a separate external weapon identifier.

Shop Delivery Actions

Product delivery can use the following action types:


Multiple alternatives can be placed in priority order:


The first currently available branch is selected.

Command templates support:

• %player% — current username.
• %uuid% — player UUID.
• %product_id% — current shop product key.
• %id% — action item or integration identifier.
• %amount% — selected delivery amount.

Custom Item Registry

The included items.yml registry can define reusable products for giveitem delivery.

A registered item can configure:

• Material.
• Base amount.
• Display name.
• Lore.
• Glow state.
• Custom model data.
• Spawner-type metadata.

The action amount acts as a multiplier. Large deliveries are split into legal Minecraft stack sizes and bounded to prevent unreasonable single-purchase output.

Example:


Product delivery:


This delivers two registry batches, for a total of eight configured items.

Purchase Safety Flow

The shop separates product resolution, balance deduction, player-owned item delivery, global command dispatch, and refund handling.

1. Resolve a valid delivery branch — unavailable actions are ignored.
2. Preflight direct-item capacity — require enough inventory storage for the complete item delivery.
3. Check current shard balance — display both required and missing amounts when insufficient.
4. Fire the shard loss event — allow integrations to cancel or modify the effective price.
5. Debit the applied amount — only after validation succeeds.
6. Deliver direct items on player ownership — inventory changes remain entity-safe.
7. Dispatch commands on global ownership — console actions do not run from an arbitrary player thread.
8. Refund known safe failures — scheduler rejection, unavailable required plugin, or command dispatch returning false can restore the debit.
9. Surface unsafe partial states — partial item insertion or an external command exception is logged for staff review instead of pretending the transaction succeeded.

A console command that returns success but later fails internally inside another plugin cannot be automatically reversed. External command routes should be tested before public deployment.

Paginated Shard Leaderboard

Players can open a cached leaderboard showing the highest shard balances.

• Player-head entries — each ranking uses the account owner's skull.
• Formatted balances — leaderboard values use the configured number formatter.
• 45 display positions per page — default GUI layout uses slots 0 through 44.
• Previous and next controls — navigate large ranking sets.
• Configurable title and navigation — edit the leaderboard YAML without recompiling.
• Asynchronous SQL ordering — results are loaded outside player-owned execution.
• Deterministic ordering — balance descending, then last known name ascending.
• Cached rank map — player-rank placeholders do not query the database per request.
• Configurable cache size — default 250 entries.
• Configurable refresh period — default 1,200 seconds.

Default leaderboard configuration:


AFK Teleport System

The /shardafk command starts a configurable countdown before teleporting the player to the stored AFK destination.

• Configurable countdown — default 5 seconds.
• Movement threshold — default 0.15 blocks from the original location.
• World-change cancellation — changing worlds during the countdown cancels it.
• Duplicate countdown protection — a player cannot start a second active countdown.
• Chat countdown — optional per-second messages.
• Action-bar countdown — optional clean timer display.
• Countdown sound — configurable per second.
• Movement cancellation feedback — clears the action bar and reports the reason.
• Asynchronous teleport — uses teleportAsync and reports success or failure.
• Persistent destination — /shards setafk writes world, coordinates, yaw, and pitch.
• Atomic location save — AFK updates use the YAML snapshot save path.

Default configuration:


SQLite and MySQL Persistence

SMP Shards supports local SQLite and remote MySQL through HikariCP.

Database table:


Indexes are created for:

• balance — leaderboard ordering.
• last_name — administrative username lookup.

Persistence behavior:

• Asynchronous account loading — player joins do not execute JDBC directly on entity ownership.
• Asynchronous name lookup — offline administrative account searches use the repository executor.
• Prepared statements — account and leaderboard queries use parameterized SQL.
• Database-native upsert — MySQL and SQLite use their appropriate conflict syntax.
• Transactional batch saves — dirty account snapshots commit together.
• Retryable dirty state — failed periodic flushes re-mark affected accounts as dirty.
• Cached online accounts — normal balance reads do not query SQL.
• Final full flush — shutdown attempts to save every cached account before closing the pool.

Default SQLite configuration:


MySQL configuration:


A complete custom JDBC URL can be supplied through jdbc-url.

PlaceholderAPI Support

PlaceholderAPI is optional. When installed, the smpshards expansion registers automatically and remains persistent across PlaceholderAPI reloads.

Available placeholders:


Replace <rank> with a positive integer, for example:


Player-specific placeholders use cached account, region, AFK, and leaderboard state. They do not perform a new SQL query for every placeholder request.

Public API and Events

Developers can obtain the enabled SMPShardsPlugin instance through Bukkit's plugin manager. The main plugin class implements SMPShardsApi directly.

The public API exposes:

• Cached account lookup by UUID.
• Asynchronous account lookup by last known name.
• Cached balance lookup.
• Asynchronous leaderboard query.
• Feature-enabled lookup.

Two Bukkit events are included:

• ShardGainEvent — cancellable and mutable.
• ShardLoseEvent — cancellable and mutable.

Gain reasons:


Loss reasons:


Listeners can cancel a transaction or replace the requested amount before the account mutation is applied. Event amounts are clamped to non-negative values.

MiniMessage and Branding

SMP Shards uses Adventure components for messages, titles, subtitles, action bars, and menu text.

• MiniMessage gradients — create modern branded headings.
• Hexadecimal colors — use exact brand colors.
• Decorations — bold, italic, underline, and other MiniMessage styling.
• Legacy ampersand colors — lines containing & can use legacy formatting.
• Central prefix placeholder — reuse %prefix% across messages.
• Currency placeholders — use %currency_singular% and %currency_plural%.
• Custom accent tag — every <accent> tag resolves to the configured brand color.

Default brand color:


Changing this value updates the custom <accent> tag used throughout messages and menus.

Configurable Sounds

Bundled sound keys include:

• Generation reward.
• Generation-zone entry.
• UI click.
• Error.
• Purchase.
• AFK countdown.
• AFK teleport.
• Kill reward.

Each sound can configure:


Set a sound to NONE to disable it. Invalid sound names are reported once per key instead of repeatedly spamming the console.

Configuration Files

SMP Shards separates major systems into focused files:


File responsibilities:

• config.yml — currency, feature toggles, providers, kill rewards, leaderboard, persistence, and number formatting.
• generation.yml — passive generation timing, bonuses, and presentation.
• afk.yml — AFK countdown, movement threshold, presentation, and location.
• branding.yml — custom MiniMessage accent color.
• integrations.yml — optional command-delivery plugin names and templates.
• messages.yml — all user-facing messages, titles, subtitles, and action bars.
• sounds.yml — sound names, volume, and pitch.
• shop.yml — root menu, category buttons, navigation, and shop behavior.
• items.yml — reusable custom item definitions.
• Categories/*.yml — category pages and product definitions.
• Gui/Leaderboard.yml — leaderboard title, slots, player entries, and navigation.

Feature Toggles

Each primary gameplay system can be independently enabled or disabled:


Disabled systems return a configurable player-facing message instead of silently doing nothing.

Default Core Configuration


Safe YAML Default Updates

When a bundled YAML file receives new keys, SMP Shards can merge missing scalar defaults into the existing disk file.

• Existing administrator values remain intact — present keys are not replaced by bundled defaults.
• Missing keys are inserted — updates can add new settings without requiring a complete reset.
• Temporary-file staging — mutable files are written through a .tmp file.
• Atomic move when available — reduces partial-write risk.
• Normal replacement fallback — works on filesystems without atomic move support.
• Path validation — resource paths reject traversal and invalid separators.

Reload Behavior

/shards reload reloads the configurable runtime state without requiring a complete server restart.

Reloaded systems include:

• Core configuration.
• Generation settings.
• AFK settings.
• Branding.
• Integration settings.
• Messages.
• Sounds.
• Shop root menu.
• Custom item registry.
• Bundled category files.
• Leaderboard GUI.
• Number formatter.
• Region-provider selection.
• Current online-player generation-zone state.

File preparation occurs asynchronously, while provider replacement and player-region refreshes are applied through the appropriate global and entity schedulers.

Folia Support

SMP Shards declares Folia support and uses Paper's ownership-aware scheduler APIs.

• Global region scheduler — repeating dispatch, command delivery, provider application, and console-owned operations.
• Player entity scheduler — balance events, messages, inventory delivery, generation ticks, and player-owned state.
• Asynchronous scheduler — configuration preparation and delayed asynchronous work.
• Dedicated JDBC executor — account loads, lookups, saves, and leaderboard queries.
• Asynchronous teleport API — AFK teleports use teleportAsync.
• Scheduler rejection handling — payment and purchase flows can restore debits when safe delivery never starts.

The plugin is built directly against modern Paper APIs. It is not a legacy Bukkit/Spigot 1.8 plugin.

Commands

Main command aliases: /smpshards, /shards, and /shard.

• /shards — display the player and administrator help lines available to the sender.
• /shards balance — display your current shard balance.
• /shards bal — alias for balance.
• /shards pay <player> <amount> — transfer shards to another online player.
• /shards shop — open the shard shop.
• /shards leaderboard — open the first leaderboard page.
• /shards top — alias for leaderboard.
• /shards see <player> — inspect a cached or persisted player's balance.
• /shards set <player> <amount> — set a balance, including zero.
• /shards give <player> <amount> — add shards.
• /shards take <player> <amount> — remove shards without allowing an overdraft.
• /shards setafk — save the current location as the AFK destination.
• /shards reload — reload configurable runtime content.
• /shardafk — begin the AFK teleport countdown.
• /afk — AFK command alias.
• /shardsafk — AFK command alias.

Tab completion includes main subcommands and online player names for payment and administrative target arguments.

Permissions

• smpshards.use — use the main command and view help.
• smpshards.pay — transfer shards to another player.
• smpshards.shop — open the shop.
• smpshards.leaderboard — open the leaderboard.
• smpshards.afk — use the AFK teleport command.
• smpshards.admin — parent administrative permission.
• smpshards.admin.balance — inspect, set, give, and take balances.
• smpshards.admin.setafk — save the AFK destination.
• smpshards.admin.reload — reload plugin files.

Default configurable bonus permissions:

• smpshards.generation.extra_two — default +2 generation bonus.
• smpshards.generation.extra_three — default +3 generation bonus.
• smpshards.kill.extra_ten — default +10 kill bonus.
• smpshards.kill.extra_twenty — default +20 kill bonus.

Bonus permission nodes can be replaced or expanded through YAML.

Soft Dependencies and Integrations

SMP Shards starts without every optional integration installed.

• WorldGuard — passive shard-generation region provider.
• SMP Regions — ArkFlame region provider.
• PlaceholderAPI — shard, rank, generation, AFK, and configuration placeholders.
• SMP Crates — optional crate-key shop delivery.
• SMP Spawners — optional spawner shop delivery.
• SMP Weapons — optional custom-weapon shop delivery.

Region generation requires at least one selected and available region provider. The remaining economy, balance, payment, kill, AFK, database, and normal shop architecture can initialize without WorldGuard or SMP Regions.

Compatibility

• Paper 1.21.4+ — primary supported platform.
• Folia 1.21.4+ — fully supported platform.
• Java 21 — required by the current build.
• SQLite — bundled local persistence option.
• MySQL — remote persistence option.
• WorldGuard 7.x — optional provider integration.
• PlaceholderAPI — optional expansion integration.
• No mandatory Vault — shards remain an independent currency.
• No mandatory database server — SQLite works locally.

SMP Shards uses modern Paper scheduler and teleport APIs. Bukkit, Spigot, Java 8, and Minecraft 1.8 are not supported by the attached 1.1.1 project.

Installation

1. Install Java 21.
2. Run Paper, Purpur, or Folia 1.21.4 or newer.
3. Place SMPShards-1.1.1.jar inside the server's plugins directory.
4. Install WorldGuard, SMP Regions, or both when using passive region generation.
5. Optionally install PlaceholderAPI and supported ArkFlame ecosystem plugins.
6. Start the server once to generate the configuration files.
7. Set region-provider.generation-regions to existing region identifiers.
8. Stand at the desired destination and execute /shards setafk.
9. Edit generation rewards, kill rewards, shop prices, messages, sounds, and database settings.
10. Restart the server or execute /shards reload.

Why Server Owners Choose SMP Shards

• Clear progression loop — earn, save, spend, transfer, and compete with one currency.
• Controlled reward zones — use existing region plugins rather than coordinate-only checks.
• Rank monetization without uncontrolled stacking — highest permission bonus wins.
• PvP incentives — reward kills while reducing basic same-victim farming.
• Large configurable catalog — begin with 215 product definitions instead of an empty menu.
• ArkFlame ecosystem potential — connect spawners, crates, and weapons through configurable commands.
• No Vault requirement — preserve the server's primary economy while adding a progression token.
• No mandatory MySQL setup — use SQLite immediately and migrate configuration to MySQL when needed.
• Modern presentation — MiniMessage gradients, titles, action bars, player heads, and sounds.
• Developer extensibility — read API, PlaceholderAPI, and mutable gain/loss events.
• Folia-first ownership model — modern scheduler separation is built into the architecture.
• Operational configuration split — edit the exact subsystem without navigating one enormous file.

Best Uses

• Survival SMP — reward active or AFK progression with a dedicated shop currency.
• Lifesteal SMP — attach shard rewards to PvP kills and valuable custom products.
• Box SMP — create repeatable generation zones and high-volume resource progression.
• Competitive SMP — combine kill rewards, ranks, leaderboards, and player trading.
• Economy servers — run a premium token beside normal money.
• Folia servers — use scheduler ownership designed for regionized execution.
• ArkFlame networks — connect SMP Regions, SMP Spawners, SMP Crates, and SMP Weapons.
• Seasonal servers — rebalance rewards and the complete product catalog between seasons.
• AFK progression servers — move players through a controlled countdown into a configured generation area.
• Ranked communities — assign permission-based generation and kill bonuses without inherited stacking.

FAQ

Does SMP Shards replace Vault money?
No. It provides an independent shard currency and does not require Vault.

Which server software is supported?
The attached project targets Paper, Purpur, and Folia 1.21.4+.

Which Java version is required?
Java 21.

Does it support Minecraft 1.8?
No. The current project is built against modern Paper 1.21.4 APIs.

How do players earn shards?
Through configured generation regions, player kills, payments, and administrative rewards.

Can I disable one earning method?
Yes. Region generation, kill rewards, payments, shop access, leaderboard access, and AFK teleport each have feature toggles.

Can I rename the currency?
Yes. Configure singular and plural names in config.yml.

Can players earn shards in WorldGuard regions?
Yes. Add the WorldGuard region IDs to region-provider.generation-regions.

Does it support SMP Regions?
Yes. Select SMP_REGIONS or use AUTO.

Can WorldGuard and SMP Regions work together?
Yes. AUTO mode combines matches from every available provider.

Do permission bonuses stack?
No. The highest matching bonus is selected independently for generation and kill rewards.

What is the default generation reward?
One shard every 15 seconds before permission bonuses.

What is the default kill reward?
Fifteen shards before permission bonuses.

Does it prevent kill farming?
It can block consecutive rewards when the same killer repeatedly defeats the same victim.

Can players pay each other?
Yes. Use /shards pay <player> <amount> for online players.

What happens when payment delivery fails?
The sender's debit is restored when receiver credit is cancelled, rejected, or cannot be scheduled.

How many shop products are bundled?
The resources contain 215 product definitions across ten categories.

Can I edit shop prices and quantities?
Yes. Every product controls its own price, amount, page, slot, icon, name, lore, and delivery.

Can I create custom categories?
The root shop maps category buttons to YAML files. Add or replace configured category files to build the desired catalog.

Can products run commands?
Yes. Use run_command or one of the specialized integration actions.

Can one product have a fallback delivery?
Yes. Separate alternatives with :R::; the first available branch is used.

Does the shop protect against a full inventory?
Direct-item delivery can be preflighted against the player's storage before balance debit.

Does it automatically refund failed purchases?
Known safe failures can restore the debit. Partial external side effects are reported for staff review instead of being blindly reversed.

Does it include a leaderboard?
Yes. The leaderboard uses player heads, pagination, cached SQL results, and configurable GUI content.

Does PlaceholderAPI query the database every time?
No. Player balances, ranks, and generation state use cached runtime data.

Does it support SQLite?
Yes. SQLite is the default persistence mode.

Does it support MySQL?
Yes. Configure host, port, database, credentials, SSL, pool size, or a custom JDBC URL.

Does database work run asynchronously?
Yes. Account loading, lookup, saves, and leaderboard queries use a dedicated executor.

Does it support AFK teleporting?
Yes. The command uses a configurable countdown and cancels when the player moves beyond the threshold.

Can I change the AFK destination?
Yes. Stand at the destination and execute /shards setafk.

Does it support MiniMessage?
Yes. Messages and menus support MiniMessage, while legacy ampersand strings remain usable.

Can I change the global accent color?
Yes. Edit branding.yml; the custom <accent> tag uses that value.

Does it expose an API?
Yes. The read API exposes accounts, balances, leaderboards, and feature state.

Can another plugin modify shard rewards?
Yes. ShardGainEvent and ShardLoseEvent are cancellable and mutable.

Does it support Folia?
Yes. The plugin declares Folia support and uses global, player, asynchronous, and database execution boundaries.

Are WorldGuard and SMP Regions mandatory?
Only passive region generation needs an available selected provider. They are soft dependencies.

Is PlaceholderAPI mandatory?
No. The expansion registers only when PlaceholderAPI is enabled.

Are SMP Spawners, SMP Crates, and SMP Weapons mandatory?
No. They are optional command-delivery integrations for their respective shop categories.


SEO keywords: SMP Shards, Minecraft shards plugin, shard currency plugin, Minecraft token economy, custom currency plugin, SMP economy plugin, survival SMP currency, Lifesteal shards plugin, Box SMP shards, PvP kill rewards plugin, AFK rewards plugin, AFK zone rewards, WorldGuard currency region, SMP Regions integration, region reward plugin, passive currency generation, player payment plugin, shard shop plugin, Minecraft shop currency, configurable GUI shop, 215 product shop, spawner shop integration, crate key shop integration, custom weapons shop, SQLite economy plugin, MySQL economy plugin, HikariCP Minecraft plugin, Folia economy plugin, Folia shards plugin, Paper 1.21 plugin, Purpur 1.21 plugin, Minecraft 1.21.4 plugin, Java 21 Minecraft plugin, PlaceholderAPI shards, shard leaderboard, player head leaderboard, MiniMessage economy plugin, permission reward bonuses, anti farm kill rewards, ArkFlame Studios, SMP Spawners integration, SMP Crates integration, SMP Weapons integration, SMP Regions plugin.