Difference between revisions of "Manual:Zone Manual/Unit Building Blocks"

From DikuMUD Wiki
Jump to navigation Jump to search
(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.
  
−
When creating your zone you will find some basic
+
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:
−
structures are used in all three unit types rooms, objects, and
+
<pre>
−
NPCs. In this chapter we will define the main building blocks of
+
symbol_name
−
all units along with some helpful hints
+
end
 +
</pre>
 +
This is a legal unit, though an empty one. Every field can be left out; what you leave out gets a default.
  
−
No matter which unit type you are dealing with there is a
+
=== The symbol ===
−
simple basic structure that lets the compiler know not only what
+
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]]:
−
unit type it is dealing with but where one unit begins and where it
+
* It starts with a letter or <code>_</code>, followed by letters, digits and <code>_</code>.
−
ends. The way the compiler tells what unit type it is dealing with
+
* At most 15 characters. A longer symbol is cut short, with only a warning.
−
is by the section header '%rooms', '%objects', and '%mobiles'. All
+
* No two units of the zone may have the same symbol, also not a room and an object.
−
rooms must be defined under the '%rooms' header and likewise objects
+
* 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]].
−
and NPCS under their respective headers. Each unit starts with a
+
* Use lowercase. The game doesn't tell capitals from small letters, so <code>Sword</code> and <code>sword</code> are the same symbol.
−
symbolic name called the unit symbol and ends with the keyword
 
−
end.  The following would be a legal definition of any
 
−
unit type:
 
−
<nowiki>
 
−
symbol_name
 
−
end</nowiki>
 
−
If you define a unit like this when it loads it will be blank, while
 
−
this is not extremely useful it is good to know you can leave
 
−
out any field you don't feel you need.
 
−
==== Unit building blocks ====
 
−
;symbol field
 
−
: In the last chapter we defined the different field types and the rules you must follow when defining a symbol. It is important enough to relist these rules here so you do not run into problems when creating your units.
 
−
* 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 symbol can be no longer than
 
−
15 characters
 
−
* No reserved keywords can be used as a symbol(Link to app-b)
 
−
<blockquote style="background-color: #E8E8E8; font-style: italic; ">It is also important to know currently it is hard to deal with units having capital letters in them, this may be fixed in the future but it is good practice to use all lower case characters in the symbols.</blockquote>
 
  
−
Another thing you should think about when defining your symbol
+
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
−
names is to be clear about what the unit is. When you list units on
+
<pre>
−
the VME server with '''wstat''' the symbolic names are
+
i6853 b2419 l1854
−
shown
+
</pre>
−
if you were to see the list:
+
tells nobody anything, while
−
<nowiki>
+
<pre>
−
i6853 b2419 l1854</nowiki>
+
long_sword healer_hut dog
−
You would have no idea what those three items were unless you
+
</pre>
−
personally built them recently, therefore it is a much better coding
+
does.
−
practice to name things what they are like:
 
−
<nowiki>
 
−
long_sword healer_hut dog</nowiki>
 
−
;title field
 
−
: The title field is probably the easiest field on all units it is what is shown on the first line of a room when you enter and it is the name shown when you get an object or attack a NPC.
 
−
There is only two important things to look at when defining titles
 
−
one is punctuation and the other is capitalization.  Room titles
 
−
need to be capitalized and so do proper names but the first letter of an object
 
−
title or a NPC title do not normally need to be capitalized. this is
 
−
best explained by some examples.
 
−
<nowiki>
 
−
title "The dragons in."/*good*/
 
−
title "a big bull dog."/*bad has a period at the end*/
 
−
title "Bill the destroyer"/*good*/
 
−
title "A long dagger"/*bad capital 'a'*/</nowiki>
 
−
Now to show why some of those are good we will demonstrate by some
 
−
sample output in the game.
 
−
<nowiki>
 
−
prompt:  l
 
−
The Dragons Inn
 
−
You are standing in a moldy inn.
 
  
−
prompt: get A long dagger
+
=== title ===
−
You get A long dagger.
+
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."
  
−
prompt kick dog
+
So the title of an object or NPC is written as part of a sentence:
−
You kick a bull dog. in the head.</nowiki>
+
* It starts with a small letter, unless it starts with a proper name: <code>"a long dagger"</code>, <code>"Bill the destroyer"</code>.
−
Notice the 'A' and the extra period do not really look right where
+
* It doesn't end with a full stop.
−
they end up appearing in the game. These may be minor nit picky
 
−
details but if you do it right the first time you won't have to deal
 
−
with the english major that just happens to be playing on your
 
−
mud.
 
−
;names field
 
−
: The 'names' field defines the names everything in the game can use to interact with your unit.  For rooms the names are used as teleport or goto points for characters and NPCs or they are sometimes used for special DIL functions on objects to trigger in certain rooms.  On NPCs and objects names can be used for anything from poking a player to giving a player an object.  The names field is very flexible it has even been used to store what a container is holding in order to have quick access to the names in the container.
 
  
−
When making rooms it is not necessary to put room names.  In
+
Room titles are headings, so they start with a capital: <code>"The Dragon's Inn"</code>. These are the right forms:
−
fact it is a good way of making sure players can't teleport to
+
<pre>
−
certain rooms because if the room doesn't have a name the person
+
title "The Dragon's Inn"      /* a room */
−
can't teleport to it. Objects and NPCs must have names because if
+
title "a big bull dog"       /* an NPC */
−
you leave names off of them you can not pick them up or kill them
+
title "Bill the destroyer"   /* an NPC with a name */
−
depending on which you are dealing with.  It is also good practice
+
title "a long dagger"         /* an object */
−
to use all combinations of the object or NPCs title so a
+
</pre>
−
player will know exactly what to type to use the item for example:
+
and these give a warning for an object or NPC:
−
<nowiki>
+
<pre>
−
bad_obj
+
title "A long dagger"        /* capital A */
−
title a small dog"
+
title "a big bull dog."       /* full stop */
−
names{"small dog","small","dog"}
+
</pre>
−
end</nowiki>
+
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:
−
It is up to you as a builder if you want to use names like 'small'
+
<pre>
−
in your names list since you would not 'get small' in real life it
+
WARNING: dagger: Title CASE seems to be wrong for 'A long dagger'
−
may not have to be added to the names list.  It is important however
+
WARNING: dog: Title ends with non-alphabet character 'a big bull dog.'
−
to define your extras from big to small because of how the VME
+
</pre>
−
command interpreter handles names of things.  For example if you had
 
−
the following names:
 
−
<nowiki>
 
−
small_item
 
−
title "a small item"
 
−
names {"small","item","small item"}</nowiki>
 
−
When you try to '''give small item Bill'''.  The interpreter
 
−
would try to give
 
−
small to item and that would not be what you wanted to do. Don't
 
−
worry the compiler will catch this and give you an error something
 
−
like:
 
−
<nowiki>
 
−
Fatal name ordering on line ###.</nowiki>
 
−
;descr field
 
−
: The description building block is used in many places.  You will find description fields on extras, exits, rooms, NPCs, objects, and as you have already seen the help and the notes field of the zone information section are also description fields.
 
  
−
  Depending on what
+
=== names ===
−
you are working on description fields can mean totally different
+
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:
−
things to the person looking in the room. A description field on a
+
<pre>
−
room can be the inside or outside of the rooms description.  A
+
small_dog
−
description on extras can be an NPCs descr or an extra description
+
names {"small dog", "dog"}
−
on the room like if you looked at a 'rug' or a 'chair'.  On an exit
+
title "a small dog"
−
the descr field describes what you see when you look in that
+
end
−
direction from the room you are in.  The important thing right now
+
</pre>
−
is no matter where you use them they all work the same.
+
Whether you also add <code>"small"</code> is up to you: nobody would say "get small" in real life.
  
−
description fields like the title field have a tag or unlike
+
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 title field can have a set of tags before them like in extras or
 
−
exits but like titles they are just a string surrounded by quotes.
 
−
You can make multiple line descriptions if the description is on a
 
−
NPC you may not want to since it is the description shown when you
 
−
walk into the room.  The following would be some examples of room descriptions.
 
−
<nowiki>
 
−
descr
 
−
"this is how you would define a room descr and as you can see it can
 
−
be much longer than a line if you like."
 
  
−
extra {"basic extra"}
+
'''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:
−
"This is a description field on an extra."
+
<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.
  
−
extra{"more advanced","extra"}{1,2,3,4,5,6}
+
=== descr ===
−
"This is still the description field.  Like the room description or
+
A description is a string, often several lines long. What <code>descr</code> means depends on the unit:
−
any description field for that matter this can be longer than a
+
* 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.
−
line."
+
* 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
+
east to bathroom descr
−
"You see one big toilet!";</nowiki>
+
"You see one big toilet!";
−
;extra fields
+
</pre>
−
: The extra field is the work horse for the builder.  It is the building block that most brings your zone to life.  You can use it to describe body parts or items in a room.  When you use DIL you will use extras to store information like quest information or special information you need later. Extras also store the main description on NPCs since the descr field on NPCs is really the long title shown in the room which will be explained later in (Link to ch-05).
+
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.
  
−
The extra Is the first structure definition you have run into
+
What players see when they '''look at''' an object or NPC is not its <code>descr</code> but an extra, below.
−
so it may take some playing with to figure it out.  The extra has
 
−
actually 4 fields three of them must be there in some form.  The
 
−
first is the identifier that tells the compiler that this is an
 
−
extra, the second is a stringlist, the third is an Optional
 
−
Intlist, and the final one is the extra description field.  If the extra
 
−
had all the fields it would look like this:
 
−
<nowiki>
 
−
extra {"small chair","chair"} {1,2,3,4,5} "Its a chair."</nowiki>
 
−
If the previous wasn't an example we
 
−
would have left out the Intlist because it is not necessary to put
 
−
the Intlist on a chair unless you want it there for some special DIL
 
−
you are creating. the Intlist is the only field that can be totally
 
−
left out but you can leave the string list blank when you want
 
−
to make the extra the default description when the object, room, or
 
−
NPC is being looked at, like this:
 
−
<nowiki>
 
−
extra {}
 
−
"This would be what you see when you look at any of the names in the
 
−
names list."</nowiki>
 
−
We will go more in-depth into why you want to do this in the
 
−
following chapters.
 
  
−
You are now ready to put these building blocks to work. You have only
+
=== extra ===
−
to learn how to put these fields to work for each of the three unit
+
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.
−
types and you will be off and running.
+
 
 +
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

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 Sword and sword are 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.

Previous: Zone information section
Next: The Room Section