Bukkit

Citizens2 Based Postal System

Getting Started:

Copy va_postal to the plugins directory.

Postal is dependant on Citizens2, so be sure and include it. As of this writing I am using citizens-2.0.3-build.443

By default, the postal system does not automatically start when the server starts. This can be changed in 'config.yml'. You don't want it to start anyway because there is nothing to do yet. 'postal start' starts it, but don't do that yet. Btw, '/postal' (no params) lists the postal commands.

The minimum: a central post office, and at least one local post office with at least one address. Chests are used to hold incoming and outgoing mail at both addresses and post offices.

1) As op'd player, go to the spot where you want the central post office and enter '/setcentral'. Place a chest within a few blocks of that position.

2) As op'd player go to where you want a local post office and enter 'setlocal <town_name>'. Like the central post office, place a chest nearby.

3a) As op'd player, go to an address that this post office will serve and enter '/setaddr <town> <address>' <town> and <address> should be 14 characters or less, all one word. Separate words using the underscore ie: 'Sunshine_Bay'

3b) Complete the address definition by indicating the route waypoints that you want to use. As op'ed player enter '/setroute <town> <address>' using the same parameters used above in the 'setaddr' command. You will enter the waypoint editor and, since this is a new route, you will be teleported to the post office. Left or right click points on the ground for the postman to follow to this new address. More about the waypoint editor below. Mark your final waypoint close to where you want your mailbox. It can be inside, or outside a building. Enter '/setroute exit' to exit the waypoint editor. Place a chest for your mailbox.

4) Go! '/postal start'

Sending Mail

Using Book and Quill, write a letter and sign it. '/tlist' will list the names of the towns. '/alist <town>' will list the addresses in that town. All the commands, where appropriate, are pretty good at completing town and address names with the minimum amount of typing. Take this book and type '/addr <town> <address>' This addresses the letter. Mistakes can be fixed by simply using the 'addr' command again. Now this book can be placed in any mailbox (chest), including post office chests. For the above example, put it in the central post office so you can see the postmaster manage out-of-town mail.

Waypoint Editor

There are two other commands besides 'exit' available while in the editor, and they are 'undo' and 'new'. Using '/setroute <town> <address>' on an existing address will immediately take you to the last point on the route. '/setroute undo' will back you up one point, deleting the point you were on this is handy for changing the mailbox location at an address. '/setroute new' will take you back to the post office to re-do the route from scratch.

The postman is pretty good about detecting doors on a route, as well as opening and closing them. He even opens/closes both doors of double doors. He can also handle gates, and waist high trapdoors. To properly lay out doors on a route, mark a point before the door (a block or two) and a point after the door. If there are multiple doors that are close together, be sure there is at least one point separating these door point-pairs. Two points might be better. If you ever have unexpected door problems, it will be because of this - just add more points. The door navigation is designed to be flexible, and trouble free. Doors often get changed, or re-hung on door frames differently. So, the postman always looks for a door between waypoints, and attempts to automatically deal with it. Hopefully this will reduce the the need for route editing as property improvements are made.

On the other hand, many points are not your friend if you want the postman to run. The algorithm has the postman's speed determined by the waypoint spacing. The further apart, the faster he goes. Waypoint spacing is the speed control.

Stairs should be marked before the first step, and after the last. He does stairs well. I have a 20 story office building serviced by local post office, in the building.

Mailboxes

Mailboxes are chests, single or double. They are normally placed near the beginning and the end of routes. The postman will look for a chest up to 10 blocks, or so, if he doesn't immediately find one. He will even add his own waypoint to get to such a chest, but it is better to keep them close and handy. The postman will favor a chest if it has a sign with '[mail]' anywhere on it, near the desired chest. This is intended to direct the postman to a particular chest if there are many.

The postman leaves a postal log in the chests at addresses. It is time-stamped every time he visits the address. This serves as an indicator of a chest being used as a mailbox, as well as proof that the postman is servicing it. Players are not allowed to remove this log, only look at a copy of it. To override this behavior, enter '/postal admin' as an op.

Permissions

Permissions are pretty simple right now. Op is required for the admin type commands. Codelock may be used to secure chests without hindering the postman. The infrastructure for player ownership of routes and post offices, and sender/sendee access to mail in chests is in place, but not yet complete.

Notes

'Concurrent_postmen' in config.yml controls the route scheduling. Set to 'true' to have all post offices run concurrently. The postmen run their routes continuously, oldest route, next. However, Mailed books are detected when mailed, and preempt the regular routes. Actual mail always takes precedence over general, route walking. A post office with 30 routes will still move the mail along efficiently.

The NPC's are created on the fly, as needed. They are removed on server shutdown. There is a hard-coded cap of 10 NPC's that can be easily changed. I will move this number to config.yml eventually, or remove the cap altogether. This means don't exceed 9 post offices yet. One Central nine local.

There is a '/postal stop' command, but it is a little rough around the edges. I would suggest leaving the 'autostart' option to 'false' until most of your postal routing is done. Modifying existing routes while postal is running is no problem and routine.

Plan on restarting the server when adding new routes or post offices. The dispatcher (scheduler) is generated when va_postal is started. New routes may be freely added while Postal is running, however, they will not be on the dispatcher until the server is restarted. A polished '/postal stop/start' will soon replace the need to restart the server.

One person may use the route editor at a time. va_postal will enforce this, and even tell you who is using the editor if it is occupied.

If the postal system will not start, it generally means that an address is defined, but has no route. This can happen by editing an existing route ('/setroute new') and exiting before marking at least one point. Defining an address without a route will cause this as well. If you know the address without a route simply use '/setroute' to mark at least one waypoint. Otherwise, it will be easy to find in 'config.yml'. Find the address without a 'Route'. I will eliminate this potential issue soon. It is not a bug - it has to do with the reality check va_postal does on start up. The Dispatcher section in 'config.yml' is generated when the server starts. An address without a route makes no sense to it, so it aborts. This section is left after server shutdown for diagnostic purposes only. It is not a big deal, but I wanted to mention it because this made my stomach drop a couple of times after doing a bunch of route work only to have va_postal say it can't start. It's ok - just find and set that missing route.

There are unimplemented commands to delete or rename addresses or post offices, but they must wait for a polished '/postal stop/start'. In the meantime, this can be easily done by directly modifying 'config.yml' Everything starting from and below the 'Static_regions' section is generated at server startup, so you don't need to touch that. You need to follow yaml rules, and please, I repeat please, always make a backup copy of 'config.yml' first. It just takes a second.

Another note on what is generated on va_postal start. All the chunks required for the routes and general operation are gathered on startup and loaded and prevented from unloading. This list is in the Static_regions section of 'config.yml'. If it were not for this the postmen would simply go to sleep when out of sight of players. This struck me as a little too realistic, so I opted to keep them running 24/7. The mail must keep moving...

To really see what is going on behind the scenes change 'debug' to 'true' in config.yml and watch the console.

VA_Postal Versiom 1.5 11/7/2012

Compiled against the latest Bukkit and Citizen2 developer builds and APIs.

Bukkit 1.4.2-R0.3, build #2457 http://dl.bukkit.org/downloads/craftbukkit/view/01549_1.4.2-R0.3/ Citizens2 Build #559 (Nov 7, 2012 12:41:04 AM) http://ci.citizensnpcs.com/job/Citizens2/

VA_postal start/stop, independent of Bukkit is in place. Mail is protected. It is transfered to a post office before de-spawning postal NPCs. The ability to design and implement new routes without restarting the server is here. Mail being carried by postmen is also protected on server shut down.

Major work was completed on the watchdog system. The watchdog monitors the NPCs and gives them a little help if needed. VA_postal will automatically reload itself if a major problem is detected. The mail must keep on moving...

Multi-World support is in place. Local post offices deliver to addresses that NPCs can walk to. The Central post office manages out-of-town, or out-of-world mail and sees that it gets delivered to the appropriate local post office, efficiently. This NPC is called the PostMaster.

Console control is in place. 'postal start/stop/restart' works as expected. CONCURRENT has been added to control multitasking (or not) of local post offices. QUIET (default) toggles only mail movement on console and client. TALK toggles summary movement of the postal NPCs. DEBUG toggles many details, probably too much. ROUTETALK toggles route summary updates. CENTRALTALK toggles the postmaster activity. MAILTALK toggles mail activity both on console and clients. ADMIN toggles op override of postal logs left in postal chests. Normally they may not be removed. QUEUETALK, is probably the most useful for monitoring the details of the scheduling. All of this, and in color too.

VA_Postal Versiom 1.6 11/11/2012

General tweaks and tuning for current Bukkit and Citizen2 developer builds

Implemented /deletelocal and /deleteaddr making it possible to quickly delete post offices and addresses without having to edit 'config.yml'.

Friendlier VA_Postal now tells you what is wrong if something is missing in the setup. Instructions to remedy issues are provided, in context.

Full Chests Full mailboxes are detected and managed. Mail is stored at the local post office until picked up, or room in the residence chest is made.

Mail Indicator A lit, redstone torch is left in front of a chest with new mail.

VA_Postal Versiom 1.7 11/16/2012

Citizens2 2.0.4, build 569 CraftBukkit 1.4.5-R0.1, build 2474

(both developer builds)

Re-worked for 1.4.4, now 1.4.5 MineCraft (a moving target)

General improvements to robustness, and friendliness to the user. Some improvements to the waypoint editor. New mail indicator, a redstone torch, removes itself when mail chest is opened. More, but a bit of a blur - I wanted to get this up for the bleeding edge folks. Seems very solid, but you tell me. Thanks.

Note: This project has been informally made available at the citizens2 forum.

http://youtu.be/U_lKzVNQMzc