Difference between revisions of "Manual:Zone Manual/Zone Source File"
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. | ||
| − | + | === Sections === | |
| − | + | A zone file is made of sections. Each starts with a header on a line of its own: | |
| − | |||
| − | + | {| class="wikitable" | |
| − | + | ! Header !! What it holds | |
| − | + | |- | |
| − | + | | <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]]. | |
| − | + | |- | |
| + | | <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. | ||
| + | |} | ||
| − | + | The rules: | |
| − | + | * <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. |
| − | + | * 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. | |
| − | + | * Section headers and field names are lowercase, and case matters: <code>%DIL</code> or <code>Title</code> is an error. | |
| − | + | * One file is one zone, and the zone's name is the file's name: <code>dragon.zon</code> holds <code>%zone dragon</code>. | |
| − | * % | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | 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: | |
| − | + | <pre> | |
| − | + | #include <macros.h> | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | : | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | %zone dragon | |
| − | + | lifespan 20 | |
| − | + | reset RESET_ANYHOW | |
| − | + | creators {"whistler"} | |
| − | |||
| − | + | %rooms | |
| − | + | %objects | |
| − | + | ||
| − | + | %mobiles | |
| − | + | ||
| − | + | %end | |
| − | + | </pre> | |
| − | + | ||
| − | + | === Fields and values === | |
| − | + | 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:
%zonecomes first and%endlast. 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
%roomssection makes vmc drop, without a word, every room, object and NPC written between the first%roomsand the second. - A
%resetsection 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:
%DILorTitleis an error. - One file is one zone, and the zone's name is the file's name:
dragon.zonholds%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 hexadecimal0x0f3. You can write a sum, which vmc works out:+,-,*,/and parentheses, with whole numbers (weight 5 + 40 / 4is 15). The headers define names for most numbers, such asSECT_SWAMPorSEX_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
{}ornullis an empty list. Used fornames,creators, the names of anextraand 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
extracan 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:
flagstakes onlyUNIT_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.
- It starts with a letter or
- Choose symbols that say what the unit is:
dark_sword, notrm_5892. Gods see them in commands such aswstatandload. - In its own zone a unit is referred to by its symbol alone. From another zone, write
symbol@zone(orzone/symbol): the sword above, in the zonedragon, isdark_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 betweendilbeginanddilend. 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.