Internet Explorer is not supported. Please upgrade to a more modern browser.
Creating Teleport Targets
Teleport targets are formed by placing horizontal item frames (specifically, facing upward) and then placing an item in that frame that indicates the type of items that should be dropped there. It is important that the item frame is facing upward. Vertically placed item frames are ignored. Various levels of matching are performed as further described below. The most common use case is to place the item frame above a hopper. When done this way, the teleported item is picked up by the hopper and then the hopper distributes it as you would expect. Another use case is to place the item frame above a lava cauldron. In this use case, the item quickly drops into the lava and is destroyed. This is very useful for quickly destroying unwanted items from farms. Another use case is to place the item frame on top of a cobweb. This allows individual items the opportunity to combine into stacks before dropping out of the bottom of the cobweb for further processing.
Creating targets for teleporting items can be as simple as placing a horizontal item frame and then placing an example of the item you wish teleported in the item frame. Exact matches occur when the teleported item exactly matches the item in the item frame.
"Item Tag" matches
Minecraft supports the "tagging" of item types. If you set the name on a name tag to the name of a recognized item tag and then place the name tag in the item frame, any items that have that tag will be dropped at that frame. For example, if you place a name tag, named "#candles" in the item frame, then any candle (regardless of color) will be dropped at the frame. Supported tags are documented within the Spigot API tag documentation. It is also possible to create custom tags using datapacks. These can also be referenced using the fully qualified name of the tag. For instance, on my servers I created a tag called "b2c꞉potions" that includes the item type "minecraft꞉potion". This allows my players to send all potions to a common set of chests by naming a name tag, "#b2c꞉potions" and placing it in the item frame. Likewise, tags for splash potions, lingering potions and enchanted books are similarly useful.
There is a special case for teleporting items with NBT data such as enchanted books and equipment. If an item frame with an exact copy of the item cannot be found, a second search will be performed for an item frame containing the same item without any NBT. So, for example, if there was an item frame containing an undamaged, unenchanted diamond chestplate, it would also be a target for any diamond chestplates, even if enchanted and/or partially damaged.
Sometimes you wish to drop more than one type of item at the same location. This is possible by placing examples of all of the items inside a shulkerbox and then placing the shulkerbox in the item frame. The teleported item will be dropped at that item frame if it matches any of the items in the shulkerbox. Bundles can be used similarly if they are available on your server.
If no matching target can be found, the plugin will look for an item frame containing a carrot on a stick (by default, but changeable in the config) and teleport the item there. Finally, if that cannot be found, the item will not be transported at all.
Order of Preference for Matches
Not all matches are treated equally by the plugin. The plugin treats some as better candidates as teleport targets than others. In order of preference the matches are:
When targets of different matching levels are available, only the best ones (that is, with the lowest number above) will be considered as a possible target.
Choosing a Teleport Target
If more than one possible teleport target is found, only the ones that match most exactly will be chosen (according to the order in which they were described above.) So, for example, if a target is found that is an exact match and one is found because it matches an item tag, only the exact match will be considered (because it is more specific). However, if there are more than one target that match equally, then one of them will be chosen at random. This allows high rate farms to easily distribute items over a large number of hoppers to support the rates.
That said, the plugin makes three attempts to teleport each item stack. During the first attempt, the plugin only looks for targets over blocks with an inventory (hoppers, chests, shulkerboxes, etc.). It will then try to place the item stack in each inventory found until either the item stack is fully placed or all of the inventories are full. (Note that if the target item frame is placed on top of a composter on top of a hopper, the plugin will find and use the hopper's inventory during this pass.)
If the item stack was not fully transferred to the available inventories, the plugin will make another pass looking for any targets over blocks that are regular blocks (that is, they do not have an inventory), such as cobwebs or cauldrons (except lava cauldrons). If any are found, the plugin will transfer the remaining items in the stack to one of the blocks found chosen at random.
Finally, if no suitable targets were found in the second pass, but a lava cauldron was found, the remainder of the item stack will be thrown into the cauldron and destroyed.
The second and third passes are so that players can devise various strategies for handling items when the inventories of the first pass overflow.
Creating Teleport Pads
Teleport pads are a convenient way to initiate the teleportation of dropped items within the kill chambers of various kinds of mob and resource grinders. Such pads consist of a vertical stack of specific blocks as defined within the plugin’s configuration. By default, the plugin recognizes two different block stacks for this purpose. This first is a crying obsidian block above a gilded blackstone block. Any dropped item in the block space above the crying obsidian block will be teleported to a matching teleport target within range (128 blocks by default) of the teleport pad. The second block stack that forms a teleport pad by default is like the first one , but with a magma block above it.
The block types for the first type of teleport pad (crying obsidian over gilded blackstone) were chosen to be somewhat challenging to find in survival mode, but not overly difficult. Crying obsidian is also resistant to breaking with repeated chops from a sword or axe and is blast resistant making it ideal as a surface block for a killing chamber. The second type (the one with a magma block as a top block) works well in a completely automatic killing chamber.
Creating Smart Item Sorters
Smart Item Sorters are blocks built from dispensers. Place an item frame on a dispenser and an eye of ender in the item frame and the dispenser will act as a smart item sorter. Once a second, the smart item sorter will teleport an item stack from one of its inventory slots. No external redstone is required to initiate the teleportation of the items. It is completely automatic as long as there are items in its inventory. This block makes it very easy to construct large-scale item sorters.
Where did the items go?
Sometimes items are not teleported where you expect them to go. For example, if players are building close to each other, their teleport pads or smart item sorters might find teleport targets in another player's build area. To help diagnose these situations, a player can hold a tool item (a stick by default) in their main hand and another item in their off hand. If they then use (that is, right-click with) the stick on a smart item sorter or the top block of a teleport pad, the plugin will notify the player in their chat window the coordinates where the item in their off-hand would have been teleported to.
Once players identify that they are interfering with each other, they can move their sorters, pad, and targets to avoid interference. Sometimes (for example in a Skyblock or Plots world), it can be helpful to tune the maximum range that the plugin will search for targets (in config.yml). If the server uses a land management plugin, it can be integrated with this plugin to enforce the land claims between smart item sorters, teleport pads, and teleport targets. There is already a companion plugin to do this for the GriefPrevention plugin.