path: root/doc/map_cache.txt

//===== Athena Doc ========================================
//= Map Cache Builder and Format Documentation
//===== By ================================================
//= DracoRPG
//===== Version ===========================================
//= 1.0
//=========================================================
//= 0.1 - Short howto for the initial builder version
//= 1.0 - Complete manual covering the improved version
//===== Description =======================================
//= A complete manual for eAthena's map cache generator
//= as well as a reference on the map cache format used
//=========================================================

Preface:
-------------------------------------------------------------------------------

Since SVN revision ~10000, the map-server does not know how to read RO client files anymore. It reads maps from a
"map cache" file that contains all and only the useful data about the maps. A map cache containing every official
kRO Sakray map currently supported by eAthena is provided as a default.
If you have custom maps or want to minimize the size of your map cache because your server does not load all of them
(multi-map-server or light test server), you can use the map cache builder to generate a new one fitting your needs.

Map cache builder manual:
-------------------------------------------------------------------------------

The source code for the map cache builder is located in src/tool/. It can be built using "make tools" if you use the Makefile
or using the "mapcache" project under Visual Studio. Named "mapcache", the executable will be in your eAthena main folder.
The map cache builder needs 3 file paths : one is a list of GRFs and/or data directory containing the maps, the second
is the list of maps to add to the map cache, and the last one is the path of the map cache to generate. Default values for
those paths are "tools/mapcache/grf_files.txt", "db/map_index.txt" and "db/map_cache.dat".
The list of GRF and/or data directory must follow the format and indication of the default file: as many "grf:" entries as
you wish and optionally one only "data_dir:" entry with trailing backslash included. // comments are supported as usual.
In fact, any file with one map name per line can be used as a map list, that's why the map index list is used as a default:
we are sure it contains every map supported by the server. Anything after the map name is ignored, // comments are supported
and if the first word on the line is "map:" then the second word is used as the map name instead: that allows using
maps_athena.conf as your map list, which is handy if you want to generate a minimal map cache for each of your multiple
map-servers.
The map cache file path can point to an already existing file, as the builder adds a map only if it's not already cached.
This way, you can add custom maps to the base map cache without even needing kRO Sakray maps. If you wish to rebuild the
entire map cache, though, you can either provide a path to a non-existing file, or force the rebuild mode.

Here are the command-line arguments you can provide to the map cache builder to customize its behavior:
 -grf path/to/grf/list
   Allows to specify the file containing the list of GRFs and/or data directory
 -list path/to/map/list
   Allows to specify the file containing the list of maps to add to the map cache
 -cache path/to/map/cache
   Allows to specify the path to the generated map cache
 - rebuild
   Allows to force the rebuild mode (map cache will be overwritten even if it already exists)


Map cache format reference:
-------------------------------------------------------------------------------

The file is written as little-endian, even on big-endian systems, for cross-compatibility reasons. Appropriate conversions
are done when generating it, so don't worry about it.
The first 6 bytes are a main header:
<unsigned long> file size
<unsigned short> number of maps
Then maps are stored one right after another:
<12-characters-long string> map name
<short> X size
<short> Y size
<long> compressed cell data length
<variable> compressed cell data