View source for Lich:A beginner's guide to the Lich mapdb

<div class="alert alert-danger"><big><center>'''NEVER UPLOAD ANYTHING TO THE MAPDB WITHOUT CAREFULLY CHECKING YOUR WORK!'''</center></big></div>

The '''Lich map database''' ('''mapdb''') is an important part of [[Lich (software)|Lich]] used for automated travel and other tasks related to room properties.  It is distinct from the [[Script Go2|go2]] script, but in general both of these two require the other for normal use.  This article aims to provide a general introduction to the mapdb at a level appropriate for basic usage as well as getting started wtih modifications.

==Introduction==

Despite their differences, updates to the '''mapdb''' are often erroneously called updates to the script go2.  The mapdb provides the basic information on which go2 operates.  For many players, the distinction between the two is not important; if someone updates the mapdb to include new paths and/or new rooms, go2 will know how to use them without further instruction.  It is, however, important to understand the distinction for anyone wishing to work on or with the mapdb.

One is a database (mapdb) and the other is a script (go2).  To exemplify their differences, consider that [[Prime]], [[Platinum]], and [[Shattered]] all have different mapdbs, but they can commonly share the same version of the go2 script.  The databases cannot be shared across instances because the actual rooms and layouts are not 100% identical between them; they can, however, share the logic used by go2 to perform operations on the mapdb and issue instructions to the game server for movement and other tasks.

The mapdb is a file with a record for each unique room it knows about.  At the time of writing (check History), the file is about 30 MB in size containing information about nearly 30,000 rooms.  These files are kept under lich/data/GSIV/map-##########.json (for the Prime instance), where the long number is an identifying timestamp which is updated automatically in an incremental fashion.  

This article will focus on the mapdb from the perspective of not only its use with go2, but other scripts such as [[Script_Narost|narost]] and ones that sort rooms by nearest location and tags (e.g., zzherb).

==What is a room?==
The best (and really only) way to interact with the '''mapdb''' is via the game through lich.  In general, if one is in a mapped room, one can have a look at its mapdb record via the command <code>;e echo Room.current.inspect</code>.  For example:

<pre{{log2|margin-right=60%}}>
@id=225
@title=["[Wehnimer's, North Ring Rd.]"]
@description=["The road turns gradually at this point as it forms the northwest corner of the city.  The main path curves along the north and west walls, and another leads south between the buildings.  The massive oak and modwir logs of the city palisade tower overhead."]
@paths=["Obvious paths: east, south, southwest"]
@location="the town of Wehnimer's Landing"
@uid=[7002]
@unique_loot=nil
@wayto={"226"=>"south", "294"=>"southwest", "224"=>"east"}
@timeto={"226"=>0.2, "294"=>0.2, "224"=>0.2}
@tags=["some sovyn clove", "some acantha leaf", "some calamia fruit", "pepperthorn root", "ironfern root", "small rose", "heath aster", "some bur-clover root", "some wingstem root", "small wild rose", "white baneberry", "small daisy", "meta:teleport:fwi"]
@image="wl-wehnimers-1264234799.png"
@image_coords=[197, 175, 233, 211]
@check_location=nil
@climate=nil
@terrain=nil
</pre>

This example is fairly straight-forward, showing some basic details without too much complication.  One should recognize it as the far west room on the North Ring Road inside the town of [[Wehnimer's Landing]].  The [[A_beginner%27s_guide_to_the_Lich_mapdb#tags|tags]] indicate a number of herbs can be foraged in this location, for example [[acantha leaf]].

==Room properties==
Here is more technical description of each field in a room record in the mapdb.

===id===
Type: Integer

The room number is a unique identifying integer, and perhaps the most common technical detail of the mapdb which is used regularly by all lich users.  They are linear in the order they are added to the mapdb, although there is no implicit relation between a room number and what may be called the geographic location in the game.

===title===
Type: Array

<pre{{log2|margin-right=60%}}>
@title=["[Wehnimer's, North Ring Rd.]"]
</pre>

The first portion of the gamefeed associated with the room before the description, shown in square brackets (&#91; and &#93;).  Used by the mapdb for identifying a room.    See also [[A_beginner%27s_guide_to_the_Lich_mapdb#description|description]] and [[A_beginner%27s_guide_to_the_Lich_mapdb#paths|paths]].

===description===
Type: Array

<pre{{log2|margin-right=60%}}>
@description=["The road turns gradually at this point as it forms the northwest corner of the city.  The main path curves along the north and west walls, and another leads south between the buildings.  The massive oak and modwir logs of the city palisade tower overhead."]
</pre>

The portion of the gamefeed after the title but before the paths.  Used by the mapdb for identifying a room.  Reading this bit is called sniffing the flowers.  Does not include the bit about 'You also see...' (to use a permanent room object, see [[A_beginner%27s_guide_to_the_Lich_mapdb#unique_loot|unique_loot]]).  See also: [[A_beginner%27s_guide_to_the_Lich_mapdb#paths|paths]], [[A_beginner%27s_guide_to_the_Lich_mapdb#title|title]].

===paths===
Type: Array

<pre{{log2|margin-right=60%}}>
@paths=["Obvious paths: east, south, southwest"]
</pre>

The portion of the gamefeed after the room description, showing the 'Obvious paths' or the 'Obvious exits'.  Used by the mapdb for identifying a room.  (NB: Not for extracting movement methods between rooms.)  See also [[A_beginner%27s_guide_to_the_Lich_mapdb#description|description]], [[A_beginner%27s_guide_to_the_Lich_mapdb#title|title]] and [[A_beginner%27s_guide_to_the_Lich_mapdb#wayto|wayto]].

===uid===
Type: Array

A uid is a value provided in the rm attribute of the nav element in the XML stream of the game.  The current value can be seen by running: <code>;e echo XMLData.room_id</code>.  There are circumstances when a single room will have multiple uids associated with it, which is why this is an array.  Used by the mapdb for identifying a room.

===location===
Type: String

The sliced output from the game's location verb, indicating the room's approximate geographic region.  Can be useful to distinguish unique rooms.

===unique_loot===
Type: String array

An optional and manually added portion of the gamefeed after the description but before the paths. It represents any static object(s) in the room which could be used for identification purposes (such as a statue or a barrel).  As this used to be covered under [[A_beginner%27s_guide_to_the_Lich_mapdb#tags|tags]], not all rooms will have this field.  The values in this array should match the hyperlinked name of the object in the room, a list for the current room can be created with <code>;e echo GameObj.loot.to_a.collect { |obj| obj.name }.inspect</code>

===wayto=== 
Type: Hash

<pre{{log2|margin-right=60%}}>
@wayto={"226"=>"south", "294"=>"southwest", "224"=>"east"}
</pre>

The method and id pair for each room a character can reach from the present room.  See also [[A_beginner%27s_guide_to_the_Lich_mapdb#timeto|timeto]].  Each key should be a string value of the destination room id.  

===timeto===
Type: Hash

<pre{{log2|margin-right=60%}}>
@timeto={"226"=>0.2, "294"=>0.2, "224"=>0.2}
</pre>

"id"=>time

The movement time (in seconds) and id pair for each room a character can reach from the present room.  See also [[A_beginner%27s_guide_to_the_Lich_mapdb#wayto|wayto]].

===image===
Type: String

<pre{{log2|margin-right=60%}}>
@image="wl-wehnimers-1264234799.png"
</pre>

Filename for the image file associated with the room in narost (if any).

===image_coords===
Type: Pixel integer array

<pre{{log2|margin-right=60%}}>
@image_coords=[197, 175, 233, 211]
</pre>

Relative location of the room in the image file, e.g., in [[Script_Narost|narost]] (if any).

x1, y1, x2, y2

x1, y1: Top left corner
x2, y2: Top right corner

This is typically obtained by using <code>;narost fix</code> and clicking the mouse.  It is one of the easiest ways new people can help contribute to the mapdb.

===climate===
Type: String

The sliced output from [[SENSE_(verb)#Rangers|a ranger's sense verb]] which could provide useful information.  See also: [[A_beginner%27s_guide_to_the_Lich_mapdb#terrain|terrain]]

===terrain===
Type: String

The sliced output from [[SENSE_(verb)#Rangers|a ranger's sense verb]] which could provide useful information.  See also: [[A_beginner%27s_guide_to_the_Lich_mapdb#climate|climate]].

===check_location===

Value: either true or nil

This is used primarily for when two separate rooms have the same description. A good example might be a locker in Solhaven compared to a locker in Wehnimer's Landing. When check_location is set to true then that room will do a further check of where you are by determining your general location, instead of matching on the description alone.

This can also be used to determine that there is an error with the room, usually with location and/or duplication. When a room is initially mapped the value defaults to nil, but when Map.current_or_new is used and there are discrepancies, then it will get toggled to true. A good example of this happening would be a room that exists in the database already, but the location value is wrong. This might cause Lich not to display the ID, amongst other issues, and thus give indication the room is not in the database. The trap is blindly creating a new database entry, but further investigation would show the location value is wrong. However, check_location being set to true would give followup issues that might yield awareness of the true issue.

If there are no duplicate entries in the database, and everything appears proper, check_location would need to be manually set back to nil as a final step.

===tags===
Type: Array

<pre{{log2|margin-right=60%}}>
@tags=["some sovyn clove", "some acantha leaf", "some calamia fruit", "pepperthorn root", "ironfern root", "small rose", "heath aster", "some bur-clover root", "some wingstem root", "small wild rose", "white baneberry", "small daisy"]
</pre>

An auxiliary portion of the mapdb for handling miscellaneous data.  The most familiar examples are things like <code>;go2 town</code> and <code>;go2 bank</code> which finds the nearest room with this tag (i.e., someone manually tagged each bank with 'bank'), sometimes indicating a mechanical feature of a room (e.g., 'node', 'supernode') or what items can be foraged there.  There are also more advanced features such as use of peer.

==Resources==
*[https://elanthipedia.play.net/Lich_mapping_reference DragonRealm's Wiki Lich MapDB Reference Page]: A more up-to-date reference guide to editing and updating the mapdb
*[http://forum.gsplayers.com/showthread.php?57828-lrn2map lrn2map thread]: Original information on the mapdb from Tillmen

[[Category:Guides]]
[[Category:Third-Party Software]]