mirror of
https://github.com/HerculesWS/Hercules
synced 2026-08-15 12:23:13 -04:00
65 lines
3.8 KiB
Text
65 lines
3.8 KiB
Text
//===== 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
|