交易表¶

本页列出行为包trading/目录中交易表文件的主要字段。交易表通常由实体组件minecraft:economy_trade_table或minecraft:trade_table引用。

根对象¶

字段	类型	默认值	说明
`tiers`	数组	未设置	交易层级数组。
`format_version`	字符串	未设置	兼容性字段，原版交易表通常可省略。

层级¶

层级对象位于tiers数组中。第一层级始终可用；后续层级按经验逐级解锁。

字段	类型	默认值	说明
`total_exp_required`	整数	索引值	解锁该层级所需交易者总经验。
`groups`	数组	未设置	交易组数组。
`trades`	数组	未设置	直接交易数组。

兼容性资料显示，同一层级同时存在groups与trades时通常优先使用groups。

层级解锁机制¶

层级按顺序解锁。当新层级解锁时，系统继续检查后续层级是否满足当前经验阈值，满足则继续解锁，依此类推。第一层级始终解锁。若某层级经验要求未满足导致解锁中断，即使后续层级的阈值更低，也不会跳过继续检查。

初始层级经验¶

第一层级的total_exp_required若非零，有特殊行为：

负值：解锁所有层级。
正值：交易者的初始经验被设为该值，并按正常解锁机制尝试解锁后续层级。

界面刷新

当第一层级的total_exp_required为非零值时，交易界面初始仅显示第一层级的交易。需要进行一次交易或关闭并重新打开界面后，界面才会正确反映实际解锁状态。

层级冻结¶

将某层级的total_exp_required设为-1（负值）可实现层级冻结：当该层级的上一层级被解锁时，该层级立即解锁（负经验要求即时满足），但玩家无法继续解锁任何后续层级。

{
  "total_exp_required": -1,
  "trades": []
}

交易组¶

交易组对象位于tiers > groups数组中。

字段	类型	默认值	说明
`num_to_select`	整数	`0`	从`trades`中选取数量。`0`通常表示选取全部。
`trades`	数组	未设置	候选交易数组。

交易¶

交易对象可位于tiers > trades或tiers > groups > trades数组中。

字段	类型	默认值	说明
`wants`	数组	未设置	需求物品数组，常见为`1`至`2`项。
`gives`	数组	未设置	给予物品数组，常见为`1`项。
`max_uses`	整数	`7`	单次补货周期内可使用次数。`0`表示显示但不可交易，负值常用于无限次。
`reward_exp`	布尔值	`true`	玩家完成交易后是否获得经验球。
`trader_exp`	整数	`1`	交易者完成此交易获得的经验。
`weight`	整数	未设置	候选随机集合内的相对权重。

交易物品¶

交易物品对象位于wants或gives数组中。

字段	类型	默认值	说明
`item`	字符串	未设置	物品标识符。可带数据值后缀，如`minecraft:log:2`。
`quantity`	整数或对象	`1`	数量或随机数量范围。
`price_multiplier`	数值	`0`	价格波动乘数。主要影响需求增长带来的价格变化。
`functions`	数组	未设置	应用于该物品的函数数组。
`choice`	数组	未设置	候选物品列表，交易生成时随机选一项。
`filters`	对象	未设置	条件过滤。

当对象同时定义item与choice时，通常以choice为准。

随机数量对象¶

字段	类型	默认值	说明
`min`	整数	`1`	最小数量。
`max`	整数	`1`	最大数量。

价格乘数与成本计算¶

price_multiplier控制因需求增加导致的价格波动。需求从0开始，每次交易耗尽后补充时增加，补充期间无交易时减少。

需求增加导致的总成本计算公式（其他因素不计时）：

c = p × (1 + m × d)

变量	含义
c	总成本（实际数量）
p	基础成本（含数量覆盖）
m	价格乘数
d	当前需求值

若price_multiplier为0，在大多数情况下数量保持不变。负值乘数不影响需求引起的价格上涨（负值被限制为0），但会影响交易者被治愈或玩家拥有"村庄英雄"效果时的旧式价格计算。

函数兼容性¶

交易物品函数与战利品函数有重叠，但并非完全等价：

set_count不在交易中生效，数量应使用quantity字段。
furnace_smelt、looting_enchant、trader_material_type在交易表中无效。
set_name、set_lore、set_damage、set_book_contents、random_dye、fill_container在需求物品上使用时无效（不会要求玩家提供符合特定属性的物品）。
enchant_with_levels与enchant_book_for_trading在给予物品上使用时，会同时覆盖第一个需求物品的quantity值；这些函数不能影响第二个需求物品的数量。

示例¶

trading/example_trades.json

{
  "tiers": [
    {
      "total_exp_required": 0,
      "groups": [
        {
          "num_to_select": 1,
          "trades": [
            {
              "wants": [
                {
                  "item": "minecraft:chicken",
                  "quantity": 14,
                  "price_multiplier": 0.05
                }
              ],
              "gives": [
                {
                  "item": "minecraft:emerald",
                  "quantity": 1
                }
              ],
              "trader_exp": 2,
              "max_uses": 16,
              "reward_exp": true
            }
          ]
        }
      ]
    }
  ]
}