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
Right now I have no barometer as to Postal version 2.6 usage. I have made it available through a Google file share, but I have no way of knowing if it is being used. The uploads in the Bukkit approval queue are going sit there for only god knows how long.
This 2.6 release is a very important one, and I would like to know if it is actually being used. Besides, too many messages from me only are starting to make me feel like a canary talking to itself in the mirror again.
So please... feedback. Or at least a 'pretty bird'...
New in the Bukkit approval queue. 2.5 was still in the approval queue, so I yanked those versions and replaced them with 2.6. This version is immediately available in pre-release form at the bottom of the notes section above. Enjoy!
Versiom 2.6
CB_1_4_6 version conforms to Bukkit non-version model, therefore rendering it non-version-specific for Bukkit CB_145_R1 (Recommended Build) and beyond. Users running Bukkit prior Bukkit builds need to use the CB_1_4_5_R02 builds of Postal.
New advanced mailbox detection and labeling system. Once a mailbox is identified by Postal a detailed sign is posted on the front of the mailbox. Postal always looks for a signed chest first. If the sign details match the chest is used. If the signed mailbox is not found, Postal falls back on proximity and/or postal log confirmation. This is a far more efficient method of mailbox detection, and serves to clearly identify mailboxes to the player as well.
Shipments are sign identified as such, making their overall roll in the Postal system clearer.
Preemptive mail handling has been expanded to include the PostMaster, or Central postal system servicing local post offices. This replaces the former round-robin, central scheduler and is designed to keep mail moving along efficiently as the number of post offices continue to increase.
An Xmas present for those reading the comments:
A pre-release 2.6 version of Postal. This is a substantial upgrade. The most noticable change is the way mail chests are now identified. Clearly labeled signs now designate Postal mailboxes. All automatic, no compatability issues. A lot of other work, too much to explain here. Enjoy!
(found at the bottom of the Notes section above)
@watarimon
There is a prerelease 1.4.6 version at the bottom of the notes section that has '/postal accept' I will have 1.4.5 R02 a little later.
@mcfacilitator
Thank you, this would be so appreciated
@watarimon
I guess I could put another copy of troublesome commands (maybe all) behind /postal. Ie: /postal accept. This way you could use your own command re-mapper to do what ever you want.
I've started to use your plugin on our server and it's a really fun idea but is it possible to change or add an alias for /accept command? We use mcMMO on our server which also has this command and takes over. I'm not able to accept a package when mcMMO is active :(
maybe /packaccept or something?
Links are up in 'Getting Started'. Pre-releases are at the bottom of the 'Notes' section.
Postal works great with 1.4.6 Use the very latest builds of everything. Postal 1.4.5 RB is fine.
@bobbshields
Postal does a lot of stuff automatically and I realize the documentation, while fairly complete, is not really a good reference. If you walk through the 'getting started' and actually get started, you will see how it works. The chests just need to be near post offices or addresses. Yhe npc will actually seek the chest out, up to 10 blocks or so if it doesn't encounter one at the end of the route.
It shouldn't be crashing your server though. There is probably some sort of a mismatch between Bukkit and Citizens2. There are other possibilites as well with the new, Bukkit enforced versioning. If you can't use the links that are currently provided in 'getting started' you might want to wait for me to get them reorganized to accommodate all the versions folks are currently using. Later tonight or to-morrow morning maybe.
And oh yes... You can simply delete the postal directory, or config.yml. Postal will just rebuild a fresh one for you if you leave it on.
@Jakeio
I haven't tried citizenz2 on 1.4.6 yet. If anyone has, plese chime in. This is because I have have been focused on th rb for 1.4.5 I have taken full advantage of the rb 1.4.5 api and have managed to contain Postal entirely whithin the Bukkit api. This means, as of the new rb 1.4.5, Postal will not be affected by the new versioning Bukkit has forced on the developers. This also means Postal will run like a top on 1.4.6 It is Citizens2 that has the challenge becuase the Bukkit api, alone does not provide what the Citizens2 developers need to give us those amazing npc's.
As for the Bukkit rb, Postal and Citizens2 are running great. The same might be true for 1.4.6 - I just haven't gotten around to it yet. I hope to get things organized for the three different Bukkit types: 1.4.5 R02, 1.4.5 RB, and, 1.4.6 later today. This can be confusing stuff, so I will try to keep it simple with links, etc... I will also make the current work available as pre-release, while the formal versions are in the Bullit approval queue.
I recently installed this for the first time and it crashed my server. It was after i set up the post offices and a couple of addresses. It notified me that there was no PO chest at the local office, so I went there to delete the slab block where i called the command to install a chest - and it took the whole java process out to where I had to cntrl-c. It caused another crash at start up so I removed the plugin.
The instructions say to call the commands "near" the chests but should it rather say on the chests, or where the chest will be installed? And is it safe to delete the data folder to stop the crash on startup?
I'm running 1.4.5 R0.2 for the moment.
Is there any build available for 1.4.6? I just updated and there is a big hole in my server where postal once was...
@Jakeio
There is no limit on post offices anymore. Sounds like you got it going (good job). You need to edit 'config.yml'. Set autostart to true and set the concurrent setting to true as well, especially since you have so many post offices.
It is not clear if you know about yml files, but in case you don't, read up on it a bit. Most importantly, always make a copy before you edit it - it just takes a second. That file represents all of your route work, so treat it as such. Get Notepad plus plus (free) and no tabs allowed in yml files.
Also, I have many towny towns on my server and need post offices for most, can you help me in how to raise the limit or will ie be in the next update or is it already implemented?
I have toggled auto start but it still won't start unless I run /postal start, should I use a command to edit config? P.s. AWESOME PLUGIN
Pre-release 2.25 is available at the bottom of the 'Notes' section. It features enhancements to the commands used to search towns addresses and player ownership. They now have global searcing capabilities described at the bottom of the 'Notes' section. Enjoy.
@Jakeio
I need more information. It is the Postmaster that visits the different towns. If you have incomplete routes, Postal will tell you what is wrong, but won't start until the route has been completed, or deleted. Postal does not need to be running to do this.
The most common example of this is defining a post office (/setlocal) without any addresses. Or, defining an address with /setaddr but not definning the route with /setroute.
If Postal entounters either of these situations on startup it won't start but should give you exact instructions on the console as to how to remedy it.
Pre-release 2.22 is up. Addresses player teleportion issues. Not everyone is effected by this. On teleportion, player would sometimes appear before the world blocks causing player to fall while blocks were generating. This is a timing issue and has been addressed. Please report further problems here.
I seem to be getting an error where a postman doesn't visit certain towns...
@Etsija
I did some more testing on the tp issue and did find some problems when tp'ing into structures. I also did some detailed debugging only to find that the point I am teleporting to is perfect, but for some reason the player ends up a block or two low on floors with air below them. Their feet will be in an air block, but the head is in solid. And, this does not happen consistently - sometimes it does, sometimes not. I have struggled with this issue before, and had the simple solution of teleporting a couple of blocks high. But that will not work in buildings with say, a 2 or three block high ceiling.
None of this matters to the player, of course. I'm just posting this note to indicate that I am not through with this issue. I yanked the last compilation that I thought fixed this. I will post a note when, presumably, this is fixed. May I reccommend creative mode for buildings for the time being(?) :-)