ItemMail

ItemMail provides an easier way for players to trade. The MySQL integration is great for cloud servers.

Features

• Players can send items to other players, as well as request them
• Friendly display names! Not sure what color of wool you have? ItemMail makes sure you know exactly what you are getting.
• New serialization system! As of version ItemMail 4, players don't lose any data like words in books.
• MySQL integration, great for cloud servers.

New Data System

There is a new data saving system in version ItemMail 4, items are saved differently, but way more efficiently! This requires a new MySQL table. Everything is done automatically for you, you just need to type one command:

• /im convert

This takes any unread mail/requests from the old table, converts it into the new format, and puts it in the new table! If you've used ItemMail prior to version 4, be sure to run this command when you install.

Full documentation on how the items are serialized can be found at http://www.kill3rtaco.com/wiki/TacoSerialization

Commands

• /im accept [id] - Accept an ItemRequest
• /im convert - Converts old data to the new format
• /im decline [id/*] - Decline ItemRequests
• /im delete [id/*] - Delete ItemMail
• /im mb - View your ItemMailBox
• /im mail-info [id] - View detailed information on mail
• /im open [id] - Open ItemMail
• /im rb - View your ItemRequestBox
• /im request <player> <item[:damage]> [amount] - Request items from a player
• /im request-info [id] - View detailed information on requests
• /im send <player> [item[:damage]] [amount] - Send ItemMail

[id] refers to the number next to each item in a players ItemMailBox or ItemRequestBox

The asterisk is another way of saying all.

Permissions

• ItemMail.admin.convert - Allows a player to run the '/im convert' command
• ItemMail.general.mail.delete - Allows a player to delete a ItemMail
• ItemMail.general.mail.open - Allows a player to open ItemMail
• ItemMail.general.mail.send - Allows a player to send ItemMail
• ItemMail.general.mail.view-info - Allows a player to view detailed information on ItemMail
• ItemMail.general.mailbox.view - Allows a player to view their ItemMailbox
• ItemMail.general.request.accept - Allows a player to accept an ItemRequest
• ItemMail.general.request.decline - Allows a player to decline an ItemRequest
• ItemMail.general.request.send - Allows a player to send an ItemRequest
• ItemMail.general.request.view-info - Allows a player to view information on ItemRequests
• ItemMail.general.requestbox.view - Allows a player to view their ItemRequestBox

Dependencies

ItemMail requires TacoAPI v2.4 or higher to run.

Tips

Permissions

An asterisk (*) can be used to give a player an permission that starts with everything before the asterisk

Examples

• ItemMail.general.* - Gives a player all 'general' permissions
• ItemMail.general.mail.* - Gives a player all permissions related to mail
• ItemMail.general.request.* - Gives a player all permissions related to requests
• ItemMail.* - Gives a player all permissions

Sending Mail

When you have an item you want to send and it fits any of these descriptions:

• It has a custom name
• It has enchantments
• It is a book, and it has words in it
• It is a written book
• It is an enchanted book
• It is leather armor, and it has been dyed

Then you will need to put it in you hotbar, hold it in your hand, and use /im send <player> to send it. If this is not done, some data may be lost, so it is best to use this method. These kind of items can't be stacked anyway, so what do you have to lose?

Unicode Characters

Most MySQL servers will create databases using the latin2 character set (depending on the location). If your server has players that may type/speak a different language, you may want to use the Unicode charset. Below are methods to change the character set to Unicode, depending if you use SQL Buddy or phpMyAdmin

SQL Buddy

1. Find out what database the table is in. This can found be referencing the config.yml for TacoAPI
2. When logging into SQL Buddy, there should be a list of databases on the left under 'Databases'. Select the correct one.
3. Navigate to the table 'itemmail'
4. You should now see 'Browse', 'Structure', 'Insert', 'Query' etc. on the top of the page. Click on 'Structure'
5. You should now see a list of column names with checkboxes next to them. Select the checkbox next to 'item' and click 'edit' above the table.
6. On the next page, you will see 'Charset:' next to a drop down box. In the drop down box, select 'utf8'.
7. Click submit.

phpMyAdmin

1. Find out what database the table is in. This can found be referencing the config.yml for TacoAPI
2. When logging into phpMyAdmin, there should be a list of databases on the left.
3. Navigate to the table 'itemmail'
4. You should now see 'Browse', 'Structure', 'Insert', 'Query' etc. on the top of the page. Click on 'Structure'
5. You should now see a list of column names with checkboxes next to them. Find 'item' and click on 'Change' (next to a pencil)
6. Under 'Collation', change it to 'utf8generalci'.
7. Click save.

For Developers

ItemMail has custom events. These events are:

• ItemMailSentEvent - Called when a player sends mail
• ItemMailOpenedEvent - Called when a player opens mail
• ItemRequestSentEvent - Called when a player sends a request
• ItemRequestAcceptedEvent - Called when a player accepts a request
• ItemRequestDeclinedEvent - Called when a player declines a request

If you plan to call any of the following methods -

• ItemMail.send()
• ItemMail.open()
• ItemRequest.send()
• ItemRequest.accept()
• ItemRequest.decline()

Then you will need to take away/give the items as needed (available in TacoAPI, or you can use your own method). The item removal/addition is done inside the appropriate TacoCommand class, not the ItemMail/ItemRequest class. This is done so developers/myself can send ItemMail from a non-existant person. For example, if the plugin uses ItemMail as a type of reward system.

If you plan to use ItemMail in one of your plugins as a type of reward system, it is best to use ItemMail.sendUnsafely() (static method). When this method is used an ItemMailSentEvent is not fired.

Useful Links

ItemMail is an open-source plugin. The source can be found at GitHub