DB File Format DB File FormatMoo databases are written to disk using a text-only format. Despite being text, it is a challenging format to read and edit due to the lack of internal signposts. This page attempts to document the format so that compatible or interfacing applications may be written.
Before diving into parsing the database file, it is worth taking a step back and asking if this is what one really wants to do. Most Moos run continuously and their database files are written to disk every hour or so. The file on the disk is just a snapshot of the Moo's database at the point it was written. Which means it is out of date. It also means that any changes to this file won't affect the Moo, and will just be overwritten next time the Moo saves itself. The only time when the disk file is considered authoritative is when the Moo is shutdown. Therefore if one is dealing with an executing Moo, one probably wants to open a network connection to it and query the database that way.
Another reason one probably does not want to use this specification is that there already exist a collection of tools which read the database:
Ok, you still want to play with the raw Moo Database file? The above three tools are good starting points. They are written in C++, C and Python respectively. The specification below describes the format in detail.
The first line of the database file specifies the version. Modern Moo
databases start with:
** LambdaMOO Database, Format Version 4 **
This format has remained stable for over ten years.
The version string is followed by four integers, each on their own line:
Next are the numbers of every object which has a player flag. The
content and the order is the same as the players() function. These are
raw integers, one per line, with no '#' symbols. This list must be the
same length as the number of players listed in the intro block. e.g.
2
71
36
38
This block is required but redundant as the player flag is also
specified on each object's definition (below).
Next is all the data to define the objects and their properties. There are two classes of objects, recycled and created. A recycled object is simple, just one line containing the object number and the word 'recycled', e.g. #123 recycled A created object is more complicated, each such object starts with the following data, one per line:
The flag integer is made by adding the following:
Thus in the above example, 152 = 128 + 16 + 8
The contents lists and child lists are encoded in a linked-list format. The parent links directly to the first child, then that child links to its next sibling, and so on until one hits -1. Likewise a container links to the first object in the contents list, then that object links to its next neighbour, and so on until one hits -1.
Each object has a list of all verbs defined on it. The definitions start with the number of verbs, e.g. 6 This is followed by that number of verb definitions. Each definition has four lines, which defines everything about the verb except the verb code itself:
The perms integer is made up by adding the following:
Thus in the above example, 45 = 32 + 8 + 4 + 1
The preposition integer is one of the following:
This is the standard list of prepositions, any changes would be made in db_verbs.c
Each object also has a list of the names of all properties defined on
it. This section starts with the number of new properties, and is
followed by exactly that number of property names. e.g.
4
drop_failed_msg
drop_succeeded_msg
take_failed_msg
take_succeeded_msg
This section contains the perms and values of every defined or inherited property for this object. As usual, the block starts with the total number of properties to be defined, e.g. 12. The properties are then listed, starting with the ones on this object (as named in the previous section), then the properties from the parent, grandparent, etc. Each of these properties contains the following three elements:
The perms integer is made up by adding the following:
Thus in the above example, 5 = 4 + 1
The type and value section is a bit more complicated. The type integer is one of the following:
| # | Type | Example (File) | Example (Moo) |
|---|---|---|---|
| 0 | integer | 0 123 |
123 |
| 1 | object | 1 5 |
#5 |
| 2 | string | 2 Hello! |
"Hello!" |
| 3 | error | 3 10 |
E_RANGE |
| 4 | list | 4 2 9 3.14 2 Pi |
{3.14, "Pi"} |
| 5 | clear | 5 | N/A |
| 9 | float | 9 2.5 |
2.5 |
The type integers are the same ones returned by the Moo's typeof() function. The odd one out is 5, clear. If the property is clear, then 5 is all that is printed, there is no value. In order to retrieve the value one would have to dig back through the object's ancestors until one found a non-clear property.
The other odd one is 4, list. A list starts with the number of elements within the list, followed by the the types and values of each element (which may themselves be lists).
The error value is indexed into the Moo's list of errors (starting with index zero). The standard list of errors is {E_NONE, E_TYPE, E_DIV, E_PERM, E_PROPNF, E_VERBNF, E_VARNF, E_INVIND, E_RECMOVE, E_MAXREC, E_RANGE, E_ARGS, E_NACC, E_INVARG, E_QUOTA, E_FLOAT}
Some Moos may have non-standard data types (such as WAIFs) which would have their own type integer and value formats.
This block is very simple, it is a list of every verb in the
database. The total number of verbs was already defined in the intro
block. Each verb starts with the object number, a colon and the number
of the verb (zero based). The verb is listed without indentation. It is
terminated with a line containing only a dot ('.'). e.g.
#5:0
this:moveto(player);
if (this.location == player)
player:tell(this:take_succeeded_msg() || "Taken.");
if (msg = this:otake_succeeded_msg())
player.location:announce(player.name, " ", msg);
endif
else
player:tell(this:take_failed_msg() || "You can't pick that up.");
if (msg = this:otake_failed_msg())
player.location:announce(player.name, " ", msg);
endif
endif
.
At the very end of the database file are four optional blocks
containing clocks, queued tasks, suspended tasks, and active
connections. Databases saved while executing may have entries here, but
in most core databases these would be empty. e.g.
0 clocks
0 queued tasks
0 suspended tasks
0 active connections with listeners
I have no interest in these status blocks, so I haven't decoded their formats. If you would like to submit documentation for this section, feel free to mail me.
