闭源 工具 经济 游戏模式 [MxysjWT]------ 玩家委托任务系统 | Paper 1.21.x | 支持Vault 经济 2026-08-14

插件简介​

在异世界的冒险旅途中，不是每一位玩家都有时间亲自采集、狩猎或寻找稀有材料。

异世界的委托（MxysjWT）让服务器拥有一个真正可用的“冒险者委托公会”。玩家可以发布物品收集委托，其他玩家可以接取并完成委托，从而形成一个自然、活跃、可信赖的玩家交易与任务生态。

发布者只需要手持目标物品，设置数量、报酬和期限，即可把委托发布到委托大厅。接取者支付接取费用后开始执行任务，提交足够物品后即可获得完整委托报酬。完成后的物品会进入发布者的待领取中心，报酬、退款和通知都支持离线持久化。

适用场景：​

- 生存服玩家市场
- RPG 冒险服
- 材料收集任务系统
- 公会、城镇、阵营委托玩法
- 玩家之间的长期经济循环

---

核心特色​

完整 GUI 流程​

玩家无需记忆复杂指令，主要操作均可通过 GUI 完成：
委托大厅、发布委托、发布确认、委托详情、接取确认、我的发布、我的接取、待领取中心、管理后台。
所有按钮、标题、Lore 和提示文本均可在语言文件中自定义。

安全的报酬托管​

发布委托时，系统会通过 Vault 扣除发布者设置的完整报酬，并由插件托管：
- 完成委托：报酬支付给接取者
- 委托过期：报酬退还给发布者
- 支付失败：进入待领取余额
- 玩家离线：不会丢失报酬
- 服务器重启：委托状态继续保留

接取费用机制​

接取者接受委托时需要支付一笔接取费用，默认是委托报酬的 10%。该费用可在界面中显示为“接取押金”，但业务上属于系统收取的接取费用，任何情况下均不退还。插件会在 Lore、聊天消息和确认界面中明确提示，避免玩家误解。

精准物品匹配​

插件支持两种物品匹配模式：
- EXACT：完整匹配物品，包括名称、Lore、附魔、耐久、CustomModelData、ItemMeta 等
- MATERIAL：只匹配物品类型
适合从普通材料收集，到定制装备、RPG 道具、特殊材料的多种玩法。

离线通知与待领取中心​

玩家不在线时也不会错过重要信息：
委托完成通知、委托过期通知、待领取物品通知、待领取余额通知、退款通知。
玩家上线后，插件会自动补发离线通知，并支持分批发送，避免刷屏。

过期自动结算​

插件会定时扫描过期委托，也会在玩家查看、接取、提交时即时检查期限：
- OPEN 状态过期：报酬退回发布者
- ACCEPTED 状态过期：报酬退回发布者
- 接取费用不退还
- 多次扫描不会重复退款

防刷与事务安全​

插件针对常见刷物品、刷钱和重复点击问题做了多重防护：
- 同一委托只能被一名玩家接取
- 重复提交不会重复发放报酬
- 重复点击不会重复扣款
- 物品不足时不会扣除任何物品
- 背包空间不足时不会丢失物品
- 数据库异常时保留审计记录
- 经济支付失败时转入待领取余额

---

插件信息​

插件内部名：MxysjWT
玩家显示名：异世界的委托
主指令：/wt
权限前缀：mxysjwt
推荐权限组名：MxysjWT
Java 版本：Java 21
服务端：Paper 1.21.x
经济依赖：Vault + Vault 兼容经济插件
数据库：SQLite / MySQL / MariaDB
是否使用 NMS：否
是否需要材质包：否

前置插件​

必装：
- Vault
- 任意 Vault 兼容经济插件，例如 EssentialsX Economy、CMI Economy、XConomy、PlayerPoints 兼容桥接方案或其他支持 Vault Economy 的经济插件。

可选：
- LuckPerms（用于管理权限组和玩家权限，插件本身不强制依赖）

数据库
默认使用 SQLite，无需额外数据库。如果服务器规模较大，建议使用 MySQL 或 MariaDB。

---

安装教程​

1. 安装前置
请先确认服务器已安装 Vault 以及一个 Vault 兼容经济插件。如果使用权限组管理，推荐安装 LuckPerms。

2. 放入插件
将插件文件放入服务器目录：plugins/MxysjWT.jar

3. 启动服务器
首次启动后，插件会自动生成配置文件：
plugins/MxysjWT/config.yml
plugins/MxysjWT/lang.yml
以及默认 SQLite 数据库文件。

4. 修改配置
根据服务器需求修改 config.yml 和 lang.yml。修改完成后可执行 /wt reload。
注意：数据库类型、数据库地址等连接配置通常需要重启服务器后生效。

5. 设置权限
如果使用 LuckPerms，可以创建玩家权限组：
/lp creategroup MxysjWT
/lp group MxysjWT permission set mxysjwt.user true
给玩家加入该组：
/lp user <玩家名> parent add MxysjWT
管理员权限：
/lp group admin permission set mxysjwt.admin true

---

玩家使用教程​

发布委托：
1. 将目标物品拿在主手
2. 输入 /wt create
3. 在 GUI 中设置所需数量、委托报酬和截止期限
4. 点击确认发布
5. 系统扣除并托管委托报酬
6. 委托进入委托大厅

接取委托：
1. 输入 /wt hall
2. 浏览委托大厅
3. 点击感兴趣的委托查看详情
4. 确认报酬、期限和接取费用
5. 点击确认接取
6. 系统扣除接取费用
7. 开始收集目标物品
注意：接取费用由系统收取，任何情况下均不退还。

提交委托：
当背包内拥有足够目标物品后，输入 /wt tj，或进入 /wt my 在“我的接取”中点击提交。
提交成功后：
- 目标物品会从接取者背包中扣除
- 委托报酬会支付给接取者
- 物品会进入发布者待领取中心

领取物品和余额：
输入 /wt claim 可以打开待领取中心，领取已完成委托的物品、离线期间获得的余额、支付失败暂存的报酬和过期退款。

---

指令列表​

玩家指令：​

管理员指令：​

权限节点​

mxysjwt.user - 普通玩家基础权限 - 默认：true
mxysjwt.command.open - 使用 /wt - 默认：true
mxysjwt.command.hall - 查看委托大厅 - 默认：true
mxysjwt.command.create - 发布委托 - 默认：true
mxysjwt.command.my - 查看自己的委托 - 默认：true
mxysjwt.command.submit - 提交委托 - 默认：true
mxysjwt.command.claim - 领取物品和余额 - 默认：true
mxysjwt.admin - 管理员总权限 - 默认：op
mxysjwt.admin.reload - 重载配置 - 默认：op
mxysjwt.admin.info - 查看委托详情 - 默认：op
mxysjwt.admin.forceexpire - 强制过期 - 默认：op
mxysjwt.admin.recover - 恢复异常委托 - 默认：op
mxysjwt.admin.debug - 查看调试状态 - 默认：op
mxysjwt.bypass.publishlimit - 绕过发布上限 - 默认：op
mxysjwt.bypass.acceptlimit - 绕过接取上限 - 默认：op

---

配置亮点​

管理员可以在 config.yml 中调整：
- 每名玩家最多发布多少委托
- 每名玩家最多接取多少委托
- 接取费用比例
- 最低接取费用
- 货币小数位
- 期限范围
- 过期扫描周期
- 即将过期提醒时间
- 物品匹配模式
- 是否检查装备栏
- 是否检查副手
- 是否自动发放待领取余额
- GUI 分页大小
- 点击防抖时间
- 离线通知批量发送间隔
- 聊天、Title、Subtitle、声音反馈

语言文件 lang.yml 支持完整中文自定义，适合不同服务器世界观。

---

数据库说明

插件默认使用 SQLite，开箱即用。默认数据目录：plugins/MxysjWT/

- 小型服务器推荐使用 SQLite
- 中大型服务器建议使用 MySQL 或 MariaDB，以获得更好的并发性能和运维能力

插件会保存：
- 委托数据
- 待领取物品
- 待领取余额
- 交易流水
- 离线通知
- 审计日志
- 数据库版本信息

建议服主定期备份数据库文件或远程数据库。

---

开发者 API​

（如果您的插件尚未实现 API，请跳过此段，不要放入商店页面以避免买家误解。）

Maven / Gradle 引入（Kotlin）：
repositories {
maven("https://your.repo.url/releases")
}
dependencies {
compileOnly("com.mxysj:MxysjWT:你的版本号")
}

获取 API：
MxysjWTApi api = Bukkit.getServicesManager().load(MxysjWTApi.class);
示例：查询玩家未完成委托数量
UUID playerId = player.getUniqueId();
api.getActivePublishedCount(playerId).thenAccept(count -> {
player.sendMessage("你当前有 " + count + " 个未完成委托。");
});

示例：监听委托完成事件
@EventHandler
public void onCommissionComplete(CommissionCompleteEvent event) {
UUID publisher = event.getPublisherId();
UUID acceptor = event.getAcceptorId();
long commissionId = event.getCommissionId();
}

建议公开的 API 能力：​

- 查询委托
- 查询玩家发布数量
- 查询玩家接取数量
- 查询待领取余额
- 监听委托发布事件
- 监听委托接取事件
- 监听委托完成事件
- 监听委托过期事件
- 监听待领取物品创建事件

---

常见问题​

Q：玩家离线时完成委托会丢东西吗？
A：不会。接取者提交成功后，目标物品会进入发布者的待领取中心。发布者上线后可以领取，并会收到离线通知。

Q：经济插件支付失败怎么办？
A：如果 Vault 支付失败，金额会进入玩家的待领取余额，玩家可以稍后手动领取。

Q：接取费用会返还吗？
A：不会。接取费用由系统收取，任何情况下均不退还。插件会在接取确认界面和提示中明确说明。

Q：服务器重启会导致委托失效吗？
A：不会。委托、期限、状态、待领取物品和待领取余额都会持久化保存。

Q：可以发布自定义物品吗？
A：可以。EXACT 模式会尽可能完整匹配物品元数据，适合 RPG 道具和自定义物品。

Q：可以只按物品类型匹配吗？
A：可以。将物品匹配模式设置为 MATERIAL 即可。