//===== Hercules Documentation =============================== //= Hercules Map Cache Builder and Format Documentation //===== By: ================================================== //= DracoRPG //===== Current Version: ===================================== //= 20160820 //===== Description: ========================================= //= A complete manual for Hercules' map cache generator as //= well as a reference on the map cache format used. //============================================================ Preface: ------------------------------------------------------------------------------- Since SVN revision ~10000, the map-server no longer knows how to read GRFs directly. 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 Hercules 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 Hercules 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/(pre-)re/map_cache.dat". As of r16867, the mapcache within SVN can be located in db/pre-re/ and db/re/. This is due to renewal and pre-renewal modes having slightly different maps. When building your cache, you should ensure you're pointing the tool to the correct location. The list of GRFs and/or data directory must follow the format and indication of the default file: as many "grf:" entries as you wish and optionally only one "data_dir:" entry with trailing backslash included. // comments are supported as usual. A custom map list can be used, in order to generate a map cache file with different (or less) maps than the current Hercules configuration. For details on the map list format, see conf/map/maps.conf. 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 int> 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