hShards

A lightweight virtual economy plugin that runs alongside your main economy, or replaces it entirely.

---

What is hShards?

hShards adds a second currency to your server called Shards (fully renameable). It's designed to sit next to your existing Vault economy, players keep their regular money for the normal stuff, and Shards become a separate progression currency that they can earn by selling items, receiving them as rewards, trading with other players, or passively through an interest system.

It can also run in PRIMARY mode and act as your main Vault economy provider if you want, replacing plugins like EssentialsX economy entirely.

I built this to pair with hShop, but the API is public so other plugins can hook into it to.

---

Features

• Dual mode - run as a secondary currency alongside Vault, or take over as the primary Vault provider
• Player-to-player payments - /pay command with optional tax and cooldown
• Item selling - define a shard price for any item and players can sell it via /hshards sell or /sellall
• Leaderboard - paginated top balance list with a configurable refresh interval and cache size
• Interest system - automatically give online players a percentage of their balance on a timer
• Max balance cap - optionally prevent players from holding more then a set amount
• Payment tax - take a configurable percentage cut from every player-to-player payment
• Transaction logging - every deposit, withdraw, payment and sell is written to a log file
• YAML or SQLite storage - choose whichever fits your server size, switchable in config
• PlaceholderAPI support - full set of placeholders for balances, ranks, leaderboard and more
• Public API - HShardsAPI class lets any plugin get/set/deposit/withdraw shard balances
• Title notifications - optional screen title when a player receives or loses shards
• Fully customizable messages - every single message is in messages.yml with color code support

---

Requirements

Dependency	Required?
Paper 1.21+	✅ Required
Vault	⭐ Soft (required for PRIMARY mode or hShop integration)
PlaceholderAPI	⭐ Soft
hShop	⭐ Soft (required if running in SECONDARY mode)

---

Modes

SECONDARY (default) - hShards doesn't touch Vault at all. It runs as a completely separate currency on the side. Requires hShop (or another integration) to actually be useful, since Vault-only plugins won't know about shards. This is the mode you want 99% of the time.

PRIMARY - hShards registers itself as the Vault economy provider. Every plugin that calls economy.getBalance() will be reading from hShards. Good if you want a fully custom economy without EssentialsX or CMI handling it.

Set this in config.yml:

mode:
  type: SECONDARY  # or PRIMARY

---

Commands

Command	Description	Permission
/hshards balance	Check your shard balance	hshards.balance
/shardbal [player]	Check your own or another players balance	hshards.balance
/pay <player> <amount>	Pay shards to another player	hshards.pay
/shardstop [page]	View the shards leaderboard	hshards.top
/hshards sell	Sell item in hand for shards	hshards.use
/hshards sellall	Sell all eligible items	hshards.use
/hshards rank	View your leaderboard position	hshards.top
/hshardsadmin give <player> <amount>	Give shards to a player	hshards.admin.give
/hshardsadmin take <player> <amount>	Take shards from a player	hshards.admin.take
/hshardsadmin set <player> <amount>	Set a player's balance	hshards.admin.set
/hshardsadmin reset <player>	Reset a player to starting balance	hshards.admin.reset
/hshardsadmin resetall confirm	Reset every player's balance	hshards.admin.reset
/hshardsadmin balance <player>	Check any player's balance	hshards.admin
/hshardsadmin reload	Reload the plugin	hshards.admin.reload
/hshardsadmin lb-refresh	Force a leaderboard cache refresh	hshards.admin

---

Bypass Permissions

Permission	Effect
hshards.bypass.pay-tax	Skip the payment tax
hshards.bypass.pay-cooldown	Skip the payment cooldown
hshards.bypass.max-balance	Exceed the max balance cap

---

PlaceholderAPI Placeholders

Placeholder	Description
%hshards_balance%	Player's raw balance
%hshards_balance_formatted%	Balance with currency symbol
%hshards_rank%	Player's leaderboard rank
%hshards_top_name_<N>%	Name of player at rank N
%hshards_top_balance_<N>%	Balance of player at rank N
%hshards_top_balance_formatted_<N>%	Formatted balance at rank N
%hshards_currency_name%	Plural currency name
%hshards_currency_symbol%	Currency symbol
%hshards_total_players%	Total players with recorded balances

Supports any rank number for top_name and top_balance — not just top 10.

---

Sellable Items

Define which items players can sell for shards in plugins/hShards/sellable-items.yml:

items:
  diamond:
    material: DIAMOND
    price: 50.0
    enabled: true
    name: "&bDiamond"
    permission: ""   # leave empty for no requirement

  netherite_ingot:
    material: NETHERITE_INGOT
    price: 200.0
    enabled: true
    name: "&8&lNetherite Ingot"
    permission: "hshards.sell.netherite"

---

Developer API

Other plugins can interact with hShards balances through the static API class:

// Check if hShards is available before calling anything
if (HShardsAPI.isAvailable()) {
    double balance - HShardsAPI.getBalance(player);
    HShardsAPI.deposit(player, 100);
    boolean success - HShardsAPI.withdraw(player, 50);
    HShardsAPI.setBalance(player, 500);

    // Formatting
    String formatted - HShardsAPI.format(balance);  // e.g. "✦ 500.00"
    String name - HShardsAPI.getCurrencyName();      // e.g. "Shards"

    // Leaderboard
    int rank - HShardsAPI.getRank(player);
    String topName - HShardsAPI.getLeaderboardName(1);
    double topBalance - HShardsAPI.getLeaderboardBalance(1);
}

Add hShards as a soft dependency in your plugin.yml and the API will be available whenever hShards is loaded.

---

Interest System

The interest system gives online players a percentage of their balance at a regular interval. Its completely optional and disabled by default.

interest:
  enabled: true
  interval: 60        # every 60 minutes
  percent: 1.0        # 1% of their balance
  max-eligible: 5000  # only the first 5000 shards count toward interest
  permission: ""      # require a permission node, or leave empty for everyone

---

Storage

hShards supports two storage backends:

• YAML - default, no setup required, good for small servers
• SQLite - recommended for larger servers, writes are async so it won't affect performance

storage:
  type: SQLITE
  sqlite-file: "hshards.db"

---

Works great with hShop

hShards pairs perfectly with hShop. Players earn shards through selling items, then spend them on special items in the shop that uses HSHARDS as their currency. The two plugins are aware of each other - hShop hooks into hShards automatically when both are present.

---

Made by hPlugins by hodakazy