I'm still here!

Rewrote fame ranking lists- changed MAP_NAME_LENGTH to 12, now there's MAP_NAME_LENGTH_EXT at 16 for
	  uses where there is / may be the .gat extension, code adjusted accordingly
- moved map_normalize_name to mapindex_normalize_name so that everything
	  handling map names uses the same extension-removing function
- greatly enhanced the map cache generator, complete documentation on the
	  tool and the map cache format can be found in doc/
- the map cache format changed a bit as a consequence, but of course a new
	  valid one is included (contains latest Nameless Island maps)
- fixed a duplicate entry in map index


git-svn-id: https://rathena.svn.sourceforge.net/svnroot/rathena/trunk@10167 54d463be-8e91-2dee-dedb-b68131a5f0ec

1 files changed, 60 insertions, 11 deletions

diff --git a/doc/map_cache.txt b/doc/map_cache.txt
index 4ab77e99b..82849cdf4 100644
--- a/doc/map_cache.txt
+++ b/doc/map_cache.txt
@@ -1,18 +1,67 @@
-"How to use the mapcache builder"

-DracoRPG

+//===== 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:

+-------------------------------------------------------------------------------

 

-This is only useful if you have custom maps, as eAthena is provided with an updated mapcache containing every map

-from kRO Sakray's data.

+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.

 

-1. First add the path to the directory / GRF containing your maps to db/grf_files.txt

-/!\ Please note you must also have the official maps as the whole mapcache will be rebuilt from scratch

+Map cache builder manual:

+-------------------------------------------------------------------------------

 

-2. Then add those custom maps at the end of db/map_list.txt, carefully chosing their index

+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.

 

-3. Now just run the mapcache builder and it'll build a new one at db/map_cache.dat

+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)

 

 

-NOTE:

-You can override those default paths by providing your own ones as command-line arguments to the mapcache builder:

-$> mapcache [grf_files_path [map_list_path [map_cache_path]]]
\ No newline at end of file
+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