hShards

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

- Fully customizable messages - run as a secondary currency alongside Vault, or take over as the primary Vault provider - Fully customizable messages - `/pay` command with optional tax and cooldown - Fully customizable messages - define a shard price for any item and players can sell it via `/hshards sell` or `/sellall` - Fully customizable messages - paginated top balance list with a configurable refresh interval and cache size - Fully customizable messages - automatically give online players a percentage of their balance on a timer - Fully customizable messages - optionally prevent players from holding more then a set amount - Fully customizable messages - take a configurable percentage cut from every player-to-player payment - Fully customizable messages - every deposit, withdraw, payment and sell is written to a log file - Fully customizable messages - choose whichever fits your server size, switchable in config - Fully customizable messages - full set of placeholders for balances, ranks, leaderboard and more - Fully customizable messages - `HShardsAPI` class lets any plugin get/set/deposit/withdraw shard balances - Fully customizable messages - 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`: ```yaml 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`:

```yaml 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:

```java // 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.

```yaml 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:

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

```yaml 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*