CircleMUD's world is divided into distinct sections called zones. Each zone typically consists of a single, modular, geographically coherent region of the MUD's virtual world with a consistent storyline. Each zone can define its own physical space (the world), monsters (usually called mobiles), objects (such as armor, weapons and treasures), and shops, in which a mobile in a particular room can buy and sell objects to players.
A single zone typically contain less than 100 rooms, 100 monster definitions and 100 object definitions, but a large region can be subdivided into several zones at the author's discretion. For example, the City of Midgaard is divided into two zones, one for the main city and one for the southern residential area. A zone can also use mobiles and objects defined by another zone, but this practice is discouraged because it makes zones less modular, meaning that it becomes more difficult to add or remove one zone without affecting another zone.
Each room, mobile and object within a zone is given a unique number called a Virtual Number or Vnum. The Vnums for the rooms, mobiles and objects are independent, so there can be both a room number 3001 and an object number 3001. When defining and referencing parts of a zone, the zone author always refers to each entity by its Vnum and never by name. Vnums are normally not seen by players. Each zone itself also has a Vnum. A common convention is to number the zone with the Vnums of its component rooms, divided by 100. For example, Midgaard is zone 30, consisting of rooms 3000 to 3099. Mobile and object numbering follows the same convention.
The author of the zone can define aspects of each room such as the terrain type, special properties like whether the room has its own light source or is a death trap, and other parameters. A very important aspect of each room is the position of other rooms in relation to it; for example, from room 3014, one can go north to reach room 3005, east to room 3015, etc. Great care should be given to making the room links logical and consistent. A player who moves east and then immediately west should find herself back in the same room in which she started.
Each mobile is given characteristics such as number of hit points, bare hand damage capability, strength, and special skills and abilities. Objects have parameters such as weight, value, and magical properties. The author can also choose how these three pieces of the world are combined to form the initial state of the zone: for example, the number of each mobile that exist and in which rooms they stand, the equipment that each mobile uses, objects which might be on the floor, and the doors which may be initially locked or unlocked.
When the CircleMUD server runs the zone, it sets each zone to its initial state as defined by the author, and then makes the zone ``come alive'' by randomly making mobiles wander through the zone and, if desired, attack players. While the players are using the zone (killing the mobiles and picking up equipment) the server periodically resets the zone to its initial state (a zone reset) to prepare the zone for the next group of players.
Before descending into the details of MUD building, it should be noted that the formats of the world files are sufficiently complex that it is probably not possible to gain a complete understanding of them merely by reading this documentation. This document is designed to be a reference manual and therefore may not serve as a particularly good tutorial. While there are examples provided at the end of each section, they are only meant to be representative and are not comprehensive examples of all possible ways to use the features that will be described. The most effective way is to learn by example: examine some of the areas that come with CircleMUD and try to figure out the meanings of the numbers in different rooms, objects, mobiles, and zone files, using this manual as a guide. Once you're proficient at reading world files, you'll find that creating them is a much easier task.
Each CircleMUD zone is defined by five types of files: world files, mobile files, object files, shop files, and zone files. World files (*.wld) define the actual rooms and the links from one room to another. Mobiles (*.mob) are the monsters which inhabit the MUD. Objects (*.obj) are the weapons, armor, treasure, and other objects manipulated by players and monsters. Shop files (*.shp) define the MUD's shopkeepers, controlling what they buy, sell, and say. Finally, Zone files (*.zon) bring all the previous elements together to define the initial state of the zone, describing how monsters should be equipped, where monsters should be placed, where objects on the ground should be, which doors should be locked, etc. These five types of files are collectively referred to as ``the world,'' or sometimes the ``tinyworld files.''
CircleMUD uses split world files to make the world easier to
manipulate. Instead of all the rooms being lumped together in a single,
cumbersome file, the rooms are split into many different files, one file
for each area of the world. All five types of files are split in a
similar manner. Circle has one directory for the room files
(lib/world/wld), one directory for the object files
(lib/world/obj), and so forth.
Circle doesn't care how the world files are split or what the names of the
files are, but certain conventions have developed to make management of the
world easier. Each file typically contains information for only a single
zone and the filename is typically the zone number, with an extension
indicating one of the 5 file types. For example, the file 30.wld
contains rooms 3000 to 3099 of zone 30; 42.mob contains mobiles 4200
to 4299 of zone 42, etc.
Also in each of these directories is a file called ``index'' that
tells the server which files from that directory should be loaded when the
server boots and a file called ``index.mini'' which (minimal) set of
files should be loaded when the server is booted with the -m option.
Every world file used by Circle (including the index files) must be terminated by the dollar sign ($) to tell the server that the file has ended. Without the dollar sign, the server will not boot properly.
The split utility that comes with CircleMUD can be used to divide a
large file into a number of smaller files; for example, if you have a
large zone that you'd like to break into several smaller zones. See the
CircleMUD Utility Manual for more information on how to use
split.
When learning about the formats of CircleMUD world files, you'll frequently see references to ``bitvectors.'' A bitvector is a group of flags which each can be either on or off. Bitvectors and their flags are used in many ways within CircleMUD, such as to define the personality of mobiles, the characteristics of rooms, etc. Understanding how to use bitvectors is essential if you want to build a CircleMUD world.
At every point where this document says a bitvector is required, it will be accompanied by a table describing the flags which you can use with that bitvector. The table will look something like this:
1 a DIRTY The room is dirty.
2 b STINKY The room stinks.
4 c MUSHY The floor of the room feels mushy.
8 d SWAMPY The room resembles a swamp.
Note there are four columns in the table. The first column contains the numeric value of the flag. The second contains the alphabetic representation of the flag. The third is the name of the flag, and the fourth is a description of what the flag does.
There are two ways you can construct a bitvector with the table above: the numeric method and the alphabetic method. The numeric method is to select all flags you'd like to activate, take the numbers of those flags as listed in the first column of the table, and add them all up. The resulting sum will be the bitvector. The alphabetic method is much easier: just write down all the letters of the flags you'd like to use with no spaces in between. For both numeric and alphabetic bitvectors, use ``0'' to indicate a bitvector where none of the flags are set.
For example, imagine you want to create a room that is dirty, mushy, and resembles a swamp, but does not stink. Using the numeric method, you'd look up the numbers of those three flags (1 for dirty, 4 for mushy, and 8 for swampy), and add them up to get 13. Using the alphabetic method, the bitvector would simply be ``acd''. Bitvectors are case-sensitive; ``acd'' is very different from ``Acd'' and ``ACD''.
At every point where the CircleMUD format requires a bitvector, you can write either a numeric bitvector or an alphabetic bitvector. They are completely interchangeable. However, be forewarned that if you use alphabetic bitvectors, your area will not be compatible with MUDs based on the original DikuMUD. Alphabetic bitvectors are a CircleMUD enhancement and may not be supported by MUDs based on Gamma Diku.
In some bitvector tables, you will see values whose descriptions say ``Reserved for internal use'' or ``Do not use''. You should never set those flag values in your world files.
After an area is written, there are three steps required to add it to the MUD for testing: copying the files into the proper directories, adding the new filenames to the appropriate index files, and running the MUD in syntax-check mode to make sure the new area is formatted correctly.
All world-related files go in the directory lib/world.
In this example, we will imagine that your new area is zone number
57 (which should consist of rooms, objects and mobiles numbered
5701-5799). Your zone probably has 5 files:
57.wld, 57.mob, 57.obj, 57.shp, and 57.zon.
The first step is to copy each of these files into their appropriate
subdirectory: 57.wld should be copied to the directory
lib/world/wld; 57.mob should be copied to the directory
lib/world/mob, and so forth.
The next step is to add the name of the newly copied world files to the
index file contained in each of the world subdirectories. Note
you will need to change 5 index files: one for each of the world files
that you copied in the previous step. Adding the filenames to the
index files tells CircleMUD that the files should be loaded; they will
not be loaded simply by virtue of being in the correct directory.
First, edit the file
lib/world/wld/index; you should see a list of the current world
(room) files. Add a single line that says 57.wld in the correct
numeric order. Next, add a similar line in the other index files:
add 57.mob to lib/world/mob/index; add 57.obj to
lib/world/obj/index, etc.
Now you can try to boot the MUD with the new world. If you're adding
a new area which hasn't been debugged yet, it's usually a good
idea to run Circle in its syntax-checking mode first. From Circle's
root directory, type bin/circle -c to run Circle's syntax checker.
If the check runs with no SYSERR messages, the syntax of the area is
probably correct and the MUD can be safely booted. Otherwise, check the
CircleMUD SYSERR List for more information on how to correct
the formatting errors. Also, see the
CircleMUD Administrator's Guide for more information on how
to run CircleMUD or how to use the syntax checking mode.