ItemBridge | SAVE ITEMS and use them wherever you want, including other plugins| Best w/ CustomItems

ItemBridge | SAVE ITEMS and use them wherever you want, including other plugins| Best w/ CustomItems -----

Use one plugin's items in other plugins | Store and Recall items | Supports CustomItems

ItemBridge is a simple, lightweight way to use items from different plugins in your server and in other plugins!

For Server Owners Using ItemBridge is simple! Just download and install the plugin on your server, and you're good to go. With ItemBridge, you can...

Use special items everywhere in any plugin that supports ItemBridge. Where you would normally specify an item in a configuration file or command using it's Minecraft name or "minecraft:item_name" namespace, you can use items from other plugins! Just replace the text with the item you want to use, like "CustomItems:greenBeet" or "QualityArmory:AWP", and you're done!

The item you give is split up into two parts. The part before ":" is where ItemBridge looks for the item, and the part after is the name of the item.

For example, "QualityArmory:AWP" looks in "QualityArmory" for the item called "AWP". Likewise, "CustomItems:greenBeet" looks in "CustomItems" for the item called "greenBeet".

When a plugin that supports ItemBridge starts up, it will print into the console what prefixes it uses. Look at your console when your server starts up!

You can also find a list of some of these prefixes below

Save Items with a simple command. Just use /ib save to save the item in your hand.

Use your Saved Items in Other Plugins, in commands, configuration files, and more! Where you would normally type the Minecraft material name of your item, like "minecraft:diamond" or "apple", just type "saved:mySavedItemName", and that's it!

Get Saved Items just as easily. Run use /ib get to get one of your saved items.

For Developers Adding ItemBridge support to your plugin is very simple, and with only a few lines of code, you can allow players to use third-party items in your plugin, and allow other plugins to use any custom items your plugin may have added!

(If you're an experienced developer, this will likely seem a little mundane to you. If that's you, check out the JavaDocs attached to each method in the
com.jojodmo.itembridge.ItemBridge class, and then take a look at the examples here)

First Steps
Download ItemBridge and add it to your plugin. If your plugin needs ItemBridge to work, make sure to modify the plugin.yml to have "ItemBridge" as a dependency. Otherwise, make sure that your plugin.yml has "ItemBridge" listed under "soft-depend"

Checking if the server has ItemBridge

Code (Java):

// An example for checking this in your Main class
public static boolean hasItemBridge ;

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

Getting an ItemStack using ItemBridge
Retrieving an ItemStack from a key is simple! Just use the static ItemBridge.getItemStack() methods.

Code (Java):

Plugin plugin ;
NamespacedKey namespaceKey ;
ItemStack item ;

item = getItemStack (plugin, "itemNameFromPlugin" ) ;
item = getItemStack (namespaceKey ) ;
item = getItemStack ( "itemKey", "itemName" ) ;
item = getItemStack ( "itemKey:itemName" ) ;

Letting ItemBridge recognize your plugin's items
Adding your items to ItemBridge is also easy!
First, make a class that implements the ItemBridgeListener interface. In here, there's only one method you need to implement:

Code (Java):

@Override
public ItemStack fetchItemStack ( String itemName ) {
// return the item from your plugin
// that has the name itemName
}

Next, make a new ItemBridge reference with a list of keys that you want to be able to be used (typically, this will just be your plugin name along with an abbreviation or two). Then, use the ItemBridge.registerListener method to register your newly created ItemBridgeListener.

For example, here's the class that handles native Minecraft items for ItemBridge (keep in mind that "minecraft" and "mc" are both reserved ItemBridge keys, so you'll have to change them to something else if you want to use this code):

Code (Text):

public class MinecraftItemBridge implements ItemBridgeListener{

private static ItemBridge bridge;
public static void setup(Plugin plugin){
bridge = new ItemBridge(plugin, "minecraft", "mc");
bridge.registerListener(new MinecraftItemBridge());
}

@Override
public ItemStack fetchItemStack(String item){
Material m = Material.matchMaterial(item);
return m == null ? null : new ItemStack(m);
}
}

Then, in the onEnable code of the Main class,

Code (Java):

public static boolean hasItemBridge ;

public void onEnable ( ) {
hasItemBridge = Bukkit. getPluginManager ( ). getPlugin ( "ItemBridge" ) != null ;
if (hasItemBridge ) {
MinecraftItemBridge. setup ( ) ;
}
else {
System. out. println ( "This server doesn't have ItemBridge!" ) ;
}
}

A walkthrough of how the internals work

Let's say we have two plugins: CustomItems and ItemDropper. CustomItems wants to make it so that other plugins can get and use its items, and ItemParty wants to let players drop items from other plugins.

This is what the code in CustomItems might look like

(Remember to call ItemBridgeCUI.setup(this) in your onEnable function)

Code (Java):

public class ItemBridgeCUI implements ItemBridgeListener {

private static ItemBridge bridge ;
static void setup (Plugin plugin ) {
// allow items to be looked up if they're prefixed with
// the keys "customitems:", "customitem:" or "cui:"
//
// for example, "customitems:apple" and "cui:MY_COOL_ITEM"
// will both get routed to this ItemBridge's listener (set up below)
// but "anotherPlugin:MY_COOL_ITEM" and "minecraft:apple" will not
bridge = new ItemBridge (plugin, "customitems", "customitem", "cui" ) ;

// register this class (ItemBridgeCUI) as a listener
bridge. registerListener ( new ItemBridgeCUI ( ) ) ;
}

@Override
public ItemStack fetchItemStack ( String item ) {
// here's the code for fetching the ItemStack for
// the CustomItem with the given item name.
//
// ItemBridge routes requests with matching keys.
// so, in this example, if ItemBridge was requested
// to get the item "customitems:apple", then
// item would be "apple". If ItemBridge was requested
// to get the item "cui:MY_CUSTOM_ITEM",
// then item would be "MY_CUSTOM_ITEM".
// if ItemBridge was requested to get the item "minecraft:MY_CUSTOM_ITEM",
// this method wouldn't be called

// You should return "null" if the item doesn't exist
ItemStack stack = CustomItemHandler. getCustomItemByID (item ) ;
return stack ;
}
}

And this is what the code in ItemParty might look like

(Remember to check that the server has the ItemBridge plugin)

Code (Java):

// give a player a bunch of items
public static void givePlayerItems (Player player ) {

// if CustomItems has the item "MY_COOL_ITEM", then the player will get one!
giveItem (player, ItemBridge. getItemStack ( "customitems:MY_COOL_ITEM" ) ) ;

// if CustomItems has the item "PARTY_HAT", then the player will get one!
giveItem (player, ItemBridge. getItemStack ( "cui", "PARTY_HAT" ) ) ;

Plugin customItemsPlugin =
Bukkit. getPluginManager ( ). getPlugin ( "CustomItems" ) ;

// if CustomItems has the item "myItem", then the player will get one!
giveItem (player, ItemBridge. getItemStack (customItemsPlugin, "myItem" ) ) ;

// if CustomItems has the item "anotherItem", then the player will get one!
giveItem (player, ItemBridge. getItemStack ( new NamespacedKey (customItemsPlugin, "anotherItem" ) ) ) ;

// give the player a minecraft diamond block
giveItem (player, ItemBridge. getItemStack ( "minecraft:DIAMOND_BLOCK" ) ) ;

// give the player a minecraft gold ingot. If something doesn't have a prefix: then ItemBridge assumes that it is a Minecraft item
giveItem (player, ItemBridge. getItemStack ( "GOLD_INGOT" ) ) ;
}

// convenience method for giving an ItemStack to the given player
public static void giveItem (Player player, ItemStack item ) {
if (stack == null ) { return ; } // avoid giving players null items
player. getInventory ( ). addItem (item ) ;
}

Advanced Features

Both ItemBridgeListener and ItemBridge.getItemStack have methods to accept arguments, which is a Map<String, Object>. This can be used to make it so that other plugins can pass arguments to your plugin when fetching a custom item (for example, if your plugin should be able to take in a player name and pass back the appropriate item).

Code (Java):

public class MyClass implements ItemBridgeListener {
ItemStack fetchItemStack (@NotNull String item, @NotNull Map < String, Object > parameters ) {
String playerName = Objects. toString (parameters. get ( "playerName" ) ) ;

ItemStack stack = new ItemStack (Material. GOLD_INGOT ) ;
ItemMeta meta = stack. getItemMeta ( ) ;
meta. setDisplayName (playerName + "'s " + item ) ;
stack. setItemMeta (meta ) ;

return stack ;
}

// you must also implement this function
public ItemStack fetchItemStack (@NotNull String item ) {
return fetchItemStack (item, new HashMap <> ( ) ) ;
}
}

public class AnotherClass {
public static void setup (Plugin plugin ) {
ItemBridge itemBridge = new ItemBridge (plugin, "myPlugin" ) ;
itemBridge. registerListener ( new MyClass ( ) ) ;
}

public static ItemStack giveExampleItem (Player player ) {
Map < String, Object > parameters = new HashMap <> ( ) ;
parameters. put ( "playerName", player. getName ( ) ) ;
ItemStack stack = ItemBridge. getItemStack ( "myPlugin:TEST_ITEM", parameters ) ;

player. getInventory. addItem (stack ) ;
}
}

Just make sure you document that you're using it and if your plugin supports/requires using arguments!

Plugins that support ItemBridge
Custom Items (prefix "CustomItems:" or "cui:")
Quality Armory (prefix "QualityArmory:" or "qa:")
Knokko's Custom Items (prefix "KnokkosCustomItems:" or "kci:")
More coming soon!

If you're a developer and want your plugin included here, send me a PM!

Commands & Permissions
You can use /ib, /itb, or /itemb in place of /itembridge

/itembridge get <item> [amount]
Permission: itembridge.get or itembridge.give

Gives you [amount] of the item <item>. Make sure to format <item> like "key:item_name", like "saved:myItem" or "cui:greenBeet"

/itembridge give <player> <item> [amount]
Permission: itembridge.give

Gives <player> [amount] of the item <item>. Make sure to format <item> like "key:item_name", like "saved:myItem" or "cui:greenBeet"

/itembridge save <name>
Permission: itembridge.save

Saves the item currently in your hand as an ItemBridge item, so that it can later be accessed by you and other plugins using "saved:<name>" or "itembridge:<name>".

Saved items are stored in the "saves" folder in yml format, so if you run /itembridge save myCoolThing, then the file "saves/myCoolThing.yml" will be saved in your ItemBridge plugin folder, and you'll be able to get the item using "saved:myCoolThing", "itembridge:myCoolThing", or "ib:myCoolThing"

/itembridge drop <world> <x> <y> <z> <item> [amount]
Permission: itembridge.drop

Naturally drops [amount] of <item> in the world <world> at the position <x>, <y>, <z>. If you don't provide the [amount] argument, 1 of the item is dropped.

Make sure to format <item> like "key:item_name", like "saved:myItem" or "cui:greenBeet"

Donations
Any and all donations are appreciated! They help me bring updates to ItemBridge!