Introduction

The ToastStunt database file is a flat ASCII text file with relevant bits of information separated by newlines. This document will go over the structure of that file and explain how various values are derived. It’s unlikely you’ll be able to make more than minor changes to a database by hand, but this information should prove valuable if you need to parse or attempt to recover a database or data from a database.

The information below is written in the exact order you’ll encounter things in an actual database file. When a specific type of MOO value is expected, that item will link to a section explaining how to interpret that specific type in the database.

Those curious about the server source code should find these functions of particular interest:

• write_db_file in db_file.cc: The entry point into database writing.

Observations to Keep in Mind

It’s worth keeping a couple of things in mind when reading, parsing, or thinking about the database format:

• Types are identified by their numeric type value (e.g. the result of typeof()) immediately before their value.
  • If a type is CLEAR or NONE (5 or 6), there will be no value after the type.
• Unless otherwise indicated, object numbers are integers and do not include the initial pound sign (#).
• See Interpreting Types below for information on how to interpret individual types.

Database

Initial Block

Every database file begins with a recognizable, human-readable header. This is typically something like: ** LambdaMOO Database, Format Version 17 **. This indicates that it’s a LambdaMOO database (of course) and the version of the format in use. The version is important because it tells the server which features are available at the time the database is written, which affects how it gets read back. (For example, databases prior to format version 15 didn’t include the last_move property for every object. Without a proper version, the server would assume this database has that property and attempt to read it, which would fail.) (See version.h if you’re curious to see what each database revision changed.)

• The total number of objects with the player flag set.
  • A list of every object number with the player flag set.

Transitory Data

• X values pending finalization: This header indicates the total number of anonymous objects that have been recycled but have not had their recycle() verb called yet.
  • The next X lines are each object pending finalization. Each object is two lines:
    • The type of the object (e.g. 12 for ANON)
    • The object number (e.g. 4 for #4)
• 0 clocks: Now meaningless. This was a part of early MOO task handling that is now obsolete. Any database with clock information will be using the LambdaMOO database format version 4 or lower, in which case you should reference Anatomy of a LambdaMOO db file
• X queued tasks: This header indicates the total number of queued (forked) tasks.
  • See Forked / Queued Tasks below.
• X suspended tasks: This header indicates the total number of suspended tasks.
  • See Suspended Tasks below.
• X interrupted tasks: This header indicates the total number of interactive tasks that were interrupted (e.g. read() or read_http()
• X active connections with listeners: This header indicates the total number of active connections at the time of shutdown. The next X lines consist of:
  • A string with two numbers separated by a space:
    1. The object number of the connected player.
    2. The object number of the listening object that the player is attached to. (Usually #0.)

Objects

• A number indicating the total number of objects, including recycled objects, in the database. Does not include anonymous objects. (max_object() plus one for #0)
• A list of every object in the database. For each object:
  • IF RECYCLED: A single line with the object number the the word recycled. (e.g. #5 recycled). Done with this object.
  • If NOT recycled: A single line beginning with a pound sign (#) and the object’s number. (e.g. #5)
    • The object’s name.
    • An integer indicating the object flags. See Object Flags below.
    • The object’s owner. (NOTE: This is a single integer, not an object type.)
    • The object’s location
    • The object’s last_move.
    • The object’s contents
    • The object’s parents. If the first number is a 1, the object only has one parent and it’s formatted as an object]. If the first number is a 4, the object has multiple parents (or was chparented with chparents() and a single parent) and is formatted as a list.
    • The object’s children
    • The number of verbs defined on the object.
    • A list of every verb. For each verb:
      • Verb name
      • Verb owner
      • Verb permissions (see Verb Permission Flags below)
      • Verb prepositions (see Verb Preposition Flags below)
    • The number of properties defined on the object.
    • Each property is listed by name.
    • The number of property values being set on the object.
    • Property values. These values are listed in the order they appear in properties(object). This includes all properties defined on the object and properties defined on every ancestor. (When multiple inheritance is involved, it follows the order of parents() for each object.) For each property:
      • The value of the property. This can be any valid type, so determine the type from the first number and consult the Interpreting Types section. NOTE: If you encounter a type of 5, the property is clear and the next two lines won’t exist.
      • The object number of the property owner. (Integer)
      • Property permissions (see Property Permission Flags below)
• The number 0

Verbs

• The total number of programmed verbs in the database.
• All programmed verbs. For each verb:
  • A string indicating the object number (starting with a pound sign) and the verb number. The number is the verb’s position in verbs(object) minus 1 (verb numbers start at 0). (e.g. #0:0)
  • The verb code, ending in a period (.) on a single line.

Queued / Forked Tasks

For each forked task, the following will be written:

• The first line for each queued task consists of four numbers separated by spaces:
  1. The number 0
  2. The next line to be executed in the verb that forked the task
  3. The Unix time the task should be started
  4. The task_id() for the forked task
• The activation information.
• X variables: This header indicates the total number of variables in the verb that forked the task. For each variable:
  • The variable name. NOTE: This includes built-in variables as well, so you will see things like NUM, player, caller, etc.
  • The value of the variable
    • The type of the variable (e.g. 0 for INT)
    • The value of the variable. See Interpreting Types below.
• The verb code of the forked task.
• A single period

Suspended Tasks

For each suspended task, the following will be written:

• A line consisting of three numbers:
  1. The Unix time that the task is scheduled to execute. (Or -1 if the task was suspended indefinitely.)
  2. The task_id() of the suspended task
  3. The type of the return value from a call to resume() that hasn’t had a chance to execute yet. If there is no return value, the type will be 0 (INT).
• The actual value of the return value from resume(). Most of the time this will be 0
• The value of the task_local() variable.
• Four numbers separated by spaces with virtual machine information:
  1. The topmost stack frame (counting from 0). (This is the activation (verb) that is currently executing.)
  2. The root activation vector.
  3. func_id (unused?)
  4. Max stack size: The value of the server option max_stack_depth
• A dump of the activation stack (one for each verb in the stack). For each frame:
  • A header indicating the language version being used. This will match the database version in use at the time the task was written. (e.g. language version 17)
  • The verb code for this particular frame. Always ends with a single period.
  • X variables: This is a header for the variables section. It indicates the total number of variables for this frame.
    • The name of the variable. (NOTE: This includes built-in variables as well, so you will see things like NUM, player, caller, etc.)
    • The value of the variable
      • The type of the variable (e.g. 0 for INT)
      • The value of the variable. See Interpreting Types below.
  • X rt_stack slots in use: A header indicating the number of activation stacks in use.
    • The next lines describe the X stack Vars. Whatever those are.
  • The activation information.
  • The value of the virtual machine’s ‘temp’ register
    • The type of the variable. (e.g. 6 for NONE)
    • The value of the variable. NOTE: If the type is 5 or 6 (clear or none), there will be no value here. See Interpreting Types
  • Three numbers separated by a space:
    1. The activation program counter.
    2. The activation builtin function program counter.
    3. The activation error program counter.
  • OPTIONAL: If the second number above (builtin PC) isn’t 0, this line will contain the name of a built-in function. (e.g. eval)
  • OPTIONAL: If builtin PC is true, and there is built-in function data, it will be here.
    • The actual data written is function dependent. To find what data a function writes here, search for register_function_with_read_write in the server source, find your MOO built-in function, find its C write function (6th argument to register_function_with_read_write), and read the source code there.

Activation

• A dummy variable that always has the value -111
• The value of this
• The object the originating verb is defined on. (The originating verb being the verb that called fork())
• The forked tasks’s thread mode. This is either a 1 for threading enabled or a 0 for threading disabled.
• Nine numbers separated by spaces:
  1. The object number of the ‘receiver’ of the verb. In the case of verb calls on primitive values (e.g. "toast":explode()), this will be the object number of the handler for the primitive value (e.g. $str_proto). Otherwise it’s the value of this.
  2. Dummy value -7
  3. Dummy value -8
  4. The object number of the player that invoked the verb.
  5. Dummy value -9
  6. The object number of the programmer of the verb.
  7. The object number of the object the verb is defined on.
  8. Dummy value -10
  9. The state of the debug flag.
• The word No
• The word More
• The word Parse
• The word Infos
• A string indicating the name of the verb as it was called by the player. This is the same as the verb variable. (e.g. shr if you typed that to invoke the shr*iek verb)
• A string indicating the full name of the verb. (e.g. shr*iek)

Object Flags

The object flag integer is obtained by adding one or more of the values from this table together:

#	Value	Flag
0	1	Player
1	2	Programmer
2	4	Wizard
3	8	Obsolete
4	16	Read
5	32	Write
6	64	Obsolete
7	128	Fertile
8	256	Anonymous
9	512	Invalid
10	1024	Recycled

For example: If you want an object to be a player, a programmer, and a wizard, you would add together the ‘Value’ column for each to get: 1 + 2 + 4 for a total value of 7.

If you’re trying to decipher a flag, it’s slightly more complicated. Without going too deeply into bits, you can accomplish this with a MOO eval. Instead of looking at the ‘Value’ column, look at the ‘#’ column. Our eval will be: FLAG &. (1 << #) != 0

Say we have an object with a flag of 7. To see if that object is a wizard (# 2 in the table), we plug it into our eval: 7 &. (1 << 2) != 0

If it returns 1, the object has the flag. In our case, yep, it’s a wizard! Just remember, use the number from the ‘#’ column, not ‘Value’.

Verb Permission Flags

Verb permissions are obtained by adding one or more of the values from this table together:

#	Value	Flag
0	1	Readable (+r)
1	2	Writable (+w)
2	4	Executable (+x)
3	8	Debug (+d)

Strangely enough, dobj and iobj are also part of a verb’s permission flags:

#	Value	Flag
4	16	dobj = any
5	32	dobj = this
6	64	iobj = any
7	128	iobj = this

For example: If you want a verb to be readable (+r) and debug (+d) with arguments {"any", "out of/from inside/from", "this"}, you would add together the ‘Value’ column for each to get: 1 + 8 + 16 + 128 for a total value of 153.

If you’re trying to decipher a flag, it’s slightly more complicated. Without going too deeply into bits, you can accomplish this with a MOO eval. Instead of looking at the ‘Value’ column, look at the ‘#’ column. Our eval will be: FLAG &. (1 << #) != 0

So if you have permission flags with a value of 9, you can check if it’s writable by plugging it into our eval: 9 &. (1 << 1) != 0

If it returns 1, the permission bit is set. In this case, nope, not writable!

Verb Preposition Flags

The preposition flag is simply a number corresponding to a value. The standard prepositions are listed here. Should your server be weird and add more, you can find them in db_verbs.cc

Value	Preposition
-2	any
-1	none
0	with/using
1	at/to
2	in front of
3	in/inside/into
4	on top of/on/onto/upon
5	out of/from inside/from
6	over
7	through
8	under/underneath/beneath
9	behind
10	beside
11	for/about
12	is
13	as
14	off/off of

Property Permission Flags

#	Value	Flag
0	1	Readable (+r)
1	2	Writable (+w)
2	4	Chown (+c)

For example: If you want a property to be readable (+r) and writable (+w), you would add together the ‘Value’ column for each to get: 1 + 2 for a total value of 3.

If you’re trying to decipher a flag, it’s slightly more complicated. Without going too deeply into bits, you can accomplish this with a MOO eval. Instead of looking at the ‘Value’ column, look at the ‘#’ column. Our eval will be: FLAG &. (1 << #) != 0

Say we have a property with a flag of 7. To see if that property is writable, we plug it into our eval: 7 &. (1 << 1) != 0

If it returns 1, the property has the flag. In our case, yep, it’s writable! Just remember, use the number from the ‘#’ column, not ‘Value’.

Interpreting Types

CLEAR

1. Numeric type value: 5

NONE

1. Numeric type value: 6

STRING

1. Numeric type value: 2
2. A string.

Example

"Hello world!"

2
Hello world!

OBJECT

1. Numeric type value: 1
2. Object number as an integer. (NOTE: Does not include the pound sign.)

Example

#2

1
2

ERROR

1. Numeric type value: 3
2. Integer representing the error value. See table below.

Integer	Error
0	E_NONE
1	E_TYPE
2	E_DIV
3	E_PERM
4	E_PROPNF
5	E_VERBNF
6	E_VARNF
7	E_INVIND
8	E_RECMOVE
9	E_MAXREC
10	E_RANGE
11	E_ARGS
12	E_NACC
13	E_INVARG
14	E_QUOTA
15	E_FLOAT
16	E_FILE
17	E_EXEC
18	E_INTRPT

Example

E_ARGS

3
11

INTEGER

1. Numeric type value: 0
2. The integer.

Example

123

0
123

BOOL

1. Numeric type value: 14
2. 1 if true, 0 if false.

CATCH

1. Numeric type value: 7
2. Integer

FINALLY

1. Numeric type value: 8
2. Integer

FLOAT

1. Numeric type value: 9
2. The float.

Example

123.45

9
123.45

MAP

1. Numeric type value: 10
2. The number of keys in the map.

For each key in the map…

1. Map Key
2. Map value. NOTE: This could be any type, so you’ll have to identify the type by the first number and then reference it in the Interpreting Types section.

Example

["source" -> #123, "time" -> 1670634392]

10
2
2
source
1
123
2
time
0
1670634392

LIST

1. Numeric type value: 4
2. The number of elements in the list.
3. If the list is not empty, the values of every element in the list. NOTE: These elements could be any type, so you have to identify the type of each element by the first number and reference it in the Interpreting Types section.

Example

{#2, "Hey, that's wizard!", 2, 2.22, {"A list in a list, oh NO!"}}

4
5
1
2
2
Hey, that's wizard!
0
2
9
2.22
4
1
2
A list in a list, oh NO!

ANON

1. Numeric type value: 12
2. Numeric reference.
   • If the anonymous object hasn’t been written yet, it’s given a new object number. Anonymous object numbers can be assigned to recycled objects or, if none are available, they are created after the last real object ( max_object() + 1).
   • If the anonymous object references an anonymous object that’s already been written, the number will match the original anon.

When looking for property values on anonymous objects, you have to look for the object created in this step. It will appear in the standard object list as any other object.

Example

*anonymous*

12
5

WAIF

1. Numeric type value: 13

If the waif is a reference to an existing waif:

2. A string beginning with r and ending with the numeric reference to the waif in the waif index.
3. A single period (.)

If the waif is new:

2. A string beginning with c and ending with a numeric reference to a waif in the waif index.
3. The waif class (Integer)
4. The waif owner (Integer)
5. The number of properties that can be set on this waif. This is the total number of instance properties (those beginning with :) on the waif’s class and all ancestors of that class.
6. The values of every non-clear property set on the waif instance. For each property:
1. An integer defining the property’s index into the property map. Properties are counted from 0, beginning with properties on the class and moving down the ancestry.
2. The value of the property. NOTE: This can be any MOO type. You’ll need to use the first number to determine the type and then reference the Interpreting Types section.
7. The number -1
8. A single period (.)

Example

We have two waif classes:
#4: Waifilicious with one property: :flavor
#5: Waiftastic with one property: :activity

Waif #5 is a child of waif #4. Our waif is an instance of #5 with the .flavor property set to "toast":
[[class = #5, owner = #2]]

13
c 0
5
2
2
1
2
toast
-1
.

Last Updated: 2022-12-15 for Database Version 17

Corrections? Comments? Wild bursts of irrational hatred? Contact me: lisdude@lisdude.com