NPC 交易


NPC Trading 是一个功能完整的交易系统插件，可让你为服务器创建自定义的 NPC 商人。 设置物品交换、配置轮换交易选项，并与 HyCitizens 无缝集成，打造身临其境的商人 NPC。

---

命令: /npctrading (或 /nt) 快速打开: /nt {商人名称}

权限:

npctrading - 允许玩家通过 /nt 或 /npctrading 打开交易菜单

npctrading.admin - 访问管理员菜单

特性

交易系统

创建和管理向玩家提供物品交换的商人。

每个商人支持：

• 自定义名称
• 多个交易选项
• 经济系统支持（需要 VaultUnlocked）
• 物品轮换 - 定时自动循环展示不同的交易
• 可配置的轮换间隔和显示物品数量
• 补货
• 与 HyCitizens NPC 集成（可选）
• 通过命令直接访问商人

交易选项

每个交易选项包括：

• 输入物品及数量（玩家支付的部分）
• 输出物品及数量（玩家获得的部分）
• 交易可用/不可用的视觉反馈

物品轮换

保持交易新鲜感，鼓励玩家定期回来查看：

• 为每个商人启用/禁用轮换
• 设置自定义轮换间隔（以分钟为单位）
• 控制同时显示多少物品
• 带倒计时器的自动轮换

---

游戏内管理界面

使用:

/npctrading (或 /nt)

这将打开交易界面，你可以在其中：

• 创建新商人
• 编辑现有商人
• 管理交易选项
• 配置物品轮换设置
• 将商人与 HyCitizens NPC 关联
• 删除商人

使用该插件无需配置文件。

---

HyCitizens 集成

NPC Trading 与 HyCitizens（可选依赖）无缝集成：

• 将商人与任何 Citizen NPC 关联
• 通过 HyCitizens 菜单可完全自定义 NPC（外观、位置、动画、装备等）
• 玩家与 NPC 交互以打开其交易菜单
• 多个 NPC 可以共享同一个商人
• 具有超时保护的自动绑定系统

注意： 此插件不包含 NPC 生成器。你需要 HyCitizens 或另一个 NPC 插件来生成 NPC。

---

快速访问

还没有设置 NPC？使用快速命令：

/nt {商人名称}

这会直接打开商人的菜单，无需与 NPC 交互。

---

Discord / 支持

如果你想加入社区、提出功能建议、报告错误或需要帮助，请加入 Discord 社区！ https://discord.gg/Snqz9E58Dr

---

支持 NPC Trading

想要支持 NPC Trading？你可以在 Ko-fi 捐赠，或与朋友分享 NPC Trading！

---

开发者 API

NPC Trading 包含一个完整的开发者 API，用于以编程方式创建、编辑和管理商人。

---

获取插件实例：

NPCTradingPlugin plugin = NPCTradingPlugin.get();

TradersManager - 所有商人操作的主要入口点：

TradersManager manager = plugin.getTradersManager();

Trader 代表一个商人及其所有设置和交易选项。

商人字段：

uuid (UUID) – 唯一商人标识符。
name (String) – 显示的商人名称。
trades (List<TradeOffer>) – 所有交易选项的列表。
citizenIds (List<String>) – 关联的 HyCitizens NPC ID 列表。
rotateItems (boolean) – 物品是否定时轮换。
rotationIntervalMinutes (int) – 轮换之间的分钟数。
displayedItemCount (int) – 轮换时同时显示的交易数量。
lastRotationTime (long) – 上次轮换的时间戳。
currentRotationOffset (int) – 当前轮换位置。

创建商人

创建一个具有随机 UUID 的新商人：

Trader trader = manager.createTrader("Blacksmith");

创建一个具有特定 UUID 的商人：

UUID uuid = UUID.randomUUID();
Trader trader = manager.createTrader(uuid, "Wandering Merchant");

这会将商人添加到注册表并保存到存储中。

管理交易选项

TradeOffer 代表一个交换（输入 → 输出）：

TradeOffer offer = new TradeOffer(
    "Resource_Iron_Ore",  // 输入物品 ID
    10,                    // 输入数量
    "Resource_Iron_Ingot", // 输出物品 ID
    5                      // 输出数量
);

向商人添加交易选项：

trader.addTrade(offer);
manager.saveTrader(trader);

按索引移除交易：

trader.removeTrade(0); // 移除第一个交易
manager.saveTrader(trader);

清除所有交易：

trader.clearTrades();
manager.saveTrader(trader);

获取所有交易：

List<TradeOffer> allTrades = trader.getTrades();

获取当前显示的交易（考虑轮换）：

List<TradeOffer> displayedTrades = trader.getDisplayedTrades();

物品轮换设置

启用物品轮换：

trader.setRotateItems(true);
trader.setRotationIntervalMinutes(5);  // 每5分钟轮换一次
trader.setDisplayedItemCount(3);       // 一次显示3个交易
manager.saveTrader(trader);

禁用轮换：

trader.setRotateItems(false);
manager.saveTrader(trader);

获取轮换设置：

boolean rotating = trader.isRotateItems();
int interval = trader.getRotationIntervalMinutes();
int displayCount = trader.getDisplayedItemCount();
long lastRotation = trader.getLastRotationTime();
int offset = trader.getCurrentRotationOffset();

关联 NPC（HyCitizens 集成）

向商人添加一个 Citizen NPC：

trader.addCitizenId(citizenId);
manager.saveTrader(trader);

移除一个 Citizen NPC：

trader.removeCitizenId(citizenId);
manager.saveTrader(trader);

检查 Citizen 是否已关联：

boolean isLinked = trader.hasCitizenId(citizenId);

获取所有已关联的 Citizen：

List<String> citizenIds = trader.getCitizenIds();

通过 Citizen ID 查找商人：

Trader trader = manager.getTraderByCitizenId(citizenId);

更新商人

修改商人后，保存更改：

trader.setName("Master Blacksmith");
trader.setRotationIntervalMinutes(10);
manager.saveTrader(trader);

删除商人

从系统中移除一个商人：

boolean deleted = manager.deleteTrader(traderUuid);

这会将商人从内存中移除并删除已保存的数据。

获取商人

通过 UUID 获取商人：

Trader trader = manager.getTrader(uuid);

通过名称获取商人：

Trader trader = manager.getTraderByName("Blacksmith");

获取所有商人：

Collection<Trader> traders = manager.getAllTraders();

获取所有商人 UUID：

Set<UUID> uuids = manager.getTraderUUIDs();

检查商人是否存在：

boolean exists = manager.hasTrader(uuid);

获取商人数量：

int count = manager.getTraderCount();

交易执行 API

TradeManager 处理玩家交易：

TradeManager tradeManager = plugin.getTradeManager();

检查玩家是否负担得起某个交易：

boolean canAfford = tradeManager.canAfford(playerRef, offer);

获取玩家背包中物品的数量：

int count = tradeManager.getItemCount(playerRef, "Resource_Iron_Ore");

执行交易：

boolean success = tradeManager.executeTrade(playerRef, offer);

这将：

• 验证玩家是否有足够的输入物品
• 从玩家背包中移除输入物品
• 将输出物品添加到玩家背包
• 发送确认消息
• 成功返回 true，否则返回 false

以编程方式打开交易界面

为玩家打开一个商人的菜单：

plugin.getTradeUI().openTradeGUI(playerRef, store, trader);

NPC 绑定系统

NPCBindManager 处理将商人与 NPC 关联的过程：

NPCBindManager bindManager = plugin.getNPCBindManager();

开始绑定会话（30秒超时）：

bindManager.startBinding(playerRef, trader);

获取活动绑定会话：

NPCBindManager.BindingSession session = bindManager.getActiveSession(playerUuid);
if (session != null) {
    Trader trader = session.trader;
    PlayerRef player = session.playerRef;
}

完成绑定：

bindManager.completeBinding(playerUuid);

取消绑定：

bindManager.cancelBinding(playerUuid);

重载系统

从存储中重新加载所有商人：

manager.reload();

致谢

此插件的实现离不开 HyUI。