龙核资源

LyDragonTrade 使用 DragonCore 提供交易申请弹窗和双人交易界面。玩家发起交易后，接收方会看到申请弹窗；接受申请后，双方进入同一个 18 格交易容器，每人可操作其中 9 个交易槽位，并可通过界面输入货币数量、锁定交易和查看完成倒计时。

申请界面和交易主界面均依赖 DragonCore 发包交互。界面文件、组件名称、发包标识或界面标题不匹配时，可能出现按钮无效、货币不同步、锁定状态不显示或倒计时不刷新等问题。

依赖说明

依赖	类型	用途
DragonCore	必需	加载申请弹窗、交易主界面，并处理客户端发包与服务端界面控制。
PlaceholderAPI	可选	在 DragonCore 界面中显示申请者、交易对象的名称与 UUID。
Vault	按需安装	使用金币交易时提供经济账户操作。
PlayerPoints	按需安装	使用点券交易时提供点券账户操作。
LyShopReload	按需安装	使用 LyShopReload#货币ID 格式的自定义货币时提供货币操作。
CraftX	按需安装	使用 CX#货币ID 格式的变量货币时提供货币操作。
TQBindReload	按需安装	启用交易后绑定功能时，对成交物品执行绑定。

插件只有在检测到 DragonCore 已启用后，才会注册交易界面、发包、背包操作和 Shift + 右键交易监听器。若控制台提示 DragonCore 未启动，龙核交易功能不会生效。

文件放置

压缩包目录	放置位置	说明
Gui/*.yml	plugins/DragonCore/Gui/	服务端 DragonCore 界面配置。
离渊/交易/	客户端 DragonCore 资源目录	交易界面使用的客户端贴图资源。

资源包中标注的 1.0.3 版本包含申请界面更新，并移除了通过 ESC 关闭申请弹窗的逻辑。建议优先使用压缩包内配套的 DragonCore 文件，不要混用不同版本的界面配置。

服务端界面文件

文件	界面标识	说明
LyDragonTrade_Apply.yml	LyDragonTrade_Apply	交易申请弹窗，显示申请者、申请倒计时以及接受、拒绝按钮。
LyDragonTrade_Gui.yml	LyDragonTrade_Gui	交易主界面，显示双方交易槽、货币输入框、锁定状态、完成倒计时和玩家背包。

文件名和界面标识会被插件直接用于打开界面或执行 DragonCore 方法，不建议修改。若必须改名，需要同步修改插件端调用；仅修改 YAML 文件名无法完成适配。

标题匹配

交易主界面默认匹配标题为 离渊交易，必须与插件 config.yml 中的 gui-title 保持一致：

gui-title: '离渊交易'

交易容器由插件创建，固定为 18 格。DragonCore 根据容器标题套用 LyDragonTrade_Gui.yml。如果 match 与 gui-title 不一致，玩家可能只会看到原版箱子界面，龙核按钮、文本框和状态显示也不会正常工作。

申请弹窗

发起交易后，插件会为接收方打开 LyDragonTrade_Apply HUD，并播放 initiated-trade-sound 配置的音效。申请倒计时由 receive-trade-count-down 控制，插件每秒更新一次 文本_交易倒计时 组件。

申请到期后会自动按拒绝处理，并关闭申请界面。接受申请后，插件会关闭双方当前容器，创建交易容器并为双方打开交易主界面。

申请界面变量

申请者信息需要 PlaceholderAPI 扩展支持。

变量	返回内容	可用对象
%ldt_apply_player_name%	当前交易申请发起者的玩家名。	接收交易申请的玩家。
%ldt_apply_player_uuid%	当前交易申请发起者的 UUID。	接收交易申请的玩家。

没有对应申请数据、变量调用者不是接收方或 PlaceholderAPI 未启用时，变量返回空文本。

申请弹窗发包

发包标识必须为 LyDragonTradeApply，第一个数据参数用于表示操作。

操作	发包标识	数据参数	原页面写法
接受交易	LyDragonTradeApply	接受交易	LyDragonTradeApply / 接受交易
拒绝交易	LyDragonTradeApply	拒绝交易	LyDragonTradeApply / 拒绝交易

插件会在当前申请列表中查找与发包玩家有关的申请。没有找到申请数据时，玩家会收到 error，不会进入交易界面。

交易主界面

交易主界面使用同一个 18 格 Bukkit 容器保存双方物品：

容器槽位	所属玩家	操作限制
0 至 8	第一位玩家	第一位玩家可放入和取回，另一方不可操作。
9 至 17	第二位玩家	第二位玩家可放入和取回，另一方不可操作。

双方各有 9 个交易槽。插件的成交转移、背包空间检查、关闭返还和槽位保护均按这组固定槽位执行，因此不能只在 DragonCore YAML 中增加或删除交易格。

物品操作规则

• 普通点击只能操作自己的交易区域，不能取走对方放入的物品。
• Shift + 点击玩家背包物品时，插件只会把物品移动到当前玩家的 9 个交易槽中。
• Shift + 点击交易物品时，只能从自己的交易槽取回背包。
• 跨越非法槽位的拖拽操作会被拦截，避免物品进入另一方区域或绕过槽位限制。
• anti-trade-for-contain-lore-item 中配置的 Lore 文本会阻止对应物品参与交易。
• 玩家锁定交易后，不能继续修改自己的交易物品，也不能通过 Shift + 点击继续添加物品。
• 交易未完成前关闭容器会取消交易，双方放入的物品会分别返还至原玩家背包。

交易界面变量

变量	返回内容
%ldt_trade_player_name%	当前交易对方的玩家名。
%ldt_trade_player_uuid%	当前交易对方的 UUID。

玩家没有处于交易中或 PlaceholderAPI 未启用时，变量返回空文本。

交易主界面发包

交易主界面的发包标识必须为 LyDragonTrade。插件根据第一个数据参数识别操作。

操作	发包标识	数据参数	原页面写法
初始化交易界面	LyDragonTrade	交易初始化	LyDragonTrade / 交易初始化
确认并锁定交易	LyDragonTrade	确定交易	LyDragonTrade / 确定交易
修改金币	LyDragonTrade	刷新货币、金币、金额	LyDragonTrade / 刷新货币 / 金币 / 金额
修改点券	LyDragonTrade	刷新货币、点券、金额	LyDragonTrade / 刷新货币 / 点券 / 金额
修改自定义货币	LyDragonTrade	刷新货币、货币键、金额	LyDragonTrade / 刷新货币 / 自定义 / 金额

交易初始化

界面打开后发送 交易初始化，插件会通知另一方界面刷新交易槽位：

• 第一位玩家初始化时，要求第二位玩家执行 对方交易槽位更新。
• 第二位玩家初始化时，要求第一位玩家执行 我方交易槽位更新。

配套 YAML 中需要保留对应的方法名称，否则另一方看到的交易物品可能不会及时刷新。

刷新货币

刷新货币发包需要依次提供：

1. 刷新货币
2. currency-textbox 中已配置的货币键
3. 输入框当前金额

插件只有在 currency-textbox.货币键 存在时才会保存金额，并把内容同步到对方文本框。货币键区分具体接入方式：

货币键格式	对接功能	示例
金币	Vault 经济	金币
点券	PlayerPoints	点券
LyShopReload#货币ID	LyShopReload 自定义货币	LyShopReload#金币
CX#货币ID	CraftX 变量货币	CX#积分

自定义货币发包中的第二个参数必须使用完整配置键，不能统一发送字面量 自定义。原页面中的 自定义 仅对应默认示例配置；扩展 LyShopReload 或 CraftX 货币时，应发送实际的 LyShopReload#货币ID 或 CX#货币ID。

插件确认交易时会把输入值转换为整数金额。界面应限制用户输入有效的非负整数，避免小数、空格或其它字符导致校验失败或数值转换异常。

确定交易

玩家点击确定按钮后，插件会依次检查：

1. 当前交易是否已经进入双方锁定后的完成倒计时。
2. 对方背包空槽数量是否足以接收当前玩家放入的物品种类。
3. 输入的货币是否为有效数字。
4. 当前玩家是否拥有足够的金币、点券或自定义货币。

检查通过后，插件会：

• 显示当前玩家的锁定幕布。
• 在对方界面显示对方玩家锁定幕布。
• 隐藏当前玩家的确定按钮。
• 将当前玩家标记为已锁定。
• 双方都锁定后，启动 trade-count-down 配置的完成倒计时。

倒计时结束后才会交换双方物品和货币。任意一方提前关闭容器都会取消尚未完成的交易。

必须保留的组件与方法

插件会直接按照以下名称控制 DragonCore 界面。修改配套 YAML 时，应保留这些组件或同步调整插件代码。

申请界面组件

名称	类型或用途	插件操作
文本_交易倒计时	申请剩余时间文本	每秒设置 texts；接受交易时清空。

交易界面组件

名称	类型或用途	插件操作
文本_交易倒计时	成交倒计时文本	设置 texts 并将 visible 设为 true。
贴图_当前玩家锁定幕布	当前玩家锁定遮罩	当前玩家确认后显示。
贴图_对方玩家锁定幕布	对方锁定遮罩	对方确认后显示。
贴图_确定交易按钮	确认按钮	当前玩家确认后隐藏。

交易界面方法

方法名	用途
我方交易槽位更新	刷新界面中的我方交易槽显示。
对方交易槽位更新	刷新界面中的对方交易槽显示。

插件通过 DragonCore 的异步方法调用执行以上刷新方法。删除或重命名方法会影响双方交易槽的同步显示。

货币文本框映射

config.yml 的 currency-textbox 用于建立货币键与对方界面文本框组件名的映射。默认配置为：

currency-textbox:
  金币: 发包_对方金币文本框
  点券: 发包_对方点券文本框
  自定义: 发包_对方自定义文本框

例如玩家发送以下数据：

LyDragonTrade / 刷新货币 / 金币 / 100

插件会读取 currency-textbox.金币，并将对方界面中 发包_对方金币文本框 组件的 text 设置为 100。

扩展货币时，配置键、发包中的货币键和税率节点必须保持一致：

currency-textbox:
  LyShopReload#货币ID: 发包_对方离渊商店货币文本框
  CX#货币ID: 发包_对方CX货币文本框

currency-tax:
  LyShopReload#货币ID:
    - 'vip.1:0.95'
  CX#货币ID:
    - 'vip.1:0.95'

文本框组件名可以自行调整，但调整后必须同步修改 currency-textbox。没有配置映射的货币发包会被忽略。

交易格数量

默认交易界面固定为双方各 9 个交易格，共 18 个容器槽位。当前插件逻辑直接使用以下范围：

第一位玩家：0-8
第二位玩家：9-17

以下逻辑均以固定 9 格为基础：

• 成交时的物品转移。
• 交易取消时的物品返还。
• 双方可操作区域判断。
• Shift + 点击自动放入区域。
• 拖拽槽位保护。
• 对方背包空间检查。

只修改 DragonCore 界面中的格子数量不会改变服务端容器逻辑，并可能造成物品显示与实际槽位不一致。普通使用不要修改交易格数量。

界面适配检查

修改或迁移 DragonCore 资源时，至少确认以下内容：

检查项	正确要求
主界面标题	YAML 的 match 与 config.yml 的 gui-title 完全一致。
申请界面标识	保持为 LyDragonTrade_Apply。
主界面标识	保持为 LyDragonTrade_Gui。
申请发包标识	保持为 LyDragonTradeApply。
主界面发包标识	保持为 LyDragonTrade。
申请操作参数	使用 接受交易 或 拒绝交易。
主界面操作参数	使用 交易初始化、确定交易 或 刷新货币。
倒计时组件	两个界面均保留 文本_交易倒计时。
锁定组件	保留当前玩家幕布、对方幕布和确定按钮的既定名称。
货币组件	currency-textbox 的值与对方文本框组件名一致。
交易槽	保持双方各 9 格，并正确映射容器槽位。
客户端资源	离渊/交易/ 中的贴图已放入客户端 DragonCore 资源目录。

常见问题

打开后显示原版容器

检查 LyDragonTrade_Gui.yml 的 match 是否与 config.yml 中的 gui-title 完全相同。默认值为 离渊交易。

接受或拒绝按钮没有反应

检查发包标识是否为 LyDragonTradeApply，数据参数是否为 接受交易 或 拒绝交易。同时确认服务器已启用 DragonCore，并已加载 LyDragonTrade_Apply.yml。

申请者名称不显示

确认已安装并启用 PlaceholderAPI，界面使用的是 %ldt_apply_player_name%。该变量只会为当前申请的接收方返回申请者名称。

交易对象名称不显示

确认已安装并启用 PlaceholderAPI，界面使用的是 %ldt_trade_player_name%。玩家必须已经进入交易容器，否则变量返回空文本。

输入货币后对方界面不刷新

检查以下内容：

• 发包标识为 LyDragonTrade。
• 第一个参数为 刷新货币。
• 第二个参数与 currency-textbox 中的配置键完全一致。
• currency-textbox 的值是对方界面的真实文本框组件名。
• 第三个参数是输入框当前金额。

点击确定后没有完成交易

双方都必须点击确定并成功通过背包空间与货币余额检查。双方锁定后，还需要等待 trade-count-down 倒计时结束。若任意一方关闭界面，交易会取消并返还物品。

锁定后仍能修改物品

配套界面的视觉锁定和服务端槽位保护是两部分。服务端会阻止已锁定玩家修改自己的交易槽及 Shift + 点击添加物品；若界面没有显示锁定效果，请检查 贴图_当前玩家锁定幕布、贴图_对方玩家锁定幕布 和 贴图_确定交易按钮 的组件名称。

修改交易格数量后物品异常

当前版本固定使用 18 格交易容器，双方各占 9 格。仅修改 YAML 无法扩展服务端槽位范围，请恢复配套界面的默认槽位数量。