/* ---------------------------------------------------------------------- */
/*
 *   TADS 3 Compass Extension.
 *   Version 3.
 *   By Steve Breslin (steve.breslin@gmail.com)
 *      Krister Fundin (fundin@yahoo.com)
 */

/* ---------------------------------------------------------------------- */
/*
 *   Introduction.
 */

   In text-based games with large maps and many exits from each location, it
can be difficult for players to keep track of their whereabouts, and having
to carefully re-read all the room descriptions just to make sure that we
haven't missed yet another exit can be a bother. To remedy this, TADS 3 can
optionally display a list of obvious exits in the status line. Another
popular way of making navigation easier is to display a compass rose
somewhere on the screen, where, if there is an exit to the east, for
instance, the compass rose would light up in that direction. Besides just
conveying this list of exits in an intuitive way, the compass also provides
a visual distinction to the various rooms on the map, since many of them
will have their own unique constellations of lit and unlit directions.

   This extension provides such a compass for use in TADS 3 games and
stories. A command to turn the compass on and off is also included, since
not all players are likely to need it, and since it might take up some of
the space that would otherwise have been used by the main window.

/* ---------------------------------------------------------------------- */
/*
 *   Basic usage.
 */

   To make use of this extension, we add the library file "compass.tl" to
our project. After recompiling, a compass rose should show up to the right
of the status line. If everything seems fine, then that is all that needs to
be done. There are some things that we might want to configure, though, and
this is what the rest of the manual will be about.

/* ---------------------------------------------------------------------- */
/*
 *   Placement of the compass.
 */

   By default, the compass rose will be placed in its own banner to the
right of the status line. If no additional banners are used, then this is
pretty much the only place where it can sensibly be located, but we may want
to consider a different placement if we have a more complex arrangement of
banners.

   To relocate the compass, we can modify the compassBanner object and
change one or more of the following properties: parent, where, other, align
and style. These all mean the same thing as the corresponding arguments to
the createBanner() intrinsic function. By default, parent is set to
statuslineBanner and align is set to BannerAlignRight.

/* ---------------------------------------------------------------------- */
/*
 *   HTML and text-only rendering.
 */

   In order to work with as many TADS 3 interpreters as possible, this
extension provides two different ways of drawing the compass. There is a
graphic version suitable for multimedia interpreters and an ASCII version
for the rest. The graphic version will be used wherever possible. On some
interpreters, even the text version might not supported, in which the
compass will simply be omitted.

   The HTML and text-only compass writers have their own source files, and
both of them are actually optional. If, for instance, a story already
requires a multimedia interpreter for other reasons, then the text-only
compass would never be used in practice, and so it would do no harm to
remove the "compass_text.t" file completely.

/* ---------------------------------------------------------------------- */
/*
 *   Configuring the HTML compass.
 */

   The most obvious thing to change about the HTML compass would be the
images that make up the compass rose. There are nine of them, and they are
stored in PNG format in the "compassres" sub-directory of this extension.
When replacing or modifying these images, it may be best to make a local
copy of the entire extension in the directory where the source files of the
story are located, since it's not possible to both use a common copy of the
extension and have different sets of images for different stories, should
this become necessary in the future.

   The size of the images is also configurable. By default they will be
scaled to a width and height of 11 or 28 pixels. (To be precise, the images
in the middle column have a width of 11 pixels and the images in the other
columns have a width of 28 pixels. The images in the middle row have a
height of 11 pixels and the images in the other rows have a height of 28
pixels. Thus, the corner images are all 28 x 28 pixels, the centre image is
11 x 11 pixels, and the rest have one long and one short side.)

   These sizes can be changed by modifying htmlCompass and overriding
flankSize (which defaults to 28) and middleSize (which defaults to 11). When
using the default images, the ratio between these should stay roughly the
same.

/* ---------------------------------------------------------------------- */
/*
 *   Exit listing in the status line.
 */

   Needless to say, the list of exits which is by default displayed in the
status line becomes a bit superfluous next to a compass rose. It may
therefore be a good idea to override exitLister.showStatuslineExits() and
exitLister.getStatuslineExitsHeight() in order to remove this list. (Another
approach would be to override exitsMode.inStatusLine and change the factory
default to nil, but the player might previously have used the SAVE DEFAULTS
command, in which case the factory default would never be applied.)

   One might also think that it would be a good idea to only disable the
exit listing if the interpreter is actually capable of displaying a compass
(which we can tell by checking if compassBanner.compassWriter is nil), but
in practice, an interpreter that can't even display the text-only compass
likely doesn't support banners at all and thus couldn't display the exit
listing either way.