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
Hey I really love the idea of this plugin but for some reason I cannot get it to work properly I am using the Craftbukkit build number 2788, Citizens 2 build 815 along with your plugin ver 2.996. I followed your getting started instructions. I set central and it seems it sets central office location dunno if it is suppose to spawn an NPC. Then when I go to set local postoffice I get a Internal Error.
[SEVERE] null org.bukkit.command.CommandException: Unhandled exception executing command 'setlocal' in plugin va_postal v2.996 at org.bukkit.command.PluginCommand.execute(PluginCommand.java:46) at org.bukkit.command.SimpleCommandMap.dispatch(SimpleCommandMap.java:189) at org.bukkit.craftbukkit.v1_5_R3.CraftServer.dispatchCommand(CraftServer.java:523) at net.minecraft.server.v1_5_R3.PlayerConnection.handleCommand(PlayerConnection.java:965) at net.minecraft.server.v1_5_R3.PlayerConnection.chat(PlayerConnection.java:883) at net.minecraft.server.v1_5_R3.PlayerConnection.a(PlayerConnection.java:840) at org.getspout.spout.SpoutPlayerConnection.a(SpoutPlayerConnection.java:120) 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 org.getspout.spout.SpoutPlayerConnection.d(SpoutPlayerConnection.java:195) at net.minecraft.server.v1_5_R3.ServerConnection.b(SourceFile:35) at net.minecraft.server.v1_5_R3.DedicatedServerConnection.b(SourceFile:30) at net.minecraft.server.v1_5_R3.MinecraftServer.r(MinecraftServer.java:581) at net.minecraft.server.v1_5_R3.DedicatedServer.r(DedicatedServer.java:226) at net.minecraft.server.v1_5_R3.MinecraftServer.q(MinecraftServer.java:477) at net.minecraft.server.v1_5_R3.MinecraftServer.run(MinecraftServer.java:410) at net.minecraft.server.v1_5_R3.ThreadServerApplication.run(SourceFile:573) Caused by: java.lang.NullPointerException at com.vodhanel.minecraft.va_postal.config.GetConfig.init_local_postoffice(GetConfig.java:1534) at com.vodhanel.minecraft.va_postal.commands.Cmdexecutor.setlocal(Cmdexecutor.java:1221) at com.vodhanel.minecraft.va_postal.commands.Cmdexecutor.onCommand(Cmdexecutor.java:147) at org.bukkit.command.PluginCommand.execute(PluginCommand.java:44) ... 17 more
I even tried different builds of craftbukkit all the way back to build number 2767 R0.1 just like your plugin says its compatible with. Even tried using citizens and postal alone with those two and tried with vault into it too but I get the same error. Please help thank you and also if you guys could get a wiki going that would be great if not maybe I can help in creating a wiki for you guys. Thank you : D Also when I try to openlocal it says dispatch is not running.
My Post Offices Arent Showing Up. The plugin loads correctly and ive used it for awhile but now all of a sudden post offices dont show up when im trying a command that involves using a post office
@CommodoreAlpha
In my example, just substitute Linux or OS X - same thing. It is not possible to run postal without NPCs. The plugin may be installed, but it won't start and run ie: '/postal start' without NPCs.
@mcfacilitator
I'm not saying I stopped Postal and it keeps firing despawn events, I'm saying I'm running Postal, yet have no Postal NPCs (that doesn't mean I won't use it in the future), and Postal still fires despawn events. The reason why I'm still bothered by that event is because it makes no sense, both to you and I. My guess is that NoLagg might be picking up on something else, while thinking it's coming from the NPCDespawnEvent, or something along those lines.
Your explanation for why Citizens fires the ChunkUnloadEvent makes sense. And I know what you mean with your Windows OS example; when I simply open a folder, explorer.exe can sometimes spike to 30% of my CPU for 'no reason'. Though, when you mention "the improvement of the OS as it evolves over time," I don't think Windows is actually evolving much, though that's just my heavy, personal bias against Microsoft and Windows.
Sorry if I was being unclear in my previous comment by the way, and thanks for the explanations.
@CommodoreAlpha
Despawn removes an NPC.
When you say that you are 'irked' by the fact that you 'continue to have no Postal NPCs, and this plugin keeps firing NPCDespawnEvents' makes no sense to me. Postal won't run if it has nothing to do. Are you saying that you stopped Postal ie: '/postal stop' and it is still firing despawns?
btw, in event driven sytems like Bukkit/Minecraft it is not unusual to have redundant responses to any particular event, as there may be any number of subsystems monitoring and responding to specific events. This is expected and managed by the underlying host and does not amount to any measurable overhead. Citizens may very well be requesting its own chunk unload to complete the reason it despawned an NPC.
If you monitored low-level system chatter on a Windows OS, for example, you would be amazed at all the activity generated by just moving the mouse around. It fills screens at the blink of an eye. The effective management of all this activity can be considered a barometer measuring the improvement of the OS as it evolves over time.
@mcfacilitator
I actually don't know any code whatsoever, I just use logic to try to deduce my problems. :D
Anyway, I used NoLagg to monitor sources of lag, and Postal/Citizens/Chunk-Provider all top the list.
I'm not complaining at all about any events by Citizens except for the ChunkUnloadEvent. All the other events (according to NoLagg) take up nearly no resources.
My lag examination from NoLagg says something completely different; that they BOTH have something to do with unloading chunks. (Chunk Provider unloads chunks and saves them to file, while Citizens, at the same time, fires a ChunkUnloadEvent.)
Thinking about this, I'm still curious as ever (and a bit suspicious; not that the plugin is malicious) as to why Citizens even bothers firing a ChunkUnloadEvent. I'm still irked by the fact that, I continue to have no Postal NPCs, and this plugin keeps firing NPCDespawnEvents (and I turned off that NPC Protector option you talked about).
Interesting mod, will have to give it a look
@CommodoreAlpha
Postal monitors the Citizens despawn event and cancels it if Citizens is trying to despawn a postman. If the NPC protector switch is on in config.yml, Postal will also cancel the despawning of any player type NPC's. That switch answered a need that existed months ago and might be obsolete now.
The Citizens despawn event is a response to the Bukkit chunk unload event intended to put portions of the world to sleep that are not occupied by live players - an efficiency mechanism.
Postal despawns NPC's in two areas only. 1) despawning and respawning is the method used to move the Postmaster from location to location, or from world to world because it is more reliable for inter world movement. 2) The NPC watchdog will despawn a troubled NPC as a last resort and try to reset it.
Don't know how you are monitoring the events, but the above is directly from the source code. My understanding is that it is Bukkit, not Citizens, that unloads the chunks.
@Morphan1
Thanks for the tip on 'use-new-finder' . That is new and I need to get caught up. I have been busy with a major system upgrade, but it has settled down.
Edit: I verified that new setting short of testing it. Your report is good enough for me. It defaults to false, so I think I can safely leave it be for right now. If I had Postal set this switch it would break it for everyone running anything but the very latest Citizens. When this new feature has been out for a while I will have Postal set it for the postmen.
Why is it that whenever Citizens fires a ChunkUnloadEvent, va_postal fires an NPCDespawnEvent at the same time? I've noticed that the two events ALSO consume the same amount of CPU. (e.g. if Citizens takes up 150 ms on this event, Postal will also take up 150 ms on this event, give or take an insignificant amount.)
These two events also take up a similar amount of CPU to the chunk provider, which effectively means that for every chunk loaded (by player, plugin, etc.), I get triple the resources consumed.
I'm not pointing fingers, or trying to blame you for anything, I'm just curious. I understand why Citizens does its ChunkUnloadEvent (because the chunk provider is loading and saving chunks), but I'm not sure why this plugin ALSO has to fire the event, despite the fact that I'm not even using any Postal NPCs at all.
@Morphan1
Nevermind! I figured out it wasn't this plugin that made the postmen fail... The Citizens new waypoint navigator was the problem. I changed the config for 'use-new-finder' to false and everything runs smoothly now.
This plugin works almost perfectly. The postmen can get from point A to point B, but they seem to have a lot of issues getting there. They refuse to walk through doors, walk down stairs, or go around corners if there are walls, and when they walk it looks like they really have a problem with the ground's existence, but other than that, they can deliver mail quickly and efficiently.
Can't wait to see the next big update.
@mcfacilitator
yes, everything looks in tact to me. i cant see anything in the config thats wrong. even regenerated it.
@morlanius
That is a database or YAML problem and isn't related to the use of Towny or Dynmap. Is that a fatal error, or did you manage to get it going? If you are stuck, and config.yml is basically intact, we might be able to salvage it with some hand editing.
@mcfacilitator
Hi, this is looking really fleshed out now, fantastic work. Only one thing tho, im getting this
2013-06-06 13:28:17 [INFO] morlanius issued server command: /postal start 2013-06-06 13:28:17 [INFO] VA_Postal start aborted - could not compile town list.
I have towny_opt_in=true, but dynmap is off because we have hidden worlds.
the last 2 versions have done this.
@TitoLompoc
Yes, there have been a lot of Towny class-not-found issues with recent cuts Postal. It has been a bear. You need to run the absolute latest Postal 2.996. It has been tested with and without Towny and same with WG. All should be good now. Let me know...
That version is only a day or so old.
@TheCanadianLizard
From system notes above:
Use ‘postal mtalk 2’ to broadcast all mail movement. The journey of a letter from pickup to postmaster handling to delivery is announced. Other than diagnostics, this may be desireable on smaller sytems not using address ownership to keep the players informed of mail that might be for them.
The only mail that notifies players individually is mail going to an owned mailbox. Other than that the top line of the sign on the mailbox turns red for new mail.
I cannot get this to work on my server, I can get it to work only if I install towny, but I do not want towny, as I am not good with permissions. When I install towny, no one on my server can build, only the admins. Without towny it tells me that an internal error has occured, and throws java class errors in my console log. From what I read this is supposed to to work with world guard, which I have. I do not understand what I could be doing wrong. Any idea as to why this will not work without towny?
One thing i notice on my server, is that whenever a player gets mail, they don't get what the (postoffice delivered you mail to mailbox) is, so they ignore it. Do you think you could have a better notification system like "playername, you have mail! Check your mailbox." or something along those lines? Thank You For Reading This. :)
@ThinkOnTheEdge
Thanks for the report. I don't know if it was causing a problem, I recognize the message. It is caused by the java optimizer I am using. I also noticed that I forgot to change the internal version number, it was left at 3.0. It was based on 3.0 to make sure all the current improvements were included, but the economy was removed. I'm trying to post a solid, pre economy cut to finish off the 2.x series.
Anyway, I pulled it and am replacing it with a version 2.996 It is available now as a pre-release, and I am submitting to Bukkit now. That class loading error should be gone now.