龙核交易系统 LyDragonTrade

LyDragonTrade 是基于 DragonCore 交易界面的 Minecraft 玩家交易插件。玩家可以向其他在线玩家发起交易申请，双方在交易界面中交换物品和货币，分别锁定后进入倒计时，倒计时结束后完成交易。

插件通过 Bukkit/Paper 服务运行，交易界面和交易申请界面依赖 DragonCore。项目构建目标为 Java 8 和 paper-api:1.16.5-R0.1-SNAPSHOT。

基本信息

项目	内容
插件名	LyDragonTrade
中文名	龙核交易系统
作者	离渊
插件版本	1.0.7
主插件指令	/ldt
构建目标	Java 8、Paper API 1.16.5-R0.1-SNAPSHOT
配置文件	plugins/LyDragonTrade/config.yml
交易界面	DragonCore 自定义界面

依赖与兼容

必需组件

组件	作用
DragonCore	提供交易申请界面、交易界面和自定义数据包交互。

DragonCore 未启动时，插件会在控制台提示前置未启动，交易监听功能不会正常工作。

可选组件

组件	作用
Vault	提供“金币”货币的余额查询、扣除和发放。
PlayerPoints	提供“点券”货币的余额查询、扣除和发放。
LyShopReload	提供 LyShopReload#货币ID 格式的自定义货币。配置注释注明需要 LyShopReload 1.0.2 或更高版本。
CraftX	提供 CX#货币ID 格式的自定义变量货币。
TQBindReload	在启用 tqbind-enable 且该插件已启动时，执行交易后的物品绑定处理。配置注释要求使用最新版。
PlaceholderAPI	注册 LyDragonTrade 的交易相关变量。

Vault、PlayerPoints、LyShopReload 和 PlaceholderAPI 均属于软依赖。对应组件未启动时，相关货币或变量功能不能使用。

主要功能

功能	说明
玩家交易申请	使用 /ldt trade 玩家名 向指定在线玩家发起交易。
Shift 右键发起	可通过 shift-right-initiate-trade 控制 Shift 右键其他玩家发起交易。
申请倒计时	交易申请创建后，双方界面会显示接受倒计时；超时后申请自动拒绝。
交易申请界面	DragonCore 界面提供接受和拒绝交易操作。
双方交易界面	交易容器固定为 18 个槽位，双方各使用 9 个交易槽位。
物品交换	双方可以在各自的 9 个交易槽位中放入物品，完成交易后物品交给对方。
货币交易	支持金币、点券、LyShopReload 自定义货币和 CraftX 自定义变量货币。
交易税率	可以按照接收方权限匹配货币到账比例；未匹配到权限时默认按 100% 到账。
双方锁定	双方确认后分别锁定，锁定期间不能修改自己的交易物品。
完成倒计时	双方完全锁定后进入倒计时，倒计时结束后结算物品和货币。
交易取消返还	交易界面关闭或倒计时被中断时，已放入交易界面的物品会返还。
交易限制	支持交易距离、世界限制、发起冷却、目标繁忙检查和重复申请检查。
物品限制	可禁止包含指定 Lore 文本的物品进入交易槽位。
背包空间检查	确认交易时检查对方背包剩余空间是否足够接收物品。
交易记录	启用后，交易完成时在控制台输出双方获得的物品和货币。
交易音效	收到交易申请时可播放指定 Bukkit 音效。

交易机制

发起交易

交易申请需要满足以下条件：

• 目标玩家在线，且不能是发起者本人。
• 发起者和目标玩家不处于其他交易申请中。
• 当前世界名称不包含 anti-trade-world 中的任意文本。
• 满足 trade-distance 对世界和距离的限制。
• 发起者不处于 initiate-trade-cool-down 冷却时间内。

申请创建后，双方会收到提示，目标玩家打开 DragonCore 申请界面，并播放 initiated-trade-sound 指定的音效。

接受与拒绝

目标玩家可以在申请界面中接受或拒绝交易。申请倒计时由 receive-trade-count-down 控制，倒计时结束后会自动拒绝申请。

接受申请后，双方进入固定 18 槽交易容器：

• 发起者使用第 0 至 8 槽。
• 接收者使用第 9 至 17 槽。

交易界面会限制双方操作对方的交易槽位，也会拦截不符合规则的拖拽和 Shift 点击操作。

锁定与结算

双方点击确认后，插件会检查：

• 对方背包剩余空间是否足够接收物品。
• 输入的货币是否为有效整数值。
• 发起者当前货币余额是否足够。
• 交易涉及的货币组件是否能够正常提供余额查询和扣款。

检查通过后，玩家进入锁定状态。双方都锁定后开始 trade-count-down 倒计时。倒计时结束后，插件按以下顺序完成结算：

1. 将双方交易槽位中的物品交给对方。
2. 根据货币类型扣除付款方货币。
3. 按接收方权限匹配税率后发放货币。
4. 输出交易记录（如果启用 log-trade-info）。
5. 向双方发送交易成功提示并关闭交易界面。

交易尚未完成时关闭界面，会取消交易并将已放入的物品返还给原持有者。

支持的货币

配置键格式	货币类型	需要的组件	说明
金币	Vault 经济	Vault 及可用的 Vault Economy 服务	使用 Vault 查询、扣除和发放余额。
点券	PlayerPoints 点券	PlayerPoints	使用 PlayerPoints 查询、扣除和发放点券。
LyShopReload#货币ID	LyShopReload 自定义货币	LyShopReload	货币ID 替换为 LyShopReload 中实际存在的货币 ID。
CX#货币ID	CraftX 自定义变量	CraftX	使用 CraftX 变量值作为货币余额。

货币输入框需要同时配置在 currency-textbox 中，并在 DragonCore 交易界面中提供对应的输入框和刷新逻辑。货币实际结算只处理项目代码支持的上述格式。

指令

指令	执行者	说明
/ldt trade <玩家名>	玩家	向指定在线玩家发起交易。不能向自己发起交易。
/ldt reload	OP	重载 config.yml。
/ldt	OP	显示插件帮助；验证完成后显示服务端交易指令。

插件没有在 plugin.yml 中声明独立的命令权限节点。指令执行限制由玩家身份和 OP 状态控制。

配置概览

配置文件为 plugins/LyDragonTrade/config.yml，完整配置说明请查看配置说明。

交易界面与货币

配置键	作用
gui-title	Bukkit 交易容器标题，需要与 DragonCore 配置中的 match 保持一致。
currency-textbox	将货币名称映射到对方货币输入框组件。
currency-tax	按货币和权限配置接收方到账比例。

交易槽位固定为 9 个，不能通过配置扩展。交易容器总共使用 18 个槽位，双方各占 9 个槽位。

交易开关与限制

配置键	作用
tqbind-enable	是否启用 TQBindReload 的交易后绑定处理。
log-trade-info	是否在交易完成时向控制台输出交易内容。
initiated-trade-sound	收到交易申请时播放的 Bukkit 音效名称。
anti-trade-for-contain-lore-item	包含指定 Lore 文本的物品禁止交易。
trade-count-down	双方完全锁定后的交易完成倒计时，单位为秒。
receive-trade-count-down	交易申请等待接受的倒计时，单位为秒。
initiate-trade-cool-down	发起交易后的冷却时间，单位为秒。
anti-trade-world	世界名称包含任意列表文本时禁止发起交易。
trade-distance	控制交易所需的同世界和距离条件。
shift-right-initiate-trade	是否启用 Shift 右键玩家发起交易。

trade-distance 的取值规则如下：

值	规则
小于 0	不限制世界和交易距离。
等于 0	必须在同一世界，不限制距离。
大于 0	必须在同一世界，且双方距离不能超过该数值。

消息

所有玩家提示位于 message 节点下。消息中的 & 颜色代码会转换为 Minecraft 颜色代码。部分消息支持以下占位文本：

占位文本	用途
{player}	替换为相关玩家名称。

PlaceholderAPI 变量

PlaceholderAPI 扩展标识符为 ldt，完整变量说明请查看插件变量。

变量	返回内容
%ldt_trade_player_name%	当前交易中的对方玩家名称；没有进行交易时返回空字符串。
%ldt_trade_player_uuid%	当前交易中的对方玩家 UUID；没有进行交易时返回空字符串。
%ldt_apply_player_name%	当前收到的交易申请的发起者名称；没有待处理申请时返回空字符串。
%ldt_apply_player_uuid%	当前收到的交易申请的发起者 UUID；没有待处理申请时返回空字符串。

这些变量只在 PlaceholderAPI 已启动并成功注册 LyDragonTrade 扩展时可用。

API 与事件

TradeAPI

插件提供 TradeAPI 接口，当前接口包含一个交易申请方法：

void tryInitiateTrade(Player p, Player t);

方法	说明
tryInitiateTrade(Player p, Player t)	按插件当前交易限制，尝试让玩家 p 向玩家 t 发起交易。

插件启用并完成核心初始化后，可通过插件实例获取该 API。具体接口定义位于 Ly.dragon.trade.client.plugin.api.event.TradeAPI。

TradeStartEvent

项目提供 TradeStartEvent Bukkit 事件类，包含以下方法：

方法	说明
setCancelled(boolean cancelled)	设置事件取消状态。
getCancelled()	获取事件取消状态。
getHandlers()	返回 Bukkit 事件处理器列表。
getHandlerList()	返回静态 Bukkit 事件处理器列表。

项目证据中未显示该事件在交易流程中被主动调用，因此不能据此确认它会在交易开始时自动触发。

DragonCore 资源

DragonCore 交互通过以下自定义界面标识和数据包标识完成：

标识	用途
LyDragonTrade_Apply	交易申请界面。
LyDragonTrade_Gui	交易主界面。
LyDragonTradeApply	处理接受或拒绝交易申请的数据包。
LyDragonTrade	处理交易初始化、货币刷新和确认交易的数据包。

配置中的 gui-title 必须与 DragonCore 交易界面的 match 保持一致。DragonCore 界面还需要提供项目代码调用的组件和方法，例如交易倒计时、锁定幕布、确认按钮以及货币输入框对应组件。资源文件的具体放置方式请查看龙核资源。

常见问题

交易指令没有反应

检查以下内容：

• 目标玩家是否在线。
• 是否向自己发起交易。
• 目标玩家是否已经处于其他交易申请或交易中。
• 当前世界是否命中 anti-trade-world。
• trade-distance 是否限制了当前世界或距离。
• 发起者是否仍处于 initiate-trade-cool-down 冷却时间内。

交易界面没有打开

确认 DragonCore 已启动，并检查 DragonCore 是否加载了 LyDragonTrade_Apply 和 LyDragonTrade_Gui 对应界面。插件启动时会在控制台提示 DragonCore 的启动状态。

货币输入后没有同步

确认货币名称已经配置在 currency-textbox 中，并且 DragonCore 界面使用的输入框组件名称与配置值一致。货币刷新数据包使用货币名称、输入值和配置中的输入框映射进行同步。

点击确认时提示货币不足

确认对应货币组件已启动，并检查玩家余额。插件支持的货币格式为 金币、点券、LyShopReload#货币ID 和 CX#货币ID。输入值必须是有效的货币整数。

交易完成后到账数量少于输入数量

检查 currency-tax 中接收方拥有的权限。匹配到的税率会作为到账比例；没有匹配到任何权限时，默认按 1.0 结算。

交易物品无法放入

可能原因包括：

• 物品 Lore 命中了 anti-trade-for-contain-lore-item。
• 当前玩家已经锁定交易。
• 尝试操作了对方的交易槽位。
• 目标玩家背包空间不足。
• 拖拽或 Shift 点击操作不符合交易界面的槽位限制。

交易中途关闭界面后物品去哪了

交易未完成时关闭交易界面会取消交易，交易槽位中的物品会返还给原持有者。只有双方锁定后倒计时完成，交易才会进入成功结算状态。

文档索引

页面	内容
配置说明	交易限制、货币输入框、税率和提示文本。
插件变量	交易对方和交易申请发起者相关变量。
龙核资源	DragonCore 界面标识、组件匹配和交互所需资源。
常见问题	交易申请、界面、货币和物品异常的排查。