currency（货币）

文件位置：data/<namespace>/mxt/currency/<path>.json

用途：物品货币面值和兑换。

字段	类型	默认	说明
items	ItemMatcher	与 item 二选一	可作为该货币的物品集合。
item	Item ID	无	单物品写法；仅为 items 的简写。
value	Long	必填	单件面值，必须大于 0。
exchanges	List<Exchange>	必填	单向兑换选项，可为空数组。

每个兑换项包含 cost（1..99）和 result（ItemStackTemplate）。items 和 item 至少提供一个；推荐新数据使用 items，这样可以同时支持物品和标签。

货币由 mxt:currency 动态注册表定义。任意已注册物品都可以作为货币；支票桌、兑换站和结算服务读取同一份注册表。

文件位置

货币文件位于数据包的 data/<namespace>/mxt/currency/ 目录。例如：

data/example/mxt/currency/iron_coin.json

其定义 ID 为 example:iron_coin。

字段

字段	类型	说明
items	ItemMatcher	与 item 二选一。可写单个物品 ID、物品标签或混合数组。
item	物品 ID	与 items 二选一。单物品简写，旧示例仍可使用。
value	长整数	必填，必须大于 0。用于支票与通用结算。
unavailable_when	条件数组	可选。任一 condition 对当前物品栈成立时，该物品当前货币价值为 0，并显示对应 reason。
exchanges	兑换数组	必填，可为空。兑换站在放入 item 后显示其中的全部条目。

unavailable_when

每项由一个现有 ItemCondition 和一个原因文本组成。reason 可以写翻译键字符串，也可以写原版文本组件对象。条件需要玩家上下文的场景（例如支票台、兑换站和 tooltip）会使用当前操作玩家判断；没有实体上下文的纯服务端查询不会擅自猜测条件结果。

{
  "items": "mxt:spirit_stone",
  "value": 10,
  "unavailable_when": [
    {
      "condition": { "type": "mxt:spirit_storage_not_full" },
      "reason": "tooltip.mxt.currency_spirit_not_full"
    }
  ],
  "exchanges": []
}

兑换条目

exchanges 中的条目按数组顺序显示在兑换站的切石机式选项列表中：

字段	类型	说明
cost	整数	必填，范围 1 到 99。从输入槽的当前货币物品中消耗的数量。
result	Item Stack	必填。成功兑换后产生的物品栈。

result 使用原版 Item Stack 形状：

字段	类型	默认值	说明
id	物品 ID	无	必填。输出物品。
count	整数	1	输出数量，范围 1 到 99。
components	对象	无	可选的原版数据组件补丁。

示例

铜币提供单向兑换选项：

{
  "items": ["mxt:copper_coin", "#example:copper_coins"],
  "value": 1,
  "exchanges": [
    {
      "cost": 10,
      "result": {
        "id": "mxt:iron_coin"
      }
    }
  ]
}

只匹配一个物品时也可以使用 item 简写：

{
  "item": "mxt:iron_coin",
  "value": 10,
  "exchanges": [
    {
      "cost": 1,
      "result": {
        "id": "mxt:copper_coin",
        "count": 10
      }
    },
    {
      "cost": 10,
      "result": {
        "id": "mxt:gold_coin"
      }
    }
  ]
}

兑换是单向的。若要允许反向兑换，必须在目标货币的 exchanges 数组中显式定义反向条目。

物品标签和带组件输出的示例：

{
  "items": "#minecraft:emeralds",
  "value": 100,
  "exchanges": [
    {
      "cost": 4,
      "result": {
        "id": "minecraft:diamond",
        "components": {
          "minecraft:custom_name": "{\"text\":\"兑换凭证\"}"
        }
      }
    }
  ]
}

没有兑换选项的货币仍必须写入空数组：

{
  "items": "minecraft:emerald",
  "value": 100,
  "exchanges": []
}

兑换站行为

兑换站采用切石机式界面：输入槽接受带有非空 exchanges 的货币物品；右侧显示该货币的所有兑换条目；选中条目后，输入数量达到 cost 时才会在结果槽显示输出。取走结果会扣除 cost 个输入物品。

列表和结果都由服务器端菜单确认。客户端仅使用同步后的动态注册表展示相同的兑换选项。

禁用标签

货币注册表的禁用标签路径为 data/mxt/tags/mxt/currency/disabled.json：

{
  "replace": false,
  "values": [
    "mxt:copper_coin"
  ]
}

被禁用的货币不会参与兑换、支票或结算，但仍可被其他数据定义引用。

校验与加载

• items 和 item 至少提供一个；推荐使用 items 以支持批量匹配。
• value 必须是正整数。
• unavailable_when 中任一条件成立时，该栈不参与货币结算。
• exchanges 必须存在；不提供兑换时使用 []。
• 每个 cost 必须位于 1 到 99。
• result 必须是有效的 Item Stack。
• 定义在世界加载时校验，并在客户端加入时同步；修改后需重新加载世界或重启服务器（/reload 不适用于数据包注册表）。