Zugg Software :: View topic - Everything I know about the Cmud Map Database

Wizard Joined: 22 Mar 2007 Posts: 2320

In this thread, I will post what I have discovered about how to modify direction values in the map database, or add new directions in Cmud. For convenience, it will be broken into several posts. If I get around to it, I will add other posts about other customizations you can make in the map database.

Wizard Joined: 22 Mar 2007 Posts: 2320

DIRECTIONS IN THE MAP DATABASE

In the sqlite map database, directions are defined in the table DirTbl. This table has seven columns:
* DirId is the internal identifier used within the map database for a particular direction. It is used in ExitTbl to specify the direction to draw links (in the DirType and DirToType columns, described below).
* DirName is a text name for the direction, but this name is not used anywhere else in the map database, nor is it used in Cmud. Cmud completely ignores this column.
* It is not clear what the column DirRef is intended for. Like DirName, DirRef is not used anywhere in the map database or in Cmud, as far as I can tell.
* The RevId column specifies the natural reverse direction for the row. It specifies the identifier (DirId) of the direction opposite to this direction, e.g. the row for north would have RevId equal to the identifier for south. It is important for reverse directions to be consistent, with each member of the pair identifying the other as the reverse. Inconsistent reverse directions may lead to weird mapping problems or database corruption errors in Cmud.
* Dx, Dy, and Dz specify the default location for a room in the specified direction. A positive Dx is to the right (normally east), positive Dy is to the bottom of the screen (normally south), and positive Dz changes level upward (normally up). The values in Dx and Dy should be interpreted as percentages, which get multiplied by the coordinate system of a zone (I believe by the DefSize and DefSizeY values of ZoneTbl, but have not tested it). The default DirTbl has values of 200 (i.e. 200%). The width of one default room is 100%, so the default map configuration has one room-width empty between adjacent rooms.

Cmud tries to interpret text from the mud, identifying room names, room descriptions, and room exits. When it creates a new room in a particular direction, say northeast, it will initially create it in the position specified by the Dx, Dy, and Dz values relative to the current room. On the map display, the exit from the current room will point in the direction Dx/Dy. If both Dx and Dy are zero, the map display will use the icon for up, down, or other exits, based on the Dz value. On the map display, the other end of the link will come out of the new room in the direction Dx/Dy specified by the reverse direction identified in RevDir. Of course, both the room placement and the direction of the reverse link can be changed manually or programmatically. The values specified in DirTbl are only the default values used when initially creating rooms and links.

In the map database, a link between two rooms is represented by two rows in the table ExitTbl. One row specifies the link information from one direction, the other row specifies the link information from the other direction. In each row, ExitId is the identifier for the link in one direction. ExitIdTo specifies the corresponding row in the other direction. Similarly, FromId specifies the room identifier (in table ObjectTbl) for the starting point of the link, and ToId is the identifier for the room at the other end of the link. DirType is the exit direction (from DirTbl) from the starting point, and DirToType is the exit direction from the other end.

It is very important that both rows match in their information: ExitId of one row matches ExitIdTo of the inverse row, FromId matches ToId of the inverse row, and DirType matches DirToType of the inverse row. If the pair of rows do not match, the map display may display weird links (best case), or you may get critical error messages. You may accidentally lose map information if Cmud tries to fix these errors. The database does not define constraints to enforce consistency! All data checking and constraints is done within Cmud, not in the database design. If you manually edit the tables, you must be extremely careful or risk fatal corruption!

(I am thinking of testing whether I can add constraints to the tables. The question is whether Cmud would consider this to be corruption and throw an error. If I experiment with this, I will post the results.)

A special direction, labeled None in DirTbl, is used for incomplete exit links. If a link has not been explored and the room to which it connects is unknown, ExitTbl will have only a single row for the link. The ExitIdTo value will be -1, the ToId will be the starting room (i.e. the same as FromId), and DirToType (the reverse direction) will be the identifier for the None exit. This causes the map to display the truncated link everyone is familiar with.

Wizard Joined: 22 Mar 2007 Posts: 2320

DIRECTIONS IN CMUD

Cmud defines directions in settings created by the #DIRECTION command or in the package editor under Edit > New > New Direction. I will refer to these as Direction Settings. Direction Settings are not normally visible in the package editor unless you have clicked Edit > New > New Direction. Direction Settings have a Name, a Reverse, a Value, and a Dir.

* Name (or dirchar) is a single letter which is used in Cmud Path values (e.g. #PATH, #MAP, #MOVE, etc.). Capitalization does not matter; 'a' is the same as 'A' in a Cmud Path. Name must be a letter, not a number or punctuation.
* Reverse (or revchar) is also a single letter, specifying the Direction Setting which is the natural reverse of this direction. It is best that pairs of inverse directions consistently specify each other as Reverse, so that #RETRACE can invert a Path. But missing or invalid Reverse values will not cause an error message or database corruption as far as I know. I believe that Reverse is only used in the #RETRACE command and the %pathreverse() and %reversedir() functions, and not any underlying Cmud or mapper functionality.
* Value (or dircommand) is a string list of commands to invoke movement in the specified direction. An example might be "n|north|swim n|swim north". Cmud will interpret any of the list members as an alias for movement. In addition, the first element (and only the first element) of the list acts as an alternative name for the Direction Setting, which can be used in the commands #MAP, #MOVE, etc.
* Dir (or mapdir) is a mapping direction which the Direction Setting corresponds to. The CMUD documentation lists the following as legal values: n, ne, e, se, s, sw, w, nw, u, d, other. However, the pull-down menu when editing a Direction Setting in the package editor lists several additional legal values: None, North-Up, East-Up, South-Up, West-Up, North-Down, East-Down, South-Down, and West-Down.

When typing commands to the mud, Cmud recognizes as movement only the commands listed in the Value string lists of the defined Direction Settings. It is possible to write aliases and triggers which expand the functionality of movement (such as for leading a party of allies). But in order to cause a character to move on the Cmud map, the alias or trigger must invoke one of the commands in the relevant Direction Setting. #MAP, #MOVE, and some other commands will only recognize the single-letter Name of a Direction Setting or the first command listed in the Value of a Direction Setting.

(Technically, you could write a detailed set of aliases and triggers which move the character with #TELEPORT commands, etc.. But generating new maps this way would essentially require duplicating the built-in Cmud functionality for recognizing rooms, exits, and descriptions, or require manual map creation. This is not practical except for specialized movement situations.)

The mapdir value Other is a special value. It is used for room exits which cannot be associated with a map direction. I recommend against repurposing this value for anything else. Some Cmud code appears to make special use of this value. Redefining this direction could lead to unexpected quirks in Cmud.

The documentation says that specifying the mapdir in the #DIRECTION command is optional. While this is technically true, leaving mapdir empty is useless. A blank mapdir in #DIRECTION creates a Direction Setting with Dir set to None. This is a special value specifying no movement. Any commands listed in the Value of this Direction Setting will be treated by Cmud as a non-action (though it will still be sent to the mud and may produce action within the mud). It is equivalent to the direction None in DirTbl in the map database. While None could probably be redefined in the map database, that would break Cmud map creation. As I described earlier, Cmud uses this special value for the other end of links which have not been completed. I have not tested it, but it seems likely that redefining the None direction could result in fatal map corruption.

This means that a value for mapdir or Dir is effectively mandatory. The Name of a Direction Setting must be a letter, so it might seem that one can define up to 26 Direction Settings. But in practice, there are only 20 legal values of Dir and two of them are special values, leaving only 18 possible Direction Settings which could be defined or repurposed. If your mud has the traditional eight compass directions plus up and down, you are limited to just 8 additional Direction Settings which can be defined.

My next post will describe the complex interaction between Cmud Direction Settings and DirTbl in the map database, but I'm not sure how soon I will get that posted.

Wizard Joined: 22 Mar 2007 Posts: 2320

EDITING THE MAP DATABASE

Before I go into the interaction of Direction Settings and the map database, I should add some general notes about viewing and editing the map database.

The map database uses SQLite. There are 14 tables in the database, but Cmud itself does not modify most of them. The only tables that Cmud modifies are ObjectTbl (listing all the rooms), ExitTbl (listing all the links between rooms), and ZoneTbl (listing all the zones). To a very limited extent, configuring a map can modify a few more tables. Even in the tables it modifies, Cmud does not modify all of the columns. Cmud will read the data from all the tables, and display the results in the mapper, but it cannot modify most of the database. The ability to modify those other tables and columns opens up huge possibilities for customizing your maps.

The easiest and safest way to modify the database is with ZMapper. To do this, you must use the mapconvert program to convert the SQLite database into the Microsoft Access database used by Zmud and ZMapper. ZMapper must be purchased, but mapconvert is available for free from Zugg's download site. ZMapper will let you do a lot of things, such as creating new room types and room shapes, new link types, create bitmap icons and vector images, add new text styles, and create background images and foreground text. There is some training documentation but it is a bit sparse. It may take some practice and experimentation to see the full potential of ZMapper.

But even ZMapper does not give you complete access to everything in the map database. In particular, it does not let you create new directions. Even more customization can be done by directly editing the map database. There are numerous SQLite database browsers out there; the one I use is DB Browser. Here are some important notes about manually modifying the map database.

First, a WARNING: Do not try to play with the the map database file unless you have some experience with SQL databases! The Cmud map database file is crudely designed, with no constraints, no validation, no definitions for cross-table references. It is far too easy to create critical errors in the data even if you know what you are doing.

Second, study the tables in the database thoroughly before trying to make any manual changes. There are complex interactions between the tables in the database, but all the interactions are coded directly in Cmud, not in the database itself. And the database does not tell you what those interactions might be! A good method to study the database structure might be to create a new map database, with a few rooms and links. This will let you see what real data looks like, without endangering your active map, if you have one. If you have ZMapper, you can also create new room types, exit types, styles, etc., and see what the result looks like when you convert back to SQLite. With study, most of the database can be interpreted, though there are some mysterious columns that I still do not understand. Some of them may not be used in the Cmud mapper at all.

Third, make a backup copy before you make manual changes. If you mess up the database badly, restoring from the backup copy is very handy.

Fourth, don't overdo it. Just because you can make fancy font styles and customized shapes for doors doesn't mean you have to do it. Think carefully about what you want to do, and plan what needs to be done to accomplish it. Simply playing with the database is a sure way to mess things up completely. On the other hand, playing can be a convenient way to learn how to do things, if you keep backup copies or use a new database for your experiments.

Later, I may add more specific tips on what can be modified in the database tables and how.

Wanderer Joined: 03 May 2005 Posts: 72

Thank you so much for taking the time to do this and write it up. Lots of useful information here