# ItemExchange
ItemExchange is a Minecraft server plugin that allows players to up in-world shops, which can be setup to have multiple
exchanges and donations if so desired.
**[Video tutorial of the basics](http://www.youtube.com/watch?v=uLIy3UlvAz0)**
## Browsing
You can browse by punching a shop block. You will then be presented with exchange information. You can cycle through the
exchanges with individual punches to the shop. If you wish to purchase or donate, punch the shop with the input item in
hand. It's recommended that you cycle through exchanges with an empty hand, otherwise you may inadvertantly purchase
something that happens to have the input you had in your hand.
*(The sign in the image is not necessary for the shop to work, nor is it created by the shop)*
## Creating a shop
Shops allow you to sell items and request donations. You do this by creating exchange rules that define the inputs and
outputs of exchanges, or just inputs for donations, will match with items.
An ItemExchange shop is any chest or dispenser with exchange rules inside. Exchange rules consist of stone buttons that
Item Exchange has attached extra information to. Anyone can use Item Exchange to generate these buttons, to make their
own shop with.
An exchange rule shows (almost) all of its information in its tooltip. To increase usability, the English displayed name
is used in place of the Bukkit material name and durability value, wherever possible.
A single exchange rule is either an input rule, defining items that the shop accepts, or an output rule, defining items
that the shop gives in return. A single exchange consists of one input rule and one output rule. These are paired by the
order that they're held in the shop's inventory; the first input rule is matched to the first output rule and so on.
The stone button items that represent the exchange rules are created using the **/iecreate** (or **/iec**) command.
There are three ways of doing this.
- Look at a chest or dispenser containing two different types of items (it's okay if they're spread across multiple
stacks), and use **/iec**. This will create an input rule matching the first item type and its quantity, and an output
rule matching the second item type and its quantity. Both are placed inside the container, so this shop is immediately
ready to be stocked and used.
- Hold an item in your hand, then use **`/iec `**. This will create an input or output rule matching
the held item, and its quantity
- Use **`/iec [amount]`**. This will create an input or output rule for the specified item,
and optionally the specified amount.
For the second and third options, you need to make sure you have both an input and an output exchange rule, then place
them in a suitable container to form an exchange. By adding more input and output rules, you can add more exchanges to
your shop, but keep in mind how they are paired.
Remember to reinforce your shop!
## Editing an exchange rule
An existing exchange rule can be edited using the **/ieset** (or **/ies**) command. This is the only way to access some
advanced features. Using this command will edit the exchange rule held in hand.
- **/ies commonname** (or **c**) **<common name>** changes the item in the exchange rule to the one specified by
its common name.
- **/ies material** (or **m**) **<common name or ID>** changes the item in the exchange rule to the one
specified by its common name or ID, without changing the durability.
- **/ies durability** (or **d**) **<number>** changes the durability of the item exchanged.
- **/ies amount** (or **a**) **<number>** changes the amount of the item exchanged.
- **/ies enchantment** (or **e**) **<enchantment rule>** adds an enchantment restriction to the exchange rule.
Enchantment restrictions have the format of **<+/?/-><enchantment><level>**. **+** makes the enchantment
required for the item, **-** makes it forbidden, and **?** removes the restriction. **level** specifies which
level the enchantment should be. **enchantment** needs to be one of the following case-sensitive codes:
- **E** for Efficiency
- **U** for Unbreaking
- **F** for Fortune
- **ST** for Silk Touch
- **S** for Sharpness
- **Sm** for Smite
- **BoA** for Bane of Arthropods
- **K** for Knockback
- **FA** for Fire Aspect
- **L** for Looting
- **Po** for Power
- **Pu** for Punch
- **Fl** for Flame
- **I** for Infinity
- **P** for Protection
- **FP** for Fire Protection
- **BP** for Blast Protection
- **PP** for Projectile Protection
- **FF** for Feather Fall
- **T** for Thorns
- **R** for Respiration
- **AA** for Aqua Affinity
- **DS** for Depth Strider
- **FW** for Frost Walker
- **LS** for Luck of the Sea
- **Lu** for Lure
- **M** for Mending
- **SW** for Sweeping Edge
- **CoB** for Curse of Binding
- **CoV** for Curse of Vanishing
For example, **/ies e +P5**, followed by **/ies e -T1** would specify the item needs to have Protection 5, but is not
allowed to have Thorns 1. Note that if the exchange rule is set to disallow all enchantments not explicitly required (
see below), forbidding an enchantment is redundant.
- **/ies allowenchantments** sets the exchange to allow all enchantments not explicitly specified by **/ies enchantment
**.
- **/ies denyenchantments** sets the exchange to disallow all enchantments not explicitly specified by **/ies
enchantment**. This is the default setting for newly created rules.
- **/ies displayname** (or **n**) **[name]** sets the display name of the item in the exchange rule. If used
without a name, it only matches items with no display name. A display name is a name given to an item by an anvil.
- **/ies lore** (or **l**) **[lore]** sets the lore of the item in the exchange rule. If used without any lore
specified, it only matches items with no lore. Multiple lines of lore can be entered by placing semicolons (;) in
place of line breaks.
- **/ies switchio** (or **s**) toggles the exchange rule between input and output.
- **/ies group** (or **g**) **[group name]** restricts an exchange to members of the specified Citadel group. If
no group name is given, it removes the group restriction. This only works on input rules.
The amount of an item specified in an exchange rule can also be increased or decreased by shift left clicking or shift
right clicking on the exchange rule respectively.
## Bulk exchange rules
It is possible to merge multiple exchange rules into one item by putting them in a crafting grid together. This will
create a bulk exchange rule. Bulk exchange rules can have more exchange rules merged into them, including other bulk
exchange rules. This means any number of exchanges can be stored in a single item, which in turn allows a shop to hold
any number of exchanges while only using one inventory slot.
The order of all exchange rules inside a bulk exchange rule is determined by how the components were placed on the
crafting grid. When merging bulk exchange rules, one is essentially appended to the other.
When forming input and output pairs, all exchange rules in the shop are considered, regardless of whether the rule is
part of a bulk exchange rule or not. The first input rule is matched to the first output rule, the second to the second
and so on, even if they are not in the same bulk exchange rule.
As an example of that, a chest containing only an input rule for 1 stone, and a bulk rule that contains an input rule
for 1 wood and an output rule for 1 charcoal, in that order, will have an exchange selling charcoal for stone. The wood
input rule cannot be matched to anything, and won't be a part of any exchange.
When a bulk exchange rule is dropped onto the ground, it splits into its component exchange rules.
## Redstone support
If there is a button attached to the block behind the chest, it will emit a redstone signal on a successful transaction.
This currently only works for chests.
