Introduction, and some confusing terminology:
---------------------------------------------
The first thing to understand about UnterMUD is that it is not a
programmable MUD. However, objects in UnterMUD can execute commands in
exactly the same manner as players can. Therefore, to understand how to
use UnterMUD to its fullest, you have only to become familiar with how
commands are parsed and executed, and how command-line variables are
expanded. In the course of this introduction, commands tied to objects,
exits, or players will be referred to as "macros". Macros are basically
commands that have been entered into the MUD server as a part of some
action taken by a player.


Definition of terms:
--------------------
There are some simple concepts that UnterMUD supports, dealing with the
"environment" in which a command or macro is executed. The "actor" of a
command is the player who actually entered a command to the server -
the actor may do something that would trigger a bunch of macros, but
the concept of the actor remains constant until the whole set of
actions that take place as a result are completed. The "locale" of a
command is defined to be the location of the actual thing that is
doing the action. This is important because some game objects
(like rooms!) don't really have locations of their own, and if they wind
up doing something as a result of the actor's action, they attempt to
use their own locale. The last concept is the "self" and that is the actual
thing that is doing the action. So, for example, if I am in a room, and
I try to leave via an exit which is locked, and the exit's fail command
is to try to kill me, I am the "actor", the room I am trying to exit
from is the "locale", the exit's fail command is a "macro" and, when
the fail macro is running the "self" is the door. Note that when my
initial command (to try to leave the room) is running, the "self" and
"actor" are identical; "actor" and "self" will often be identical, but
not necessarily so. In macros, these three things are often referred to
as $actor (for "actor"), $me (for "self"), and $here (for "locale").


Object Types, IDs, and Cyberportals:
------------------------------------
In UnterMUD, there are basically only four different object types: player,
room, exit, and thing (sometimes referred to as an object).  Everything
has its own unique object id number, which it can be referred to by, as
well as by name.  Each UnterMUD has a mudname, which (hopefully) is
unique among all other UnterMUDs.  Players and objects have a slightly
different object id than rooms and exits do.  They have what is referred
to as a "fully qualified" object id.  This means that their object id
contains the mudname of the UnterMUD they were created on.  An example
player object id is "123@ZooMUD".  An object will have a similar object
id, while rooms and exits will only have a number (ex: "45").  The reason
for having two different types of object ids is because only things with
fully qualified object ids can use cyberportals.
When you use a cyberportal, the two unters connect and transfer information
back and forth.  If all is successful, your player object and everything
you were carrying gets added to the database of the remote mud.  Things
in your inventory get deleted from the local database, but your player
character just gets 'ghosted' (its location field removed).  The local
unter then sends you a cyberportal reconnection string, which your client
should read and interpret as a new place to connect to.  Assuming your
client knows how to deal with cyberportals, you can walk through an exit
onto a totally different unter without noticing a thing.  If you don't
have a smart enough client, you'll have to manually disconnect from
the local unter and reconnect to the remote one and log in yourself.
(See the file "cyberportals" for more detail).


Tinymud-speak:
--------------
The two most common types of MUDding operations (at least in systems
that are derived from TinyMUD's conceptual ancestry) are the say
and pose/emote commands, ususally abbreviated to double quotes and colons:

:hops around!
"hello here!

 are taken to mean:

so-and-so hops around!
so-and-so says, "hello there!"

UnterMUD supports this syntax, by treating lines beginning with " or :
to mean that the remainder of the line should be handed to the "say"
or "do" commands, respectively. Typing:

say "hello there!"

is 100% the same as typing:

"hello there!

as the same server routines are responsible for handling both cases.
You can, to a degree, replace the way these routines behave for you
during the course of play by making a macro, as will be discussed later.


Multiple commands:
------------------
Commands can be grouped several to a line, by separating them with
semicolons. However, commands can also be delimited with quotation
marks which can prevent semicolons from being taken to mean a break
in commands. For example:

say hello there!;do hops up and down!

would result in:

so-and-so says, "hello there!"
so-and-so hops up and down!

while:

say "hello there!;do hops up and down!"

would result in:

so-and-so says "hello there!;do hops up and down!"

because the quotation marks were interpreted to mean "take the rest of the
quoted string as a single token". When you use a "do" or "say" command
with a single " or : at the beginning of the line, the same approach is
used, in that the rest of the line is assumed to be one token by the
command processor.


Quotable quotes and other magic:
--------------------------------
Quotes can be quoted as well, by using apostrophes as alternate quotes.
Like in the UNIX shell, apostrophe quotes have a slightly different
meaning from double quotes, but at this point, it is sufficient to
understand that a quoted string consists of a quote character, and then
a number of other characters, up to the matching quote. So:

"this shouldn't be 5 tokens"

is treated as one token, despite the existence of a mismatched quote
character within it.

Other "special" characters can all be "escaped" in a line of text by
using a '\' backslash character in front of the character you wish to
have escaped. Newlines can NEVER be escaped, but everything else can
be, including backslash characters. So:

this is\"\; one weird\\string

is tokenized into four tokens, despite the presence of a quote:

this, is";, one, weird\string

More importantly, it is one command, despite the presence of an unquoted
semicolon.


The equals character, and how not to quote at all:
--------------------------------------------------
You will encounter occasions when you don't WANT to have to worry about
quoting and escaping semicolons and so forth, and you simply want to
type stuff in directly. This is done using the equals character '=',
which means, roughly, "treat everthing from this point on as a single
token, and ignore quoting and all that rot."

The '=' syntax is also good for providing a *degree* of TinyMUD-like
interface, since you can type:

set me desc =some description or other that's got quotes

and not worry about quoting and so forth after the '='. One *difference*
between the UnterMUD equals sign and TinyMUD is that spaces after the
equals sign are preserved. When UnterMUD says, "I won't tokenize past
an unescaped '='," it means it.

You must remember that most commands gleefully will do exactly what you
tell them to. For instance, if there is a "little red wagon" in the room,
and you try to get it like this:

get little red wagon

what will really happen is that your command will be tokenized to be
four tokens:

get, little, red, wagon

These all get passed to the 'get' command, which assumes that you want to
get three things, ie, "get little", "get red", and "get wagon".  Since 
this obviously isn't what you meant, you need to either put quotes around
"little red wagon", or use an equals sign:

get =little red wagon
get "little red wagon"

Both work equally well.


Attributes - what are they?
---------------------------
All MUDs are basically network-oriented databases of objects. Each object
contains information that somehow is used by the server to present a
"pretend universe" based on that information: descriptions of things,
names of things, actions, exits, and so forth. These are all attributes
that an object may have. UnterMUD uses a very flexible means of encoding
the various attributes of an object, unlike some MUDs that may use a
static data structure of some type, UnterMUD objects are very free-form
and can be easily modified by players. Depending on the degree of
modification this can result in something as simple as changing the
description of an object, to changing the layout of the MUdiverse.

All UnterMUD servers are programmed to recognize certain types of
attributes, namely lists of things, strings, commands, numbers, and
boolean expressions. It's easy to add new types to UnterMUD, but
only if done wisely. Adding new attributes to an object, however, is
very simple. For one thing, each server has an internal table of
"known" attributes, which can be accessed by issuing the command:

set help

which will list the settable attibutes this MUD recognizes and some
information about them. Some are "wizard only" which means that they
have a sufficiently large impact on the MUDiverse that ordinary
players aren't allowed to modify them. An example of a "wizard only"
attributes is the "players in a room" list - if just anyone could
change that, someone could effectively teleport other players around
at random, or simply place them in a data-limbo. If you look at
the attribute listing, you'll see these attributes marked clearly.

Other attributes are the ones a wizard *WANTS* players to set - things
like descriptions, names, and so forth - the things that make a MUD
interesting. These can all be changed by players with the "set"
command.

Look at the attribute listing with the 'set help' command and you'll
see that there are two words for descriptions. One is the long
form of the attribute name ("description") and the other the
short, internal name ("dsc"). You can set an object's description
by typing:

set object description =text object description.
set object desc =this is another way to do it.
set object dsc =this is yet another way to do it.

The "set" command prevents you from specifying something ambiguous,
and knows the correct attribute type for the "description" attribute
(a string) and automatically uses that.

If you try to set an attribute that Unter doesn't know about, it will
complain. You have to explicitly tell it what type of attribute you're
setting. For instance, if you want a string attribute called "info1",
you would have to do:

set object str info1 =this is a string.



mjr.