MapUtils
========
Miscellaneous utilities for processing ASCII map data from
BatMUD in various interesting ways.

Programmed by Matti Hämäläinen (aka Ggr Pupunen @ BatMUD)
(C) Copyright 2006-2017 Tecnic Software productions (TNSP)


NOTICE!
=======
The raw ASCII map data included in this package originate directly
or indirectly from BatMUD(tm) <http://www.bat.org/> and are
(C) Copyright 2002-2017 Balanced Alternative Techniques Ry.

Those files are distributed here under the belief that since the
data is publicly available, it can be freely distributed under
"fair-use" paradigm when used non-commercially.


Requirements
============
The compilation and usage of these utilities requires following
software packages or functional equivalents installed:

 - GCC 4.6 or later
 - GNU Wget
 - Perl 5.10
 - ImageMagick
 - GNU diff, patch, make and sed
 - bash, dash or some other compatible shell
 - libpng 1.2 or 1.6 and development headers

 - TNSP "th-libs" C utility code library, usually you need the latest
   one for the latest maputils, available as Mercurial repository at
   http://tnsp.org/hg/th-libs/

 - Stuff under www/ obviously requires PHP5, but it's not really even
   meant for public consumption, this repository just works as a
   storage medium for it. All the required files (the simplistic
   "web framework" of mine) is not even included.

   .. but if you are really interested, ask, and ye shall receive.


Usage
=====

 1) Verify that your system fulfills the requirements stated above.

 2) In maputils root directory, clone th-libs under it:

    $  hg clone http://tnsp.org/hg/th-libs/

 2) Edit 'Makefile' and 'config.mak' in top directory, if needed.

 3) In the main directory, type 'make' or 'gmake' to compile.
    If compilation succeeds, you can move to step 4.

    If compilation fails, you are on your own. If you don't know what
    the problem is, then please DON'T ask me (Ggr). I am not interested.

 4) cd world/ and run 'make' or 'gmake' again.


Map updating and building procedure
===================================

 1) In world/ directory, to fetch new raw ASCII map data

    $ make fetch

 2) In order to automatically find any changes in raw ASCII maps,
    and update the location files with templates of new locations.
    Also updates the ASCII map data in the repository with terrain
    changes. New pcities and markers are only stored in loc files.

    $ make diff

 3) If there were new locations, manually edit changed loc files
    with relevant information. This part requires running around
    in BatMUD to retrieve names for the new places (pcities, areas).

 4) Make a test build of maps, to see if the new markers look okay:

    $ make maps

 5) Check maps visually, adjust loc files (location marker label
    alignment etc.) if necessary.

 6) Repeat 4-5 until satisfied.

 7) Commit changes to repository (hg ci, hg push)

 8) At this point I use GIMP (http://www.gimp.org/) to compress
    the PNG format map images better, by converting them to Indexed
    color, using 64 colors max. GIMP's quantization algo is the
    best I've seen, and unfortunately ImageMagick, pngcrush etc.
    don't come even close, making this part require manual work.

    $ make gimp

 9) Upload files to server:

    $ make upload

The city maps and hcbat maps have somewhat similar procedures, except
they do not require the GIMP step as no PNG maps are generated.


NOTICE! For changing HCBat map locations, you do NOT edit hcbat.loc,
but hcbat.ref instead! It is a loc file, but with special syntax for
referencing the new world loc files under world/. Location name
prefixed with @ ("at" character) will expand to the matching location
information in the new maps loc files.


Included utilities
==================

* mkloc
  Perhaps the most important tool in this package, a multi-purpose
  utility for converting, manipulating and updating location files.

  Can also combine an ASCII map with location data to produce output
  with location information (which can be further converted to different
  formats via 'colormap').

* colormap
  Transforms given input BatMUD ASCII maps (also some sub-area maps)
  into various formats, including coloured XHTML+CSS, HTML and ANSI
  text.

* diffmap
  Computes a 'diff' between two ASCII maps of equivalent size. Output
  is a specially formatted binary file, which can be converted to
  bitmap images via 'map2ppm', or used as patches for 'patchmap'.

* patchmap
  Patches a given ASCII map with a patch produced by diffmap.

* map2ppm
  Similar to 'colormap', converts ASCII map to a PPM or PNG format
  image file, which can be then further converted/manipulated with
  ImageMagick or netpbm utils, or other image processing software.
  Is able to upscale the image by integer values if wanted.
  Can also use output of 'diffmap' to create images with differences
  highlighted.

* combine
  Combines several ASCII maps into a bigger one, based on coordinate
  offsets.

* mkspecial
  Given an input with "map pieces" (generated with help of TF scripts)
  and sufficient parameters for interpreting, this utility stitches
  together a bigger ASCII map from the pieces.

* mapstats
  Generate simple statistics about different "terrain" types used
  in a given ASCII map.

* mkcitymap
  Specialized utility for generating HTML format maps from city maps.


Miscellaneous information
=========================

world/  map data for continents and associated Makefiles for generating
        the output maps.

misc/   map data for various city and area type locations, e.g.
        Arelium, Lorenchia, etc.

old/    contains maps and data from the Old BatWorld, before the Age of
        Exiles and new continents. Also the HardCore BatMUD map / location
        data can be found here.

tf/     few utility scripts for mapping for TinyFugue MUD client.

www/    PHP-glue and data files used for http://tnsp.org/maps/ site.