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.