交易表
交易表是实体进行物品交易时的基础数据框架。交易表不能独立存在，必须通过实体组件引用。利用交易表提供的随机化特性，即使所有实体都指向同一个交易表，不同实体实例间的交易内容、物品数量和价格计算也可能各不相同。
交易表没有版本标识机制。与战利品表类似，交易表不支持Molang表达式，而是依赖JSON结构（如范围对象和功能函数）。虽然结构不同，交易表同样支持注释功能。
集成方式
交易表不像方块或生物群系那样属于核心附加系统。它们不需要放置在特定目录中注册，而是通过实体引用来生效。交易表可以存放在行为包的任意位置。
TIP
建议遵循原版规范，将所有交易表统一放置在行为包根目录下的trading文件夹中。在此目录下可以自由建立子目录结构。
- 📝minister.json
- 📝cleric_trades.json
下文将通过这个示例文件进行详细解析：
交易表示例文件
{
"tiers": [
{
"groups": [
{
"num_to_select": 1,
"trades": [
{
"wants": [
{
"item": "wiki:blessing_glyph",
"quantity": {
"min": 2,
"max": 4
},
"price_multiplier": 0.5
},
{
"item": "minecraft:book"
}
],
"gives": [
{
"item": "minecraft:enchanted_book",
"functions": [
{
"function": "enchant_book_for_trading",
"base_cost": 4,
"base_random_cost": 12,
"per_level_cost": 4,
"per_level_random_cost": 8
}
]
}
],
"max_uses": 7,
"trader_exp": 3
},
{
"wants": [
{
"item": "wiki:crystalline_spiritite",
"quantity": 32,
"price_multiplier": 0.125
}
],
"gives": [
{
"item": "wiki:exalted_blade",
"functions": [
{
"function": "enchant_with_levels",
"treasure": true,
"levels": {
"min": 15,
"max": 25
}
}
]
}
],
"max_uses": 2,
"reward_exp": false,
"trader_exp": 8
}
]
}
]
},
{
"total_exp_required": 28,
"trades": [
{
"wants": [
{
"choice": [
{
"item": "wiki:sacred_stones",
"quantity": {
"min": 4,
"max": 6
},
"price_multiplier": 0.5
},
{
"item": "wiki:blessed_beads",
"quantity": {
"min": 16,
"max": 24
},
"price_multiplier": 0.5
}
]
}
],
"gives": [
{
"item": "wiki:aeleon_jewels",
"quantity": {
"min": 4,
"max": 6
}
}
],
"max_uses": 2
}
]
}
]
}结构说明
交易表采用无版本号、无命名空间的JSON对象结构。
{
"tiers": [
{
"groups": […]
},
{
"total_exp_required": 28,
"trades": […]
}
]
}交易表使用层级结构来组织交易内容。顶层必须包含"tiers"数组属性。层级在交易界面中按定义顺序显示。
交易层级
层级代表可解锁的交易集合，是交易表中的最高级分组单位。
{
"groups": […]
}{
"total_exp_required": 28,
"trades": […]
}每个层级必须包含交易组（"groups"）或交易项（"trades"）中的至少一种。若定义交易项，该层级将显示所有指定交易；若定义交易组，则根据组配置从各组中选择交易项显示。
注意
若同时定义"trades"和"groups"，系统将优先采用交易组定义而忽略交易项。
同一层级中的交易项按定义顺序显示。若采用分组结构，交易组及其内部交易项也都按定义顺序排列。不同组的交易项在界面上没有视觉区分，只有不同层级之间会有明显分隔标识。
经验需求
当交易者积累足够经验值时会解锁新层级。每个交易者都有独立的内置经验值系统，通过与玩家交易获得成长。单次交易获得的经验量由交易者经验奖励决定。可选属性"total_exp_required"用于设定解锁该层级所需的总经验值。
"total_exp_required": 28默认情况下，所需经验值等于层级索引值（从0开始）。例如第二层级需要1点经验，第三层级需要2点，以此类推。首层级始终自动解锁，不受经验阈值限制。
层级解锁机制
层级按顺序逐个解锁。当新层级解锁时，系统会立即检查后续层级是否也满足经验条件，若满足则继续解锁，形成连锁反应。这种检查会在以下情况触发：(1)单次交易奖励的经验值足以解锁多个层级；(2)游戏正确更新后，初始经验值满足后续层级的解锁条件。
注意
由于层级是逐个检查的，若中间某个层级未满足条件，即使后续层级已达标也不会被检查。
初始层级经验
首层级的非零经验阈值有特殊处理逻辑：若为负值，将解锁所有层级；若为正值，则将该值设为交易者的初始经验。
WARNING
当首层级设置非零经验阈值时，需要手动刷新才能使交易界面正确显示。此时需要完成一次交易或重新打开交易界面，系统才会更新显示状态（初始仅显示首层级）。
层级冻结
除初始层级外，可以通过特殊设置冻结层级进度：
"total_exp_required": -1当满足前置条件时，负经验需求的层级会正常解锁，但玩家将永远无法解锁后续层级。
交易组
交易组用于为单个交易者随机选择该层级可用的交易项。
{
"num_to_select": 1,
"trades": […]
}必须通过"trades"数组定义候选交易项列表，每个元素都是一个交易项。可选属性"num_to_select"决定每组为交易者选取的交易项数量，默认为0表示选择全部交易项。
注意
交易组不支持嵌套结构实现复杂概率选择。
TIP
目前无法随机决定选取数量，也不支持按权重选择。但可以通过在数组中重复添加相同交易项来提高其被选中的概率。
交易项
交易项代表交易者与玩家之间的具体交易协议。
{
"wants": […],
"gives": […],
"max_uses": 2,
"reward_exp": false,
"trader_exp": 8
}交易项一旦被选中放入交易槽，其核心内容就不会改变。只有数量可能在某些情况下产生波动。
TIP
单个交易项定义不仅能影响交易本身。值得注意的是，实体可以根据玩家手持物品做出特定反应。
需求与给予物品
交易的核心内容通过"wants"和"gives"定义：玩家提供"wants"换取"gives"。这两个属性都是必须的数组。
"wants": […],
"gives": […]每个交易项可包含1-2个需求项，但必须恰好1个给予项。数组中的每个元素可以是物品或选项。
交易界面会根据需求物品数量自动调整布局。某些情况下（如数量修正附魔函数）只对第一个需求物品生效。
注意
若某个元素同时包含物品和选项属性，系统只会识别选项部分而忽略物品定义。
交易次数限制
交易者通常有单次交易项的使用上限，超过后需要补货。数值属性"max_uses"用于配置这个上限。
"max_uses": 2使用限制是每个交易项独立的。一个交易项的库存耗尽不会影响其他交易项，即使它们的需求/给予物品完全相同。默认情况下，交易者可以执行7次相同交易后才需要补货。
注意
补货行为由实体组件("minecraft:trade_resupply": {})控制。
设为0时，该交易项会显示但无法使用。设为负值时，该交易项可无限次使用。
玩家经验奖励
通过布尔属性"reward_exp"可以禁用交易给玩家带来的经验球奖励。
"reward_exp": false默认为true，玩家完成交易将获得经验值。奖励经验量不可配置。
交易者经验奖励
数值属性"trader_exp"决定交易完成后交易者获得的经验值，这是建立层级进度系统的关键。
"trader_exp": 8该属性可选，默认值为1。通过合理设置不同层级的经验奖励，可以实现非线性成长曲线。
TIP
通常高阶层的交易会设置更高经验奖励，使低阶交易对升级影响较小。
选项组
选项组用于从多个物品中随机选择交易内容，每个交易者实例会独立随机。
{
"choice": [
{
"item": "wiki:sacred_stones",
…
},
{
"item": "wiki:blessed_beads",
…
}
]
}选项组必须包含"choice"数组属性，其中每个元素都是物品定义。至少需要提供一个选项。
注意
选项组不支持嵌套结构。
TIP
目前无法直接设置选项权重，但可以通过重复添加相同物品来提高选中概率。
物品定义
物品定义是交易的主体内容，需求与给予物品共享定义格式，但根据使用位置有不同影响。
{
"item": "wiki:sacred_stones",
"quantity": {
"min": 4,
"max": 6
},
"price_multiplier": 0.5
}{
"item": "wiki:exalted_blade",
"functions": [
{
"function": "enchant_with_levels",
"treasure": true,
"levels": {
"min": 15,
"max": 25
}
}
]
}物品引用
通过必须的"item"字符串属性指定交易物品。
"item": "wiki:exalted_blade"必须使用有效的物品ID。可以直接在引用中添加数据值后缀：
"item": "minecraft:log:2"TIP
数据值也可以通过set_data函数设置（且支持更灵活的随机化）。
对于需求物品，若未指定数据值则接受任意数据值的该物品。对于给予物品，未指定时默认为0。
物品数量
可选属性"quantity"决定交易物品的数量。
"quantity": {
"min": 4,
"max": 6
}可以是固定数值或范围对象（如上例）。使用范围时会随机选取区间内的整数值（包含边界）。未设置时默认数量为1。
注意
数量受堆叠上限限制，且只能影响单个交易槽。例如无法通过单槽要求100个木板（但可以用2个需求项实现），也无法通过单次交易给予2把无法堆叠的剑。
价格乘数
"price_multiplier"决定物品基础数量在某些事件影响下的波动幅度。
"price_multiplier": 0.5该属性可选，默认为0。系统支持新旧两套价格计算机制：现代机制仅影响第一个需求物品，旧机制可影响所有需求物品。
价格波动因素
交易价格会在以下情况产生波动：
- 多次补货后对同一物品需求增加
- 交易者刚被治愈（如僵尸村民变回村民）
- 附近有其他刚被治愈的交易者
- 与拥有"村庄英雄"效果的玩家交易
除"村庄英雄"效果在使用新公式时采用固定值外，其他情况都受价格乘数影响。
价格计算公式
价格乘数直接影响因需求增加导致的价格上涨。基础需求值为0且不会低于该值。当交易项耗尽后补货时需求值+1，若补货期间未发生交易则需求值-1。
仅考虑需求增长的价格计算公式如下（线性增长）：
c = p × (1 + m * d)
变量说明：
| 变量 | 含义 |
|---|---|
| c | 总成本 |
| p | 基础成本（含数量修正） |
| m | 价格乘数 |
| d | 当前需求值 |
注意
其他情况的价格计算还涉及实体属性，此处不做赘述。
若乘数为0，在多数情况下数量保持恒定（"村庄英雄"使用新公式时除外）。
注意
负乘数不会影响需求增长导致的价格上涨（此时乘数视为0），但会影响治愈相关事件和"村庄英雄"使用旧公式时的价格。
功能函数
通过"functions"数组可以对物品进行各种修改。该属性可选。
"functions": [
{
"function": "enchant_with_levels",
"treasure": true,
"levels": {
"min": 15,
"max": 25
}
}
]交易表与战利品表共享函数库。当用于需求物品时（受限条件），这些函数会限制需求物品的属性，且仅对第一个需求物品有效。
通用限制函数
以下函数在交易表中完全无效：
set_countfurnace_smeltlooting_enchanttrader_material_type
无效的需求物品函数
以下函数用于需求物品时不会强制匹配，因此没有实际效果：
set_nameset_loreset_damageset_book_contentsrandom_dyefill_container
数量修正附魔函数
有两个函数作为给予物品使用时，会覆盖第一个需求物品的数量：
enchant_with_levelsenchant_book_for_trading
注意
虽然覆盖了数量，但所有价格波动机制仍正常运作。这些函数无法影响第二个需求物品的数量（即使使用旧公式）。若用于需求物品则不会触发数量覆盖。
附魔等级函数
enchant_with_levels会像附魔台一样随机附魔物品。
贡献者
