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
15:00:26 [INFO] chris012696 issued server command: /setlocal threldom 15:00:26 [SEVERE] null org.bukkit.command.CommandException: Unhandled exception executing command 'setl ocal' in plugin va_postal v2965_146_plus at org.bukkit.command.PluginCommand.execute(PluginCommand.java:46) at org.bukkit.command.SimpleCommandMap.dispatch(SimpleCommandMap.java:18 9) at org.bukkit.craftbukkit.v1_5_R3.CraftServer.dispatchCommand(CraftServe r.java:523) at net.minecraft.server.v1_5_R3.PlayerConnection.handleCommand(PlayerCon nection.java:965) at net.minecraft.server.v1_5_R3.PlayerConnection.chat(PlayerConnection.j ava:883) at net.minecraft.server.v1_5_R3.PlayerConnection.a(PlayerConnection.java :840) at net.minecraft.server.v1_5_R3.Packet3Chat.handle(Packet3Chat.java:44) at net.minecraft.server.v1_5_R3.NetworkManager.b(NetworkManager.java:292 ) at net.minecraft.server.v1_5_R3.PlayerConnection.d(PlayerConnection.java :109) at net.minecraft.server.v1_5_R3.ServerConnection.b(SourceFile:35) at net.minecraft.server.v1_5_R3.DedicatedServerConnection.b(SourceFile:3 0) at net.minecraft.server.v1_5_R3.MinecraftServer.r(MinecraftServer.java:5 81) at net.minecraft.server.v1_5_R3.DedicatedServer.r(DedicatedServer.java:2 26) at net.minecraft.server.v1_5_R3.MinecraftServer.q(MinecraftServer.java:4 77) at net.minecraft.server.v1_5_R3.MinecraftServer.run(MinecraftServer.java :410) at net.minecraft.server.v1_5_R3.ThreadServerApplication.run(SourceFile:5 73) Caused by: java.lang.NoClassDefFoundError: com/palmergames/bukkit/towny/exceptio ns/NotRegisteredException at com.vodhanel.minecraft.va_postal.commands.Cmdexecutor.setlocal(Cmdexe cutor.java:1150) at com.vodhanel.minecraft.va_postal.commands.Cmdexecutor.onCommand(Cmdex ecutor.java:143) at org.bukkit.command.PluginCommand.execute(PluginCommand.java:44) ... 15 more Caused by: java.lang.ClassNotFoundException: com.palmergames.bukkit.towny.except ions.NotRegisteredException at java.net.URLClassLoader$1.run(Unknown Source) at java.net.URLClassLoader$1.run(Unknown Source) at java.security.AccessController.doPrivileged(Native Method) at java.net.URLClassLoader.findClass(Unknown Source) at org.bukkit.plugin.java.PluginClassLoader.findClass0(PluginClassLoader .java:80) at org.bukkit.plugin.java.PluginClassLoader.findClass(PluginClassLoader. java:53) at java.lang.ClassLoader.loadClass(Unknown Source) at java.lang.ClassLoader.loadClass(Unknown Source) ... 18 more Could You Help Me Recognize The Problem?
There were still issues with my system that was supposed to turn off api's if they weren't there, or opted out. There is a pre-release 2.98 up on the Citizens/Postal page that I believe fixes it once and for all. Postal has only one DEPEND and that is Citizens2. The rest are SOFT depends, and I mean that. I want to hear about any issues that make that untrue. The last thing I want to do is inconvenience folks not running the other plugins.
I am close to releasing the big 3.0, and I'm not sure if it makes sense for me to try to slip in this fix here on Bukkit. Hopefully those that need it can use the pre-release that is available right now. Non-Towny users need this, no one else....
Postal 3.0 is in the works:
http://dev.bukkit.org/server-mods/postal/pages/economy/
2.965 has been in the Bukkit approval queue for over a day now, it should be coming up soon. 2.97 pre-release uses the new scoreboard api in the route editor as a HUD display. Turned out nice. Backwards compatibility is retained, however. The scoreboard api is only on the very latest Bukkit builds.
@turtledude01
Be sure and get the most recent cut and check out /gps, /plist. /tlist and /alist. Try them first with no parameters.
A bug has been identified that prevents Towny opt-out from properly taking hold. This only affects users not running Towny. The fix is up on the Citizens2 site on the Postal page. I will be submitting it here shortly.
@mcfacilitator
Thanks for all the cool new stuff, It's nice that I don't have to restart postal now to load new addresses and post offices.
Just another update. Dynmap has been reworked so that address and post office additions and deletions are posted immediately, thus rendering the /postal restart mechanism I have slaved over for months, almost useless. Everything tests out very well so far, and I will get this out very soon. Feel free to use the pre-release to help test.
Other improvements: /setroute no longer needs parameters. It will automatically select the address the player is closest to. The route editor now clears the quickbar so that you have nothing clunky in your hands while designing routes. It places a compass in the middle slot, which now points to the address the player is designing a route for. Exiting the route editor restores the quickbar the way it was.
There is a pre-release on the Citizens2 site, Postal page featuring an improved dispatcher that allows new address creation and deletion hot. No /postal restart's necessary. Preliminary tests look great. It looks like the only thing the restart system is needed for is to update Dynmap.
@WriteEscape
[Server] means un-owned. That is what appears on a mailbox that is on an un-owned plot. Outside of a Towny town /owneraddr may be used to assign an address to a player. Inside a town, Postal follows Towny definitions and will put the plot owner's name on the mailbox if there is one.
You don't have to restart the server, you restart Postal with '/postal restart'. And that is only required for new addresses and new PO's. Editing existing routes and Postal making updates to Towny names is done automatically, and hot.
Post offices are updated each time the postmaster visits it, Addresses are updated each time the postman visits it.
I'm currently working towards making it possible to do everything hot. I didn't realize what I was getting myself into by supporting Towny :-)
That is what a proper Towny implementation is going to take since the whole idea is to make it possible for players to manage all of this without admin help.
@mcfacilitator
Ah ok, Also, i'm currently having to turn my server off and on to get the addresses owned by the town and not the server, is that because, i'm not part of the town i'm in, or just because it defaults to [Server] instead of Unowned which would make more sense.
Any suggestion as to whats going on?
@turtledude01
I must have a blind side concerning Postal restarts. But of course the mayors need assistance activating a new route because that requires a Postal restart. Everything else can be done by the Mayor and plot owner. I limit Postal restart to real admins for obvious reasons.
I really don't want to try to modify the scheduler to implement new routes hot. I'll have to think about that. One of the reasons Postal is so reliable is because it rebuilds the dispatcher every time it is started, or restarted. That is when new PO's and addresses get registered. And, Postal needs to be stopped to delete addresses.
A couple of ideas I have: Limit the mayor to X number of restarts per hour. Or, have Postal restart itself every X number of minutes - the mayor would be able to see when the next refresh is going to happen..... and...., it would only occur if a restart request were made, Postal knows when a restart is needed, so that could be automatic, and the mayor would simply be informed as to when.
Version 2.96 features two important things:
Item shipping with '/package' now includes the details of items being shipped. So, if you are shipping a potion, the potion will be received instead of an empty water bottle. Colored wool will be received instead of white wool, etc....
Secondly is geographical awareness. Commands like /tlist and /alist are more intelligent and do different things base on where you are. /tlist, with no parameters, in addition to giving you a alphabetical list of post offices, also lists the three closest post offices. These close post offices include the distance and compass heading to get there. The compass alignment is the native Minecraft alignment seen when pressing [F3]. The compass automatically aligns to this coordinate system so that it may be used.
Complimenting the geographical awareness is a new command: /gps <postoffice> [address] This command may be used to set your compass to either a post office, or a two part address.
Other improvements have to do with keeping the postal log out of player hands to prevent it from being used as a trading commodity. General tightening up of /postal restart to make it more thorough about resetting itself. And, improvements made in the dynamic waypoint system used to navigate the postmen. Also, built in aliases for often used commands are set up in plugin.yml IE: /gl for /gotolocal, or /pk for /package....
@WriteEscape
An interesting idea, my partner made the same suggestion a few days ago. An NPC servicing the post office while the other is out walking the route. If you need more route servicing the better alternative is another post office.
The postman and postmaster are pretty good about responding to mail delivery and pickups before they do anything else. They can generally handle a lot of routes, efficiently. But, if you have a lot of traffic, it is better to have more post offices to get more, concurrent pickups and deliveries.
The postman can also be configured to spend more time in the post office instead of walking routes with the 'cool' settings in config.yml. You don't have to worry about setting long breaks for the postman because he will interrupt his break to process mail.
this plugin is great, but, can a local post office have more then 1 post man?
@pathetique78
You can't edit 'config.yml. while the server is running. That is normal behavior.
@T3cKno0Kill3R
That may be done with permissions. Only ops or players with 'postal.admin' or 'postal.setlocal' permissions will be able to create a post office outside of towny.
Hello,
This plugin is great :) But when i try to edit the config.yml, for example to change Autostart: 'true', i restart the plugin with /postal start and it's the initial config.yml without my change :( Could you help me please. Thanks and sorry for my "poor" english
Can you make that the locals post office are only in towns of towny?
@nickoos
I can't tell what Bukkit you are running, but I can see you are running a version of Citizens2 that goes back to Feb. To make the issue even more challenging, the version of Postal is a pre-release.
Postal, generally is not very sensitive about Bukkit versions, but you could have a raw cut there, so you could try the latest cut about a half hour ago, or the version here.
I tend to focus on the Citizens2 age because a lot has taken place since Feb. But I can't advise without knowing the Bukkit build. It can't be anywhere near current because Citizens2 build must be very carefully synched with Bukkit builds.
Also, the version of Postal you are running only supports 146 and later Bukkit. If you are earlier you need the file tagged with 145_minus, available here.
Edit: I just noticed that you did indeed give me the file versions - I always try to find them in the log, thank you for making it easy for me. The versions appear to line up OK. So try the newer pre-release, or what is here. The stack trace showed a problem building the array that carries chunk info, and Postal was initializing, so maybe start a fresh install and make sure you platform has enough resources. Let me know. It should work.