<html>
<head>
<title>The Daleken v1.12 File Format</title>
<link rel="stylesheet" type="text/css" href="doc.css"
title="Documentation Standard Style">
</head>
<body bgcolor="#ffffff">
<table class="main" width="600" border="0">
<tr><td>
<div align="right">
DalekenMUD 1.12 documentation.
<br>Updated 5 November 2000.
<br>by Martin Thomson.
</div>
</td></tr>
<tr><th class="heading">
<h1>The Daleken v1.12 File Format</h1>
</th></tr>
<tr><td>
<p>This document outlines the file format that is used by virtually all files in Daleken. This format is universal to area and player files as well as the many miscellaneous files used by the server. Let this serve as a warning for those who wish to read on, this document is a little technical and dry, it contains a specification that I have tried to make palatable, but this is very difficult given the subject matter.</p>
<p>The basic concept is that the server will know what data it wants, through the use of detailed tables (see db_io.c for details). However the format is designed to be able to cope with some unknown data.</p>
<p>The format is based somewhat on C language syntax. However this does not entirely suit the purpose of a data file, so this has been added to somewhat.</p>
</td></tr>
<tr><th class="heading">
<h2>Basic Syntax</h2>
</th></tr>
<tr><td>
<p>Each object in a data file is a single line. This may seem limited, but through the use of bracketing this is quite flexible.</p>
<p>Every line must end with a semi-colon (<code>;</code>). This gives the server a point of reference, as well as looking tidy.</p>
<p>The basic format of <em>every</em> line is as follows:
<blockquote><code>
<name> <value>;
</code></blockquote>
This format is the basic building block of the file format, it can be extended greatly as we will see.</p>
<p>Names are known by the server and they tell where the data is to be put. A name is case insensitive, so 'extra' and 'eXtrA' are the same to the server. This name tells the server not only where to put the data, but what type of data to expect and how to process that data.</p>
<p>Files end when the name 'eof' is read. Anything after this tag is ignored, completely.</p>
<h3>Comments</h3>
<p>Comments are marked by a hash (<code>#</code>). Anything on a line after a hash is ignored. In this document comments are often used to point out notable features.</p>
<h3>White Space</h3>
<p>The format follows the C convention with white space, which means that it is used as boundaries to values, but the amount is not important. Tabs and end-of-line characters are treated in the same manner as single spaces and the number that occur is not important (the exception to this is within a quoted string, see below).</p>
</td></tr>
<tr><th class="heading">
<h2>Data Types</h2>
</th></tr>
<tr><td>
<p>There are four types for data in the file format:
<ul><li>Numbers</li>
<li>Strings</li>
<li>Arrays</li>
<li>Compound Structures</li></ul>
Of these, the types can be reduced to the two basic elements, Number and String</p>
</td></tr>
<tr><th class="heading">
<h2>Numbers</h2>
</th></tr>
<tr><td>
<p>There are several forms for a number in the file format, this is representative of having several uses for numbers in the server. A number is not always simply used as a pure number, sometimes it must represent a bit field or it might represent a value. These two types are refered to as 'direct' and 'mapped'.</p>
<p>Direct numbers are entered directly as digits into the file, this is the simplest form of a number. Direct numbers may also be entered in octal (precede with <code>0x</code>) and they may also include vertical bars (<code>|</code>) to represent the binary OR of several values.</p>
<pre>
Strength 12; # A simple number.
Act 0x13; # A bit field represented in octal.
Affected 4|8|128; # A list of OR'd values.
</pre>
<p>Mapped values represent bit fields or some form of enumeration, the value is represented as a parenthesized series of words. Each word in the set represents a different bit, an enumeration is represented as a single word.</p>
<p>For most values the lookup table used to map the words to values in the server will be known, however to enhance the flexibility of the format the lookup table may be specified in the file. Simply make the first word in the wordlist the name of the lookup table, enclose this word in angle brackets (<code><></code>)to signify that it is the table name.</p>
<pre>
Act (npc sentinel); # Two flags in a bit field.
Class (warrior); # An enumerated type.
Spec (<specfun> breath_any); # Naming the table.
</pre>
<p>Thus it can be seen that numbers take two forms, direct and mapped. All direct values start with a digit and all mapped values start with a left parenthesis.</p>
<p><b>Note:</b> Words used for mapped values may contain spaces, but they must be quoted. This sounds a little strange until you see an example:</p>
<pre>
Class (Martial Artist); # Makes no sense to the parser - WRONG.
Class ("Martial Artist"); # Makes perfect sense.
</pre>
<p><b>Note:</b> Vectors are bit fields that extend past the normal bounds for a number, they are stored in small arrays. The file format does not distinguish between vectors and regular bit fields. The distinction is made by the server, this simplifies the format since there is no need for any different treatment.</p>
</td></tr>
<tr><th class="heading">
<h2>Strings</h2>
</th></tr>
<tr><td>
<p>Strings as values are different from the words used as keys and in the mapped numbers. Each string is quoted in the style of C, that is it starts and ends with a double quote (<code>"</code>). In the string special characters may be represented by quoting with a backslash (<code>\</code>). End of lines are represented by <code>\n</code>, so strings may exist all on the one line. So that strings are more readable actual end of lines are ignored.</p>
<pre>
Name "a person"; # The most basic string.
Description "A man stands here shivering in the\ncold. He has black hair.\n";
</pre>
<p>In the above example, the long description covers two lines, the same string may be entered in the file as follows with no change in the outcome.</p>
<pre>
Description "A man stands here shivering in
the\ncold. He has black hair.\n";
</pre>
<p>However the space after 'in' may be missed in this case. The preferred method of entering a string is as follows:</p>
<pre>
Description "A man stands here shivering in the\n
cold. He has black hair.\n";
</pre>
<p>This form is the easiest to read and debug.</p>
<p>A number of different backslashed values are understood by Daleken, the number is restricted as only a few are needed in the server, some values may cause problems in display such as the escape character (<code>\e</code>).</p>
<table class="sub" cellspacing="0" cellpadding="2">
<tr><th class="top">Code</th><th class="top">Meaning</th></tr>
<tr><td><code>\n</code></td><td>End of line.</td></tr>
<tr><td><code>\r</code></td><td>End of line (same as <code>\n</code>, don't duplicate these).</td></tr>
<tr><td><code>\"</code></td><td>Double quote - doesn't end string.</td></tr>
<tr><td><code>\\</code></td><td>Backslash character.</td></tr>
<tr><td><code>\t</code></td><td>Tab character.</td></tr>
<tr><td> </td><td>Anything else is entered as is.</td></tr>
</table>
</td></tr>
<tr><th class="heading">
<h2>Arrays</h2>
</th></tr>
<tr><td>
<p>Arrays are a simple form of compound data. They are usually a group of values of the same type. Arrays may be represented in this format by a enclosing a list of values in square brackets (<code>[]</code>). Each element of the array is separated by commas.</p>
<p>In order to allow for sparse arrays with a default value in most elements and differing values at only a few points the array cells may be referenced. The array reference comes before a value and it starts with an 'at' symbol (<code>@</code>). This symbol is followed by the index of the array, which may be entered in any of the forms for a number described above. If the next index is not specified, then it is assumed to be one larger than the last value.</p>
<pre>
# An array of numbers:
Numbers [ 1, 2, (wielded), 0 ];
# An array of strings:
Strings [ "one", "\thello" ];
# An indexed array of strings:
Indexed [ @3 "third", @5 "fifth", "sixth" ];
# Another indexed array:
Skills [ @(<skill> magic missile) 75, @(<skill>armour) 76 ];
</pre>
<p><b>Note:</b> When using mapped numbers to index the array, ensure that you specify what table to map the values onto. The file reader is not capable of determining where to look in this case.</p>
</td></tr>
<tr><th class="heading">
<h2>Compound Structures</h2>
</th></tr>
<tr><td>
<p>This is the most complex of the data types, integral to the storing of actual objects in the system. A complex type consists of a combination of up to all four data types in a single object.</p>
<p>A compound structure's value is enclosed in curly braces (<code>{}</code>). Within these braces the values of the complex object are specified.</p>
<pre>
object {
vnum 700;
name "flaming gate hell pit";
short "a &rflaming&x gate to &KHell&x";
long "Flames erupt from a pit in the ground leading to the depths of Hell.\n";
level 1000;
};
</pre>
<p>Compound types may be nested within other compound types and within arrays. This allows for a range of flexibility. There is no limit to how deep a compound object may be nested.<p>
<p>Compound types that are nested may also be members of linked lists. The loading program will recognise linked list members and any of these objects that occur twice will be chained together into that list.<p>
<pre>
Object {
Vnum 3717;
Name "white holy symbol";
Short "a white holy symbol";
Long "You see a white holy symbol here.";
Level 1;
Weight 5;
Type (armour);
Wear (take neck);
Extra (bless);
Material (steel);
Values [2, -10, 0, 0];
Affect { # A nested compound object.
Location (wisdom);
Modifier 1;
};
Affect { # The second affect element.
Location (mana-spirit);
Modifier 10;
};
};
</pre>
<p>The following example demonstrates nesting of compound objects within arrays. The 'exit' key is an array of complex values. The array indexing is used with the 'dir' table so that the file is easier to read.</p>
<pre>
Exit [ @(<dir> north) {
ToRoom 3714;
Flags (door closed);
}, @(<dir> south) {
ToRoom 3712;
} ];
</pre>
<p><b>Note:</b> The format does not have any mechanism that allows for two dimensional arrays (nesting arrays).</p>
</td></tr>
<tr><th class="heading">
<h2>Miscellaneous</h2>
</th></tr>
<tr><td>
<h3>Loading</h3>
<p>The server loads any file using the data definitions it has (<code>db_io.c</code>). Any objects that occur at the top level (i.e. any object not nested inside another) has a function associated with it that allows it to be entered into the world. At this top level objects are created and entered into the world based on these functions. Nested objects are only entered as a part of the top level object.</p>
<h3>Naming</h3>
<p>Every object name is unique at the level that it exists. This means that all top level objects have a unique name. On the other hand objects within objects only need a unique name within that object. This leads to a form of name space that allows for the same name to be used within different objects.</p>
<h3>Default Values</h3>
<p>Almost every value has a default value in the data definition tables. If a name-value pair is missing from the file, then this value is automatically assigned. Two benefits come from this: smaller data files with keys missing on purpose; and additions to data definitions without the need to hand edit files - the default value can be applied to every instance.</p>
<h3>Saving Data</h3>
<p>One of the benefits of this file format and the associated data definitions is that files can be written using the same definitions as are used for reading. Most of the data in the area files are written using the automated saving system. This system has inbuilt support for default values, which makes the saved files comparatively small.</p>
<h3>Exceptions to the Rule</h3>
<p>It is acknowledged that this format is inadequate for all types of data as stored by a mud. Thus there is a facility to extend the format slightly for these cases. Resets are one such example, although they could fit within the bounds of the format, the old format is maintained somewhat to simplify their representation.</p>
<pre>
Resets {
M 3711 1;
E 3713 ("waist");
};
</pre>
<p>The format has a need to utilise these functions occasionally in order to read or write special data units, however this is streamlined through the use of an association of each data type with a special function that handles all special cases if needed. One good example of this is object values, which are written differently based on what type of object is represented.</p>
</td></tr>
</td></tr>
</table>
</body>
</html>
