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

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

Licensed under GNU General Public License version 2 or later,
see file "COPYING" for more information. Applies to this package
except for the parts listed below:

 - th-utils library
   Programmed and designed by Matti 'ccr' Hämäläinen <ccr@tnsp.org>
   (C) Copyright 2002-2024 Tecnic Software productions (TNSP)
   Licensed under 3-clause BSD style license, see th-libs/COPYING

 - The raw ASCII map data in *.map files originate directly
   or indirectly from BatMUD(tm) <http://www.bat.org/> and are
   (C) Copyright 2002-2024 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.

 - world/MonospaceBold.ttf TrueType font
   Copyright (C) 1990-2001 George Williams. See the license
   information in file world/MonospaceBold.copyright

 - world/svn2cl.xsl
   Copyright (C) 2004, 2005 Arthur de Jong. See the license
   information in file world/svn2cl.xsl


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

 - GCC or Clang or possibly other C11 compatible compiler
 - GNU wget or curl
 - ImageMagick (GraphicsMagick might not work)
 - GNU diff, patch, make and sed
 - GNU bash
 - TNSP "th-libs" C utility code library, usually you need the latest
   one for the latest maputils, available as Mercurial repository at
   https://tnsp.org/hg/th-libs/

Optional:

 - GIMP 2.x or newer for best quality worldmap PNG color reduction.
   Without GIMP the worldmap PNG files will be 32-bit RGBA (and
   rather large, for that matter.)

 - xsltproc for generating changelog.txt

 - Perl 5.10 or later for regenerating old/hcbat.loc via old/mapref.pl

 - libpng 1.6 and development headers for PNG output support
   in map2ppm.

 - libwebsockets, libuv and perhaps some other depencies
   if you want the "mapsearch" server. Only following versions
   of libwebsockets have been tested: 2.0.3, 2.2.0, 3.2.1 and
   4.0.20 .. I can't guarantee compatibility with all versions.

 - PHP 7.x or 8.x for src/genbcxml.php in order to generate
   Batclient markers.xml

 - Stuff under www/ requires PHP 7.x or 8.x, but it's not really
   even meant for public consumption, this repository just works as
   a storage medium for it.


Usage
=====

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

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

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

 2) Edit 'Makefile' and/or '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) To build the HTML/PNG/etc worldmaps:

    $ cd world/ && make


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.

* stitchmap
  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.

* mapsearch
  A map search server that uses WebSockets to communicate with Javascript-
  based front-end (see www/search.js and www/search.php). Can be used to
  search the maps and locations. See also scripts/ directory for some
  related SysV init scripts etc.


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 https://tnsp.org/maps/ site.