Valhalla v2.07
-- The New and Improved Database Format --
A Pre-release description by quinn@diku.dk
Comments to seifert@valhalla.com
HISTORY
v2.07: Got rid of old format for money definitions.
v2.06: Added 'title' field to zones.
v2.05: Changed 'height' to be a unit field.
v2.03: Added note about importance of proper capitilization of
names.
NAME
dmc - DikuMUD database-compiler.
SYNOPSIS
dmc [-v] [-m] [-s] pathname ...
DESCRIPTION
Dmc is the databse-compiler for DikuMUD (Version 2 and later). It
takes as input a number of source files, and produces a corre-
sponding number of binary datafiles, in a format readable by the
DikuMUD-server.
FILENAMES
A sourcefile should have a filename ending in '.zon'. Files end-
ing in '.zon.Z' are assumed to be compressed, and are piped
through 'zcat' before processing. Output is placed in files with
corresponding filenames, and the suffixes '.data' and '.reset'.
OPTIONS
The argument string is processed from left to right. Options may
appear between filenames, but it should be noted that an option
only takes effect when it is encountered. In most cases, options
should be placed to the left of the filename arguments.
-v Verbose output.
-m Make option. Only compile sourcefiles if they have been modi-
fied more recently than the corresponding output files.
-s Suppress the generation of output files.
GENERAL CONCEPT
The new database format is designed to improve the system on two
factors: Runtime efficiency and user-friendliness (ease of build-
ing). The second part is achieved through the use of a format
that imitates a series of data assignments in a high-level pro-
gramming language. To prevent this higher-level format from af-
fecting the performance of the game, the data files are 'com-
piled' into a binary format that is easily read by the server
program. In some cases, it is possible to store data directly in
the structures used by the server; Thus, data can be read and as-
signed in a single operation. Symbolic names are used for all da-
ta-fields. The Compiler is able to supply default values for
most fields, so the builder frequently only needs to define a few
key values. All units will be referred to by symbolic, user-
selected names within the source files, improving readability.
The compiler will filter the input files through the C-
preprocessor, allowing builders to benefit from the use of in-
cluded files and macro definitions. Predefined macros for often-
used values and names will be automatically included. Each 'zone'
of the game will be contained in one single file, making the pro-
cess of using constructors from foreign sites considerably more
attractive.
The C-PREPROCESSOR
If you're already familiar with this program, you can skip this
section. If not, this is a brief outline of the most important
functions. For details, consult a C-manual (or man cpp).
MACRO SUBSTITUTION
For our purposes, this is the most powerful feature of the pre-
processor. It allows you to enter lines like:
#define DIRTFLOOR {UNIT_FL_NO_WEATHER, UNIT_FL_CAN_BURY}
(note that the '#' must be in column one)
Then, later on in the text, you can write:
flags {DIRTFLOOR, UNIT_FL_SPEC_TICK}
The preprocessor will substitute the 'macro' resulting in:
flags {{UNIT_FL_NO_WEATHER, UNIT_FL_CAN_BURY}, UNIT_FL_SPEC_TICK}
Another function, #include, allows you to include other files in
your zone description. Files containing macro definitions for the
most important values are automatically included.
In addition, of course, the preprocessor permits you to put com-
ments enclosed in /* ... */ anywhere in your file - increasing
the readability.
THE ZONE FILES (data format)
Spaces, Htabs, and linefeeds are considered whitespace and ig-
nored.
A zonefile is split up into 5 sections. A zone-declaration sec-
tion, a mobile (NPC) section, an object section, a room section,
and a reset section. None of the sections actually have to be in
the file, and they may appear in any order.
Each section is preceded by a section header. These are the five
possible headers:
%zone
%rooms
%mobiles
%objects
%reset
The first four sections may be considered lists of definitions.
The last section is can be considered a program in a simple pro-
gramming language.
A definition takes the general form:
field value
Where field is the name of a data field, and value is some value.
Values are of one of 5 types:
Number: A (possibly hexa-) decimal integer, possibly prepended by
a '-'. Hexadecimal numbers are on the normal C-style format (eg.
0x0f3). Hexadecimal digits may be in lower or upper case.
String: A string of characters enclosed in '"'s. Newlines may ap-
pear in the string.
Stringlist: Either a single string (see above), or a construction
like:
{ "Adolf Adolfson", "Adolf", "guard" }
NOTE: A stringlist is used to provide a unit with one or more
names by which the players can refer to it. Due to the way the
parser works, there are some important considerations to make
when writing a stringlist.
An obvious namelist for, say, a small dwarf would be:
names {"small", "small dwarf", "dwarf"}
However, if a player were to type:
hit small dwarf with bottle,
The parser would assume that "small" was the name of the dwarf,
and that "dwarf bottle" was the weapon to be used.
Thus, if one name can form a prefix for another in this style, it
should be placed AFTER that name, e.g.:
names {"small dwarf", "small", "dwarf"}
Note also that the name "small" is really a very questionable way
of referring to a small dwarf, and that maybe "small dwarf" and
"dwarf" should be left as the only alternatives.
Flags: Either a single number, or a list like:
{8, 16, 1, 128}
A list like the above has the effect of binary ORing each member
of the list together. Thus, the list above wouldhave the value
153.
Actually, one would rarely see lists like the above; macro
definitions are supplied for all of the commonly-used flag val-
ues. Thus, you might see:
uflags {UNIT_FL_NO_WEATHER, UNIT_FL_CAN_BURY}
in the definition for a room with a dirt floor.
the '{'...'}' pairs may be nested, to ease the creation of macros
with multi-flag values.
Symbol: Either a standard C-style identifier, denoting some unit
within the zone, or two identifiers, separated by a @ or a /, to
reference a unit in a different zone. The format is:
@
or:
/
The two versions are interchangeable, but it is probably wise to
stick to one format within a single zonefile in order to maintain
readability.
The usual care should be applied when choosing identifiers -
they should be easy to remember and eay to type - especially for
objects that're to be frequently loaded 'manually', eg. by immor-
tals within the game.
Below are descriptions for each of the sections.
ZONE section
The Zone-section defines the global parameters for the current
zone. It is usually wise to place this section in the top of the
file. The fields and their formats are as follows:
title This is the title of the zone, for example Town of
Midgaard, Thieves Guild, Forest of Haon Dor, or whatever. It is
currently only used when players request a list or available ar-
eas in the game. Leaving it undefined will keep it away from the
areas list.
lifespan
This defines the interval between resets for this zone, in min-
utes. Default is 60.
reset
This should be set to one of the macros RESET_NOT, RESET_IFEMPTY,
RESET_ANYHOW. Default is RESET_ANYHOW, which means that the zone
will be reset even if players are present within it.
creators
This should contain the MUD names of the creators of the zone.
Filling out this field will enable immortals to see who to con-
tact in case of zone problems. It also gives the possibility for
directing errors to you directly via mud-mail. Seen via the 'stat
zone' mud-command.
notes
This is a plain text description of the zone for other immortals.
Seen via the 'stat zone' mud-command. It is often a good idea to
include your e-mail address in the notes so that you can be
reached easily by the implementors.
If existing, this entry defines the name of the zone.
Default is the trailing component of the current filename, minus
the trailing ".zon".
ROOM section
This section defines the rooms in the zone. Each room consists of
a symbol, which is the identifier of the room; a number (possibly
zero) room fields, and a trailing 'end', to mark the end of the
room.
The fields are as follows:
movement
How hard it is to walk in and out of the room. The possible val-
ues are defined and described in values.h, and have SECT_ prefix-
es.
romflags
Special flags for this room (room/object/mobile-flags; hence the
name). The values are defined in values.h, and have the prefix
ROOM_FL_.
exit[] to , key , keyword ,
open , descr ;
At least one of the subfields must be defined, and they may ap-
pear in any order. The separating commas are optional, whereas
the trailing semicolon must be present.
The macros NORTH, SOUTH, EAST, WEST, UP, and DOWN denote the ex-
its. Further, the macros north, south, east, west, up, down (low-
ercase) are supplied. The macro north is defined to exit[NORTH],
etc. A valid exit definition is thus:
exit[NORTH] to temple@midgaard keyword "temple";
or:
north to temple@midgaard keyword "temple";
(note that the '{' and '}'s are not needed for the stringlist, if
it contains only a single string.)
The keywords can be used, for example, for the 'enter'-command in
the game (eg, "enter shop").
The description is seen by a player which tries to look in that
direction. If none is defined, he/she sees "You see nothing of
interest.", or some such string.
the to-field says which room the exit leads to (it may be in an-
other zone). If it is left undefined, the exit is 'blocked'.
The flags for the open-subfield are defined in values.h, and have
EX_ prefixes.
The key defines the key which can lock/unlock this door. If none
is defined, the door cannot be locked/unlocked.
UNIT-fields
In addition to the standard room-fields, each unit
(room/mobile/object) has a common set of fields. These are de-
scribed below:
names
The namelist of the unit. Default is a list consisting of a sin-
gle name, namely the identifier of the unit. See the discussion
about stringlists above.
Be aware of the proper use of capital letters. Any proper name
such as Mary, Adolf, Tiamat, Jafar, Hansen and John should be in
caps, whereas names like cityguard, guard, armourer, weaponsmith,
alchymist and mage should be in lowercase only. The reason should
be fairly obvious - if not mail me and I will add a lengthy ex-
planation. The "caps" consideration is exactly the same which
must be used in the "title" section (below).
For example:
names {"Adolf Adolfsson", "Adolf", "cityguard", "guard", "cap-
tain"}
title
For rooms : the string shown before the long description, eg.
"The Temple".
For objects: eg. "an apple", "a dagger", etc.
For mobiles: eg. "the dragon", "the dwarf", "Fido", etc.
Please be conscious of the capitalization of these strings:
Whereas the title of a room should often contain leading capital
letters, this is rarely the case for mobiles and objects. An ex-
ception is a monster like "Puff".
Default is the first name of the namelist.
descr
The long-description of the unit. Again, this is treated somewhat
differently for the various kinds of units.
For rooms: The description people see when they stand in the room
(unless they're in compact mode).
For mobiles: What people see of a mobile if it's in its default
position, Eg. "A big ugly troll looms before you.".
For objects: What people see when the object is lying in the
room.
extra Adds an extra-description to the
unit. An arbitrary number may exist in any unit. An empty
stringlist ('{}') matches the namelist of the current unit.
Hence, if you want to tag a description to the name(s) of a unit,
this is a good shorthand.
key
The object necessary to lock/unlock this unit. Eg:
key goldkey@midgaard
open
Some characteristics related to containers. The flags are the
same as for room-exits (the EX_ prefix macros).
manipulate
Flags describing the handling-characteristics of the unit. The
flags are defined in values.h, with MANIPULATE_ prefixes.
alignment
The alignment of a unit, -1000 is most evil, 0 is neutral, +1000
is most good. Any value in [-1000..-350] is considered evil. Any
value in [+350..+1000] is considered good. Values in between are
neutral. Default is 0.
minv
The level for which this unit is invisible. Default is zero.
flags
Flags describing the unit. The values have the prefix UNIT_FL_
(see values.h)
weight
The weight of the unit.
capacity
The carrying-capacity of the unit.
height
The height a monster in centimeters, the length of a rope, or the
size of a weapon, shield or armour (the latter have their size
specified as the size of the humanoid required to wield them).
One centimeter = 0.3937 inches, and 1 inch = 2.54 cm. 12 inches
is 30.48 cm, 12*6 inches = 72 inches = 182.88 cm
special text time bits
The number of a special routine to associate with this mobile.
An arbitrary number of special routines may be associated with a
mobile. The text-field is optional. If included, it sets the da-
ta-field associated with that function. Note that only some func-
tions use the data-field, and that others elect to set it them-
selves. An example of a special-routine that uses a text-string
stored in the data-field is SFUN_RANSAY, which, at random inter-
vals, feeds the text to the 'say'-command. The