Difference between revisions of "Manual:Zone Manual/Unit Building Blocks"
(checked against the current code (wiki review 2026-11-15)) |
|||
| Line 1: | Line 1: | ||
== Unit building blocks == | == Unit building blocks == | ||
| + | Rooms, objects and NPCs are all '''units''', and they share some basic fields. This chapter explains those: the symbol and <code>end</code>, the names, the title, the descriptions and the extras. The chapters on rooms, objects and NPCs build on them. | ||
| − | + | Rooms go in the <code>%rooms</code> section, objects in <code>%objects</code> and NPCs in <code>%mobiles</code>. Each unit starts with its symbol on a line of its own and ends with the keyword <code>end</code>. Its fields come in between, in any order: | |
| − | + | <pre> | |
| − | + | symbol_name | |
| − | + | end | |
| + | </pre> | ||
| + | This is a legal unit, though an empty one. Every field can be left out; what you leave out gets a default. | ||
| − | + | === The symbol === | |
| − | + | The symbol is the unit's name for the compiler and for gods. The rules, from [[Manual:Zone_Manual/Zone_Source_File|Zone Source File]]: | |
| − | + | * It starts with a letter or <code>_</code>, followed by letters, digits and <code>_</code>. | |
| − | + | * At most 15 characters. A longer symbol is cut short, with only a warning. | |
| − | + | * No two units of the zone may have the same symbol, also not a room and an object. | |
| − | + | * A keyword or a lowercase macro (<code>north</code>, <code>up</code>...) can't be a symbol. See [[Manual:Zone_Manual/Appendices/Reserved_keyword_listing|Reserved keyword listing]]. | |
| − | + | * Use lowercase. The game doesn't tell capitals from small letters, so <code>Sword</code> and <code>sword</code> are the same symbol. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | * The | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | < | ||
| − | + | Make the symbol say what the unit is. Gods see the symbols in <code>wstat</code> and use them with <code>load</code> and <code>goto</code>. A list such as | |
| − | + | <pre> | |
| − | + | i6853 b2419 l1854 | |
| − | + | </pre> | |
| − | + | tells nobody anything, while | |
| − | + | <pre> | |
| − | + | long_sword healer_hut dog | |
| − | + | </pre> | |
| − | + | does. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | === title === | |
| − | + | The title is the unit's short name. For a room it is the first line players see when they enter; for an object or NPC it is the name the game uses in sentences: "You get ''a long dagger''.", "You kick ''a big bull dog'' in the head." | |
| − | + | So the title of an object or NPC is written as part of a sentence: | |
| − | + | * It starts with a small letter, unless it starts with a proper name: <code>"a long dagger"</code>, <code>"Bill the destroyer"</code>. | |
| − | + | * It doesn't end with a full stop. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | Room titles are headings, so they start with a capital: <code>"The Dragon's Inn"</code>. These are the right forms: | |
| − | + | <pre> | |
| − | + | title "The Dragon's Inn" /* a room */ | |
| − | + | title "a big bull dog" /* an NPC */ | |
| − | + | title "Bill the destroyer" /* an NPC with a name */ | |
| − | + | title "a long dagger" /* an object */ | |
| − | + | </pre> | |
| − | + | and these give a warning for an object or NPC: | |
| − | + | <pre> | |
| − | + | title "A long dagger" /* capital A */ | |
| − | + | title "a big bull dog." /* full stop */ | |
| − | + | </pre> | |
| − | + | In the game they would read "You get A long dagger." and "You kick a big bull dog. in the head." vmc warns about both: | |
| − | + | <pre> | |
| − | + | WARNING: dagger: Title CASE seems to be wrong for 'A long dagger' | |
| − | + | WARNING: dog: Title ends with non-alphabet character 'a big bull dog.' | |
| − | + | </pre> | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | === names === | |
| − | + | The names are the words players use for the unit: <code>get sword</code>, <code>kill dog</code>, <code>look at statue</code>. Objects and NPCs need names, or players can't get, give, look at or kill them. Give every word a player is likely to type, from the whole title down to the single noun: | |
| − | + | <pre> | |
| − | + | small_dog | |
| − | + | names {"small dog", "dog"} | |
| − | + | title "a small dog" | |
| − | + | end | |
| − | + | </pre> | |
| − | + | Whether you also add <code>"small"</code> is up to you: nobody would say "get small" in real life. | |
| − | + | Rooms usually have no names. Give a room names when something must find it by name: the <code>enter</code> command matches them for a room inside another room, and <code>goto</code> accepts a room's name as well as its symbol. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | '''The order matters.''' The game takes the first name that the player's words start with, and the rest of the words are what comes next in the command. With <code>{"small", "item", "small item"}</code>, <code>give small item bill</code> would find "small", and then try to give it to "item". So no name may begin with the words of a name before it in the list: put the longer names first. vmc stops with an error when the order is wrong: | |
| − | + | <pre> | |
| + | FATAL: Name order error (or matching names) for 'small item' in small_item@ | ||
| + | </pre> | ||
| + | The same rule holds for the names of extras and the keywords of doors. vmc also refuses a name that ends in <code>'s</code>, a name that is <code>self</code> or starts with <code>self </code>, and names longer than 60 characters. | ||
| − | + | === descr === | |
| − | + | A description is a string, often several lines long. What <code>descr</code> means depends on the unit: | |
| − | + | * On a '''room''' it is what players see when they look around in it. vmc puts three spaces in front of it, so don't indent it yourself. | |
| − | + | * On an '''object''' it is the line shown when the object lies in a room: "A long dagger lies here." | |
| + | * On an '''NPC''' it is the line shown when the NPC stands in a room: "A big bull dog is here, drooling." | ||
| + | * On an '''exit''' it is what players see when they look in that direction. | ||
| + | <pre> | ||
| + | descr | ||
| + | "You are standing in a mouldy inn. A worn rug covers the floor in | ||
| + | front of the bar." | ||
| − | + | east to bathroom descr | |
| − | + | "You see one big toilet!"; | |
| − | + | </pre> | |
| − | + | The line breaks in a description are shown as you write them; the game only wraps a line that is too long. Break the lines yourself, at under about 72 characters, as the zones that come with the server do. | |
| − | + | What players see when they '''look at''' an object or NPC is not its <code>descr</code> but an extra, below. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | You are now | + | === extra === |
| − | + | Extras are the builder's workhorse. They describe the things in a room that players can look at, the parts of an NPC, the inscription on a sword. DIL programs also use them to store information on a unit. | |
| − | + | ||
| + | An extra has the keyword <code>extra</code>, a string list of names, an optional number list, and a description: | ||
| + | <pre> | ||
| + | extra {"small chair", "chair"} {1, 2, 3, 4, 5} "It's a chair." | ||
| + | </pre> | ||
| + | The number list is for DIL programs; leave it out unless a program needs it: | ||
| + | <pre> | ||
| + | extra {"worn rug", "rug"} | ||
| + | "The rug is threadbare and stained with ale." | ||
| + | </pre> | ||
| + | When a player types <code>look at rug</code>, the game shows the description of the extra with that name. The names follow the same rule as <code>names</code>: longer names first. | ||
| + | |||
| + | An extra with an empty list of names, <code>extra {}</code>, is the unit's own description: what players see when they look at the object or NPC itself. | ||
| + | <pre> | ||
| + | extra {} | ||
| + | "It looks friendly enough, as long as you leave its bone alone." | ||
| + | </pre> | ||
| + | |||
| + | An extra whose first name starts with <code>$</code>, such as <code>extra {"$visits"}</code>, is for DIL programs. Players can't look at it, and the name order rule doesn't apply to it. | ||
| + | |||
| + | === An example === | ||
| + | A room, an object and an NPC with these fields. This compiles as <code>inn.zon</code>: | ||
| + | <pre> | ||
| + | #include <macros.h> | ||
| + | |||
| + | %zone inn | ||
| + | lifespan 20 | ||
| + | reset RESET_NOT | ||
| + | creators {"manual"} | ||
| + | |||
| + | %rooms | ||
| + | |||
| + | inn | ||
| + | title "The Dragon's Inn" | ||
| + | descr | ||
| + | "You are standing in a mouldy inn. A worn rug covers the floor in | ||
| + | front of the bar." | ||
| + | extra {"worn rug", "rug"} | ||
| + | "The rug is threadbare and stained with ale." | ||
| + | east to bathroom descr | ||
| + | "You see one big toilet!"; | ||
| + | end | ||
| + | |||
| + | bathroom | ||
| + | title "A small bathroom" | ||
| + | descr | ||
| + | "There is barely room to turn around in here." | ||
| + | west to inn descr | ||
| + | "You see the inn."; | ||
| + | end | ||
| + | |||
| + | %objects | ||
| + | |||
| + | small_chair | ||
| + | names {"small chair", "chair"} | ||
| + | title "a small chair" | ||
| + | descr "A small chair stands here." | ||
| + | extra {} | ||
| + | "It is a plain wooden chair." | ||
| + | end | ||
| + | |||
| + | %mobiles | ||
| + | |||
| + | bull_dog | ||
| + | names {"big bull dog", "bull dog", "dog"} | ||
| + | title "a big bull dog" | ||
| + | descr "A big bull dog is here, drooling." | ||
| + | extra {} | ||
| + | "It looks friendly enough, as long as you leave its bone alone." | ||
| + | M_DOG_TINY(12, SEX_MALE) | ||
| + | end | ||
| + | |||
| + | %end | ||
| + | </pre> | ||
| + | The <code>M_DOG_TINY</code> line sets the dog's race, level, abilities and the rest; [[Manual:Zone_Manual/The_NPC_Section/NPC_macros|NPC macros]] explains these templates. | ||
| + | |||
| + | You can now put these building blocks to work. The next chapters show the fields that belong to each kind of unit, starting with [[Manual:Zone_Manual/The_Room_Section|rooms]]. | ||
<div style='padding-top: 30px; padding-bottom: 20px; text-align: left;float:left;width:50%;'>[[Manual:Zone_Manual/Zone_Source_File/Zone_information_section|Previous: Zone information section]]</div> | <div style='padding-top: 30px; padding-bottom: 20px; text-align: left;float:left;width:50%;'>[[Manual:Zone_Manual/Zone_Source_File/Zone_information_section|Previous: Zone information section]]</div> | ||
<div style='padding-top: 30px; padding-bottom: 20px; text-align: right;float:right;width:50%;'>[[Manual:Zone_Manual/The_Room_Section|Next: The Room Section]]</div> | <div style='padding-top: 30px; padding-bottom: 20px; text-align: right;float:right;width:50%;'>[[Manual:Zone_Manual/The_Room_Section|Next: The Room Section]]</div> | ||
Latest revision as of 06:19, 15 November 2026
Contents
Unit building blocks
Rooms, objects and NPCs are all units, and they share some basic fields. This chapter explains those: the symbol and end, the names, the title, the descriptions and the extras. The chapters on rooms, objects and NPCs build on them.
Rooms go in the %rooms section, objects in %objects and NPCs in %mobiles. Each unit starts with its symbol on a line of its own and ends with the keyword end. Its fields come in between, in any order:
symbol_name end
This is a legal unit, though an empty one. Every field can be left out; what you leave out gets a default.
The symbol
The symbol is the unit's name for the compiler and for gods. The rules, from Zone Source File:
- It starts with a letter or
_, followed by letters, digits and_. - At most 15 characters. A longer symbol is cut short, with only a warning.
- No two units of the zone may have the same symbol, also not a room and an object.
- A keyword or a lowercase macro (
north,up...) can't be a symbol. See Reserved keyword listing. - Use lowercase. The game doesn't tell capitals from small letters, so
Swordandswordare the same symbol.
Make the symbol say what the unit is. Gods see the symbols in wstat and use them with load and goto. A list such as
i6853 b2419 l1854
tells nobody anything, while
long_sword healer_hut dog
does.
title
The title is the unit's short name. For a room it is the first line players see when they enter; for an object or NPC it is the name the game uses in sentences: "You get a long dagger.", "You kick a big bull dog in the head."
So the title of an object or NPC is written as part of a sentence:
- It starts with a small letter, unless it starts with a proper name:
"a long dagger","Bill the destroyer". - It doesn't end with a full stop.
Room titles are headings, so they start with a capital: "The Dragon's Inn". These are the right forms:
title "The Dragon's Inn" /* a room */ title "a big bull dog" /* an NPC */ title "Bill the destroyer" /* an NPC with a name */ title "a long dagger" /* an object */
and these give a warning for an object or NPC:
title "A long dagger" /* capital A */ title "a big bull dog." /* full stop */
In the game they would read "You get A long dagger." and "You kick a big bull dog. in the head." vmc warns about both:
WARNING: dagger: Title CASE seems to be wrong for 'A long dagger' WARNING: dog: Title ends with non-alphabet character 'a big bull dog.'
names
The names are the words players use for the unit: get sword, kill dog, look at statue. Objects and NPCs need names, or players can't get, give, look at or kill them. Give every word a player is likely to type, from the whole title down to the single noun:
small_dog
names {"small dog", "dog"}
title "a small dog"
end
Whether you also add "small" is up to you: nobody would say "get small" in real life.
Rooms usually have no names. Give a room names when something must find it by name: the enter command matches them for a room inside another room, and goto accepts a room's name as well as its symbol.
The order matters. The game takes the first name that the player's words start with, and the rest of the words are what comes next in the command. With {"small", "item", "small item"}, give small item bill would find "small", and then try to give it to "item". So no name may begin with the words of a name before it in the list: put the longer names first. vmc stops with an error when the order is wrong:
FATAL: Name order error (or matching names) for 'small item' in small_item@
The same rule holds for the names of extras and the keywords of doors. vmc also refuses a name that ends in 's, a name that is self or starts with self , and names longer than 60 characters.
descr
A description is a string, often several lines long. What descr means depends on the unit:
- On a room it is what players see when they look around in it. vmc puts three spaces in front of it, so don't indent it yourself.
- On an object it is the line shown when the object lies in a room: "A long dagger lies here."
- On an NPC it is the line shown when the NPC stands in a room: "A big bull dog is here, drooling."
- On an exit it is what players see when they look in that direction.
descr "You are standing in a mouldy inn. A worn rug covers the floor in front of the bar." east to bathroom descr "You see one big toilet!";
The line breaks in a description are shown as you write them; the game only wraps a line that is too long. Break the lines yourself, at under about 72 characters, as the zones that come with the server do.
What players see when they look at an object or NPC is not its descr but an extra, below.
extra
Extras are the builder's workhorse. They describe the things in a room that players can look at, the parts of an NPC, the inscription on a sword. DIL programs also use them to store information on a unit.
An extra has the keyword extra, a string list of names, an optional number list, and a description:
extra {"small chair", "chair"} {1, 2, 3, 4, 5} "It's a chair."
The number list is for DIL programs; leave it out unless a program needs it:
extra {"worn rug", "rug"}
"The rug is threadbare and stained with ale."
When a player types look at rug, the game shows the description of the extra with that name. The names follow the same rule as names: longer names first.
An extra with an empty list of names, extra {}, is the unit's own description: what players see when they look at the object or NPC itself.
extra {}
"It looks friendly enough, as long as you leave its bone alone."
An extra whose first name starts with $, such as extra {"$visits"}, is for DIL programs. Players can't look at it, and the name order rule doesn't apply to it.
An example
A room, an object and an NPC with these fields. This compiles as inn.zon:
#include <macros.h>
%zone inn
lifespan 20
reset RESET_NOT
creators {"manual"}
%rooms
inn
title "The Dragon's Inn"
descr
"You are standing in a mouldy inn. A worn rug covers the floor in
front of the bar."
extra {"worn rug", "rug"}
"The rug is threadbare and stained with ale."
east to bathroom descr
"You see one big toilet!";
end
bathroom
title "A small bathroom"
descr
"There is barely room to turn around in here."
west to inn descr
"You see the inn.";
end
%objects
small_chair
names {"small chair", "chair"}
title "a small chair"
descr "A small chair stands here."
extra {}
"It is a plain wooden chair."
end
%mobiles
bull_dog
names {"big bull dog", "bull dog", "dog"}
title "a big bull dog"
descr "A big bull dog is here, drooling."
extra {}
"It looks friendly enough, as long as you leave its bone alone."
M_DOG_TINY(12, SEX_MALE)
end
%end
The M_DOG_TINY line sets the dog's race, level, abilities and the rest; NPC macros explains these templates.
You can now put these building blocks to work. The next chapters show the fields that belong to each kind of unit, starting with rooms.