ItemBridge - 跨插件物品存储与调用

ItemBridge 是一款简单轻量的插件，它能让你的服务器和其他插件使用来自不同插件的物品！

💡概述

通过 ItemBridge，你可以在任何支持它的插件中，使用其他插件添加的特殊物品。只需在配置文件或命令中，将原本的 Minecraft 物品名（如 minecraft:diamond）替换为指定格式的键名（如 CustomItems:greenBeet）即可。它还允许你保存手中的物品，以便在其他地方重复调用。

🎮服务器管理员指南

如何使用

在支持 ItemBridge 的插件配置中，你可以使用特定格式的键名来引用其他插件的物品。

• 格式为：前缀:物品名
• 例如：QualityArmory:AWP 或 CustomItems:greenBeet
• 插件启动时会在控制台输出其使用的前缀，请留意日志信息。

保存与获取物品

ItemBridge 提供了便捷的命令来管理你自己的物品。

• 保存物品：手持你想保存的物品，执行 /ib save <名称>。该物品将被保存，之后可通过 saved:<名称> 的格式调用。
• 获取物品：使用 /ib get <物品键名> 来获取一个已保存或其他插件注册的物品。

🔧命令与权限

你可以使用 /ib、/itb 或 /itemb 作为 /itembridge 的快捷命令。

• /itembridge get <物品> [数量]

- 权限：`itembridge.get` 或 `itembridge.give`

- 给予你指定数量的物品。`<物品>` 格式需为 `前缀:物品名`，例如 `saved:myItem`。

• /itembridge give <玩家> <物品> [数量]

- 权限：`itembridge.give`

- 给予指定玩家物品。格式同上。

• /itembridge save <名称>

- 权限：`itembridge.save`

- 保存你手中的物品。之后可通过 `saved:<名称>`、`itembridge:<名称>` 或 `ib:<名称>` 调用。物品数据保存在插件文件夹的 `saves/<名称>.yml` 文件中。

• /itembridge drop <世界> <x> <y> <z> <物品> [数量]

- 权限：`itembridge.drop`

- 在指定世界和坐标自然掉落物品。不指定数量则默认为1。

✨开发者指南

为你的插件添加 ItemBridge 支持非常简单，只需几行代码即可让玩家使用第三方物品，并允许其他插件调用你添加的自定义物品。

第一步：检查与依赖

首先，确保服务器已安装 ItemBridge。

• 在 plugin.yml 中，根据需要添加依赖：

- 必需依赖：`depend: [ItemBridge]`

- 软依赖：`softdepend: [ItemBridge]`

• 在插件主类中检查 ItemBridge 是否存在：

public static boolean hasItemBridge;
public void onEnable() {
    hasItemBridge = Bukkit.getPluginManager().getPlugin("ItemBridge") != null;
}

获取物品

使用 ItemBridge.getItemStack() 静态方法，通过键名获取 ItemStack。

// 多种调用方式示例
ItemStack item = ItemBridge.getItemStack(plugin, "itemName");
ItemStack item = ItemBridge.getItemStack(namespaceKey);
ItemStack item = ItemBridge.getItemStack("itemKey", "itemName");
ItemStack item = ItemBridge.getItemStack("itemKey:itemName");

注册你的物品

要让 ItemBridge 识别并分发你插件的物品，需要实现一个监听器。

• 创建一个实现 ItemBridgeListener 接口的类。
• 实现 fetchItemStack(String itemName) 方法，根据物品名返回对应的 ItemStack（不存在则返回 null）。
• 在插件启用时，创建 ItemBridge 实例并注册监听器。

public class MyItemBridge implements ItemBridgeListener {
    private static ItemBridge bridge;
    public static void setup(Plugin plugin) {
        // 定义你的前缀，例如 "myplugin" 和 "mp"
        bridge = new ItemBridge(plugin, "myplugin", "mp");
        bridge.registerListener(new MyItemBridge());
    }
    @Override
    public ItemStack fetchItemStack(String item) {
        // 根据你的插件逻辑，通过 item 名称返回 ItemStack
        // 例如：return MyPlugin.getItem(item);
        return null; // 如果物品不存在
    }
}
// 在 onEnable 中调用
if (hasItemBridge) {
    MyItemBridge.setup(this);
}

高级功能：使用参数

ItemBridgeListener.fetchItemStack 和 ItemBridge.getItemStack 支持传入参数字典 Map<String, Object>，允许其他插件在获取物品时传递额外参数（如玩家名）。

@Override
public ItemStack fetchItemStack(@NotNull String item, @NotNull Map<String, Object> parameters) {
    String playerName = Objects.toString(parameters.get("playerName"));
    // 使用参数定制物品...
    return stack;
}
// 获取物品时传入参数
Map<String, Object> params = new HashMap<>();
params.put("playerName", player.getName());
ItemStack stack = ItemBridge.getItemStack("myplugin:TEST_ITEM", params);

请务必在你的插件文档中说明是否支持及如何使用参数功能。

⭐支持 ItemBridge 的插件

以下插件已支持 ItemBridge（括号内为可用前缀）：

• Custom Items (CustomItems: 或 cui:)
• Quality Armory (QualityArmory: 或 qa:)
• Knokko's Custom Items (KnokkosCustomItems: 或 kci:)

更多插件即将加入！如果你是开发者并希望将你的插件列入此列表，请联系作者。

❓注意事项

• 前缀 minecraft 和 mc 为 ItemBridge 保留，用于调用原版物品。
• 保存的物品文件位于 ItemBridge 插件文件夹的 saves/ 目录下，格式为 YAML。
• 开发者请参考 com.jojodmo.itembridge.ItemBridge 类的 JavaDocs 以获取完整 API 信息。