兑换系统

兑换系统可以独立使用，不需要 CDK。
它适合做 RPG 材料兑换、NPC 商店、副本奖励兑换、活动兑换、宝石兑换、图纸兑换。

推荐把兑换配置放在：

plugins/GTCDK/exchanges/
  基础/物品兑换示例.yml
  物品库/物品库兑换示例.yml
  高级/系数兑换示例.yml

GTCDK 会递归读取 exchanges/ 下的所有 .yml 文件。

最小兑换

消耗 3 个钻石和 1 个绿宝石，执行奖励动作：

name: "&b钻石兑换礼包"
description:
  - "&7消耗 3 个钻石和 1 个绿宝石兑换奖励。"
  - "&7这是独立兑换功能，不需要生成 CDK。"
conditions:
  - "%player_level% >= 0"
actions:
  - "[message] &a兑换成功，奖励已发放。"
  - "[sound] ENTITY_PLAYER_LEVELUP 1 1"
exchange:
  consume: true
  cooldown-seconds: 3
  materials:
    - "DIAMOND 3"
    - "EMERALD 1"
gui:
  material: "DIAMOND"
  slot: 22
rewards:
  items: []

效果：

• 玩家材料足够时可以兑换。
• 成功后扣除 3 个钻石和 1 个绿宝石。
• 冷却 3 秒。
• 播放声音并发送提示。

exchange 字段

exchange:
  consume: true
  cooldown-seconds: 3
  materials:
    - "DIAMOND 3"
    - "EMERALD 1"

字段	说明
consume	成功后是否扣除材料
cooldown-seconds	兑换冷却
materials	需要提交的材料

consume: false 适合做检测型兑换，例如只检查玩家是否持有某些材料，不扣除。

原版材料

materials:
  - "DIAMOND 3"
  - "EMERALD 1"

格式为：

物品ID 数量

原版物品直接写 Material，不需要 vanilla: 前缀。

物品库材料

exchange:
  materials:
    - item: "ni:example_token"
      amount: 1
      name: "兑换代币"

常用前缀：

前缀	内容
ni:	NeigeItems
mm:	MythicMobs
ia:	ItemsAdder
oraxen:	Oraxen
ce:	CraftEngine

例子：

materials:
  - item: "mm:ICE_DRAGON_CORE"
    amount: 2
    name: "冰龙核心"
  - item: "ce:gear_core"
    amount: 1
    name: "齿轮核心"

奖励动作

actions:
  - "[item] DIAMOND 5"
  - "[item] ni:ruby 1"
  - "[money] give 1000"
  - "[message] &a兑换成功。"
  - "[sound] ENTITY_PLAYER_LEVELUP 1 1"

常用动作：

动作	说明
[item] DIAMOND 5	给原版物品
[item] ni:ruby 1	给 NI 物品
[item] mm:LEGEND_SWORD 1	给 MM 物品
[item] ce:gear_core 1	给 CraftEngine 物品
[money] give 1000	给金币
[console] command	控制台命令
[op] command	玩家临时 OP 命令
[message] 文本	发送消息

GUI 放入物品保存

复杂物品推荐在 GUI 里保存，不手写物品 ID。

适合 GUI 保存的情况：

• 需要识别 NBT。
• 需要保留附魔、Lore、PDC。
• 物品来自副本、宝石、装备系统。
• 物品是临时拿出来的特殊成品。

常用流程：

1. 执行 /gtcdk。
2. 进入兑换管理。
3. 创建或选择一个兑换。
4. 点击需求物品编辑。
5. 把要消耗的物品放进去保存。
6. 点击奖励物品编辑。
7. 把要发放的物品放进去保存。
8. 回到兑换界面测试。

这类保存方式更适合 RPG 服，因为物品的 NBT 和特殊数据不会丢。

条件

等级限制：

conditions:
  - "%player_level% >= 30"

职业限制：

conditions:
  - "%player_class% == WARRIOR"

权限限制：

conditions:
  - "hasPermission('gtexchange.vip')"

条件不满足时不会扣材料。

系数兑换

系数兑换可以按权限、变量和公式改变材料需求、奖励倍率、冷却倍率。

name: "&6系数兑换示例"
description:
  - "&7材料、奖励、冷却都可以按权限和公式变化。"
conditions:
  - "%player_level% >= 0"
actions:
  - "[message] &a兑换完成，倍率：材料 {requirement_multiplier} 奖励 {reward_multiplier}"
exchange:
  consume: true
  cooldown-seconds: 10
  materials:
    - "DIAMOND 8"
  limits:
    min-times: 1
    max-per-click: 64
coefficients:
  requirement:
    base: 1.0
    min: 0.5
    max: 2.0
    permissions:
      "gtexchange.vip": 0.9
      "gtexchange.svip": 0.8
    variables:
      level_reduce: "min({level}, 50) * 0.002"
    formula: "clamp({base} * {permission_multiplier} - {level_reduce}, 0.5, 2.0)"
  reward:
    base: 1.0
    min: 1.0
    max: 3.0
    permissions:
      "gtexchange.vip": 1.2
      "gtexchange.svip": 1.5
  cooldown:
    base: 1.0
    min: 0.2
    max: 1.0
    permissions:
      "gtexchange.vip": 0.8
      "gtexchange.svip": 0.5
gui:
  material: "GOLD_INGOT"
  slot: 24
rewards:
  items: []

效果：

• VIP 消耗材料更少。
• SVIP 消耗材料更少、奖励更多、冷却更短。
• 等级越高，材料需求可继续降低。

自定义 GUI 打开兑换

在 plugins/GTCDK/guis/main.yml 中写按钮：

items:
  E:
    template: "物品兑换示例"
    name: "&b物品兑换"
    lore:
      - "&7消耗配置材料，直接兑换奖励。"
      - "&7不需要生成 CDK。"
    actions:
      - "[exchange] 物品兑换示例"

[exchange] 物品兑换示例 会执行对应兑换。

NPC 绑定

兑换可以绑定到 NPC，用来做副本兑换员、材料商人、活动使者。

推荐做法：

1. 创建兑换配置。
2. 创建一个只展示该兑换的 GUI。
3. 将 NPC 右键动作绑定到打开这个 GUI。
4. 玩家右键 NPC 后直接进入兑换界面。

这种方式可以按地图、副本、阵营拆分兑换，不需要玩家记命令。

设计例子

副本材料换宝石

name: "&c副本宝石兑换"
description:
  - "&7消耗副本核心兑换红宝石。"
conditions:
  - "%player_level% >= 30"
actions:
  - "[item] ni:ruby 1"
  - "[message] &a兑换成功，获得红宝石。"
exchange:
  consume: true
  cooldown-seconds: 1
  materials:
    - item: "ni:dungeon_core"
      amount: 5
      name: "副本核心"
gui:
  material: "NETHER_STAR"
  slot: 20

图纸合成装备

name: "&6图纸锻造"
description:
  - "&7消耗图纸和材料兑换装备。"
conditions:
  - "%player_level% >= 50"
actions:
  - "[item] mm:LEGEND_SWORD 1"
  - "[console] say {player} 锻造出了一把传说武器！"
exchange:
  consume: true
  cooldown-seconds: 5
  materials:
    - item: "ni:legend_blueprint"
      amount: 1
      name: "传说图纸"
    - "DIAMOND 64"
gui:
  material: "DIAMOND_SWORD"
  slot: 22

排查

材料足够但不能兑换

检查：

1. 需求物品 ID 是否写对。
2. 物品是否有特殊 NBT，建议用 GUI 保存需求物品。
3. conditions 是否满足。
4. 玩家是否还在冷却中。

兑换成功但没奖励

检查：

1. actions 是否写对。
2. [item] 的物品库前缀是否正确。
3. 背包满时奖励是否掉落或被拦截。
4. 控制台是否有动作执行错误。

想做很多兑换

按用途分文件夹：

exchanges/
  副本/冰龙.yml
  副本/火山.yml
  主城/材料商人.yml
  活动/春节.yml

再用不同 GUI 或 NPC 打开对应兑换组。