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
@sakura_blades
I haven't seen that behavior before. Any one of the commands you typed should have exited the editor, as well as quitting. And, you say everything is current ie: latest Postal here, and recent developer build of Bukkit....
I would suspect that some other plugin might be hijacking the /exit command, but disconnecting, wait a minute, and reconnect should take you out of the editor too, which it sounds like you did. The other way to exit is to double (left) click the same block.
Can you try a test to eliminate a plugin conflict as a possibility? Ie: rename your plugins directory to 'plugins.sav', create a new plugin directory with just bare minimum and see if the behavior persists? Then just delete the directory, and rename the original back.
Edit: Before you do that, take a good look at the server log and make sure there are no stack traces I should know about.
@mcfacilitator
-facepalms-
I have citizens... My problem, as I stated.. Was that I CAN NOT exit the route editor of this plugin. EVERYTHING else seems to work fine. But once I am in that editor I cannot get out of it despite trying these commands:
I couldn't even logout and get out of the editor, I log back in and I'm STILL in the waypoint editor for this plugin. EVERYTHING I have is up to date, and if it's required I have it installed.
I followed your step by step guide how to set up the plugin on my server (ingame) but:
@sakura_blades
Welcome. I am glad you are giving it a try. Yes, it can be a little complicated getting started, and Postal depends on another, advanced plugin, Citizens2. I will be happy to help get you going. For a start, make sure you have a valid Citizens2 installation. It must be a current dev build, see the link in 'Getting Started'. I am assuming MC 6.2, make sure you are current on Bukkit too.
So, make sure you are able to create NPC's ie: /npc create test
Then, assuming you are still stuck, I need the Postal version you are using, and platform info.
@ThinkOnTheEdge
Right. A wake up call, maybe? I emailed fullwall about it making sure he knew he could count on me if he needed help defraying costs. Apparently the domain registrar neglected to notify the domain owner to renew, and they are exploring options.
These guys do an amazing job maintaining a plugin that needs to bypass the Bukkit api to work. This has become more difficult now that built in obsolescence is enforced by the Bukkit versioning that started last December. It is not only being maintained, but it is getting better and more sophisticated.
I guess the best place to show support would be at:
http://dev.bukkit.org/bukkit-plugins/citizens/forum/
Ya know i have wanted to use this plugin for a very long time, and when I get a chance to install it and am trying to set it up, first of all the Route setup or whatever doesn't work right... THEN when I try to exit out of it, it doesn't let me. I can't log out and get out of the editor, nothin'....
The citizensnpcs.com domain is showing an advertisement and the whois lookup says that the domain registration expired on 20 Aug 2013 18:21:31
That doesn't seem good. :(
Got it! thanks. :) I'll stick it back on when there arent any users online and report back. had to yank it due to the lockette problem.
@madmage1
Bukkit doesn't like the posting of such links, but let's try this slight obfuscation in the interest of getting folks what they need, when they need it. (boilerplate) Bear in mind that this is a cut of Postal not tested or approved by Bukkit. I will look into the the Citizens site.
https://
drive.google.com/
folderview?id=0Bx7tHj365ioxQ3UzX1ZKbGUxMjA&usp=sharing
Update: The Citizens site is being worked on. I think I am also going to submit it to Bukkit as 3.31
can you post 3.35 to dropbox? looks like the citizensnpcs.com website is having issues.
@MarnixxTS
Better language support is on the list; IE menus, messages and maybe even command mapping. Thanks for the reminder.
Working on a Dutch translation right now..
Translation finished!
Link: https://www.dropbox.com/s/vj6z7zjmxjlxc1m/config.yml
I thought I had all the bad interactions with Lockette fixed, but unfortuanately, not. The good news is the fix is available right now as pre-release 3.35 on the Postal page of the Citizens2 site.
Version 3.35
Fixed a bad interaction between Postal and Lockette. A Postal listener was not adequately determining Postal ownership before manipulating the chest – fixed. Affects Lockette controlled chests with signs on the front of the chest. Postal was changing the sign, and opening the chest when it should not be opened.
Postal 3.3 just submitted to Bukkit:
Version 3.3
The /gps command was configured to override any competing /gps commands, for the sake of consistancey. If GPS or gpsTowny is being used, use the alternate commands /gpse and /gpst, respectively. Both are my own plugins, so I am entitled to assign which plugin owns the ‘/gps’ command. Postal was first, so….
Distributions, or mass mailings were changed so not to trigger new-mail flags on the last version. This change was not entirely incorporated. While the mailbox sign was fixed not to show new-mail, the yaml database was still being flagged, thus causing undesired new-mail notifications. Now fixed.
More detailed door articulation added to the npc as it navigates through doors. The npc now looks at the door as it opens and closes the door. This appears more natural. This feature requires the absolute latest version of Citizens2.
Owned mailboxes not properly clearing new-mail indicator on Postal sign. Fixed. ‘[Postal_Mail]’ on the top line of a Postal sign’ed mailbox is normally green. When the mailbox contains unread mail, it turns red. This should clear when the chest is opened by a qualified player. Owned mailboxes can only be cleared by the owner (not even an admin can clear it), Server mailboxes may be cleared by anyone.
Waypoint editor expansion. Complementing the recent /move command facilitating mid route moving of waypoints, out of sequence, are two new commands: /insert and /remove. As they imply, these commands may be used anywhere on a route. A good example of where /insert is very valuable is a long, detailed route where the point between door pairs was forgotten. In previous versions of Postal one would have to sequentially backup until the desired part of the route is reached, and add the waypoint, then do the route again.
Also added to the route editor is a waypoint inquiry command which is just the ‘/’ (forward slash) alone. Once invoked, left clicking existing waypoints will report the formal sequence number. Dense and complicated routes sometimes get disorienting, this is a good tool to verify sequence.
The waypoint editor has basic /first /mid and /last commands to roughly position on a route. Complimenting these is a new ‘/pos <sequence number>’ command facilitating precise positioning, instantly via teleport.
/setroute behavior has been modified. If invoked using the proximity sensing by simply invoking it without parameters, near an address, it will only move the player to the last sequence number if the route is not complete, or new. Invoking /setroute with parameters will only move the player closer to the route if he/she beyond visible range of the nearest waypoint on the route, or if the route is not complete. While the sequence control of waypoints is crucial, the editing methods are now not sequential, thus eliminating the need to start players at the end of a route.
Postal was accepting correctly id’d chests past the defined search_dist in the config file. Changed to strictly honor this setting.
New config file setting ‘allowed_geo_proximity’ specifies the maximum distance a player may be away from a Postal object when invoking a command using proximity sensing. Ie: /setroute, /showroute, /setowner….
/setaddr and /setlocal commands changed to enforce placing chest to be the mailbox or mail storage, first. A better practice, and eliminates potential confusion during route definition.
/setroute and /expedite now automatically open the indicated route, if currently closed. Often the dispatcher will close a route while it is being worked on because it is found invalid. Now the finishing of a route or the explicit /expediting of a route implies that the route should be open.
Additional change to /setaddr and /setlocal commands. Sign is placed on the chest immediately upon successful completion of the command. This is another measure designed to further decrease potential confusion about who, or what plugin owns the chest. /setaddr now requires the target chest to be placed in advance, and the player must be within a couple of blocks of the chest. This is the best time for Postal to claim ownership of the chest. There are further restrictions placed on what constitutes a valid chest described below.
In consideration of other plugins that use signs to manage chests, Postal now checks the validity of a target chest before it will attempt to use or manipulate it in any way. if a chest has a sign anywhere on it or adjacent to it, and it does not belong to Postal, Postal will not use it or do anything with it, regardless of what is written on any of the signs. IE: Before using chest, and already known that it is not Postal’s - check N,S,E,W,U, D for a sign and don't use if a sign found. If inventory slots > 27, find other half, and do the same thing.
Added to the /package blacklist is any chest with a sign on it, or adjacent to a sign. This is griefer prevention.
Distributions were unnecessarily being protected. Fixed. Now available to anyone with mailbox access.
Postal shipments not effectively sealed. Fixed. Shipments are inaccessible and unbreakable to everyone unless the original shipper is in hand.
@xanderortiz
Good question, but I don't have the answer. You might want to consider, resources permitting, making an entire second copy of your server setup and put in on another port.
@HammerHedd
If it is a server mailbox, anyone should be able to access the distributions unless general mailbox access is turned off with 'private_mailboxes' in the config file. Owned mailboxes are subject to the rules of ownership permissions that start with the actual owner, and allow admin authorities as well. I will test this as an unprivileged user to make sure it is working right.
Edit: Upon testing with low permissions I found that distributions were indeed being unnecessarily protected. Fixed in the current pre-release. I consider distributions junk mail. Nothing personal about them Expendable.
@Elfsovereign
When you say 'latest' are you talking about the latest here on Bukkit, or the pre-release 3.3 on the Citizen's site?
Please let me know because I am on the verge of submitting 3.3 to Bukkit, and don't want a nagging problem like that in it.
Looking at the release notes, I think the final fix is in pre-release 3.3.
To disable the incremental mail report set 'new_mail_secs' in the config file to 0.
If someone can't read letters from a general distribution, is it probably a permission problem or am I just sending it wrong?
@mcfacilitator
I will try to make time to do the plugin test you mentioned, but it will be a while since there are always lots of players on my server. Until then, can you tell me how to view all the errors in full? Like you know how the log says "...20 more." How do I view those 20 more? I'd like to first view those and see if the answer is there somewhere. Thanks.
@mcfacilitator
I am running the latest. Issue still present.
@HammerHedd
Heartbeat can be set to 'auto' and let Postal calibrate it for you.. You can just see what Postal comes up with for your system. Or, just set it to 70. Go higher if you don't mind slop in the scheduling. Don't worry about the stability reports - only important to the developer.