UltiTrade - 玩家交易系统
安全的玩家间交易模块，支持物品、金币和经验交换，具备双方确认机制、BossBar 倒计时、交易日志、玩家黑名单和 PlaceholderAPI 集成。
功能概述
UltiTrade 为 Minecraft 服务器提供完整的玩家间交易功能。两名玩家通过命令或 Shift+右键点击对方发起交易请求，对方在聊天中收到可点击的 [接受]/[拒绝] 按钮，同时屏幕顶部出现 BossBar 倒计时。接受后双方各自打开一个 54 格的交易界面（GUI），左侧放自己要交出的物品，右侧实时显示对方放入的物品。除了物品交换，还支持金币交易（需要 Vault 插件）和经验值交易，点击 GUI 中的金币/经验图标在聊天中输入数额即可。双方都确认后交易自动完成，物品、金币和经验同步交换。如果涉及大额金币或经验（超过可配置的阈值），系统会弹出一个额外的确认界面，防止误操作。所有完成和取消的交易都会记录到数据库中，过期日志自动清理。每位玩家可以单独开关自己的交易功能，也可以将特定玩家加入黑名单拒绝交易请求。
安装
有两种安装方式：
方式一：通过 UPM 在线安装
/upm install UltiTrade方式二：手动安装
- 安装前置插件：
- UltiTools-API 6.2.0+（必需）
- Vault（金币交易需要，可选）
- PlaceholderAPI（交易统计变量，可选）
- 将
UltiTrade.jar放入plugins/UltiTools/plugins/目录 - 重启服务器
安装完成后，配置文件会自动生成在 plugins/UltiTools/UltiTrade/config/trade.yml。
快速开始
安装完成后，任何有 ultitrade.use 权限的玩家都可以交易。最简单的使用方式：
/trade Steve # 向玩家 Steve 发起交易请求Steve 会在聊天中看到可点击的 [接受]/[拒绝] 按钮。接受后双方打开交易界面：
- 在左侧的绿色区域放入你想交出的物品
- 点击左下角的金币图标输入要交易的金币数额
- 点击左下角的经验瓶图标输入要交易的经验值
- 右侧显示对方放入的物品、金币和经验
- 确认无误后点击底部的"确认交易"按钮
- 双方都确认后交易自动完成
快捷方式：按住 Shift 键右键点击另一名玩家，也可以直接发起交易请求。
命令
所有命令的别名为 /trade 和 /t，权限节点统一为 ultitrade.use。所有命令仅限玩家使用（不支持控制台）。
| 命令 | 说明 | 示例 |
|---|---|---|
/trade <玩家名> | 向指定玩家发起交易请求。如果对方已经向你发送了请求，会自动匹配并开始交易 | /trade Steve |
/trade accept | 接受收到的交易请求 | /trade accept |
/trade deny | 拒绝收到的交易请求 | /trade deny |
/trade cancel | 取消当前正在进行的交易，物品会退回 | /trade cancel |
/trade toggle | 开启或关闭自己的交易功能。关闭后其他玩家无法向你发送交易请求 | /trade toggle |
/trade block <玩家名> | 将指定玩家加入交易黑名单，该玩家将无法向你发送交易请求（玩家必须在线） | /trade block Griefer123 |
/trade unblock <玩家名> | 将指定玩家从交易黑名单中移除（玩家必须在线） | /trade unblock Griefer123 |
配置文件
配置文件路径：plugins/UltiTools/UltiTrade/config/trade.yml
# ==================== 基础设置 ====================
request-timeout: 30 # 交易请求超时时间（单位：秒，范围：5-600）
trade-timeout: 120 # 交易窗口超时时间（单位：秒，范围：30-600）
max-distance: 50 # 交易最大距离（单位：格，范围：0-1000，0 表示无限制）
allow-cross-world: false # 是否允许跨世界交易
# ==================== 交易功能 ====================
enable-money-trade: true # 启用金币交易（需要 Vault 插件）
enable-exp-trade: true # 启用经验交易
enable-shift-click: true # 启用 Shift+右键点击玩家发起交易
# ==================== 税收设置 ====================
trade-tax: 0.0 # 金币交易税率（范围：0-1，0 表示不收税，0.05 表示 5%）
exp-tax-rate: 0.0 # 经验交易税率（范围：0-1，0 表示不收税）
# ==================== 确认设置 ====================
confirm-threshold: 10000 # 大额交易确认阈值（金币或经验超过此值需要二次确认）
# ==================== 日志设置 ====================
enable-trade-log: true # 启用交易日志记录
log-retention-days: 30 # 日志保留天数（范围：1-365）
cleanup-interval-hours: 24 # 日志清理间隔（单位：小时，范围：1-168）
# ==================== 效果设置 ====================
enable-sounds: true # 启用交易音效（发送请求、接受、完成、取消等）
enable-particles: true # 启用交易粒子效果（完成/取消时的视觉反馈）
enable-bossbar: true # 启用 BossBar 请求倒计时（收到请求时屏幕顶部的进度条）
enable-clickable-buttons: true # 启用可点击的聊天按钮（收到请求时的 [接受]/[拒绝]）
# ==================== GUI 设置 ====================
gui-title: "&6与 {PLAYER} 交易" # 交易界面标题（{PLAYER} 会替换为对方玩家名）
# ==================== 消息设置 ====================
messages:
request-sent: "&a已向 &f{PLAYER} &a发送交易请求！"
request-received: "&e{PLAYER} &f请求与你交易！输入 /trade accept 接受"
request-timeout: "&c交易请求已超时！"
trade-complete: "&a交易完成！"
trade-cancelled: "&c交易已取消！"
trade-disabled: "&c对方已关闭交易功能！"
player-blocked: "&c对方已将你加入黑名单！"
toggle-on: "&a你已开启交易功能！"
toggle-off: "&c你已关闭交易功能！"
block-success: "&a已将 {PLAYER} 加入交易黑名单！"
unblock-success: "&a已将 {PLAYER} 移出交易黑名单！"
already-blocked: "&c{PLAYER} 已在你的黑名单中！"
not-blocked: "&c{PLAYER} 不在你的黑名单中！"消息占位符说明
| 占位符 | 说明 |
|---|---|
{PLAYER} | 对方玩家名 |
使用教程
场景一：基础物品交易
玩家 A 想用 10 个钻石跟玩家 B 换一把附魔钻石剑：
- 玩家 A 执行
/trade B（或按住 Shift 右键点击 B） - 玩家 B 在聊天中点击绿色的 [接受] 按钮
- 交易界面打开，玩家 A 在左侧区域放入 10 个钻石
- 玩家 B 在左侧区域放入附魔钻石剑
- 双方可以在右侧看到对方放入的物品（悬浮可查看附魔、耐久等详情）
- 双方分别点击"确认交易"
- 交易完成，物品互换
场景二：金币交易
如果你的服务器安装了 Vault 经济插件，可以交易金币：
- 发起交易并打开交易界面
- 点击左下角的金币图标（金粒）
- 在聊天中输入金额，例如
5000（输入cancel取消） - 金额会显示在 GUI 中
- 如果配置了税率，GUI 中会显示税金和对方实际收到的金额
场景三：经验交易
- 在交易界面中点击左下角的经验瓶图标
- 系统会提示你当前拥有的总经验值
- 在聊天中输入要交易的经验值
- 确认无误后确认交易
场景四：大额交易确认
当交易中涉及的金币或经验总额超过配置的 confirm-threshold（默认 10000）时：
- 点击"确认交易"后会自动弹出确认界面
- 确认界面显示完整的交易摘要：你给出/收到的物品、金币、经验，以及税金明细
- 点击绿色"确认交易"完成确认
- 点击红色"取消"返回交易界面（不会取消整个交易）
- 双方都在确认界面确认后交易才会完成
场景五：管理黑名单
如果某个玩家经常骚扰你发交易请求：
/trade block Griefer123 # 把这个玩家加入黑名单
/trade unblock Griefer123 # 以后想移除可以这样被加入黑名单的玩家向你发起交易时会看到"对方已将你加入黑名单"的提示。
如果你暂时不想接收任何人的交易请求：
/trade toggle # 关闭交易功能
/trade toggle # 再次执行开启交易功能场景六：设置交易税
服务器腐竹想收取 5% 的金币交易税和 3% 的经验交易税：
trade-tax: 0.05 # 5% 金币税
exp-tax-rate: 0.03 # 3% 经验税税金在交易完成时自动扣除。例如玩家 A 给出 1000 金币，税金 50，玩家 B 实际收到 950 金币。
场景七：禁止跨世界交易
如果你不希望不同世界的玩家交易：
allow-cross-world: false # 禁止跨世界
max-distance: 50 # 最大 50 格距离PlaceholderAPI 变量
安装 PlaceholderAPI 后可以使用以下变量（标识符前缀为 ultitrade）：
| 变量 | 说明 | 示例输出 |
|---|---|---|
%ultitrade_total_trades% | 玩家完成的总交易次数 | 42 |
%ultitrade_total_money% | 玩家交易过的总金额（给出） | 15000.00 |
%ultitrade_total_exp% | 玩家交易过的总经验值（给出） | 8500 |
%ultitrade_trade_enabled% | 玩家的交易功能是否开启 | true / false |
%ultitrade_enabled_display% | 交易功能状态（中文显示） | 开启 / 关闭 |
%ultitrade_is_trading% | 玩家是否正在交易中 | true / false |
%ultitrade_last_trade_time% | 上次交易时间 | 2026-02-13 14:30 |
%ultitrade_last_trade_ago% | 距离上次交易多久 | 3天前 / 2小时前 / 刚刚 |
%ultitrade_blocked_count% | 黑名单中的玩家数量 | 2 |
常见问题
1. 安装后不生效怎么办？
检查以下几点：
- 确认 JAR 文件放在了
plugins/UltiTools/plugins/目录（不是plugins/根目录） - 确认服务器安装了 UltiTools-API 6.2.0 或更高版本
- 重启服务器（不是
/ul reload，新模块需要完整重启） - 查看控制台是否有 "UltiTrade 已启用！" 日志
- 如果金币交易不工作，检查是否安装了 Vault 和一个经济插件（如 EssentialsX）
2. 改了配置文件没效果？
保存配置文件后，使用 /ul reload 命令重载配置。注意检查 YAML 格式是否正确（缩进必须用空格，不能用 Tab）。消息和配置数值的修改在重载后立即生效。
3. 权限怎么设置？
UltiTrade 只有一个权限节点 ultitrade.use，控制所有 /trade 命令的使用权限，以及 Shift+右键快捷交易。使用 LuckPerms 等权限插件设置：
/lp group default permission set ultitrade.use true建议给所有普通玩家组开放此权限，让大家都能交易。
4. 金币交易显示"未启用"怎么办？
金币交易需要两个前置条件：
- 安装 Vault 插件
- 安装一个实际提供经济功能的插件（如 EssentialsX、CMI 等）
只安装 Vault 但没有经济插件是不行的。
5. 交易时关闭界面会怎样？
关闭交易界面（按 Esc 或打开其他界面）会自动取消交易。你放入交易界面的物品会退回到你的背包。如果背包满了，物品会掉落在你脚下。
6. 一方离线了会怎样？
交易进行中如果一方离线，交易会自动取消。双方放入的物品都会退回（在线玩家退回背包，离线玩家的物品退回背包或掉落在离线前的位置）。金币和经验只在交易完成时才会实际转移。
7. 交易日志存在哪里？
交易日志通过 UltiTools-API 的 DataOperator 存储，具体位置取决于 UltiTools 的存储配置（默认 SQLite 数据库在 plugins/UltiTools/ 目录下）。日志会按 log-retention-days 配置自动清理过期记录。
更新日志
v1.0.0 (2026-02-13)
初始发布。
新增：安全的双方确认交易机制 新增：GUI 交易界面（54 格大箱子布局，左侧放入/右侧预览） 新增：金币交易功能（需要 Vault），支持交易税 新增：经验值交易功能，支持经验税 新增：BossBar 倒计时显示交易请求剩余时间 新增：聊天中可点击的 [接受]/[拒绝] 按钮 新增：Shift+右键点击玩家快捷发起交易 新增：大额交易二次确认界面（金币或经验超过阈值） 新增：玩家交易开关（/trade toggle） 新增：玩家黑名单功能（/trade block、/trade unblock） 新增：交易日志记录（完成和取消的交易都记录），自动清理过期日志 新增：交易统计（总交易次数、总金额、总经验、上次交易时间） 新增：PlaceholderAPI 集成（9 个变量） 新增：交易音效反馈（发送请求、接受、物品放入、完成、取消） 新增：交易粒子特效（完成时绿色粒子，取消时烟雾粒子） 新增：物品详情悬浮预览（对方物品显示附魔、耐久度、物品标志等） 新增：交易距离限制和跨世界交易控制 新增：双方互发请求时自动匹配开始交易 新增：所有消息可自定义，支持颜色代码
贡献者
Ling Bao
Claude Opus 4.6