MultiBank

插件

· 作者 roguiii

经济插件,支持个人与共享群组账户、角色系统、图形界面、原子交易、可选的 Vault 桥接以及开发者 API。

0 本站下载 0 关注 更新于 1 个月前

最新 2.1.0+mc26.3 · 26.3 · Paper / Purpur

一键开服(送7天)

MultiBank

适用于 Paper/Purpur 26.3 服务器(2.0.0 版本运行于 26.2,1.x 版本运行于 1.21.x)的安全、功能丰富的经济插件。

MultiBank 替代 EssentialsX Economy,作为服务器的主要经济系统,支持 GUI、多账户管理、用于兼容旧插件的 Vault 桥接以及简洁的开发人员 API。

功能

  • 多账户系统:个人 + 群组/联名账户,支持角色权限(OWNER, MANAGER, MEMBER, VIEWER)
  • GUI 界面:通过 /mb 提供全功能的库存 GUI — 向玩家付款、管理账户、查看历史记录、接受邀请、查看余额排行
  • Vault 桥接:旧插件(商店、拍卖行等)可通过 Vault Economy 提供商无缝工作
  • 开发人员 API:通过 Bukkit ServicesManager 暴露,支持异步 CompletableFuture 方法
  • 自定义事件:BalanceChangeEvent, TransferEvent, AccountCreateEvent, PrimaryAccountChangeEvent, AccountFrozenEvent
  • 原子事务:无重复、无双重支付、无竞态条件 — 所有数据库操作均为事务性
  • SQLite/MySQL:可配置的存储后端,配备 HikariCP 连接池
  • 本地化:英语 (en_US) + 葡萄牙语 (pt_PT),易于扩展
  • 速率限制:可配置的单玩家操作节流
  • 长整型分币存储:余额在内部以 long 类型分币存储 — 无浮点数精度损失

银行模块

四个可选模块,默认开启,每个均可在 config.yml 中切换而不丢失数据。

  • 储蓄账户 (/poupanca):按期间持有的最低余额支付利息,因此在刻度前一刻存入的资金不会产生利息。
  • 定期存款 (/poupanca prazo):资金锁定在托管账户中固定期限,且不计入玩家余额,利率高于活期储蓄。累积的利息在到期前保持隐藏 — 提前取消则精确返还本金至分币。
  • 贷款 (/emprestimo):向国家借款,或通过报价板向其他玩家借款,其中资金在报价时托管,接受为数据库比较并交换操作。违约将导致余额被扣押,从借款人未来的收入中收取。
  • 证书 (/certificados):基于葡萄牙工具的储蓄和国库债券模型。认购即向国家放贷,由国家运作资金。
  • 国家 (/estado):公共国库资产负债表及其资助的社区项目。交付项目会销毁货币 — 这是经济体中唯一的有意消耗项。

没有任何模块会创造货币。 每一笔贷方都有对应的借方:利息由国库支付,贷款移动国库或托管资金,如果国家无力支付,则不支付而不是铸造。/mb admin audit 将托管账户与其背后的合同进行对账,并报告任何偏差。

安装

  1. 下载 MultiBank-2.1.0+mc26.3.jar
  2. 将其放入服务器的 plugins/ 文件夹
  3. (可选)将 Vault.jar 放入 plugins/ 以支持旧插件
  4. 启动服务器 — 将生成 config.yml 和 lang/ 文件
  5. 编辑 plugins/MultiBank/config.yml 以自定义货币、数据库、支付限额等。
  6. 使用 /mb admin reload 应用配置更改而无需重启

命令

玩家命令

命令 别名 描述
/mb — 打开主 GUI
/money [player] /bal, /saldo, /balance 检查余额(主账户)
/pay <player> <amount> [fromAccount] /pagar 向其他玩家付款
/pay confirm — 确认待处理的大额付款
/pay cancel — 取消待处理的付款
/topbal [page] /top, /baltop, /topmoney 查看最富有账户

账户管理 (/mb account)

命令 描述
/mb account list 列出您的所有账户
/mb account info <accountId> 查看账户详情
/mb account create <name> 创建群组/联名账户
/mb account rename <accountId> <name> 重命名账户
/mb account setprimary <accountId> 设置您的主账户
/mb account invite <accountId> <player> 邀请玩家加入您的群组账户
/mb account accept [inviteId] 接受邀请(若无 ID 则为最新)
/mb account kick <accountId> <player> 从您的群组账户中移除成员
/mb account role <accountId> <player> <OWNER|MANAGER|MEMBER|VIEWER> 更改成员角色
/mb account leave <accountId> 退出群组账户(如果是所有者则无法退出)

储蓄和定期存款 (/poupanca, /savings)

命令 描述
/poupanca 储蓄和定期存款 GUI
/poupanca abrir [name] 开设储蓄账户
/poupanca depositar <amount> [savingsId] 将资金转入储蓄
/poupanca levantar <amount> [savingsId] 提取资金
/poupanca info 您的账户、利息基数及距下次支付的时间
/poupanca taxa 当前利率及其计算方式
/poupanca prazo tipos 提供的定期存款类型
/poupanca prazo abrir <type> <amount> 将资金锁定固定期限
/poupanca prazo 您的锁定头寸
/poupanca prazo cancelar <id> 取消或领取 — 资金始终全额返还

利息按期间持有的最低余额支付,因此在整个期间未承担风险的资金不会产生收益。定期存款的应计利息在到期前保持隐藏。

贷款 (/emprestimo, /loan)

命令 说明
/emprestimo 信贷仪表盘
/emprestimo simular <amount> <periods> 在承诺借款前,对政府贷款进行报价估算
/emprestimo pedir <amount> <periods> 向政府借款
/emprestimo oferecer <amount> <rate%> <periods> 向其他玩家提供贷款(资金将存入托管账户)
/emprestimo mercado 浏览公开的贷款要约
/emprestimo aceitar <offerId> 接受某项要约
/emprestimo cancelar <offerId> 撤回你自己的要约
/emprestimo pagar <loanId> [amount] 还款;若不提供金额则结算全部余额
/emprestimo meus 你欠下的贷款以及你发放的贷款
/emprestimo credito 你的信用评分、记录及授信额度

分期款项会自动扣收。若拖欠过多导致违约,系统将按比例从借款人收到的资金中扣除欠款,直至结清。

债券 (/certificados, /certs)

命令 说明
/certificados 债券图形界面
/certificados series 当前发行的债券系列,含利率与条款
/certificados subscrever <series> <amount> 向政府出借指定金额
/certificados resgatar <certId> 赎回债券
/certificados meus 你持有的债券

政府 (/estado, /state)

命令 说明
/estado 国库与项目图形界面
/estado info 余额、债务、对外放贷情况、偿付能力
/estado projetos 社区项目及其进度
/estado propor <goal> <name…> 提议一个新项目
/estado votar <projectId> 为某项提议投票
/estado financiar <projectId> <amount> 注资支持

管理员命令 (/mb admin)

命令 说明 权限节点
/mb admin give <player|accountId> <amount> [reason] 给予金钱 multibank.admin.give
/mb admin take <player|accountId> <amount> [reason] 扣除金钱 multibank.admin.take
/mb admin set <player|accountId> <amount> [reason] 设置余额 multibank.admin.set
/mb admin freeze <player|accountId> <on|off> 冻结/解冻账户 multibank.admin.freeze
/mb admin reload 重新加载配置文件和语言文件 multibank.admin.reload
/mb admin treasury info 查看国库资产负债表 multibank.admin.treasury
/mb admin treasury grant <amount> [reason] 向国库注入初始资金(铸造货币;会如实记录) multibank.admin.treasury
/mb admin treasury burn <amount> [reason] 销毁国库中的货币 multibank.admin.treasury
/mb admin project open <goal> <name…> 开放项目以接受注资 multibank.admin.project
/mb admin project complete <id> 标记项目已交付——消耗并销毁相应资金 multibank.admin.project
/mb admin project cancel <id> 取消项目并退还所有贡献者的资金 multibank.admin.project
/mb admin audit 核对托管资金与合同的一致性;报告偏差 multibank.admin.audit

这些命令的控制台和 RCON 回复均写入服务器日志:查询操作由数据库线程处理,而 RCON 请求在此时已经关闭。

国库初始为空。在其拥有资金之前,无法放贷或支付利息——你可以使用 /mb admin treasury grant 为其注入初始资金,或等待其通过债券认购和贷款费用自动充盈。

OP 覆盖命令 (/mb op)

这些命令仅限 服务器 OP (isOp()) 和 控制台 使用——无需权限节点,仅检查 OP 身份。 它们始终针对玩家的 个人 账户,无论其当前设置的主要账户为何。

命令 说明 示例
/mb op set <player> <amount> 强制设置玩家的个人余额 /multibank op set username 4000
/mb op give <player> <amount> 向玩家的个人账户给予金钱 /mb op give username 250
/mb op take <player> <amount> 从玩家的个人账户扣除金钱 /mb op take username 100

规则:

  • 金额支持小数(例如 4000.50),内部转换为分单位存储
  • 支持 离线玩家(通过 Bukkit.getOfflinePlayer 查找 UUID)
  • 所有操作均为 原子性(单次数据库事务)
  • 每个操作都会记录到控制台和交易历史中,原因标注为 "OP override"
  • 当余额可能变为负数时的“扣除”行为可配置:
    • clamp-negative-to-zero: true(默认)——只扣除玩家现有的金额,余额归零
    • clamp-negative-to-zero: false —— 完全拒绝该操作
    • allow-negative-after-take: true —— 允许余额为负(覆盖上述钳制逻辑)

示例:

/multibank op set Steve 4000       → 将 Steve 的个人余额设置为 $4,000.00
/mb op give Alex 250.50            → 向 Alex 的个人账户给予 $250.50
/mb op take Notch 100              → 从 Notch 的个人账户扣除 $100.00

权限

权限 描述 默认值
multibank.use 使用 /mb GUI 和基本命令 所有玩家
multibank.balance 查看余额 所有玩家
multibank.pay 使用 /pay 所有玩家
multibank.top 查看余额排行榜 所有玩家
multibank.account.create 创建群组账户 所有玩家
multibank.admin 访问管理子命令 仅 OP
multibank.admin.give /mb admin give 仅 OP
multibank.admin.take /mb admin take 仅 OP
multibank.admin.set /mb admin set 仅 OP
multibank.admin.freeze /mb admin freeze 仅 OP
multibank.admin.reload /mb admin reload 仅 OP
multibank.savings 储蓄账户和定期存款 所有玩家
multibank.loan 贷款命令和 GUI 所有玩家
multibank.loan.borrow 借款或接受贷款要约 所有玩家
multibank.loan.lend 发布出借要约 所有玩家
multibank.cert 证书 所有玩家
multibank.state 查看国库和项目 所有玩家
multibank.project.vote 对提议的项目投票 所有玩家
multibank.project.propose 提议项目 所有玩家
multibank.admin.treasury /mb admin treasury 仅 OP
multibank.admin.project /mb admin project 仅 OP
multibank.admin.audit /mb admin audit 仅 OP

节点在启用时于代码中注册。Paper 会忽略 paper-plugin.yml 中的 permissions: 块,且未注册的节点会静默默认为 OP——这导致尽管配置暗示并非如此,multibank.account.create 仍仅限员工(staff)使用。

角色(群组账户)

角色 存入 取出 转账 邀请 踢出 设置角色 重命名 设置主账户 查看
OWNER
MANAGER
MEMBER
VIEWER

Vault 桥接

如果服务器中存在 Vault,MultiBank 会自动注册为 Vault Economy 提供者。这意味着任何使用 Vault Economy API 的插件(商店、拍卖行、工作插件等)都将透明地使用 MultiBank 余额。

工作原理:

  • Economy.getBalance(player) → 读取玩家的个人账户余额
  • Economy.depositPlayer(player, amount) → 存入个人账户(原子操作)
  • Economy.withdrawPlayer(player, amount) → 从个人账户取款(原子操作)
  • Economy.has(player, amount) → 检查个人账户余额
  • Economy.createPlayerAccount(player) → 自动创建带有初始余额的个人账户
  • 银行操作 → 返回 NOT_IMPLEMENTED(请使用 MultiBank 的群组账户)

启动日志:

  • "Vault bridge enabled — MultiBank is now the economy provider." — 成功
  • "Vault not found; bridge disabled." — 服务器上未找到 Vault(这是正常的)

配置: 在 config.yml 中设置 vault.enabled: false 以禁用桥接。

线程安全: 所有 Vault 操作均使用带超时保护的异步数据库调用。该桥接可从任何线程安全调用。

开发者 API

包

pt.henrique.multibank.api.MultiBankApi

事件位于:

pt.henrique.multibank.api.event.*

获取 API

import pt.henrique.multibank.api.MultiBankApi;

// 在你的插件的 onEnable() 中:
MultiBankApi api = getServer().getServicesManager().load(MultiBankApi.class);
if(api ==null){

        getLogger().

        warning("MultiBank not found! Economy features disabled.");
    return;
            }

API 方法

所有方法均返回 CompletableFuture 以支持异步执行。可使用 .thenAccept() / .thenCompose() 进行链式调用以实现非阻塞使用。

账户解析

CompletableFuture<Account> getPersonalAccount(UUID playerId)
CompletableFuture<Optional<Account>> getAccountById(String accountId)
CompletableFuture<List<Account>> listAccounts(UUID playerId)
CompletableFuture<Account> getPrimaryAccount(UUID playerId)
CompletableFuture<Void> setPrimaryAccount(UUID playerId, String accountId)

余额操作

CompletableFuture<Long> getBalanceCents(String accountId)
CompletableFuture<TransactionResult> deposit(String accountId, long cents, String reason, UUID actor)
CompletableFuture<TransactionResult> withdraw(String accountId, long cents, String reason, UUID actor)
CompletableFuture<TransactionResult> transfer(String fromAccountId, String toAccountId, long cents, String reason, UUID actor)

群组管理

CompletableFuture<String> createGroupAccount(UUID owner, String name)
CompletableFuture<Void> inviteMember(String accountId, UUID inviter, UUID target)
CompletableFuture<Void> setMemberRole(String accountId, UUID actor, UUID target, Role role)

安全性

boolean isFrozen(String accountId)

用法示例

// 获取玩家的主账户余额
api.getPrimaryAccount(playerUuid).thenAccept(account -> {
    long cents = account.getBalanceCents();
    getLogger().info("Balance: " + (cents / 100.0));
});

// 存入资金
api.deposit(accountId, 5000L, "Shop purchase refund", actorUuid)
    .thenAccept(result -> {
        if (result.isSuccess()) {
            getLogger().info("Deposit OK, txId=" + result.transaction().txId());
        }
    });

// 在账户间转账(原子操作)
api.transfer(fromId, toId, 10000L, "Trade deal", actorUuid)
    .thenAccept(result -> {
        if (result.isSuccess()) {
            // 转账完成 — 两个余额均已原子更新
        } else {
            // result.status() 告诉你原因:INSUFFICIENT_FUNDS, ACCOUNT_FROZEN 等
        }
    });

// 创建群组账户
api.createGroupAccount(ownerUuid, "My Faction Bank").thenAccept(accountId -> {
    getLogger().info("Created group account: " + accountId);
});

// 检查账户是否被冻结
boolean frozen = api.isFrozen(accountId);

自定义事件

所有事件均位于 pt.henrique.multibank.api.event 包中,并在主服务器线程上触发。

事件 可取消 字段
BalanceChangeEvent accountId, oldBalance, newBalance, amount, actor, reason
TransferEvent fromAccountId, toAccountId, amount, actor, reason
AccountCreateEvent accountId, type, owner, name
PrimaryAccountChangeEvent playerId, oldAccountId, newAccountId
AccountFrozenEvent accountId, frozen, actor
import pt.henrique.multibank.api.event.BalanceChangeEvent;

@EventHandler
public void onBalanceChange(BalanceChangeEvent event) {
  getLogger().info("账户 " + event.getAccountId()
          + " 余额变动了 " + event.getAmount()
          + " 分。原因: " + event.getReason());
}

将 MultiBank 添加为依赖项

在你的插件的 build.gradle.kts 文件中:

repositories {
    // 添加托管 MultiBank 的仓库,或使用本地 jar 文件
}

dependencies {
    compileOnly(files("libs/MultiBank-1.0.0.jar"))
}

在你的 paper-plugin.yml 文件中:

dependencies:
  server:
    MultiBank:
      load: BEFORE
      required: true  # 如果为可选依赖则设为 false
      join-classpath: true

配置

请参阅 plugins/MultiBank/config.yml 以获取所有选项:

部分 键选项
language en_US, pt_PT(或任何自定义语言文件)
starting-balance 新账户的起始资金(默认值:100.00)
currency.* 符号、位置、小数位数、分隔符、名称
database.* sqlite(默认)或带有主机/端口/凭据的 mysql
pay.* 启用/禁用、最小/最大金额、确认阈值
accounts.* 透支、邀请过期时间、最大群组账户数
admin.op-override.* 启用/禁用 OP 覆盖、允许控制台操作、负余额规则
vault.enabled 启用/禁用 Vault 桥接
top.* 模式(personal/all/primary)、每页大小
security.* 速率限制、GUI 防抖

数据库架构

表名 用途
accounts 账户 ID、类型、所有者 UUID、名称、冻结标志、创建时间戳
balances 账户 ID → 以分为单位的余额 (long)
account_members 账户 ID + 成员 UUID + 角色
primary_accounts 玩家 UUID → 其主账户 ID
invites 邀请 ID、账户、目标、邀请人、过期时间
transactions 完整审计日志:交易 ID、时间戳、类型、来源/目标账户、金额、操作者、原因、是否成功
schema_version 迁移记录;升级是累加且幂等的
savings_state 每个账户的累计水位线、低水位余额和已赚利息
interest_accruals 每个 (账户, 周期) 一行,用于贷记 — 储蓄的幂等键
loan_offers 点对点贷款要约及其托管状态
loans 合同:本金、未偿余额、逾期金额、利率、期限、排期位置、状态
loan_charges 每个 (贷款, 周期) 一行,用于扣费 — 分期付款的幂等键
garnishments 从债务人收入中收取的违约余额
credit_profiles 还款记录和信用评分
certificates 订阅的证书和定期存款及其托管情况
cert_accruals 每个 (证书, 周期) 一行,用于累计收益
projects, project_contributions, project_votes 社区项目、贡献和投票

安全说明

  • 原子事务:所有经济操作(存款、取款、转账、设置)均使用数据库事务 —— 无法进行部分更新
  • 防双花:转账操作在一个原子事务中同时扣款和入账两个账户
  • SQLite WAL 模式:已启用,配合忙等待超时以确保并发读写安全
  • 速率限制:可配置每位玩家的操作节流(默认:30次/分钟),防止滥用
  • GUI 防抖:点击防抖(默认:250毫秒)防止双击漏洞利用
  • 冻结账户:在管理员解冻之前,无法发送或接收任何资金
  • 基于 UUID 的身份标识:所有内部操作均使用 UUID —— 从不信任玩家名称
  • 长整型分币存储:余额以 long 类型的分币存储 —— 无浮点数精度问题
  • 交易审计日志:每项操作都会生成唯一的 txId UUID,并记录操作者、原因和时间戳
  • 非负强制:除非启用了 allow-overdraft,否则余额不能为负
  • Vault 超时安全:Vault 桥接操作使用 10 秒超时,以防止服务器挂起
  • 数据库内算术运算:每次余额变更均在 SQL 语句中计算,并在行的写锁保护下进行。如果在 Java 中进行读-改-写,两个线程可能会观察到相同的余额并同时写入 —— 这正是本插件修复的丢失更新重复问题
  • 幂等累积:利息和分期付款通过主键认领其周期,因此调度器误触发、批量追赶或手动重跑只会支付每个周期一次
  • 单调时间:累积水位线按完整周期从其前一个值推进,从不使用墙钟时间;时钟回拨将导致零周期,且追赶逻辑会被限制
  • 承诺前的托管:贷款报价在发布时会借记贷方,因此它绝不可能由已花费的资金支撑,且一个余额不能支撑多个报价
  • 比较并交换合约:接受报价、赎回证书和完成项目都会使行从预期状态翻转;并发尝试只产生一个赢家
  • 防套利验证:如果计息产品的收益高于借贷成本,该配置将在启动时禁用该产品而非被接受,并且持有债务会阻止投资 —— 这也关闭了“向朋友借 0% 贷款”的变体
  • 账目对账:/mb admin audit 检查每个托管账户与其支持的合约,并报告偏差,这是任何重复错误留下的痕迹

从源码构建

从一个源代码树构建两个目标:

git clone <repo-url>
cd MultiBank

./gradlew build                 # 26.3 (默认) — 运行测试套件
./gradlew -Pmc=262 build        # 26.2
./gradlew -Pmc=1211 build       # 1.21.11

输出:build/libs/MultiBank-<version>+mc26.3.jar(或 +mc26.2, +mc1.21.11)。

每个目标均生成 Java 21 字节码。26.x API 编译为 class file 69,只能由 JDK 25 读取,因此需要 JDK 25 工具链;将其放入 /opt/jdk-25 或调整 org.gradle.java.installations.paths。

测试针对真实的 SQLite 数据库检验银行逻辑,包括一个随机化的 400 次操作运行,断言货币供应量永不改变。

要求

  • Paper 或 Purpur 26.3(26.2 对应 2.0.0,1.21.x 对应 1.x)
  • Java 25
  • (可选)VaultUnlocked 用于支持旧版插件经济

许可证

GPL-3.0 — 请参阅 LICENSE。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源