hShards
一个轻量级的虚拟经济插件,可与你的主经济系统并行运行,或完全取代它。
什么是 hShards?
hShards 为你的服务器添加了一种名为 Shards(可完全重命名)的货币。它旨在与现有的 Vault 经济系统共存:玩家保留常规货币用于日常消费,而 Shards 则成为一种独立的进度货币,玩家可以通过出售物品、获得奖励、与其他玩家交易或通过利息系统被动赚取。
你也可以将其设置为 PRIMARY 模式,作为你的主 Vault 经济提供者,从而完全取代 EssentialsX 经济等插件。
我构建此插件是为了配合 hShop 使用,但其 API 是公开的,其他插件也可以接入其中。
功能
- 双模式 - 可作为 Vault 的辅助货币运行,也可接管成为主要的 Vault 提供者
- 玩家间转账 -
/pay 命令,可选配置税费和冷却时间
- 物品出售 - 为任何物品定义 Shard 价格,玩家可通过
/hshards sell 或 /sellall 出售
- 排行榜 - 分页显示余额最高的玩家列表,支持可配置的刷新间隔和缓存大小
- 利息系统 - 按定时器自动向在线玩家发放其余额的一定百分比
- 最大余额上限 - 可选择防止玩家持有超过设定数量的余额
- 支付税费 - 从每笔玩家间转账中抽取可配置的百分比作为税费
- 交易日志 - 每一笔存款、取款、转账和出售操作都会记录到日志文件中
- YAML 或 SQLite 存储 - 根据你的服务器规模选择适合的存储方式,可在配置中切换
- PlaceholderAPI 支持 - 提供完整的占位符,用于余额、排名、排行榜等
- 公开 API -
HShardsAPI 类允许任何插件获取/设置/存入/取出 Shard 余额
- 标题通知 - 当玩家获得或失去 Shards 时,可选地在屏幕上方显示标题提示
- 完全自定义消息 - 所有消息均位于
messages.yml 中,支持颜色代码
依赖
| 依赖项 |
是否必需 |
| Paper 1.21+ |
✅ 必需 |
| Vault |
⭐ 软依赖(PRIMARY 模式或 hShop 集成时需要) |
| PlaceholderAPI |
⭐ 软依赖 |
| hShop |
⭐ 软依赖(SECONDARY 模式下需要) |
模式
SECONDARY (默认) - hShards 完全不接触 Vault。它作为完全独立的货币在旁运行。需要 hShop(或其他集成)才能发挥实际作用,因为仅使用 Vault 的插件无法感知 Shards。这是 99% 情况下推荐使用的模式。
PRIMARY - hShards 注册自己为 Vault 的经济提供者。每个调用 economy.getBalance() 的插件都将从 hShards 读取数据。如果你希望拥有完全自定义的经济系统,而不使用 EssentialsX 或 CMI 来处理,这是一个不错的选择。
在 config.yml 中设置:
mode:
type: SECONDARY # 或 PRIMARY
命令
| 命令 |
描述 |
权限 |
/hshards balance |
查看你的 Shard 余额 |
hshards.balance |
/shardbal [player] |
查看你自己或其他玩家的余额 |
hshards.balance |
/pay <player> <amount> |
向其他玩家支付 Shards |
hshards.pay |
/shardstop [page] |
查看 Shards 排行榜 |
hshards.top |
/hshards sell |
出售手中的物品以换取 Shards |
hshards.use |
/hshards sellall |
出售所有符合条件的物品 |
hshards.use |
/hshards rank |
查看你在排行榜中的位置 |
hshards.top |
/hshardsadmin give <player> <amount> |
给予玩家 Shards |
hshards.admin.give |
/hshardsadmin take <player> <amount> |
从玩家处扣除 Shards |
hshards.admin.take |
/hshardsadmin set <player> <amount> |
设置玩家的余额 |
hshards.admin.set |
/hshardsadmin reset <player> |
将玩家余额重置为初始值 |
hshards.admin.reset |
/hshardsadmin resetall confirm |
重置所有玩家的余额 |
hshards.admin.reset |
/hshardsadmin balance <player> |
查看任意玩家的余额 |
hshards.admin |
/hshardsadmin reload |
重载插件 |
hshards.admin.reload |
/hshardsadmin lb-refresh |
强制刷新排行榜缓存 |
hshards.admin |
绕过权限
| 权限 |
效果 |
hshards.bypass.pay-tax |
跳过支付税费 |
hshards.bypass.pay-cooldown |
跳过支付冷却时间 |
hshards.bypass.max-balance |
突破最大余额上限 |
PlaceholderAPI 占位符
| 占位符 |
描述 |
%hshards_balance% |
玩家的原始余额 |
%hshards_balance_formatted% |
带货币符号的格式化余额 |
%hshards_rank% |
玩家在排行榜中的排名 |
%hshards_top_name_<N>% |
排名第 N 的玩家名称 |
%hshards_top_balance_<N>% |
排名第 N 的玩家余额 |
%hshards_top_balance_formatted_<N>% |
排名第 N 的格式化余额 |
%hshards_currency_name% |
复数形式的货币名称 |
%hshards_currency_symbol% |
货币符号 |
%hshards_total_players% |
有记录余额的玩家总数 |
top_name 和 top_balance 支持任意排名数字,不仅限于前 10 名。
可出售物品
在 plugins/hShards/sellable-items.yml 中定义玩家可以出售以换取 Shards 的物品:
items:
diamond:
material: DIAMOND
price: 50.0
enabled: true
name: "&bDiamond"
permission: "" # 留空表示无要求
netherite_ingot:
material: NETHERITE_INGOT
price: 200.0
enabled: true
name: "&8&lNetherite Ingot"
permission: "hshards.sell.netherite"
开发者 API
其他插件可以通过静态 API 类与 hShards 余额进行交互:
// 在调用任何方法之前检查 hShards 是否可用
if (HShardsAPI.isAvailable()) {
double balance = HShardsAPI.getBalance(player);
HShardsAPI.deposit(player, 100);
boolean success = HShardsAPI.withdraw(player, 50);
HShardsAPI.setBalance(player, 500);
}
// 格式化
String formatted - HShardsAPI.format(balance); // 例如 "✦ 500.00"
String name - HShardsAPI.getCurrencyName(); // 例如 "Shards"
// 排行榜
int rank - HShardsAPI.getRank(player);
String topName - HShardsAPI.getLeaderboardName(1);
double topBalance - HShardsAPI.getLeaderboardBalance(1);
}
在 `plugin.yml` 中将 hShards 添加为软依赖,当 hShards 加载时 API 即可使用。
---
## 利息系统
利息系统会定期给予在线玩家其余额的一定百分比作为利息。该功能完全可选,默认处于禁用状态。
```yaml
interest:
enabled: true
interval: 60 # 每 60 分钟
percent: 1.0 # 余额的 1%
max-eligible: 5000 # 仅前 5000 个碎片计入利息
permission: "" # 需要权限节点,或留空以允许所有人使用
存储
hShards 支持两种存储后端:
- YAML - 默认选项,无需配置,适合小型服务器
- SQLite - 推荐用于大型服务器,写入操作是异步的,不会影响性能
storage:
type: SQLITE
sqlite-file: "hshards.db"
与 hShop 完美配合
hShards 与 hShop 搭配效果极佳。玩家通过出售物品赚取碎片,然后在商店中使用这些碎片购买特殊物品,商店将 HSHARDS 作为其货币。这两个插件可以互相识别——当两者同时存在时,hShop 会自动钩入 hShards。
由 hodakazy 制作的 hPlugins 出品
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
评论 0
登录后参与评分
还没有评论,来抢沙发吧