Special Items API 1.0

Helps manage items with custom data.

  1. ralitski
    Special Items

    The Special Items API helps developers manage items with custom data and properties. It also has a few commands that can be helpful on their own.

    • Keep track of special items and their properties using a permanent data tag system, backed by Minecraft's NBT item tags
    • Wraps minecraft source code, so plugins using this API never have to deal with messy, obfuscated, unstable code
    • Adds commands that can modify items (both special and regular)
    The API

    For full documentation, see the Special Items GitHub page.

    The Special Items API is rather simple; it does not catch any events, does not handle any special commands (except the 5 coveredbelow), does not embed itself anywhere into spigot or minecraft, etc. It is simply an interface to register and recognize special items, and to interact with their data.

    The basis of the API is the SpecialItem interface (in package
    com.ralitski.mc.bukkit.items). To begin using the API, create a class that overrides this interface, then register it with the SpecialItemManager instance found in the plugin's main class, SpecialItemPlugin. Example:
    SpecialItemPlugin.getInstance().getItemManager().registerItem(new MySpecialItem());​

    Then, any time you are interacting with an item (such as by catching an event) that you may want to do something special with, you retrieve a SpecialItemInstance from the SpecialItemManager like this:
    SpecialItemInstance specialItem = SpecialItemPlugin.getInstance().getItemManager().getSpecialItem(myBukkitItemStack);​

    Or you can use the SpecialItemInstance shortcut:
    SpecialItemInstance specialItem = SpecialItemInstance.getSpecialItem(myBukkitItemStack);​

    Both of these methods will return null if the ItemStack you pass is not a special item. If you wish instead to create an item, you may use these two (identical) methods:
    SpecialItemInstance specialItem = SpecialItemPlugin.getInstance().getItemManager().createSpecialItem(myBukkitItemStack);​
    SpecialItemInstance specialItem = SpecialItemInstance.createSpecialItem(myBukkitItemStack);​

    These methods will never return null. If the ItemStack you pass is already a special item, they will return the previous SpecialItemInstance, rather than overriding the data.

    Once you have a SpecialItemInstance, you have access to the item's custom data. You can use SpecialItemInstance.getTag() to get a TagCompound (an NBT tag wrapper) that contains all of the item's special item data. You can then get and set your own data on this compound tag, and it will stay there forever (unless you purposely remove it). You do not need to save the data yourself; it is saved automatically, and can be accessed instantly.
    In fact, you don't need to save any data to use this API; you only need to register your SpecialItem type, then use your special items when you want to. You also don't need to worry about when you register your SpecialItem, as the type is identified only when the API is called, and the item data will not be damaged if your SpecialItem type has not been registered. The only note is that you must register your type before attempting to use it, otherwise the API will not recognize it when checking if an item is special.


    All commands are accessed through the "/specialitems" base command.
    The following commands are available:​
    • /specialitems check
      • Permission: specialitems.cmd.check (default: op)
      • Checks if the item you hold is a special item. If it is, it gives you the id of its special item type.
    • /specialitems delete
      • Permission: specialitems.cmd.delete(default: op)​
      • Removes the special item data from the item in your hand.
    • /specialitems clone
      • Permission: specialitems.cmd.clone (default: op)​
      • Duplicates the item in your hand, along with all of its data, and places the copy in your hand. This command works with regular items and special items.
    • /specialitems rename [name]
      • Permission: specialitems.cmd.rename (default: op)​
      • Sets the name of the item in your hand. The percent symbol (%) can be used for text color and formatting codes. This command works with regular items and special items.
    • /specialitems lore [index] [lore]
      • Permission: specialitems.cmd.lore (default: op)​
      • Adds lore to the item in your hand. The lore is set in the specified index (starting at 0). The percent symbol (%) can be used for text color and formatting codes. This command works with regular items and special items.

    To install, simply drag the jar file into your plugins folder and run your server. :)
    If you're a developer wishing to use this API, you can visit the GitHub page or simply download the jar and add it to your dependencies-- the jar file contains all of the sources (including documentation).


    Let me know if you're a developer using this API, especially if you have some comments about usage.
    Also check out my Command Items plugin, which uses this API.

    Here's a basic demo of the commands included in the plugin: