.\"Copyright(C) 1990, Marcus J. Ranum,  All rights reserved.
.\"original text by Andrew Molitor.
.\ macros
.\ example start
.de EX
.sp
.ft B
.fl
.nf
.na
..
.\ example end
.de XE
.sp
.ft R
.fi
.ad
..
.\ end macros
.hy 0
.EH 'Ubermud Monitor
.OH '\(C)Copyright, Marcus J. Ranum, 1990
.TL
The Ubermud Monitor and User Input Interface
.PP
This document provides a brief description of the Ubermud player interface,
or \fI'monitor'\fR. The purpose of the monitor is to dispatch user input,
handling it as play input, program text, or other types of commands. The
monitor has a simple command set that allows a user to toggle between
programming mode, game-playing mode, and any other modes that may
eventually be added.
.NH 1
Basic Monitor Modes
.PP
The monitor has three modes at present: login authentication mode,
game-playing mode, and programming mode. Each mode evaluates user
input differently, and certain modes may be inaccessible to a
particular player at any given time. Login authentication mode simply
prompts the user for a login and password, and refuses to perform
any other operations until a valid login and password has been
provided. Game-playing mode takes a block of user input, reads it
a line at a time, and attempts to match the input to meaningful
options available to the player's "game self", depending on the
location of the "game self" and the current universe rules.
Programming mode accepts U-code program text, and squirrels it
away in a temporary file for later compilation and execution.
.PP
Within each mode of the monitor, a player can switch to any other
without having to break connection or lose any output that the
game may be producing for them. Mode-switching is done by sending
a single line of input to the server, with the first character
being \fI'@'\fR, followed by a monitor mode command. The monitor
may then perform a variety of operations.
.NH 2
Monitor Switching Commands
.PP
The current monitor recognizes the following internal commands:
.sp
\fB@quit\fR - Terminate the connection immediately. This option can
be entered from any monitor mode, at any time.
.sp
\fB@login\fR - Re-initialize the connection without disconnecting.
This option can be entered from any monitor mode, and causes the
current player to be "logged out", and the login prompt to re-appear.
.sp
\fB@play\fR - Enter game-playing mode. This option causes all user
input to be treated as "player actions", and interpreted in the
context of whatever universe rules are in effect.
.sp
\fB@program\fR - Enter programming mode. This option causes all player
input to be stored in a temporary file for later compilation. If there
is already data in the temporary file, it is left intact, but the player
is warned how much program text there is. Players can toggle freely
between game-playing and program modes, without the temporary file
being damaged. This is convenient in the case where something interrupts
a person who is programming, or a person who is programming wishes to
perform a quick player action in the game.
.sp
\fB@flush\fR - Cleans out the temporary file of U-code and does not
in any other way change monitor modes.
.sp
\fB@compile\fR - Compiles the U-code in the temporary program file,
returning any error messages or output generated by the compiler.
After compilation, successful or otherwise, the temporary file is
flushed. Note that the compile directive can be issued when in any
other mode, and does not change monitor modes. It is perfectly
feasible to enter some U-code, switch to game-playing mode, play
for a while, and then compile the U-code. Each player's input
code is stored in a separate file, so there is no danger of
players interfering with each other's temporary code files.
.PP
The monitor commands are \fIcase-sensitive\fR (as is most of Ubermud)
and can be abbreviated to significant characters (EG: \fI@pl\fR
for \fI@play\fR).
.NH 1
Operation of Ubermud in Each Mode
.NH 2
Programming Mode
.PP
For a detailed description of how to program in the U programming
language, see the reference guide, \fI"The U Programming Language"\fR.
Some important non-language aspects of programming mode are worth
mentioning here, however.
.PP
Comments are not permitted in U. This may seem drastic, but is for
the simple reason that shipping masses of comment text over the
network is wasteful. U-code is only accepted in 'raw' form by the
compiler. This was a deliberate decision, because it enforces use
of software development tools on the player's host machine. Ubermud
is distributed with a simple U-code submitter called \fIusubmit\fR
that handles the dirty work of running a U-code file through the
C pre-processor, logging into the U-server, setting programming
mode, compiling the submitted code, and disconnecting. This is to
encourage users to maintain copies of their better creations for
re-use or to enable them to be "transported" easily between
U-servers. Remember that at this time there is no U-code disassembler
so it is impossible to regenerate the source U-code for an object
at the server end. Ideally many people will use the C pre-processor,
but it seems unreasonable to enforce that in the environment. If
you do use the C pre-processor, ensure that all \fI#line\fR
directives are stripped out, as the U-compiler will treat them as
syntax errors.
.NH 2
Game-Playing Mode
.PP
In game-playing mode, the monitor functions only as a simple parser
that tokenizes user input, and tries to resolve each line of text
typed by a player into a call to a U function. The functions that
are defined are out of the scope of this document, as they are not
static, but are defined in the universe rules that the particular 
server is running under. There are a very few hard-coded rules in
the monitor - the rest are configured by the \fICreator\fR of the
U-universe in question.
.PP
The first thing the monitor does is examine the text line for various
special initial characters, which are 'hot-wired' to certain functions
in the universe. These are \fI'"'\fR, \fI':'\fR and \fI'>'\fR,
which are intended to emulate to a degree the functionality of \fITinyMUD\fR
and other MUDs. The \fI'"'\fR character passes the remainder of the
player's input line to whatever is defined as the current universe's
\fBsay()\fR command (in U, designated as \fB@.say()\fR). Thus, typing:
.EX
"foo ? wa ?
.XE
Is exactly the same as calling the function:
.EX
@.say("foo ? wa ?");
.XE
Presumably, in most universes, the "say" command will result in some
form of player speech.
.PP
Similarly to the way in which the \fI'"'\fR leading character generates
a call to the universe's "say" command, the \fI':'\fR leading character
generates a call to the universe "emote" command. The \fI'>'\fR leading
character is used as an abbreviation for "go", in the same manner. This
is a departure from \fITinyMUD\fR for performance reasons, as a Ubermud
universe has to contend with disk accesses, and excessive searching and
matching is to be avoided. Thus, a player in a room typing:
.EX
>west
.XE
Will call the universe's "go"  function (\fB@.go()\fR in U-code) with
a single string parameter, \fI"west"\fR.
.PP
If the the leading character of the input line is not a 'hot-wired'
special character that invokes an automatic call, the monitor
tokenizes the input line, chopping it up into a list of words.
Words in the input line can be specifically grouped into strings
by use of quotes. EG:
.EX
say "how's now" brown cow
.XE
Would be broken up as:
.EX
word #1: "say"
word #2: "how's now"
word #3: "brown"
word #4: "cow"
.XE
Strings quoted with either " or ' are treated as single tokens. A quote
will remain in effect until the matching quote character is encountered,
or the end of the line is reached. In the example above, the apostrophe
in "how's" was preserved because it was surrounded by the double quotes.
A double quote can be placed in text by surrounding it with single
quotes, and so on.
.PP
Once the input is tokenized, the universe rules table (in U-code object @)
is searched for a function with the same name as the first token. Note
that \fBthis is case sensitive\fR.
.PP
A check is made to ensure
that the leading character of the function being called is not an
underscore \fI'_'\fR character. If the character is such, the system
table, room, and user are not scanned unless the effective user-id is
that of the \fICreator\fR. This is intended to permit the \fICreator\fR
to incorporate frequently used "utility" commands in the universe
rules table without their being directly callable from within game-playing
mode. Note that they are still callable from within programs, or
programming mode. This provides a degree of control.
.PP
If a legal matching function is found, it is called
with all the remaining tokens passed as parameters. For example:
.EX
take "the orange cat
.XE
Will search the universe rules table for a function named \fB"take"\fR (in
U-code, \fB@.take()\fR), and if it is found, it is called as:
.EX
@.take("the orange cat");
.XE
Note that the quoted string was left unterminated. The monitor assumes that
the player wanted the entire line as a single token.
If no such function is found, an identical search is performed within
the room the player is currently in (in U-code: \fB#actor._loc\fR).
If a function matching the first token exactly is found, it is called,
just as in the case where a match is made in the universe rules.
.PP
Thus, if the system table has a \fI"look"\fR function, but
no \fI"hop"\fR function, and the room the player is in \fIdoes\fR have
a \fI"hop"\fR function, the monitor resolves input as follows:
.EX
look Albert          -calls>  @.look("Albert");
hop around happily   -calls>  <room>.hop("around","happily");
hop "around happily" -calls>  <room>.hop("around happily");
.XE
Note how the tokens are broken up differently based on quoting.
It is also important to note that case-sensitivity is preserved.
.PP
If the monitor fails to successfully find a function in either the
universe rules or the current room, it checks the object
the player is using for an function whose name matches the first token.
The mechanism here is exactly like that of within a room.
.PP
If a matching function is found, it is called with the second and succeeding
tokens passed as parameters. For a programmer who is writing functions
bound to objects, one important distinction must be made: when the
monitor generates a call to a function, all parameters are passed as
type \fIstring\fR even if they are numeric. There are U-code built-in
functions for converting strings into numbers or object numbers,
to simplify interfacing with the monitor.
.NH 1
Universe Rules
.PP
It is impossible to predict what universe rules a U-universe might
be running under. It is perfectly possible that the rules of a
universe might be intentionally guarded as secret by the \fICreator\fR
for some reason or another. Needless to say, this makes documenting
things rather difficult - especially since changing the rules of a
universe is a matter of seconds. Presumably users will become
familiar enough with the monitor that they can get about in even
the strangest set of universe rules. \fICreators\fR are encouraged
to make the U-code for their universes available to people who
plan to program in them, and to provide at least rough documentation
of the commands in the universe table (since they are always searched,
and could surprise a player rather badly).
.NH 1
Funky Objects
.PP
Owners of rooms will have considerable powers to create "funky objects",
damaging objects, U-virusses, and so forth. Ideally a \fICreator\fR
will only give programming access to people who will not do such
things lightly. As a deliberate design decision there are no attempts
other than the basic permissions system to prevent such programming,
since correctly used in a spirit of fun, "funky objects" can be
extremely entertaining. Presumably each \fICreator\fR will have some
published or arbitrary guidelines governing confusing and damaging
objects.
.NH 1
Conclusion
.PP
The Ubermud monitor is still somewhat rough, but provides a reasonable
amount of flexibility. The basic trade-off is between the desire for
complex parsing in the monitor, and the desire to make as few 
assumptions as possible about the universe rules that the current
U-server is running under. The monitor was deliberately designed with
the idea of a "mode switch" to allow easy adding and experimenting
with new user-input processors. Once the user's input has been
massaged into a set of calls to compiled U-code, the universe
rules, which are far more dynamic and easily changed take effect.