Igor the Ferret Building Docs, Unter-Style
------------------------------------------

This is an example of things new players might like to do, from the very
simple stuff on up into reasonably complex building examples.

Igor the Ferret (he loves spaces in his name, like you can do in unter),
has the object id of 123@Zoo. He is a new player. He sets his description 
by typing:
   set me desc=Igor is a ferret with an evil glint in his eye.

In Unter, you have to be careful about strings. Strings are denoted by
quotation marks, so Igor COULD have done
   set me desc "Igor is a ferret with an evil glint in his eye."
or even used single quotes. However, the equals sign ('=') is usually 
easier to deal with. It means "take the rest of this line as one string".
For most uses, it's the simplest way to do things. For macros, as we'll
see later, it's best to use quotation marks.

In Unter, there are no pennies, so there's no rob command, as in TinyMUD.
Players do not have success, fail, drop, or kill messages either.

Igor wants to set his gender, so he uses a macro most Unters have:
	male me

If he wanted to be weird, he could "female me", or even "many me" if he
wanted to be plural. He could even custom set his own messages, but we'll
get to that later.

Igor wants to set a message that he will use a lot, so he makes a macro on
himself, like this:
   set me cmd nip=@do runs around nipping at everyone's heels.

Now, if he wants to run that macro:
   Igor types:    nip
   Everyone sees: Igor the Ferret runs around nipping at everyone's heels.

Another thing Igor can do is to make his own custom say command. He does:
   set me cmd say=@do growls ferret-like, \"$+1\"

Notice that he escaped the quotes there, so they'll show up when he does
the macro. For example, if Igor types:
   say hello!
or "hello!
everyone will see: Igor the Ferret growls ferret-like, "hello!"

Igor wants to make an object called 'Ferret chow'. He types:
   build object "Ferret Chow"
   set "ferret chow" desc=This is a big bag full of yummy ferret chow. 
   set "ferret chow" succ=You tear into the end of the bag, stuffing yourself.
   set "ferret chow" osucc=tears into the Ferret Chow bag, eating greedily.

He could have saved himself a little bit of time by making full use of the
'build object' command, and added a desc right there, with:
   build object "Ferret Chow" =This is a big bag full of yummy ferret chow.
Note that only the 'build object' command can do this; each different 'build'
command can do slightly different things.

Now Igor decides that he wants to be the only one who can pick up the bag.
   set "ferret chow" lock me
(He didn't have do use '=me', because 'me' is only one word.)
   set "ferret chow" fail=It's icky Ferret Chow. It would probably taste gross.
   set "ferret chow" ofail=decides Ferret Chow is icky.
If Igor picks up the bag:
   Igor types:   get =Ferret Chow 
   Igor sees:    You tear into the end of the bag, stuffing yourself.
   all else see: Igor tears into the Ferret Chow bag, eating greedily.
Notice that he had to type "get =ferret chow". He stuck that = sign in there,
because otherwise the unter would think he was trying to get two different
things, "ferret" and "chow".

Igor is now carrying the bag. He must drop it if he wants to see the messages
again.  If Murf picks up the bag:
   Murf types:   get =Ferret Chow
   Murf sees:    It's icky Ferret Chow. It would probably taste gross.
   all else see: Murf decides Ferret Chow is icky.
Because the bag was locked to Igor, Murf cannot get the bag.

Also, Igor could set "drop" and "odrop" messages on the bag of ferret chow,
that will be displayed when anyone drops the bag.

Igor wants to build a few rooms. He can only build off of a place where he
can get a link. He needs to ask around to find one of these if he is just
starting to build. Murf is going to give Igor a link named 'n;north'. That
means that both 'n' and 'north' activate that exit. Igor digs a room, and
links the exit to it. He types:
   build room "Igor\'s House"
At this point, the program will respond "Dug room xxxx". We'll pretend it
gave the room number as 1234.

Now, Murf should have created a 'n;north' exit, and made it unowned. Things
in Unter have a *list* of owners, instead of just one. Igor can add himself
to the list of owners, and then he'll be able to relink the exit to his
new room. He types:
   set north own +me
   build link north 1234
The program will respond with "Added 123@Zoo to owner list", then "Linked 
exit to 1234." Now Igor sets a few messages on the exit. He types:
   set north desc=North is Igor's House.
   set north succ=You crawl into Igor's House.
   set north osucc=crawls into Igor's House.
These messages work just the same way they work on object, like the Ferret Chow.
Next, Igor goes in the room, and creates an out exit. Murf has been nice enough
to not only give Igor the n;north exit, but to set his room linkok. This means
that Igor can link an exit to Murf's room. (A room is set linkok by doing
"set here linkok T", for 'true', which means anyone can link to it. A room
can be linkok as a boolean, which means it acts like a lock. You can set a
room to be linkok ONLY for player 123@Zoo by doing "set here linkok 123@Zoo").

Murf's room number is 623.  Igor types 'n' or 'north' to go in the room,
then types:
   build exit "out;back;exit;s;south" 623
The program will respond with "Opened exit 1235. Linked exit to 623." Igor now
has a south exit back to Murf's room. Murf can now make his room not linkok,
so no one else can link to it. (He does this with "unset here linkok", or
"set here linkok F", for 'false'.) Igor puts some messages on the south exit 
as well. He then decides he wants to describe the room, so he types:
   set here desc=This is Igor's home. It is a small room, lined with paper
   shreds. Over in the corner is a small hole.
(That's all one line; unter does not allow newlines in strings.)

Now Igor wants to dig a small room that the hole connects to. This time,
he's going to make full use of the 'build room' command, since he owns
this room, the room he's standing in. He types:
   build room "Igor\'s Hidden Room" "hole;in" "out;back;exit"
The program responds with all the messages about the exits being opened and
linked, and the room being dug. He then puts a few messages on the exit
into his new room, with:
   set hole desc=This is a small hole, just the size of Igor.
   set hole lock=me
   set hole fail=You can't fit.
   set hole ofail=can't fit through the hole.
   set hole succ=You slip into the hole.
   set hole osucc=slips into the hole.
   set hold odrop=slips in through the hole.
He's locked the exit to him, so only he can go through it. When he uses the
exit, the success and osuccess messages will be displayed. When someone else
tries to use the exit, the fail and ofail messages will be displayed. 
He can now type 'hole' or 'in' to go in the room, and set messages on the room
there, and also on the exit back out.

If Igor wants everyone BUT Murf to be able to go 'hole', he first must know
Murf's object id number. Let's say it's 35@Zoo. Igor then types:
   set hole lock =!35@Zoo
This locks the hole against the player Murf. If he wants a person to be able to
go through 'hole' only if they have the bag of Ferret Chow, he types:
   set hole lock=ferret chow
(The ferret chow must be in the room or in his inventory, so the 'set' code
will know what Igor's talking about. Otherwise, he'll have to use the ferret
chow's object id, just like he did with Murf.)
If he wants himself to be able to go in the hole, even if he doesn't have the
Ferret Chow, he types:
   set hole lock = (ferret chow) | me
If he wants to lock everyone out except for himself and Murf if Murf has the bag
of Ferret Chow, he types:
   set hole lock =(35@Zoo & (ferret chow)) | me
If he wants to lock everyone out UNLESS a certain sign is sitting in the
room (no one's holding it), he types:
   set hole lock =(with sign)
You can get more and more complicated with locks this way.

Igor is done building his home, and wants to set his home to it, so when he
types 'home' he will go there instead of Limbo. He goes in his house,
and types:
   set me home here
The program will respond with "Home set." Now Igor can go 'home', and QUIT
and not worry about his inactive body cluttering up the landscape.

Also, any object that Igor creates can have its home set to him, so whenever
he teleports, his objects will stay with him.

When you build a room, it makes it neater if you have a very thorough
description. Every thing listed in the description can be detailed by
making exits in the room that are locked, and using them for scenery.
For example, here is a room description:
   You stand in a large square room. There's a lamp in one corner, currently 
   lit. A few chairs are here and there, and there's a couple of toys
   scattered over in another corner.

Now, you noticed the chairs in the room. A 'look chair' will show:
   Several comfortable padded chairs sit about the room.
Next, a 'sit' will get you:
   You sit down in a chair.
Everyone else will see a message about you sitting down as well.

This was done using a scenery exit. This is an exit that is locked, so
you can't go through it. In this case, here's how it was done:
   build exit "chair;chair;sit" home
   set chair lock F
   set chair desc=Several comfortable padded chairs sit about the room.
   set chair fail=You sit down in a chair.
   set chair ofail=sits down in a chair.

Some people prefer to use dark objects instead of locked exits for scenery.
It's done the same way, except you have to 'get' the object to see the fail
message, and also, only wizards can set objects dark. Using locked exits
is usually a whole lot simpler.

You also noticed the lamp in the corner. A 'look lamp' shows this:
   You see a bright lamp, turned on. There's a large OFF switch at the base.

Being curious, you 'turn lamp off'. Everyone sees a message about you
turning the lamp off. You look at the room again, and this is what you see:
   The room is quite dark, almost pitch black. In fact, the only thing
   you can see is a small glowing ON switch on what might be a lamp in
   the corner.

You 'look lamp', and see: 
   It's really too dark to tell, but this could be a lamp.

Then, you 'turn lamp on', and everyone sees a message about you turning on
the lamp. When you look at the room again, the description is back to normal.

This lamp trick was done using unter macros. First of all, an exit is built,
called "turn lamp on;lamp", locked, and given the normal lamp description.
The fail, however, is a macro. Before writing it, though, we set a few
strings on the lamp.
   set lamp str onsucc "turns the lamp on."
   set lamp str offsucc "turns the lamp off."
   set lamp str meondesc "You see a bright lamp, turned on. There's a large
   OFF switch at the base."
   set lamp str meoffdesc "It's really too dark to tell, but this could be
   a lamp."
   set lamp str ondesc "You stand in a large square room. There's a lamp in
   one corner, currently lit. A few chairs are here and there, and there's a
   couple of toys scattered over in another corner."
   set lamp str offdesc "The room is quite dark, almost pitch black. In fact,
   the only thing you can see is a small glowing ON switch on what might be
   a lamp in the corner."

Next, we add the macros that will do all the hard work.
   set lamp cmd xxon=set $me cmd fail=set here desc "$me.ondesc";@do 
   $me.onsucc;unset here dark;set $me desc "$me.meondesc";set $me name
   "lamp;turn lamp off";xxoff
   set lamp cmd xxoff=set $me cmd fail=set here desc "$me.offdesc";@do
   $me.offsucc;set here dark;set $me desc "$me.meoffdesc";set $me name
   "lamp;turn lamp on";xxon

These two macros do quite a bit of message setting. In unter, $me refers
to whatever's actually doing the work; $actor is the player himself.
In the case of a macro, $me is the object that macro's attached to. 
Macros run with the permissions of the objects they're attached to, NOT
with the permissions of the player. So in this example, $me is the lamp
exit. Since it's setting messages on itself and on the room, it needs to
own both itself and the room. Remember that ownership is a list, so this
is easy to take care of. Simply find out the exit's object id (with 
'which exit lamp'), and "set here own +<oid>" and "set lamp own +<oid>".
The other thing you'll notice is all those $me.foobar things. That's
string substitution. Try doing "say $me.desc" sometime. Only strings can
be done like this; $me.loc, for instance, wouldn't work, since 'loc' is
not a string. 

The final thing to do to make this exit work, is to give it a push start,
so to speak. Once it's been run correctly the first time, it will always
work properly. We do:
   set here cmd fail=xxon
then try the 'lamp' exit. The first time won't do anything noticable,
but it should set up the fail macro to do all its tricks the next time
you turn the lamp off.

There are all sorts of other little toys like this that are easy to make,
once you've got the hang of it. By no means is it necessary; you can just
stick with building strictly scenery exits, with no macros at all, and 
still have just as neat a place to explore as one loaded with macro toys.