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.

Exact matches

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.

Similar matches

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.

Bundle matches

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.

No matches

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:

1. exact match (as described above) to the item frame item.
2. exact match to any of the items in a shulkerbox in the item frame
3. item tag match (as described above) for nametag in item frame
4. item tag match for nametag in a shulkerbox in item frame
5. similar match (as described above) to the item frame item.
6. similar match to any of the items in a shulkerbox in the item frame
   
7. item frame containing the default item (typically, carrot on a stick)

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.

CONFIGURATION (config.yml)

When the plugin starts, it will create its configuration file, config.yml in its configuration directory, SmartItemSort, if it does not already exist. The plugin will never modify an existing config.yml even when new configuration options are added to the plugin. (This is so that any helpful comments that an administrator has added to config.yml are not lost as Spigot's API for modifying configuration does not preserve comments.) Even so, the plugin will create/overwrite a config.example.yml every time it starts. An administrator should never modify this file as changes will be routinely overwritten. This latter file serves as documentation of all configuration items that the current version of the plugin supports (and their default values if unspecified.)

INTEGRATIONS
This plugin integrates with some other plugins. This is especially useful with plugins that enforce land claims so that items are only ever teleported to locations under the same control as the teleport source.

Known Integrations

• SmartItemSort-GriefPrevention - enforces GriefPrevention land claims
• SmartItemSort-WorldGuard - enforces WorldGuard regions

KNOWN ISSUES

- The plugin has limited support for enforcing land claims. This plugin's author is open to adding integrations for popular land management plugins as needed. Even if this author declines to develop an integration, it is still possible to integrate with less popular plugins. Example code (see SmartItemSort-GriefPrevention) is publicly available.

Controlling Use Through Permissions

The plugin itself does not attempt to implement strong control over use of smart item sorters using permissions. Instead, for situations in which more control is desired, the plugin can be configured to be activated only using a custom, uncraftable, block instead of the default ender eye item. Once this is done, the server administrator could use other resources to control the creation and distribution of these custom activation blocks.

If you wish to strongly control who can create smart item sorters then you will want to choose an activation item (the item placed in the item frame) that cannot be gathered or crafted from the world through normal means. In this case, you can set the activation item to a serialized ItemStack specification in the config.yml. Below is an example that forces the use of an eye of ender with a specific descriptive "lore" and plugin-specific NBT data. The plugin-specific NBT data can be added with the /smartitemsort item mark command. Once the custom item configuration has been added to config.yml and the plugin reloaded, use the /smartitemsort item give command to get this block in-game. The use of the give command itself is controlled with the craftmatic.command.give permission.

NOTE: The above example was generated on Spigot 1.17. The serialized form can change with each Spigot version and may necessarily be different in other servers.

Although the activationItem configuration item can be created and edited by hand, it is not recommended. Instead, the admin should create the item in-game using other plugins to edit the item name and lore as desired. The " /smartitemsort item mark" command can also be used to add additional NBT data to the item that cannot easily be manipulated by other plugins. Once the item has been completed as desired, use the " /smartitemsort item show" command to generate and display the necessary org.bukkit.inventory.ItemStack value for the activationItem configuration. The admin can then copy and paste the generated value into config.yml and reload the plugin.

COMMANDS and PERMISSIONS

All commands are implemented as sub-commands of the /smartitemsort command.