交易 API

TradingAPI在已有的Blabber交谈中打开商人目录，并提供个人交情阶段查询。村民与NPC共用目录生成、支付、库存记录和照拂服务。玩家规则见交易。

入口

使用net.kzeroko.isekaiexpansion.api.trading.TradingAPI，门面委托给内部DialogueTrading。blabber:open_trade与isekaiexpansion:open_npc_trade动作进入同一服务。Blabber负责面板导航及一次性回复令牌，所有状态变更由服务端处理。

常见用法

打开当前说话者的商店

Blabber.getActiveDialogueEntity(player)
        .ifPresent(merchant -> TradingAPI.open(player, merchant));

导入io.github.ladysnake.blabber.Blabber与上述门面。实体须为实现Merchant的MobEntity，或BaseNpcEntity。当前对话必须绑定同一实体；不符合准入条件时返回false。

绑定NPC职业

在NPC预设中，将trade_profession设为minecraft:farmer等目录ID。相应目录写在data/<namespace>/trade_overrides/，格式版本3见交易覆盖。自定义职业不必注册为村民职业；可选来源模组通过requires_mods限制。

BaseNpcEntity.getTradeProfession()优先读取普通NPC已保存的个体职业，再读取预设。setTradeProfession(identifier)为普通NPC指定职业，传入null恢复使用预设。唯一NPC拒绝个体赋值，始终使用预设；伊芙琳娜使用isekaiexpansion:mahoutsukai_evelina。canTradeWith要求目录已启用，并满足预设的trade_access：默认trusted要求信任，public允许公开买卖。菜单锁定和服务端准入使用同一谓词。唯一NPC在展示和执行端均排除照拂、换货与议价，自动补货仍保留。

这些实体方法是内部集成入口。预设字段可省略，默认没有交易职业；标识符格式错误会拒绝该预设。对应实体NBT可选字符串为TradeProfession。人形导出命令会保留当前生效的职业。

查询熟客阶段

int rank = TradingAPI.rapportRank(player, merchant);

merchant为MobEntity。结果属于当前玩家与商人这一对关系。村民对话处理器在3阶段使用熟客场景，并通过Registries.VILLAGER_PROFESSION的注册ID解析职业路径。

方法一览

TradeOverrideManager初次即生成1–5所有货品层级，种子由商人UUID、职业、层级、报价ID及轮换值确定。VillagerTradeAuthorityMixin关闭原版升级；未被覆盖的职业依次调用各层级的原版或模组工厂。覆盖目录在构造与读取边界冻结结构。重建保留兼容的报价状态及职业/报价ID使用记录。缓存依赖定义、版本与轮换值，不依赖交情。

TradeTransaction通过TradePricing从基础货币值计算声望价格，再议价；检查两份材料、货币与输出空间后，使用异界核心NumismaticCompat支付。界面交换项来自同一份报价。找零可能占据空间，余下输出通过offerOrDrop交付。村民的Merchant.trade只在同步回调内设置顾客，并在finally清除。村民经验不再推进商品资格；NPC直接使用共享的权威报价列表。

支付完成后，服务记录库存使用和个人交情。MerchantCourtesies在赠送或保养前复核目录定义、对话、阶段、次数及物品。保养再次比较已选择的主手快照，只改变损伤；赠品在消耗次数前检查背包空间。

注册照拂动作

net.kzeroko.isekaiexpansion.api.trading.CourtesyAPI.register(type, parser)委托内部注册表。请在通用初始化阶段、资源重载前注册；重复ID抛错。解析器收到包含type的JsonObject副本，返回不可变的CourtesyAction实现；该内部类型仅为此扩展约定公开。解析器应拒绝未知字段与无效数据。

icon(player)与description()提供界面内容，canApply(player, merchant)只检查资格，不改变状态。apply(player, merchant)必须在服务端线程同步执行并再次验证，无法完成时返回false且不作任何变更；调度器只在true之后消费照拂。解析后的动作不能持有玩家或世界引用。内置动作包含赠品、保养、用餐、净化与限时效果。参数见交易覆盖。

声望报价与信息栏

TradePricing.resolve读取身份势力、所在地势力与村民当前流言。流言乘4后限制在−1000…1000；有负值时取最差的一项，否则取最好的一项。村庄英雄只在声望非负时提供正值下限，每级100，最多500。势力转流言的桥接因此不会重复叠加。买价调整范围为−15%…+40%，收购价为−20%…+5%；使用防溢出的整数计算，取整到百分点，再对买价应用议价。货币从原始堆叠取值，非货币材料保留原版调整。每次目录只解析一份价格上下文，确认时重新解析并比较完整报价。

MerchantDialogueMetadata同步阶段、交情、下一门槛、照拂次数/容量与买卖调价。MerchantDialogueHud复用NPC状态栏的DialogueInfoBar紧凑条形样式。两者分别通过Blabber预留顶部行，空间不足时用省略号收窄文字。Blabber对象更新会刷新元数据。DialogueAPI.lastSpeech(player)在进入空白结束动作后保留最后的作者台词，商店据此维持唯一NPC的专属发言。

持久实体字段

IsekaiCommerce是按需创建的内部存档数据。下表描述当前格式，不是数据包格式。

线程与生命周期

游戏逻辑入口在服务端线程调用；异步打开会抛出异常。每位商人同时只接待一位交易玩家。准入检查存活、世界、4格距离、战斗、恐慌、现有顾客及NPC目录策略。会话保存对话UUID、实体、报价列表、轮换值、日期、职业和目录版本；职业、版本或NPC日期变化会使旧选项失效。重载、断线及停服清除活动会话。

确认前再次检查报价对象与当前费用，Blabber在回调前消耗回复令牌。生命周期关闭不会重开面板。村民补货和NPC日期向前推进时清除议价及库存使用；换货仅轮换选择，两者都保留交情。日期使用主世界实际流逝时间除以24000 ticks（20 ticks每秒时为1200秒）。

验证

运行./gradlew.bat -I tools/trading/verify.gradle checkCommerce processResources及python tools/trading/validate_coverage.py。JVM检查直接使用生产解析器，覆盖交情限额、收款预算、存取及库存转换。覆盖检查将配置的职业导出表与目录、场景和双语文本逐项比对。

游戏内检查新生的1级村民、两名不同交情的玩家、全部5个货品层级、重复交易、重启、补货及轮换。测试满背包赠品、更换主手后的保养、NPC职业变化及报价打开时重载。分别在有货和无货时打开新制图师的服务菜单。REI显示内置货品层级及初访即可购买的提示。这些交互检查需要运行整合包。

相关页面

• 交易：玩家规则。
• 交易覆盖：目录及照拂字段。
• NPC对话：准入与路由。