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.