Postal
There is no substitute for personal service.
New
- GPS address plotting and compass navigation, Detailed item shipment.
- New WorldGuard, Towny and Dynmap support. New bulk mailing capability.
Introduction
Postal is a Craftbukkit plugin dependant on Citizens2. It is a messaging system making it possible for Minecraft players to communicate with one another using the book and quill, written book item. These written communications may span worlds. Postal is an animated postal presence that may be added to any Minecraft town, settlement or mailroom. Chests are used as residence mailboxes as well as mail storage in local post offices.
Postal Pages | ||
---|---|---|
Getting Started | Permissions | Economy Support |
Towny Support | WayPoint Editor | System Notes |
Postal Wiki |
Postal Crew
Citizen2 based NPC’s are the Postal crew. They are the postmen spawned and dispatched by Postal. These NPC postmen walk regular routes in towns serviced by Postal post offices. A central post office connects all of the local post offices by teleporting a NPC worker called the PostMaster from town to town, or world to world. This central NPC continually monitors and moves out of town mail to the appropriate destination. The local NPC postman takes it from there. Pickups and deliveries are done on foot, cheerfully. They know how to open and close doors, and they are a wonder on stairs. They are polite.
Addresses
Postal has a two part address system it uses to plot the location of the mailbox it services, as well as define the post office that services the address. A typical address looks like this:
<PostOffice [Address]>
Postal commands generally accept addresses as one word, or two words. If one word is indicated as an address, it is assumed that the subject is a post office. A two word address is a complete address indicating a specific residential mailbox.
The exceptions to this rule of thumb are commands that imply a residence but accept a two word address specifying the post office. /setaddr is an example of this. Invoked with a one word parameter implies that the one word is an address name and Postal is to choose the post office.
There is no built in limit on how many post offices a server may have. The Postal system typically traverses worlds.
New post offices and addresses are created and deleted on the fly. These addresses and post offices are part of a tightly written, hierarchically-structured database. This database is designed to meet the requirements of a dispatcher bent on getting mail delivered efficiently. The post man likes to walk around the town when there is nothing better to do, but get out of his way if there is mail to pick up or deliver.
Geo-Aware
Postal always knows what post office or address you are close to when invoking commands and will be as helpful as possible to relieve you of name details. This help is contextual in nature which makes it possible to use commands without any parameters simply based on your location. Complimenting this ease of use is a command-confirm system that makes it possible for Postal to safely attempt to complete complicated names with just a few characters. This is because you have an opportunity to confirm the completed command with a single ‘/’. If the command didn’t come out right you can simply try again without confirming.
For Towny users, Postal always knows when it is on Towny soil and will defer to Towny hierarchy. All appropriate Postal commands are Towny aware and try to accommodate what Towny players need when used
Creating Addresses
The geographic awareness built into Postal makes it easy to create new addresses. To define a new address the only parameter required is the name you would like to use since Postal will automatically find the closest post office for you. Designing the route for the postman is even easier because Postal will figure out everything based on where you are standing. On a new address you will be teleported to the servicing post office, the beginning of the route, and given a compass pointing to your address. A modern HUD display is included to provide helpful stats while clicking on waypoints. Once you double click the final waypoint the postman will automatically appear using the route you just defined to initialize your mail box.
Finding Addresses
- / TLIST Short for town-list, will present the player with a formatted, alphabetical list of towns when entered without parameters. The closest 3 towns, in order of distance, are also shown. If entered with enough characters to identify a particular town, the addresses of that town are listed.
- / ALIST Short for address-list, will list the addresses of the closest town when entered without parameters. Like /tlist, it will list the addresses of a particular town if entered with enough characters to identify it. The two commands complement each other including details that the other doesn’t.
- / PLIST Short for player-list, lists the closes 8 players, in order of distance when entered without parameters. Along with the listed player is the Postal address he/she is closest to with the compass heading required to get there. If entered with enough characters to complete a player name, Postal will list any Postal addresses or post offices owned by the player.
- / GPS Lists the closest 8 post offices or addresses with their respective compass headings when entered without parameters. /gps may also be given the name of a post office, or an address pair to set your compass to this location.
- / GO Teleports to Postal locations. The type type of location is determined by the number of parameters entered. Entered with no parameters assumes the central post office. One parameter assumes a local post office or town. Two parameters indicates a full residential address. Complicated names are automatically completed, and full named locations, as completed by Postal, are displayed for confirmation before teleportation. These location types may be secured or require owner permission to use.
- Dynmap Postal uses Dynmap if it is installed. All addresses and post offices are plotted and labeled. The active routes and post man locations are shown in real-time.
Navigation
Your compass is calibrated to line up with the standard, Minecraft coordinate system when listing headings with the above commands. These are the same compass directions shown when pressing [F3]. So, with your calibrated compass and the distance and heading combination from the list, you have what you need to navigate to it. This is the way compasses are normally used outside of Minecraft. The benefit of navigating to a destination is that you remain aware of where you are in relation to all the listed destinations, as well as other distance and heading destinations received from other plugins ie: GPS, Pplot and gpsTowny.
Mail and Shipping
Postal letters are based on the written book item. This book will handle up to 50 pages of written correspondence. Item shipping is done with single chests. The two commands used for this have the built-in address finding and completing capabilities described above. Indicating desired addresses is done with the minimum amount of typing. The two commands are: /addr <PO [Address]> and /package <PO [Address]>
On servers that have economy turned on, both of these commands tell you the price of the postage or shipping and give you a chance to confirm it.
Once addressed, letters may be put in any accessible Postal mailbox, and Postal will take it from there. Shipments involve the creation of a shipping label which may be mailed like any letter. Once packaged, the shipment is sign-sealed and indestructible until the post man picks up the shipping label. The post man removes the chest at that point for transport to the recipient.
The recipient of a shipment may refuse the shipment. If refused, the shipment is returned to the sender.
Mass mailings sent to entire towns, even worlds are available to administrators, Towny mayors and post office owners. The /distr command facilitates this.
Capacity Management
Full mail boxes are managed. If the chest is full, the postman will delete the oldest junk mail if he finds one. If that doesn't create the room he needs, he will look for a non-book to delete. If unable to find room in a mailbox, the postman will continue trying to deliver until successful. Mail is otherwise held at the local post office.
Bulk distributions available to post office owners, Towny mayors, and administrators are sent with an expiration date. Regular information mailings therefore do not back up and become undesired clutter
Dispatcher
The NPC dispatcher provides regular coverage and route-walking, oldest next. This dispatcher is also preemptive in that it recognizes mail waiting to be delivered or picked up. The dispatcher manages the route walking schedule to favor actual mail movement over route-walking, or postal presence. Both the post men and the PostMaster are preemptively dispatched to keep the mail moving efficiently.
Chunk Manager
Postal has a chunk manager that monitors chunks required for postal routes. These chunks are automatically loaded and kept loaded. This makes it possible for NPC's to continue doing their job when there is no player in sight. NPC's have a tendency to go to sleep when no player is around. This chunk manager also facilitates the control of spawning monsters on Postal routes. There is a switch in the config file that controls this. By default, Postal routes are kept monster free.
WatchDog
Postal has an evolved watchdog, monitoring system. The Postal workers are vigilantly monitored. It is capable of respawning a NPC worker if something happens to it. It can restart itself if needed. Mail is always backed up. A Server crash or NPC griefing should not result in lost mail. The Citizens NPC’s are pretty reliable on their own.
General Notes
The Bukkit versioning that started early December 2012, applies to all plugins that go outside the Bukkit api to reach the Minecraft api. This started with 145.R1, the first recommended build for 145.
Coincidently, and the cause for much confusion here, The Bukkit api was expanded to include dealing with Book and Quill items. Pre 145.R1 Postal does go beyond the Bukkit api to deal with written books because it has to. Post 145.Ri uses the Bukkit api instead and is therefore exempt from the Bukkit versioning restrictions.
There are only two versions of Postal, delineated by an api improvement not a versioning requirement.
Citizens2 Note: At Citizens build 762 the NPCs underwent navigational, speed refinement. As this relates to Postal there is a modest speed change. It causes the NPCs to move a little slower. It can trigger watchdog activity by Postal since the NPCs don't seem to be on schedule. The fix is simple. Just change the Speed setting in 'Config.yml' from 1.0 to 1.2
Videos
YouTube Getting Started by Hmmcrunchy
@Etsija
Oh, it's documented, but maybe there is something I can do as a shorter reference. Meanwhile, what you are doing in articulating your startup issues will most probably benefit others, and I'm sure it will be appreciated. That is the way I view it, so keep them coming...
The sign is completely optional and does not replace the /setaddr command. The /setaddr command is the admin's tool because it is used to define and create a new address. /setroute is a maintenance tool, and therefore available to owners as well as admins.
Just place the sign on a wall or somewhere as close as possible to the desired chest. The postman will find this sign, distiguished by the brackets and matching, non case sensitve address name between them.
I will look into your teleporting issue.
(edit) If you are using the pre-release Postals in the notes section, you might want to try the 2215 version. I couldn't reproduce your issue, but I did some work on the teleport safety. Hopefully it will not tp you into solids anymore.
Regarding the signs on mailbox: where exactly does it need to be, and do I still have to use the /setaddr command even if I use the sign? Anyway, I guess you could spend a little time updating the documentation for this marvelous plugin. At least a table of all the plugin commands would be excellent. Mind you, /postal does not give me nearly all the commands!
@mcfacilitator
I was standing on "cobble on dirt".
This same happened to me today on two other post offices as well.
@Etsija
Yes, I guess you found a bug. I always said Postal has a killer route editor, but that is not what I had in mind.
If you are able to figure it out, it would help me a lot to know exacly what you were standing on when you did your /setlocal command. And maybe one block below what you were standing on. ie tall grass on dirt, or whatever
Postal does a little work on teleports to make sure you are put at the right height - not too high, or too deep. You apparently found a combo I didn't allow for.
@Etsija
What you can do in dense neighborhoods is label the mailbox with a sign containing the address name in brackets, ie: [108_good_st]. It can also be a subset if the name is too long for a sign line ie: [108_good]. Postal will search up to 10 blocks looking for a mailbox if there is not one at the last waypoint. This is the way to avoid cross-linked mailboxes. Postal does this because residents are constantly changing the mailbox location. Maybe I should make this search distance configurable, or shorter....
Anyway, now for some real bug...for a change...Postal just killed me!
I have defined a post office, and an address a little bit far from the local office. I typed "/setroute office addr", which should teleport me back to the local office.
Instead, it teleported me one coordinate off from the local office's center point - inside a rock, and I started to take hits. Not even /spawn could save me from certain death.
So, something wrong with the teleport or what? Basically, it teleports one coordinate off the local post office's place, and since I have a pretty crowded hut as a local office, it decided to put me inside a wall instead :D
Stupid meeeeeee...found the reason why the postman hasn't picked up my mails from that particular box. Well, it just so happens there is another chest nearby - and I defined my route so badly the mailman walks to this chest instead of the one I meant...so, everything seems to be in order!
(I'll go bang my head on the wall for stupidity now.)
@mcfacilitator
No the postman didn't leave a log, and yes, the mail has been addressed. The mail says "mailed from: [not-processed]", could this have anything to do with the problem?
Anyvay, I used /addr again, let's see what happens.
EDIT: No, wait - the mailbox has exactly the same name as the recipient player. Could this be it?
@Etsija
WG hasn't caused any problems that I have seen. Did the postman leave a postal log? Has the mailed item been addressed? Mousing over it in the chest should reveal the recipient town/adress. Take it out of the chest and use /addr while holding it to fix anything.
Thanks for the info; we'll probably set ownership of the privately-owned mailboxes then.
- - -
Meanwhile, one problem to report: we have our spawn area protected by WG, and in the area, there is a mailbox. Postman Pat comes to the mailbox but does not take the mailed item from the chest; he leaves it there. Something conflicting with the area protection? No errors on console.
@Etsija
Player owned address will automatically limit the mail access to either owner or sender. Anything sent to an owned address will automatically infer the player that owns the address. Another way to limit access is to send mail to a players attention. This limits access to sender or recipient, regardles of geographical location. The only exception besides admin access is sending mail to the attention of a player to an address owned by another player. The owner will always have admin access and will be able to access any mail sent to that owned address. Much of these privileges will come into play with the economy implementation. Such priveleges generally have a cost, determined by the sever admin.
I will consider your /alist expansion. Bt default it tries its best to uniquely complete what it is given as a town. Perhaps it should take a wildcard with a partial name to signal listing all similar addresses rather than asking user to narrow down the town name.
A new pre-release is up in the notes section. Lets you change the postal uniforms in 'config.yml'
Hmm, I think it would be really good to do it so that /alist would accept a wildcard for a town. So "/alist * Ets" would search through all towns and return all addresses beginning with "Ets" (so, my addresses on our server :)).
One more question, related to this: we haven't yet set up ownerships for the player mailboxes. Should we be doing this, ie. does the plugin then prevent anyone else from stealing the player's mail? Atm we have just instructed the players to protect their mailboxes with Lockette signs...
@Etsija
/tlist is meant to be global since it shows all the towns on the server with their respective worlds. /alist, of course, will zoom in on a particular town. How would you like to search globally(?) Maybe tlist could take a [player] parameter and, when present, list the addresses owned by that player, globally. Or, alist could take a wilcard '*' and recusively list all addresses on the server, by town. Could be a bit like listing the telephone book, though.
One question: is there currently a "global" address search existing? Seems a bit of a nuisance to go through all post offices / towns with /tlist and /alist, to find an address.
Wow, I bumped into this plugin yesterday. It is purely awesome. Have to take it into trial use on our server!
@Nyinja
You are very welcome! There is a pre-release available at the bottom of the notes section above. There is also a description of the item shipping in the 'Getting Started' section above. Enjoy.
Thanks for this great plugin I can't wait for item shipping. I really appreciate all of the hard work that went into this plugin.
OK, the poll results say do the item shipping next, and I agree. Btw, it wasn’t a big tally and I want to thank those that participated, and commented.
The economy will be very important for this item shipping because eventually shipping needs to be paid for and merchandise needs to be paid for. I can say the same thing about the current mail system. Pre-stamped books ready to be written and mailed should be available at the post office for a price and the /addr command should be dinging your bank account.
But we want to start seeing items being picked up and delivered by the postman, so I am going to get going on this while keeping the economy issues in mind. The economy implementation will be optional for those that don’t need that type of account tallying. There is no harm in doing it separately.
Here is the concept I currently have; a single chest will act as a shipping container, or box. It should be reasonably close to a designated mailbox, and accessible to the postman. The player loads it up any way he/she wants, but leave at least one open space for the statement. When ready to ship it, the player stands in front of it and invokes the shipping command, probably ‘/package <town> <address> [player]’ A statement containing everything in the chest will be compiled in book form. A copy will be placed in the chest, and another copy will be placed in the player’s hand. To physically ship the chest (virtually speaking) the player puts the book in the mailbox. The statement, later on, will be used to establish pricing.
Postman picks up the box and delivers the statement to the recipient. If the recipient wants the shipment he/she simply enters ‘/accept’ while holding the statement, and poof! the shipment will appear. Type ‘/refuse’ and it is put back by the senders mailbox.
Comments?
btw 2.1 is in the Bukkit approval queue.
The shipping container doesn't really need to be close to the mailbox. Maybe it would be better to not have any requiements about where it is placed for packing and storing until the postman picks it up. It will simply disappear when the postman picks up the mailed statement. But it will re-appear if the recipient doesn't accept it. Shipments will always be somewhere ie: actual possession of sender, possession of postman, possession of a post office, or actual possession of recipient upon receipt.
Written books in the shipment: The statement needs to be there for sure. But a chest full of written books takes some special handling. Written books are not stackable, but, think about a chest full of written books, each 50 pages long. This would take some special handling and I’m not sure if it is really needed. When sending a parcel, the recipient is going to receive the statement first. The recipient will be able to look at a detailed list of the chest contents and decide to /accept or /refuse. It would be nice if a note could be included with the statement. So, when the parcel is prepared with the /package command, the chest will be searched for a written book titled ‘statement’. If found, it will be replaced by the formal, compiled statement, and any text in that book will be included in this statement. Further, other written books may be included in the chest, but the total pages of all the books will have to be less than 45 or so.
@ObsceneNameHere
No problem. The suggestions I am getting just make Postal better. It's up btw.
@mcfacilitator
Thanks dude, Best developer I've seen in a while. You actually want to get things done haha