
plugin_mapzone by Douglas Bliss (aka traF relliK)

*************************************************************************
*                              DISCLAIMER                               *
*************************************************************************
This plugin is provided for use at your own risk.  The module has been
designed to provide a means for enhancing your half-life server's
capability, and every precaution has been taken to ensure that it runs
safely (see version notes below).  However, the author can not be held
liable for compatibility or usage issues with any existing or future 
modules that may be in use on *your* server.  It is *your* responsibility 
to ensure that this module does not adversely affect your game server or 
the client machines that connect to it (this module does *not* contain
any commands that are sent to the client machine).

Now that the above has been said, let's see what this can do for you...

PRIMARY PURPOSE:

This addin provides a means of identifying 'zones' within each map.
Any target player will then be identified as being in that zone by
the 'admin_locate <target>' command.  Two levels of access can be
granted to the users for location purposes.  With ACCESS_ZONETEAM, 
players may query the location of players on their team only.  With 
ACCESS_ZONEALL, they may locate all players.  To create and edit the 
map files, ACCESS_ZONEMAP needs to be granted to the user.

COMMANDS:

The commands this plugin registers are:
	admin_locate [target]		Displays which zone target is in
	admin_zonecreate <name>		Creates a new zone record
	admin_zoneupdate [name]		Updates a zone record
	admin_zonereset [name]		Resets zone to current location
	admin_zoneundo			Undoes the last update
	admin_zonesort			Sorts map file to remove elevation conflicts

The only required parameter is with the admin_createzone command,
which creates a zone even if the name matches an existing zone name.
The others are optional (using the 'current' zone name, or implying
the user for admin_locate).

WORKING WITH MAPZONE:

The creation of map files may appear to be a daunting task, and
reducing that task down to easy steps is what this plugin is all
about.  To begin with, I would like to describe the intended use
for this plugin -- having a way to create a file where respawn
campers are identified by my server's A.I. module (S.A.M.), and to
deal with them appropriately (multiple punishment levels).  At first,
I simply created a command to identify my current location, and wrote
down the coordinates of the 'hot zones.'  This was tedius, and I
didn't get very far.  Since I knew that I needed a location function,
I created the first three commands and automated the update process.

As I worked with it, I was happy with the results, until I made
a mistake...  I bound a key to the 'admin_zoneupdate' command and
pressed it by accident while in a totally different area, updating
the wrong zone.

Needless to say, this prompted the need for a reset and undo
capability.  Things went well from there, until I noticed that
the 'ceiling space' that I had alloted was causing issues based
on the definition sequence in the file.  After some thought,
the obvious choice was to sort the zone entries by their vertical
position, from highest to lowest.  Thus, if a location has a ramp
defined in the center of a larger space, the ramp will be 'on
top' of the larger area, and take precedence.  This reduced the
advance planning requirements down to the following tasks:

 - Define your zone name in the console 
	(i.e. "admin_zonecreate in blue main respawn")
 - Move to each wall/extreme
 - Press a key bound to "admin_zoneupdate"
 - Repeat as needed...
 - Sort the map in the console ("admin_zonesort")

Some of the less obvious stuff:

 - The map files reside in a "MAPData" subdirectory under your
   mod's directory (i.e. ...\Half-Life\TFC\MAPData).  The included
   2fort.txt file can be placed there as a starting point (although
   it contains more rooms than I'd recommend, and only contains the
   blue base's data at present).
 - Bind a key to "admin_locate" to check your location periodically
 - If you need to update previously defined zones, locate yourself
   there first.  This makes your zone current (only if the target
   is yourself).
 - Don't forget to include vertical limits to your rooms, by going
   to each floor/wall combination (while it is only necessary to
   go to the lower/left/near and upper/right/far corner, you will
   find it more convenient on odd shaped rooms to 'be redundant').
 - The 'admin_help plugin_mapzone' command will list all commands.
 - If you kludge up a room and can't undo it, reset it by going
   to the 'actual' room (usually distorted by mistake), and
   using the admin_zonereset command.  The room will now ONLY
   include your current location, and you can update it from there.
 - Don't worry about room precedence until you are finished with
   the entire area.
 - Define an 'overlay' area that encompases the entire blue base,
   etc..., then, if a specific room is not defined, it will fall
   back on 'in the blue base' instead of giving you an ugly 'not
   found' message.  This overlay area should include the absolute
   lowest point within the base, to come after everything else
   (it might still require manually editing the text file to put
   it at the bottom though).


ADDITIONAL INFORMATION:

 - The admin_locate command is actually intended to be a development
   tool rather than a final implementation.  Within your server's
   workings you will probably want to include some feature that
   queries the location and displays it with a bit more flash.  Even
   a novice small programmer should have no trouble understaning
   the admin_locate routine enough to create a similar routine, as
   I've used building blocks extensively to limit the complexity 
   of the primary functions.
 - Although it would have been easy to provide a handlesay response
   handler, I thought it was best to leave that to anyone using it.
   Mainly since having too many handlesay's will quickly degrade
   performance, but also because it's a matter of style how you
   will want to incorporate this module into your server.

FINAL THOUGHTS:

 - I realize that there are several potential improvements to this,
   but I am too busy working on my server's A.I. to devote any time
   to this relatively simple tool.  This doesn't mean I'm not interested,
   so please feel free to drop me a note about what you've done to 
   it or what you feel should be done to it.  I'll *try* to respond
   to the better ideas -- I just can't promise any immediate responses.
 - Oh yeah... SEND ME YOUR MAP FILES! ;-p

Douglas Bliss
aka traF relliK
dougb@dougware.com
