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
Just the bleeding edge weather report... I'm back to the current Citizens2 build which is 597. Can't use builds 585 through 596 due to navigation issues. I will update the link in Getting Started.
@mcfacilitator
thanks for the info
Postal 1.91 is in the Bukkit approval queue.
Use the version of Citizens2 linked in 'Getting Started', or earlier.
In addition to what has already been indicated about 1.9; it has a new UI that has been in the works for a while, but finally ready for use. When entering commands the user is now given a chance to confirm what was entered. This is particularly important on Postal because of the extensive name completion it attempts. a couple of characters of a name may expand to a full 14 charecter name if Postal can determine uniqueness. It was difficult to fully implement the name completing without giving the user some way to confirm it. Confirming is a simple matter of entering '/'
No compatability issues. Enjoy!
@yurikoma
Thanks for the pastie, that was very helpful. A relatively new feature of /setroute is to automatically promote the schedule of the route just edited so you can see the result of your edit. New routes are different because they are not live until Postal is restarted, but the schedule promoter was not expecting this. It is now. Your editing should have been ok. Postal just blew up trying to advance a schedule that didn't exist (yet). Now, there is a good reason to put 1.9 up....
Stopping Postal for creating new routes on 1.8 is a good work around. Editing existing routes, live, should not be a problem. Postal is designed for live route editing. I want to encourage live route editing. We want to be able to allow players designated as owners to edit and manage their own routes. Server administrators can't have users starting and stopping Postal.
I noticed that navigation seems to be broken on the citizen2 development builds past build 584. Here is a link to the version I am working to right now:
Build: 584
I am going to stay with it until something changes. That build is just a few day old. Anything before it is fine as well. Not to worry, this pretty normal stuff with bleeding edge, developement builds. It is not a problem either, if you know about it, hence this message.
I am going to keep a direct link to the version of Citizens2 I am working with at the top of the 'Getting Started' page here. I will keep it up to date. That way everyone will know exactly what the developer is using and testing on.
@mcfacilitator
the idea i had was
"the purchase of mailable raw materials like a stamped letter, ready to be written and put in a mailbox"
the main world i am using this on is a survival one, so not everyone had enough materials to make the book, so it would be great if they could buy them from the post office.
(another plugin could probably do the job as well, but i was thinking it would fit in well here)
EDIT: lol don't hold back on updates, i'm sure they won't mind, much,
i voted for both, but i would say items would be the most fun and helpful for my players
EDIT 2: i am having an issue, i created my first address fine, but when i try to do the second one i get this when i exit the path editor http://pastie.org/5465503
EDIT 3: dw i found out what it was, you can't change routes while postal is started, works fine after i stop it
Please ding the vote above. Postal will have both, but each is equally complex and must be focused on individually. What is your most important need right now.
Comments are very welcome and make me feel less like a parakeet talking to itself in a mirror.
Well...., yes - another update. Everything up there is good, mind you. 1.9 is probably the last cut prior to an economy implementation. But I am wearing out the Bukkit folks with my updates, so I am going to sit on this one for a little bit unless I see interest or need in some of its new features.
It addresses technical interaction with Citizen2 npc's that caused the postal workers to temporarily stop working, or slow down. Not a problem though since Postal is able to nudge them back to work. This only occurs when players leave an area, or the game. Postal was probably the only manager that noticed this.
1.9 has an awsome (that's right, awsome) route editor. It uses both mouse buttons similar to the Citizens2 path editor. It has it's very own command processor, completely dedicated to route design. Once in the editor there is no longer any need to preface editing commands with '/setroute'. There is actually no need to enter any editing commands since right clicking the last waypoint deletes it and double clicking your final waypoint finishes and exits the route editor. Waypoints are highlighted with redstone dust as you create them. When editing existing routes, the existing waypoints are highlighted for your inspection or modification. This editor was built and designed by someone that uses it.
I don't mean this as a tease (ha!). But I really don't want to add any unnessesary work to the Bukkit workload, you know, the folks that make Postal possible.
@yurikoma
Good, you found 'postal.admin'. I put that in for servers like yours. Version 1.8 (waiting for approval) has a full set of permission nodes. It also has player ownership of post offices, addresses, routes and mail making contextual, permission elevation possible. It also makes private mail possible, but optional.
So your economy idea about buying letters from the post office. Would that be like paying for delivery of a letter addressed to you, or is that the purchase of mailable raw materials like a stamped letter, ready to be written and put in a mailbox?
A couple of ideas I have are: Post offices may be privatized like UPS, or Fedex. Also, should Postal integrate with Towny?
is it possible to add a feature where players can buy letters (writing books) from the post office
also could we get some permissions plz, i don't want anyone on my server to need to be op.
Edit: dw about the permissions, i found postal.admin in the plugin.yml
@nhoclesnar
That is what it is all about, and thanks, I like to hear that. I guess most people do crossword puzzles.
I like the Citizen2 NPC's. They are hard workers with good attitudes. There have been rumblings though. Oh yes, they make it look like Bukkit, or Minecraft issues, but I think I know what is going on. I think they are trying to unionize. They already have civil servant protection, what more do they need(?) I think I better try to get the economy stuff designed and implemented before there is a collective bargaining push.....
@mcfacilitator
lol inspiration is a very good thing for a developer. I'm glad that you enjoy developing this plugin. I want you to know that we enjoy using it as well :)
Version 1.8 has been upload and is in the Bukkit, approval queue. Sorry about the frequency of the updates, but each one has important additions and each one appears solid enough for me to post. What can I say?, when I am inspired, I am inspired.... All is backward compatable. Just drop in the plugin directory and use your existing work. One change, however, If you use signs with [mail] to direct the NPC to a particular chest just change it to [po_name] or [address_name] instead.
1.8 probably deserves a higher number, but I want to save 2.0 for the time I believe Postal is reasonably complete. The only thing it is missing right now is the economy implementation.
This new version has player ownership integrated into it and implemented. Postal was designed for this. Mailboxes and mailed books are now protected and secure. There is now a permission node for each Postal command. The details are in the release notes, and I will be updating the documentation here reflect the new features as I have time.
Now that post offices and addresses may be owned and the mail is secure, this is a good time for ideas on how the economy should be implemented.
@CJHacker
Thanks for the pastebin. No problem preventing that. I just uploaded a pretty big update and it is in the approval queue. 1.75 It automatically fixes your issue. But please keep me informed if you see it again. This upate lays the groundwork for the permission system and player ownership system, detailed in the release notes.
I have some ideas I want to implement in the waypoint editor to make it more visual and intuitive. I also want to use both mouse buttons, consistant with the citizens path editor. But I figure it does the job right now. I better finish player ownership, permissions and mailbox protection first.
@mcfacilitator
I am using v1.72 when this came up. I rebuilt them and so far they seem to be working fine again. I'll see what happens after a reboot or two. One thing I did notice, is if you try to Undo the route too far, it comes up with this: http://pastebin.com/UEyNqd89 Not sure if that's something you can catch in the code or not. Would be nice to throw a message stating that it is already at 0?
Keep up the great work!
@CJHacker
Thanks. Are you running a version of Postal that is earlier than what is posted here on Bukkit? That is a symptom of an earlier version and I would like to know if it is still possible for this to happen.
Go to each address being flagged on the console and remove all of the postal logs. '/postal admin' allows you to bypass the otherwise indelible nature of the postal log. Then use '/setroute' on that address and enter '/setroute undo' while in the waypoint editor to undo the last waypoint, or two. Now re-click the final waypoint(s) making the final waypoint near the front of your mailbox.
This should solve the problem. If it doesn't - I want to know :-) The above must be done with a current version of Postal.
This is an excellent plugin and a great use of Citizens! It was pretty easy to set up, and they were off and running. Lately though, I noticed I've been getting a lot of this in my console:
02:18:31 [INFO] Found wrong Postal Log at: Spawntown, 100_Sam_Court Replacing.
Along with this, some of my mailboxes now have 4 log books in them. Is there a way to clear out log books, and do you have any ideas why It keeps finding the wrong log books?
Thanks! Keep it up!
@n33dy1
I went to great pains to make the mail more secure and reliable. You are the second person to ask me for something different. :-) If I understand this request it would appear that stopping the mail might be part of a challenge in some game environments.
The current version of Postal will would probably take unfair advantage of players since the NPC's are monitored and will simply re-spawn with backup mail if destroyed. I do think it reasonable to have a way to turn off the preemptive mail handling. This would slow the mail down and cause everything to process sequentially. I suppose the watchdog could be switched off as well. Btw, there is a new command on the last version that lets you do the opposite. 'postal expedite' will push a specific route as next.
I have been thinking about another Sentry traited version of Postal called something like go-on-make-my-day Postal. Try to stop the mail..... Postmen going postal....
@InfroCZE
My current unreleased version has a 'postal.admin' permission node as an alternative to op. It will go up in a day or so. If this is urgent for you, let me know. I can get it to you somehow...
Can you make it so sometimes it takes extra long for a player to get a message and sometimes the messages don't go through at all? For realism.