Jbank

Jbank — Hytale 玩家库

Jbank 是一个服务器端插件，为玩家提供了一个安全的游戏内货币存储平台。存入银行的资金免于死亡损失，并按计划获得可调节的利息。一个干净的原生图形界面让玩家无需输入任何命令即可管理账户。

---

特色

玩家银行账户

• 每个玩家都有一个独立于库存钱包的个人银行账户
• 存款金额随意——无手续费
• 可设定可配置的费用（默认：2%）用于提取
• 银行余额完全免受死亡保护
• 所有操作都会立即持久化到磁盘——崩溃或重启时不会丢失数据

利息 / 收益率

• 可配置利率自动在指定时间应用
• 支持每天多次支付（例如 08:00、14:00、20:00）
• 时区感知调度（可按服务器配置）
• 仅在线支付——利息只会在支付时计入连接的玩家，奖励活跃玩家并鼓励玩家在服务器上的存在感
• 每当利息入账时，玩家会收到聊天通知

原生图形界面（/bank）

通过 /bank 命令访问。四个标签页：

标签页	描述
余额	显示当前银行余额、利率及下一次还款计划
存款	输入金额并确认——钱包余额实时显示
取款	在确认前，输入金额、费用和显示的净金额
历史	可滚动的最近50笔交易列表，包含日期、类型、金额和余额

交易历史

每条记录如下：

• 日期和时间（服务器时区）
• 类型：存款、取款、利息、费用
• 金额（绿色表示入账，红色表示出账）
• 操作后的余额

收费

• 所有取款手续费均汇入全球银行账户
• 银行余额可以通过公开 API 供管理员和其他插件访问
• 完整的费用收入历史均保存在 data/bank.json

---

命令与权限

命令	权限	描述
/bank	jbank.use	打开银行图形界面
/bank open <player>	（服务器端）	为玩家打开银行图形界面——专为 NPC 银行家设计
/bank admin balance	jbank.admin	在聊天中显示全球银行余额
/bank admin reload	jbank.admin	在不重启服务器的情况下重新加载 config.json 和消息

NPC 银行家设置

Jbank 支持 NPC 银行家工作流程，玩家需要亲自找银行 NPC 交互，而不是直接使用 /bank。

工作原理：

1. 在 config.json 中启用该功能：

"npcCommandEnabled": true

1. 移除玩家的 jbank.use 权限，这样 /bank 就无法访问。
2. 配置 NPC 在玩家与 NPC 互动时执行以下服务器端命令：

bank open {player}

因为 /bank open 运行在服务器端（作为服务器而非玩家），它完全绕过了 jbank.use，为互动玩家打开了银行图形界面。玩家完全无需输入命令。

---

配置（config.json）

{
  "withdrawFeePercent": 8.0,
  "interestRatePercent": 0.5,
  "interestSchedule": ["08:00", "14:00", "20:00"],
  "timezone": "America/Sao_Paulo",
  "currencyId": "money",
  "maxHistoryEntries": 50,
  "economyProvider": "auto",
  "language": "pt_BR",
  "npcCommandEnabled": true
}

字段	描述
withdrawFeePercent	每次取款收取的百分比（例如 2.0 = 2%）
interestRatePercent	按计划支付的利息百分比（例如 0.5 = 0.5%）
interestSchedule	利息支付时间列表 (HH:mm) — 服务器时区
timezone	用于调度的 Java 时区 ID（例如 America/New_York）
currencyId	传递给经济提供商的货币标识符
maxHistoryEntries	每个账户保留的最大交易记录数
economyProvider	auto、hyvault 或 vaultunlocked
language	要加载的消息文件：pt_BR、en_US 或 es_ES
npcCommandEnabled	启用用于 NPC 银行家设置的 /bank open <player> 服务器端命令

---

本地化

Jbank 内置三种语言：

• pt_BR — 巴西葡萄牙语
• en_US — 英语
• es_ES — 西班牙语

所有面向玩家的消息——聊天通知、GUI 标签、错误信息——均从 Messages/<language>.json 加载。你可以自由编辑这些文件，或通过创建新文件并在 config.json 中设置 "language" 来添加自己的语言。

---

经济兼容性

Jbank 在启动时自动检测你的经济插件：

• HyVault（单货币）
• VaultUnlocked（多货币）

设置 "economyProvider": "auto" 让 Jbank 自动检测，或使用 "hyvault" 或 "vaultunlocked" 强制指定特定提供商。

---

数据存储

所有数据存储在插件的数据目录中：

data/
  accounts/<player-uuid>.json   — 每个玩家的余额 + 交易历史
  bank.json                     — 全球银行余额 + 费用收入历史

每次操作后文件都会写入磁盘。无需数据库。

---

公开 API — 供插件开发者使用

Jbank 提供了一个静态 API，同一服务器上的任何插件都可以使用它来读取、存入或提取全球银行余额。这对于多个插件共享公共金库的经济生态系统非常有用。

设置

将 Jbank JAR 作为 compileOnly 依赖项添加到你的项目中。JAR 可在 Jbank 发布资产中找到。

Gradle (Kotlin DSL)：

dependencies {
    compileOnly(fileTree("libs") { include("Jbank-*.jar") })
}

Jbank 插件必须在运行时加载到服务器上。你的插件不需要声明硬依赖——只需在调用前进行空值检查。

---

获取 API 实例

JbankPlugin jbank = JbankPlugin.getInstance();
if (jbank == null) {
    // Jbank 未加载——优雅处理
    return;
}
BankManager bank = jbank.getBankManager();

getInstance() 在 Jbank 未安装或尚未完成加载时返回 null。使用前务必进行空值检查。

---

读取银行余额

double balance = bank.getBankBalance();

以 double 类型返回当前全球银行余额。

---

存入银行

bank.addToBankBalance(double amount);

将 amount 添加到全球银行余额。操作：

• 线程安全（synchronized）
• 立即持久化到磁盘
• 记录在银行交易历史中
• 记录到服务器控制台

示例——将代金券销售收入存入：

double salePrice = 500.0;
JbankPlugin jbank = JbankPlugin.getInstance();
if (jbank != null) {
    jbank.getBankManager().addToBankBalance(salePrice);
}

---

从银行取款

boolean success = bank.withdrawFromBankBalance(double amount);

从全球银行余额中扣除 amount。返回：

• true — 操作成功，余额已更新并持久化
• false — 余额不足或金额无效（无任何更改）

该操作线程安全，持久化到磁盘，并记录到控制台。

示例——支付服务器服务费用：

double cost = 200.0;
JbankPlugin jbank = JbankPlugin.getInstance();
if (jbank != null) {
    boolean paid = jbank.getBankManager().withdrawFromBankBalance(cost);
    if (!paid) {
        // 银行资金不足——相应处理
    }
}

---

API 总结

方法	返回	描述
JbankPlugin.getInstance()	JbankPlugin 或 null	获取活跃的插件实例
jbank.getBankManager()	BankManager	访问所有银行操作
bank.getBankBalance()	double	当前全球银行余额
bank.addToBankBalance(amount)	void	存入银行（线程安全）
bank.withdrawFromBankBalance(amount)	boolean	从银行取款（线程安全）

所有 API 方法均可从任何线程安全调用。

---

需求

• Hytale 服务器 API
• HyVault 或 VaultUnlocked（经济插件）
• Java 25+
• MIT 许可证