XzBank
XzBank 是一款服务端 Paper 插件,提供钱包货币、金币、玩家转账、货币票据、经验值凭证、服务器银行、交易历史、可选的 Vault 经济提供商、PlaceholderAPI 占位符以及用于 XzPlugin 集成的 API。
依赖项
- 与插件声明的 Paper API 版本匹配的 Paper 或 Purpur。
- Java 21。
- XzCore 0.3.x 或更高版本。必须安装 XzCore。
- SQLite 存储已内置,且是本版本唯一支持的数据库后端。
可选集成:
- Vault,当其他插件需要 XzBank 注册为服务器经济提供商时。
- PlaceholderAPI,用于
%xzbank_*% 占位符。
安装
- 安全停止服务器。请勿使用 Bukkit
/reload 进行 JAR 更新。
- 在替换现有安装之前,备份现有的
plugins/XzBank/ 文件夹及其 xzbank.db 数据库。
- 将 XzCore JAR 和 XzBank JAR 放入
plugins/ 目录。
- 启动服务器并确认 XzCore 已就绪。
- 以管理员身份运行
/xzbank version、/xzbank status 和 /xzbank health。
- 运行
/bank update 查看配置更新。仅在审查计划并保留备份后,才使用 /bank update confirm。
全新安装会创建 plugins/XzBank/ 配置文件夹和 SQLite 数据库 xzbank.db。
核心玩家命令
| 命令 |
用途 |
权限 |
/bank |
打开银行菜单。 |
xzbank.use |
/bal |
显示钱包余额。 |
xzbank.balance |
/bal top |
显示金钱排行榜。 |
xzbank.top |
/pay <player> <amount> |
发送钱包金钱。 |
xzbank.pay |
/coins |
显示金币余额。 |
xzbank.coins.balance |
/coinpay <player> <amount> |
向其他玩家发送金币。 |
xzbank.coins.pay |
/bank note money <amount> |
创建允许的金钱票据。 |
xzbank.note.money |
/bank note xp <amount> |
创建允许的经验值凭证。 |
xzbank.note.xp |
金钱票据和经验值凭证使用配置的安全面额。票据存储在数据库中,且只能兑换一次。
管理
xzbank.admin 包含了在 plugin.yml 中声明的各个管理员权限。常见的诊断命令包括:
/xzbank version
/xzbank status
/xzbank health
/xzbank history <player>
/bank update
管理金钱、金币、服务器银行、税收、审计、迁移和配置的命令需要相应的 xzbank.admin.* 权限。仅授予受信任的工作人员这些权限。
配置
所有默认配置文件均存储在 plugins/XzBank/ 下。
| 文件 |
用途 |
config.yml |
SQLite 文件名、金钱比例、票据设置、限制、费用和 GUI 布局。 |
economy.yml |
经济提供商启用、Vault 注册、货币符号和玩家命令。 |
coins.yml |
金币命名、初始余额、余额政策和金币命令。 |
server-bank.yml |
服务器银行启用、初始余额和金库命令选项。 |
taxes.yml |
税收类别和税率。 |
audit.yml |
审计队列和刷新设置。 |
migration.yml |
EssentialsX 迁移保护措施。 |
messages.yml |
面向玩家的提示信息。 |
保持 storage.type: sqlite。请勿将 XzBank 指向共享或网络同步的 SQLite 文件。在服务器停止时,请一起备份 xzbank.db、xzbank.db-wal 和 xzbank.db-shm。
Vault 兼容性
当安装了 Vault 且 economy.yml 启用了注册时,XzBank 会将其钱包注册为 Vault 经济提供商。这支持正常的玩家余额、账户创建、存款、取款和格式化。
有意不支持 Vault 银行账户方法。XzBank 的服务器银行通过 XzBank 管理员命令进行管理,并不作为 Vault 银行账户暴露。其插件需要 Vault 银行支持的服务器应使用实现了该功能的提供商。
PlaceholderAPI
当可用 PlaceholderAPI 时,XzBank 会注册 xzbank 扩展。可用的占位符如下:
%xzbank_balance%
%xzbank_balance_formatted%
%xzbank_coins%
%xzbank_coins_formatted%
%xzbank_xp_balance%
%xzbank_xp_balance_formatted%
%xzbank_total_deposited%
%xzbank_total_withdrawn%
%xzbank_daily_withdrawn%
%xzbank_daily_banknote_created%
API 使用
XzPlugin 集成可以获取 XzBankApi,以实现异步余额、钱包操作、幂等外部收费、金币收费、双货币预留以及由服务器支持的经验值凭证发行。
调用者必须为每次幂等收费或预留提供一个稳定的操作 ID。请勿对不同的玩家或金额重用操作 ID。切勿在 API 未来(future)上阻塞 Paper 主线程。
更新与迁移
请使用干净的服务端重启来进行 JAR 更新。保留所有者管理的 plugins/XzBank/ 目录。在 /bank update confirm 之前先运行 /bank update;更新过程旨在添加缺失的默认值,同时保留自定义值。
除非在 migration.yml 中明确启用,否则 EssentialsX 迁移将被禁用。始终先运行预览,并在导入余额之前保留生成的备份。
故障排除
XzCore is not ready:首先更新或启动 XzCore,然后干净地重启服务器。
Vault provider registration skipped:当第三方插件需要 Vault 经济访问时,请安装 Vault。XzBank 自身的钱包功能仍然可用。
- SQLite unhealthy:停止服务器,备份完整的 XzBank 数据文件夹,然后在尝试恢复之前使用 SQLite 完整性检查来检查数据库。
- 支付失败:验证发送者余额、接收者名称、权限、已启用的经济设置以及服务器日志。
- 配置更新报告了更改:审查计划,备份 XzBank 文件夹,然后确认更新。
XzBank
XzBank is a server-side Paper plugin that provides wallet money, Coins, player transfers, money notes, XP vouchers, a Server Bank, transaction history, an optional Vault economy provider, PlaceholderAPI values, and an API for XzPlugin integrations.
Requirements
- Paper or Purpur matching the plugin's declared Paper API version.
- Java 21.
- XzCore 0.3.x or newer. XzCore is required.
- SQLite storage is built in and is the only supported database backend for this release.
Optional integrations:
- Vault, when other plugins need XzBank to register as the server economy provider.
- PlaceholderAPI, for
%xzbank_*% placeholders.
Installation
- Stop the server cleanly. Do not use Bukkit
/reload for JAR updates.
- Back up the existing
plugins/XzBank/ folder and its xzbank.db database before replacing an existing installation.
- Place the XzCore JAR and XzBank JAR in
plugins/.
- Start the server and confirm XzCore is ready.
- Run
/xzbank version, /xzbank status, and /xzbank health as an administrator.
- Run
/bank update to review configuration updates. Use /bank update confirm only after reviewing the plan and retaining a backup.
A fresh installation creates the plugins/XzBank/ configuration folder and the SQLite database xzbank.db.
Core player commands
| Command |
Purpose |
Permission |
/bank |
Open the Bank menu. |
xzbank.use |
/bal |
Show wallet balance. |
xzbank.balance |
/bal top |
Show the money leaderboard. |
xzbank.top |
/pay <player> <amount> |
Send wallet money. |
xzbank.pay |
/coins |
Show Coin balance. |
xzbank.coins.balance |
/coinpay <player> <amount> |
Send Coins to another player. |
xzbank.coins.pay |
/bank note money <amount> |
Create an allowed money note. |
xzbank.note.money |
/bank note xp <amount> |
Create an allowed XP voucher. |
xzbank.note.xp |
Money notes and XP vouchers use the configured safe denominations. A note is stored in the database and can only be redeemed once.
Administration
xzbank.admin includes the individual administrator permissions declared in plugin.yml. Common diagnostics are:
/xzbank version
/xzbank status
/xzbank health
/xzbank history <player>
/bank update
Administrative money, Coin, Server Bank, tax, audit, migration, and configuration commands require their corresponding xzbank.admin.* permission. Grant these permissions only to trusted staff.
Configuration
All default configuration files are stored under plugins/XzBank/.
| File |
Purpose |
config.yml |
SQLite filename, money scale, note settings, limits, fees, and GUI layout. |
economy.yml |
Economy-provider enablement, Vault registration, currency symbol, and player commands. |
coins.yml |
Coin naming, starting balances, balance policy, and Coin commands. |
server-bank.yml |
Server Bank enablement, starting balance, and treasury command options. |
taxes.yml |
Tax categories and rates. |
audit.yml |
Audit queue and flush settings. |
migration.yml |
EssentialsX migration safeguards. |
messages.yml |
Player-facing messages. |
Keep storage.type: sqlite. Do not point XzBank at a shared or network-synced SQLite file. Back up xzbank.db, xzbank.db-wal, and xzbank.db-shm together while the server is stopped.
Vault compatibility
When Vault is installed and economy.yml enables registration, XzBank registers its wallet as a Vault economy provider. This supports normal player balances, account creation, deposits, withdrawals, and formatting.
Vault bank-account methods are intentionally unsupported. XzBank's Server Bank is managed through XzBank administrator commands and is not exposed as a Vault bank account. Servers whose plugins require Vault bank support should use a provider that implements it.
PlaceholderAPI
When PlaceholderAPI is available, XzBank registers the xzbank expansion. Available placeholders are:
%xzbank_balance%
%xzbank_balance_formatted%
%xzbank_coins%
%xzbank_coins_formatted%
%xzbank_xp_balance%
%xzbank_xp_balance_formatted%
%xzbank_total_deposited%
%xzbank_total_withdrawn%
%xzbank_daily_withdrawn%
%xzbank_daily_banknote_created%
API use
XzPlugin integrations can obtain XzBankApi for asynchronous balances, wallet operations, idempotent external charges, Coin charges, dual-currency reservations, and server-backed XP-note issuance.
Callers must supply a stable operation ID for every idempotent charge or reservation. Do not reuse an operation ID for a different player or amount. Never block the Paper main thread on an API future.
Updating and migration
Use a clean server restart for JAR updates. Preserve the owner-managed plugins/XzBank/ directory. Use /bank update before /bank update confirm; the update process is designed to add missing defaults while preserving customized values.
The EssentialsX migration is disabled unless explicitly enabled in migration.yml. Always run its preview first and retain the generated backup before importing balances.
Troubleshooting
XzCore is not ready: update or start XzCore first, then restart the server cleanly.
Vault provider registration skipped: install Vault when third-party plugins need Vault economy access. XzBank's own wallet features remain available.
- SQLite unhealthy: stop the server, back up the complete XzBank data folder, then inspect the database with a SQLite integrity check before attempting recovery.
- A payment fails: verify sender balance, recipient name, permission, enabled economy settings, and server logs.
- A configuration update reports changes: review the plan, back up the XzBank folder, then confirm the update.
评论 0
登录后参与评分
还没有评论,来抢沙发吧