Difference between revisions of "Manual:Zone Manual/Zone Source File"

From DikuMUD Wiki
Jump to navigation Jump to search
(checked against the current code (wiki review 2026-11-15))
 
Line 1: Line 1:
 
== Zone source file ==
 
== Zone source file ==
 +
This chapter shows the parts of a zone file and the kinds of values its fields take. The next page covers the zone's header. After both you can write an empty zone that compiles.
  
−
In this chapter we will define all the sections of a zone file
+
=== Sections ===
−
and go in-depth on the zone info section. Once complete with this
+
A zone file is made of sections. Each starts with a header on a line of its own:
−
chapter you should be able to create an empty yet compilable zone.
 
  
−
A zone source file is split up into 6 sections. A
+
{| class="wikitable"
−
zone-declaration section, a mobile (NPC) section, an object
+
! Header !! What it holds
−
section, a room section, a reset section, and the DIL
+
|-
−
section.  The zone section is the only section that  has to be in the file, and
+
| <code>%zone</code> || The zone's name and its global settings: title, reset interval and mode, creators. See [[Manual:Zone_Manual/Zone_Source_File/Zone_information_section|Zone information section]].
−
they may appear in any order.
+
|-
 +
| <code>%rooms</code> || The rooms. See [[Manual:Zone_Manual/The_Room_Section|The Room Section]].
 +
|-
 +
| <code>%objects</code> || The objects. See [[Manual:Zone_Manual/The_Objects_Section|The Objects Section]].
 +
|-
 +
| <code>%mobiles</code> || The NPCs. See [[Manual:Zone_Manual/The_NPC_Section|The NPC Section]].
 +
|-
 +
| <code>%dil</code> || DIL templates: programs that any room, object or NPC, in any zone, can use. See [[Manual:Zone_Manual/The_DIL_Section|The DIL Section]].
 +
|-
 +
| <code>%reset</code> || The commands that load NPCs and objects and set doors, run when the zone resets. See [[Manual:Zone_Manual/The_Reset_Section|The Reset Section]].
 +
|-
 +
| <code>%end</code> || The end of the zone. Only comments may follow it.
 +
|}
  
−
Each section is preceded by a section header. These are the  six
+
The rules:
−
possible headers:
+
* <code>%zone</code> comes first and <code>%end</code> last. Both are required.
−
* %zone
+
* The other sections are optional and may come in any order. Most zones use the order <code>%zone</code>, <code>%dil</code>, <code>%rooms</code>, <code>%objects</code>, <code>%mobiles</code>, <code>%reset</code>.
−
* %rooms
+
* Use each section once. A second <code>%rooms</code> section makes vmc drop, without a word, every room, object and NPC written between the first <code>%rooms</code> and the second.
−
* %mobiles
+
* A <code>%reset</code> section must have at least one command; an empty one is a syntax error. Leave it out if you have nothing to reset.
−
* %objects
+
* Section headers and field names are lowercase, and case matters: <code>%DIL</code> or <code>Title</code> is an error.
−
* %reset
+
* One file is one zone, and the zone's name is the file's name: <code>dragon.zon</code> holds <code>%zone dragon</code>.
−
* %DIL
 
−
The  first four sections may be considered lists of definitions.
 
−
The reset section can be considered a program in a simple  programming
 
−
language. And the DIL section is a bit special - it
 
−
includes the zone templates (DIL functions that can be used from any
 
−
zone, on anything, as opposed to "specialized" DIL functions placed
 
−
inside a unit's
 
−
definitions).  After all sections you are using are defined you
 
−
must tell the compiler you are done the special symbol '%end'
 
−
must be placed at the end of the zone for this reason.
 
−
=== Definition types ===
 
  
−
When creating your zone there are six main building blocks.
+
The rooms, objects and NPCs sections are lists of units. The reset section is a short program in a simple language, and the DIL section holds programs in DIL.
−
We call these definition types.  Each type represents some kind of
 
−
data you want the compiler to be able to recognize. These data
 
−
definitions take the basic form:
 
−
<nowiki>
 
−
field value</nowiki>
 
−
Where field is the name of a data field, and value is some value.
 
−
Values are of one of 6 types:
 
  
−
;integer
+
A skeleton that compiles:
−
: A whole number or if you are in practice of using Hex you can use the C style hex numbers in either upper or lower case (i.e 0X0f3 0x0f3)
+
<pre>
−
;string
+
#include <macros.h>
−
: Text enclosed in Double Quotes.  The string can span more than one line as it would in a description.
 
−
<nowiki>
 
−
title "The dark dragon altar"
 
−
descr
 
−
"There are many things you can see and there are many things that
 
−
can't be seen but this is still a description none the less."</nowiki>
 
−
;stringlist
 
−
: A set of strings, it can be a single string or multiple depending on your needs.
 
−
These are used in names, extras, creators, and special keywords all to be
 
−
defined later in their respective places.  These are defined in the following
 
−
manor.
 
−
<nowiki>
 
−
&lt;fieldname&gt;    {"string1","string2","string3", ...}</nowiki>
 
−
;intlist
 
−
: A list of numbers which can be used with an extra.  This type works like the stringlist but doesn't need the quotes.
 
−
<nowiki>
 
−
extra {"mynumberlist"} {1,2,3,4,5,6,7,...}
 
−
"This is a number list attached to an extra"</nowiki>
 
−
;flags
 
−
: Like the Intlist the flag is defined with a list of numbers.  The list of numbers is not taken literally however it is combined to create one number by binary ORing the number list together.  If that confuses you don't worry, it takes some getting used to.  These types are used for Manipulation, flags, and positions.
 
−
<nowiki>
 
−
flags {2,8}
 
−
manipulate {8}</nowiki>
 
−
In the previous example the 'flags' value after this zone compiles
 
−
would be 10 because binary oring the two flags together is a lot
 
−
like adding.  The two numbers probably make no sense so most flags
 
−
you use will have defines if I used the defines found in
 
−
''vme.h'' the previous example would look like this:
 
−
<nowiki>
 
−
flags {UNIT_FL_INVISIBILE,UNIT_FL_BURIED}
 
−
manipulate {WEAR_BODY}</nowiki>
 
−
We will cover this more in-depth later but it was necessary to give
 
−
a good overview so you understand this field type enough to recognize
 
−
what it is when you see it.
 
−
;symbol
 
−
: A label you reference from other parts in your zones.  Every unit (room,object,room) and even the zone itself has a unique label that can be referenced.  It is important to make symbol names that are clear so the Administrators of the mud know what each item is when using the online administration commands.
 
−
<nowiki>
 
−
dark_sword /*good symbol*/
 
−
rm_5892 /*Bad symbol*/</nowiki>
 
−
When loading items online the zone symbol and the item symbol are
 
−
combined to create a reference to the item.  For example if our zone
 
−
name was 'dragon' and our item was 'dark_sword' the symbolic name for
 
−
this item would be 'dark_sword@dragon'.  Using symbols will be
 
−
covered more in the DIL manual and in the administration manuals for
 
−
loading objects online.  For now it is enough to understand
 
−
symbols must follow the following rules when being defined.
 
−
* The first letter of the
 
−
symbol must be a letter of the alphabet or a '_' character
 
−
* Characters following the first can be numbers, alphabet
 
−
letters, and '_' characters
 
−
* The name can be no longer than
 
−
15 characters
 
−
* No reserved keywords can be used as a name
 
−
(Link to app-b)
 
−
<blockquote style="background-color: #E8E8E8; font-style: italic; ">the end tag that ends all unit definitions is also considered a symbol it is just a symbol that must be included</blockquote>
 
  
−
There are two other field types that can not be defined as a
+
%zone dragon
−
regular field type.  These are the function reference and the
+
lifespan 20
−
Structure.  The function reference can be either a reference to a
+
reset RESET_ANYHOW
−
DIL function or a special function called from the
+
creators {"whistler"}
−
base code.
 
  
−
<blockquote style="background-color: #E8E8E8; font-style: italic; ">Special functions are being replaced with DIL for better performance and should only be used when no DIL functions exist to replace them</blockquote>
+
%rooms
  
−
The Structure field types are a combination of other field types
+
%objects
−
to make a special field type for the unit being defined. A good example
+
 
−
of this is a 'exit' for a room. The exit has everything from flag,
+
%mobiles
−
string, stringlist, and even description fields. The exit field will be
+
 
−
defined much more in-depth in the chapter on rooms but it is important
+
%end
−
to know some fields are considered Structure fields because they can have
+
</pre>
−
many values. The only two Structure fields are the exit and extra
+
 
−
fields which will both be defined more later because they can be used
+
=== Fields and values ===
−
differently depending on what you are using them for.
+
Everything in a section is a field followed by its value:
 +
<pre>
 +
field value
 +
</pre>
 +
<code>field</code> is a keyword such as <code>title</code> or <code>weight</code>, and the value is one of the types below. Fields are separated only by spaces and line breaks; there are no commas or semicolons between them.
 +
 
 +
;Number
 +
: A whole number: <code>20</code>, <code>-500</code>, or in hexadecimal <code>0x0f3</code>. You can write a sum, which vmc works out: <code>+</code>, <code>-</code>, <code>*</code>, <code>/</code> and parentheses, with whole numbers (<code>weight 5 + 40 / 4</code> is 15). The headers define names for most numbers, such as <code>SECT_SWAMP</code> or <code>SEX_MALE</code>.
 +
 
 +
;String
 +
: Text between double quotes. It may run over several lines, and the line breaks are kept as you wrote them:
 +
<pre>
 +
title "The dark dragon altar"
 +
descr
 +
"A black stone altar fills the middle of the room. Its top is
 +
scorched and still warm."
 +
</pre>
 +
: A string can't contain a double quote, not even as <code>\"</code>; use a single quote instead. A string that you forget to close runs on to the next <code>"</code> in the file, and the error is reported far below. Strings may contain [[Manual:Zone_Manual/Color_and_Formatting_Codes|colour and formatting codes]].
 +
 
 +
;String list
 +
: Strings in braces, separated by commas. A single string without braces is a list of one, and <code>{}</code> or <code>null</code> is an empty list. Used for <code>names</code>, <code>creators</code>, the names of an <code>extra</code> and the keywords of a door:
 +
<pre>
 +
names {"black dragon", "dragon"}
 +
creators {"whistler", "papi"}
 +
</pre>
 +
 
 +
;Number list
 +
: Numbers in braces, separated by commas, or a single number. An <code>extra</code> can carry one for DIL programs to read:
 +
<pre>
 +
extra {"$visits"} {1, 2, 3}
 +
"A hidden extra that holds three numbers."
 +
</pre>
 +
 
 +
;Flags
 +
: A number, or several numbers in braces. The numbers in braces are combined into one (a binary OR): each flag is one bit, so <code>{2, 8}</code> is 10. Always use the names from the headers:
 +
<pre>
 +
flags {UNIT_FL_NO_WEATHER, UNIT_FL_INDOORS}
 +
manipulate {MANIPULATE_TAKE, MANIPULATE_WEAR_BODY}
 +
</pre>
 +
: Make sure the flags fit the field: <code>flags</code> takes only <code>UNIT_FL_</code> flags. vmc sees only the numbers, so a flag meant for another field compiles and sets something else.
 +
 
 +
;Symbol
 +
: The name of a unit (a room, object or NPC) or of the zone. Every unit has one, written on the line that starts the unit, and other parts of the zone use it to refer to that unit. The rules:
 +
:* It starts with a letter or <code>_</code>, followed by letters, digits and <code>_</code>.
 +
:* At most 15 characters for a unit and 30 for a zone. A longer name is cut short, with only a warning.
 +
:* No two units of a zone may have the same symbol, whatever their kind. The game doesn't tell capitals from small letters, so use lowercase.
 +
:* A keyword can't be a symbol (<code>door</code>, <code>key</code>, <code>level</code>, <code>names</code>...), and neither can a word that a header defines as a macro (<code>north</code>, <code>up</code>, <code>pause</code>...). The keywords are listed in [[Manual:Zone_Manual/Appendices/Reserved_keyword_listing|Reserved keyword listing]].
 +
: Choose symbols that say what the unit is: <code>dark_sword</code>, not <code>rm_5892</code>. Gods see them in commands such as <code>wstat</code> and <code>load</code>.
 +
: In its own zone a unit is referred to by its symbol alone. From another zone, write <code>symbol@zone</code> (or <code>zone/symbol</code>): the sword above, in the zone <code>dragon</code>, is <code>dark_sword@dragon</code>. That is also how gods load it in the game: <code>load dark_sword@dragon</code>.
 +
 
 +
=== Fields with several parts ===
 +
A few fields take more than one value:
 +
* '''Exits''' of a room: a direction, then the exit's own fields, ended by a semicolon: <code>north to altar descr "You see an altar.";</code>. See [[Manual:Zone_Manual/The_Room_Section|The Room Section]].
 +
* '''Extras''': <code>extra</code>, a string list, an optional number list, and a string. See [[Manual:Zone_Manual/Unit_Building_Blocks|Unit Building Blocks]].
 +
* '''DIL programs''': <code>dilcopy name@zone(arguments);</code>, or a whole program between <code>dilbegin</code> and <code>dilend</code>. See [[Manual:Zone_Manual/The_DIL_Section|The DIL Section]].
 +
* '''Affects''' on objects, such as a bonus to strength. You set them with the macros in <code>wmacros.h</code>; see [[Manual:Zone_Manual/The_Objects_Section/Object_macros|Object macros]].
  
 
<div style='padding-top: 30px; padding-bottom: 20px; text-align: left;float:left;width:50%;'>[[Manual:Zone_Manual/General_Compiler_Information/The_VMC_pre-processor|Previous: The VMC pre-processor]]</div>
 
<div style='padding-top: 30px; padding-bottom: 20px; text-align: left;float:left;width:50%;'>[[Manual:Zone_Manual/General_Compiler_Information/The_VMC_pre-processor|Previous: The VMC pre-processor]]</div>
 
<div style='padding-top: 30px; padding-bottom: 20px; text-align: right;float:right;width:50%;'>[[Manual:Zone_Manual/Zone_Source_File/Zone_information_section|Next: Zone information section]]</div>
 
<div style='padding-top: 30px; padding-bottom: 20px; text-align: right;float:right;width:50%;'>[[Manual:Zone_Manual/Zone_Source_File/Zone_information_section|Next: Zone information section]]</div>

Latest revision as of 06:19, 15 November 2026

Zone source file

This chapter shows the parts of a zone file and the kinds of values its fields take. The next page covers the zone's header. After both you can write an empty zone that compiles.

Sections

A zone file is made of sections. Each starts with a header on a line of its own:

Header What it holds
%zone The zone's name and its global settings: title, reset interval and mode, creators. See Zone information section.
%rooms The rooms. See The Room Section.
%objects The objects. See The Objects Section.
%mobiles The NPCs. See The NPC Section.
%dil DIL templates: programs that any room, object or NPC, in any zone, can use. See The DIL Section.
%reset The commands that load NPCs and objects and set doors, run when the zone resets. See The Reset Section.
%end The end of the zone. Only comments may follow it.

The rules:

  • %zone comes first and %end last. Both are required.
  • The other sections are optional and may come in any order. Most zones use the order %zone, %dil, %rooms, %objects, %mobiles, %reset.
  • Use each section once. A second %rooms section makes vmc drop, without a word, every room, object and NPC written between the first %rooms and the second.
  • A %reset section must have at least one command; an empty one is a syntax error. Leave it out if you have nothing to reset.
  • Section headers and field names are lowercase, and case matters: %DIL or Title is an error.
  • One file is one zone, and the zone's name is the file's name: dragon.zon holds %zone dragon.

The rooms, objects and NPCs sections are lists of units. The reset section is a short program in a simple language, and the DIL section holds programs in DIL.

A skeleton that compiles:

#include <macros.h>

%zone dragon
lifespan 20
reset RESET_ANYHOW
creators {"whistler"}

%rooms

%objects

%mobiles

%end

Fields and values

Everything in a section is a field followed by its value:

field value

field is a keyword such as title or weight, and the value is one of the types below. Fields are separated only by spaces and line breaks; there are no commas or semicolons between them.

Number
A whole number: 20, -500, or in hexadecimal 0x0f3. You can write a sum, which vmc works out: +, -, *, / and parentheses, with whole numbers (weight 5 + 40 / 4 is 15). The headers define names for most numbers, such as SECT_SWAMP or SEX_MALE.
String
Text between double quotes. It may run over several lines, and the line breaks are kept as you wrote them:
title "The dark dragon altar"
descr
"A black stone altar fills the middle of the room. Its top is
scorched and still warm."
A string can't contain a double quote, not even as \"; use a single quote instead. A string that you forget to close runs on to the next " in the file, and the error is reported far below. Strings may contain colour and formatting codes.
String list
Strings in braces, separated by commas. A single string without braces is a list of one, and {} or null is an empty list. Used for names, creators, the names of an extra and the keywords of a door:
names {"black dragon", "dragon"}
creators {"whistler", "papi"}
Number list
Numbers in braces, separated by commas, or a single number. An extra can carry one for DIL programs to read:
extra {"$visits"} {1, 2, 3}
"A hidden extra that holds three numbers."
Flags
A number, or several numbers in braces. The numbers in braces are combined into one (a binary OR): each flag is one bit, so {2, 8} is 10. Always use the names from the headers:
flags {UNIT_FL_NO_WEATHER, UNIT_FL_INDOORS}
manipulate {MANIPULATE_TAKE, MANIPULATE_WEAR_BODY}
Make sure the flags fit the field: flags takes only UNIT_FL_ flags. vmc sees only the numbers, so a flag meant for another field compiles and sets something else.
Symbol
The name of a unit (a room, object or NPC) or of the zone. Every unit has one, written on the line that starts the unit, and other parts of the zone use it to refer to that unit. The rules:
  • It starts with a letter or _, followed by letters, digits and _.
  • At most 15 characters for a unit and 30 for a zone. A longer name is cut short, with only a warning.
  • No two units of a zone may have the same symbol, whatever their kind. The game doesn't tell capitals from small letters, so use lowercase.
  • A keyword can't be a symbol (door, key, level, names...), and neither can a word that a header defines as a macro (north, up, pause...). The keywords are listed in Reserved keyword listing.
Choose symbols that say what the unit is: dark_sword, not rm_5892. Gods see them in commands such as wstat and load.
In its own zone a unit is referred to by its symbol alone. From another zone, write symbol@zone (or zone/symbol): the sword above, in the zone dragon, is dark_sword@dragon. That is also how gods load it in the game: load dark_sword@dragon.

Fields with several parts

A few fields take more than one value:

  • Exits of a room: a direction, then the exit's own fields, ended by a semicolon: north to altar descr "You see an altar.";. See The Room Section.
  • Extras: extra, a string list, an optional number list, and a string. See Unit Building Blocks.
  • DIL programs: dilcopy name@zone(arguments);, or a whole program between dilbegin and dilend. See The DIL Section.
  • Affects on objects, such as a bonus to strength. You set them with the macros in wmacros.h; see Object macros.
Previous: The VMC pre-processor
Next: Zone information section