Purpur Build
136 lines
6.4 KiB
Markdown
136 lines
6.4 KiB
Markdown
# 🏦 CraftBank（工艺银行）
|
||
|
||
> 适用于 **Folia / Purpur 1.21.8** 的全能经济与银行核心插件 —— 旨在完全替代 XConomy 等传统经济插件。
|
||
|
||
[](https://papermc.io/software/folia)
|
||
[](https://purpurmc.org/)
|
||
[](https://adoptium.net/)
|
||
[](https://www.spigotmc.org/resources/vault.34315/)
|
||
|
||
CraftBank 内置完善的「个人钱包 / 现金」系统，并引入深度模拟的银行系统：实体银行卡、可交易支票、活期储蓄与严格的定期存款（带利息）。在 Folia 上遵循多核服务端线程模型，使用 `AsyncScheduler` / `GlobalRegionScheduler` / `RegionScheduler` 调度；在 Purpur / Paper 上自动回退到 Bukkit 同步 / 异步任务调度。
|
||
|
||
---
|
||
|
||
## ✨ 核心功能
|
||
|
||
| 模块 | 说明 |
|
||
|------|------|
|
||
| 💵 **核心经济** | 每位玩家独立现金账户；实现 Vault `Economy` 接口并以 `Highest` 优先级注册，接管全服扣款 |
|
||
| 🧩 **平台兼容** | 同一个 jar 支持 Folia 与 Purpur/Paper；运行时自动选择正确调度器 |
|
||
| 💳 **银行卡** | 实体物品，PDC 绑定 UUID + 序列号；右键指定方块开柜；丢失可挂失补办（旧卡作废）|
|
||
| 📜 **支票** | `/cheque <金额>` 具现化为可流通实体物品；右键兑现入钱包；PDC 防伪 + 防刷 |
|
||
| 💰 **活期储蓄** | 存取自由，按真实时间戳逐日复利结算（含离线补偿，带封顶）|
|
||
| ⏳ **定期存款** | 7/15/30 天可选，到期前**任何情况不可提前支取**；到期本息自动入活期 |
|
||
| 📒 **交易流水** | 记录转账、存取、支票、定期、利息与管理操作；管理员可分页查询 |
|
||
| 🧾 **手续费** | 转账与活期取现可按配置收取固定 / 百分比手续费 |
|
||
| 💬 **自定义金额输入** | 银行 GUI 左键进入聊天输入自定义金额，右键保留「全部」快捷操作 |
|
||
|
||
---
|
||
|
||
## 🛠️ 依赖
|
||
|
||
- **必须**：[Vault](https://www.spigotmc.org/resources/vault.34315/)（CraftBank 作为其 Service Provider 注入）
|
||
- **可选**：[PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/)
|
||
|
||
> MySQL 驱动默认未内置；若使用 MySQL，请将驱动放入服务端 `libraries`，或在 `build.gradle.kts` 中取消相应依赖注释后自行打包。
|
||
|
||
---
|
||
|
||
## 💻 指令与权限
|
||
|
||
### 基础经济（所有人）
|
||
| 指令 | 说明 |
|
||
|------|------|
|
||
| `/money [玩家]` | 查看现金余额（查他人需 `craftbank.money.others`）|
|
||
| `/pay <玩家> <金额>` | 现金转账 |
|
||
| `/baltop [页码]` | 现金排行榜 |
|
||
|
||
### 银行玩家（`craftbank.use`）
|
||
| 指令 | 说明 |
|
||
|------|------|
|
||
| `/bank open` | 打开银行 GUI（可配置是否允许）|
|
||
| `/bank card apply` | 申请新银行卡 |
|
||
| `/bank card revoke` | 挂失并作废当前银行卡 |
|
||
| `/bank deposit <金额>` | 现金 → 活期 |
|
||
| `/bank withdraw <金额>` | 活期 → 现金 |
|
||
| `/cheque <金额>` | 开具支票 |
|
||
|
||
### 管理员（`craftbank.admin`）
|
||
| 指令 | 说明 |
|
||
|------|------|
|
||
| `/bankadmin reload` | 重载配置 |
|
||
| `/bankadmin give/take/set <玩家> <金额>` | 增加 / 扣除 / 设置现金 |
|
||
| `/bankadmin setinterest <savings\|term_7d\|term_15d\|term_30d> <利率>` | 动态修改利率 |
|
||
| `/bankadmin log <玩家> [页码]` | 分页查看玩家交易流水 |
|
||
|
||
---
|
||
|
||
## 🔌 PlaceholderAPI 变量
|
||
|
||
### CraftBank 原生变量
|
||
|
||
| 变量 | 含义 |
|
||
|------|------|
|
||
| `%craftbank_cash%` | 现金（纯数字）|
|
||
| `%craftbank_cash_formatted%` | 现金（含货币符号）|
|
||
| `%craftbank_bank_saving%` | 活期（纯数字）|
|
||
| `%craftbank_bank_saving_formatted%` | 活期（含货币符号）|
|
||
| `%craftbank_total%` | 现金 + 活期总额（纯数字）|
|
||
| `%craftbank_total_formatted%` | 现金 + 活期总额（含货币符号）|
|
||
| `%craftbank_has_card%` | 是否持有有效银行卡 |
|
||
| `%craftbank_savings_rate%` | 当前活期日利率百分比 |
|
||
|
||
### XConomy 兼容变量
|
||
|
||
CraftBank 会额外注册 `xconomy` PlaceholderAPI 扩展，原先使用 XConomy 的变量无需替换即可继续解析。
|
||
|
||
| 变量 | 含义 |
|
||
|------|------|
|
||
| `%xconomy_balance%` | 现金余额，按 XConomy 默认显示格式输出 |
|
||
| `%xconomy_balance_value%` | 现金余额原始数字 |
|
||
| `%xconomy_balance_formatted%` | 现金余额缩写格式（k / m）|
|
||
| `%xconomy_top_player_<名次>%` | 指定名次的玩家名，例如 `%xconomy_top_player_1%` |
|
||
| `%xconomy_top_balance_<名次>%` | 指定名次的余额 |
|
||
| `%xconomy_top_balance_value_<名次>%` | 指定名次的余额原始数字 |
|
||
| `%xconomy_top_balance_formatted_<名次>%` | 指定名次的余额缩写格式 |
|
||
| `%xconomy_top_rank%` | 当前玩家现金排行榜名次 |
|
||
| `%xconomy_top_rank_<玩家名>%` | 指定玩家现金排行榜名次 |
|
||
| `%xconomy_top_hidden%` | 兼容返回 `0`（CraftBank 不隐藏排行榜）|
|
||
| `%xconomy_paypermission%` | 兼容返回 `DEFAULT` |
|
||
| `%xconomy_paypermission_global%` | 兼容返回 `1` |
|
||
| `%xconomy_paytoggle%` | 兼容返回 `1` |
|
||
| `%xconomy_sum_balance%` | 全服现金总额 |
|
||
| `%xconomy_sum_balance_value%` | 全服现金总额原始数字 |
|
||
|
||
---
|
||
|
||
## ⚙️ 配置文件
|
||
|
||
详见生成的 `config.yml`，涵盖：数据库（SQLite/MySQL）、货币设置、利率（活期 / 各定期）、银行交互方块、转账 / 取现手续费、交易流水开关、银行卡与支票的自定义材质 / CustomModelData / 名称 / Lore、以及全部消息文案。
|
||
|
||
---
|
||
|
||
## 🔨 从源码构建
|
||
|
||
```bash
|
||
# 需要 JDK 21+（已用 JDK 25 验证通过）
|
||
./gradlew shadowJar
|
||
```
|
||
|
||
产物位于 `build/libs/CraftBank-<version>.jar`，已内置 SQLite 与 HikariCP 驱动，可直接丢进 `plugins/` 目录。
|
||
|
||
---
|
||
|
||
## 🤖 Folia 线程安全设计
|
||
|
||
- **Folia 后台任务**（数据库、`/baltop` 排序、利息扫描）走 `AsyncScheduler`；Purpur/Paper 走 Bukkit 异步任务。
|
||
- **Folia 玩家相关操作**（扣物品、开 GUI、发消息）从异步切回时调度到 `player.getScheduler()`（实体区域线程）；Purpur/Paper 走 Bukkit 主线程任务。
|
||
- 经济数据缓存使用 `ConcurrentHashMap`，单账户余额变更用 `synchronized` 保证原子，抵御来自其它插件异步线程（经 Vault）的并发刷钱。
|
||
- 支票兑现在玩家区域线程独占操作物品栏；定期领取用数据库 `UPDATE ... WHERE claimed = 0` 原子置位防重复发放。
|
||
|
||
---
|
||
|
||
## 📄 许可证
|
||
|
||
见 [LICENSE](LICENSE)。
|