MUSH Manual Version 2.008: Copyright 1993, 1994, 1995, Lydia Leong (lwl@netcom.com / Amberyl) Last revised 5/22/95. Section II: Building and an introduction to programming Table of Contents: 3. Building. 3.1 Creating a room: @dig, FLOATING flag 3.2 Connecting rooms: @open, @link and @unlink, LINK_OK flag, @entrances 3.3 Refinements: ABODE and JUMP_OK flags, drop-tos and STICKY flag on rooms 3.4 Exit conventions and the TRANSPARENT flag 3.5 Do it! -- home 4. Introduction to Programming 4.1 The stack and string substitutions - % substitutions 4.2 General attributes and action lists - @trigger and GET() 4.3 The queue: @ps, @wait, and @halt. HALT flag 4.4 Decision making: @switch 4.5 Other ways of triggering: @use and @startup 4.6 User-defined commands: $command, @scan, @verb 4.7 Introduction to functions: ADD() and other math, RAND(), TIME() 4.8 Do it! -- falcon control 3. Building 3.1 Creating a room Building a room is done quite simply, using the @dig command. The syntax is: @dig =, in1, in2, and in3 are all exit "aliases" - typing any one of these names will bring you through the exit into the room. You may have as many of these as you wish; the names must be separated by semi-colons. in1 will be the visible "primary" exit name, which appears in the room's Obvious Exits list. out1, out2, and out3 are similar. This exit goes from the room you just dug to the room that you are in. On TinyMUDs, building convention dictates that exits be set DARK - i.e. no exit names appear in the "Obvious Exits" list. Many people like visible exits, however, and in the age of MUSHes, most exits are visible. Visible exits are the default. You must control the room that you are @digging from. If you don't own a room, you should first @dig and then @tel to that room. (Or use @dig/teleport, which builds the room then moves you there). You can then build off that room. If your room is not linked to something, however, you will occasionally get the message "You own a disconnected room, ." To avoid this, set the room FLOATING. ============================= [ Example 3.1: Living Room ] > l Foyer(#3108R) This is the foyer of a small private home. Obvious exits: Doorway > @dig Living Room=Living Room;lr;living,Foyer;f;out;o Living Room created with room number #3813. Opened. Trying to link... Linked. Opened. Trying to link... Linked. > l Foyer(#3108R) This is the foyer of a small private home. Obvious exits: Living Room Doorway > lr Living Room(#3813R) Obvious exits: Foyer ============================= 3.2 Connecting rooms To open an exit between two existing rooms, use the syntax @open =#, This will open and link exits between the two rooms. You can also open an exit in but not out by simply using @open =#room To change an exit destination, simply "@link =#". (Certain older versions of MUSH might require you to first "@unlink exit".) Be careful not to leave exits unlinked, because an unlinked exit will become the property of whomever @links it. If you want to have an exit going no place, like something called "sit" which displays the @fail message "You sit down." @link the exit to the room it is in - i.e. @open sit=here. @lock sit=#0. @fail sit=You sit down. You can let people open/link exits to one of your rooms by setting it LINK_OK. Note that people cannot open an exit from your room into something else; they can only link an entrance. * * * * * The "@entrances " command returns all links to -- exits which are linked to the object, rooms which have their drop-tos set to the object, and players and things which have their homes set to the object. This command in 1.50 also takes switches, allowing you to specify exits, rooms, players, or things alone. This command is computationally expensive, costing the same as @find. You can limit the dbref range which @entrances searches by specifying "@entrances =,". This is similar to restricting the range on @find. 3.3 Refinements If you want people to be able to @teleport to your room, set it JUMP_OK. Beware - if you are in a JUMP_OK room and someone does a @whereis on you, the room number will be listed, and that person will be able to @tel to your location, so if you don't want unexpected visitors dropping in, it might be best not to set the room JUMP_OK. If you want other people to be able to set their homes in your room - i.e. be sent there automatically when they type 'home' - set the room ABODE. To set yourself or another object's home, @link =. In older versions of MUSH code, most notably MicroMUSH, the JUMP_OK and ABODE flags are merged; a room set ABODE may both be @linked to and @teleported to. * * * * * Rooms may be @linked to other rooms, using @link =#. This sets a "drop-to". Objects dropped in room1 will automatically be sent to room2. "Drop-tos" may be delayed by setting the STICKY flag on room1. If the room is STICKY, the drop-to will not be performed until the last player has left the room. 3.4 Exit conventions There are certain exit conventions used on TinyM*s which make following other players around easier. Exits should, if possible, have an @osucc and @odrop message. The @osucc message is triggered when someone uses an exit; it is displayed to everyone else in the room that the person just left. The @odrop message is triggered the same way, but is displayed to everyone in the room that the person enters. Thus, you can tell where people are going to, and where they are coming from. For purely aesthetic purposes, exits often have @desc and @succ messages. The @desc message is displayed when someone "looks" at an exit; the @succ message is displayed to the person who walks through the exit. * * * * * Several clever things can be done with "null" exits. These are exits that don't lead anywhere, but simply display a message to the player. For example, an exit named "sit" could give the message "You sit down." These exits are usually locked to #0, linked to the room they are in, and DARK. Use of these kinds of exits is generally discouraged on MUSHes that enforce building quotas and/or are trying to conserve disk space. In areas that use a lot of directions - north/south/east/west etc. - it is often helpful to have a null exit with the names of the remaining directions in it. For example, if a room has exits in all directions except east and west, a null exit called east;e;west;w with a @fail message of "You can't go that way." is very helpful. Otherwise, the player who types "east" will simply get a "Huh? (Type "help" for help.)" message. Before you make such fake exits in your rooms, though, it might be a good idea to check that your MUSH doesn't have them already defined in the Master Room. MudCore provides the Master Room support for these fake direction exits (and the message "There is no exit in that direction.") MudCore takes this a step further, however, providing customization of these fake exits without taking up more database space for extra "real" exits. Sometimes, when building an area, you will want to have, for example, a "north" exit which provides a message like, "You walk down a long corridor, discover nothing interesting, and return to where you started." and doesn't actually lead to another room. Such exits give the illusion of "space", making a small area feel larger. In MudCore, "fake" exits in the cardinal directions can be designed by placing the attributes DESC_ and FAIL_ on the room. For the above example, one might use, "&DESC_NORTH here=To the north is a long, featureless corridor." and "&FAIL_NORTH here=You walk down a long, corridor, discover nothing interesting, and return to where you started." * * * * * There is a flag called TRANSPARENT, which can be set on exits. If this flag is set, players looking at the exit see, after the exit description, the description of the next room and its contents (but not its succ/fail messages or exits). This is useful for creating the illusion of an archway or similar portal, where it makes logical sense to be able to look through it into the next room. In 1.50, the TRANSPARENT flag can also be set on rooms. This causes the obvious exits in the room to be displayed with each exit on a line by itself, giving the destination room. For example, you might have: Obvious exits: South leads to Foyer of the Bank. East leads to Intersection of Park and Hill Streets. instead of: Obvious exits: South East 3.5 Do it! -- home This builds a very simple home of three rooms, linked in a triangle: Living Room | \ Workroom------Bedroom Issue the following commands: @dig/teleport Living Room [ The room will be dug and you will be moved into it. Note its dbref number ] @set here=FLOATING [ Suppresses disconnected room warnings ] @desc here= @dig Workroom=Workroom;w;work;south;s,Living Room;lr;living;north;n;out;o go workroom @desc here= @dig Bedroom=Bedroom;b;east;e;bed,Workroom;w;work;west go bedroom @desc here= @open Living Room;lr;living;northwest;nw;out;o=#,Bedroom;b;bed; southeast;se [ Note: the previous line is wrapped-around. is the room number of the Living Room, which you should have noted earlier. ] @set here=ABODE @link me=here [ Sets your home to this bedroom ] All three rooms are dug and linked - now, all you have to do is to spiffy up the exits, and you're all set! 4. Introduction to Programming 4.1 The Stack and string substitutions The MUSH stores several variables, related to the cause of an action, the object that is executing an action, and the program state during that action, referred to as the "stack". These are accessed via a "percent substitution". One such variable is the "enactor" -- the object which caused an action to be performed. For example, if Sareena looks at a Plush Shaav Doll, Sareena is the enactor. The enactor is sometimes referred to as the "cause". The percent substitution '%N' returns the name of the enactor; in this case, it would be "Sareena". The substitution '%n' also returns the name of the enactor, but the first letter is in lower-case. Another substitution, '%#', returns the dbref number of the enactor. It is also possible to get the appropriate pronoun for the enactor. '%s' is the subjective pronoun (he/she/it). '%o' is the objective pronoun (him/her/it). '%p' is the possessive pronoun (his/hers/its). The capital letter forms ('%S', etc.) return the pronoun with the first letter capitalized. The game determines the pronoun to use by looking the @sex attribute on the enactor. These substitutions are equivalent to the function evaluations "SUBJ(%#)", "OBJ(%#)", and "POSS(%#)". In the example above, since Sareena is female, these substitutions would return "she", "her", and "hers", respectively. The substitution %l returns the dbref number of the enactor's location. This is useful when programming objects in the Master Room, and does not pose a "security risk", since the enactor has volunteered his position by triggering a $command or similar. The object performing the action can be referenced via '%!'. This returns the dbref number of the object. It is equivalent to the function evaluation "NUM(me)". In the above example, the object that has been triggered (and thus is performing the action) is the Plush Shaav Doll. * * * * * The "stack" in MUSH is simply a place where strings are stored; it is not a literal "stack" in the usual sense of having a top object which can be pushed and popped (as in MUF, or as defined in a standard computer science class). The stack consists of ten strings, numbered 0 through 9. Strings on the stack are referred to as %0, %1, %2, and so on, through %9. The mechanisms for copying strings into the stack will be explained later. Related to "percent" substitution is the V() function. It produces identical output to the equivalent percent substitution. For example, '[v(0)]' is equivalent to '%0', and '[v(N)]' is the same is '%N'. Throughout this manual, however, '%0' and other percent substitutions will be used instead of 'v(0)', since the evaluation of percent subtitutions is faster than the evaluation of V-functions. 26 registers, "numbered" va-vz, are available for programming, as part of the "standard" collection of MUSH attributes. They may be accessed by either %va, or [v(va)]. Note that the square brackets [] force something to be evaluated as a string. 1.50 provides the additional registers wa-wz and xa-xz. These behave in a manner identical to va-vz. Percent substitutions should always be used instead of functions, where possible. In fact, you should ALWAYS use the percent substitution, unless you are SURE that the function version is required -- use %N instead of v(N), %! instead of num(me), and so forth. There are virtually no situations which require the functions, and thus using the function versions is inefficient and wasteful. Furthermore, please note that it's just "%0", NOT "[%0]"; the additional square brackets cause an unnecessary extra evaluation and thus are inefficient. Please note that if you access something with a percent-substitution, if you capitalize the first letter of the substitution, then the first letter of the text returned will also be capitalized. The S() function forces an additional round of pronoun substitution. This is useful if you are evaluating a string and want to force the parser to substitute in the values for all (non-escaped) functions. Percents can also be used to add in special characters. %r is a carriage return, %t is a tab character, and %b is a blank space. To show a literal "%", use "%%". '%r' is actually two characters (a carriage return and newline), and functions like STRLEN() will count it as two. Finally, there are temporary storage "registers", also numbered 0 through 9. They are set via the function SETQ(), and retrieved via the function R(), or through the %q-substitution. The values set via SETQ() are preserved through the entire command list associated with a given command. SETQ() is a function which just returns a blank string, and has the syntax, "setq(,)". "r()" retrieves the value. These functions will be explained in greater detail later. For now, just believe that they allow you to keep values around temporarily. The odd name SETQ comes from the programming language LISP. ====================================== [ Example 4.1: Percent demonstration ] > @sex me=female Set. > @va me=test Set. > say %va You say "test" > say %Va You say "Test" > say %N is demonstrating %p example. You say "Amberyl is demonstrating her example." > say [setq(0,testing for fun)]-- %q0 You say "-- testing for fun" > say [setq(0,testing for fun)]-- %Q0 You say "-- Testing for fun" ====================================== 4.2 General attributes and action lists The 26 registers are often referred to as "general attributes," since they can be used to store anything. Often, they are good places to put variables. In addition to being accessible by the v-function, they can also be accessed by using the GET() function. The syntax for this is "get(object/attribute)". "[get(me/va)]" is always equivalent to "[v(va)]" or "%va". GET() is very similar to the v-function, except it requires an object to get the attribute from. It may be used to get any attribute - registers, descriptions, non-standard attributes, etc. When working only with one object, it is generally more efficient to use a v-function instead of using GET(). GET_EVAL() is similar to GET(), except that it also evaluates the attribute. U() is also similar, and also evaluates the attribute, but it can be used for user-defined functions which take parameters (more on this later). GET_EVAL()'s syntax is like GET()'s: "get_eval(object/attribute)" U()'s basic syntax can be like either V()'s or GET()'s; either "u(attribute)" or "u(object/attribute)" is valid. (For information on how to pass parameters to U(), see a later section in this manual.) There is a subtle difference between the two functions, in addition to U()'s ability to take parameters The enactor of a GET_EVAL() is the object which is actually performing the GET_EVAL(); the enactor of a U() is the original enactor. ====================================== [ Example 4.2a: GET_EVAL() vs. U() ] > say %! You say "#3" > @create Test Test created as object #1034 > @va test=Enactor: %# -- Me: %! Set. > @vb test=$test: @pemit %#=Get_Eval: [get_eval(me/va)]%rU: [u(va)] Set. > test Get_Eval: Enactor: #1034 -- Me: #1034 U: Enactor: #3 -- Me: #1034 ====================================== If you're confused by the difference between GET(), GET_EVAL(), and U(), don't worry about it; details will be provided later, and you don't need to worry about the latter two functions if you're only doing very basic things with MUSH. * * * * * General attributes are often used to store action lists, which are long lists of commands, to be queued and executed. For example, you could @create an object called Test, and "@va Test=:explodes.; @destroy me" General attributes are usually activated by "triggers". The syntax for this is @trigger object/attribute. @trigger is usually abbreviated to @tr. Most of the time, one attribute will trigger another, but you can also type directly @tr object/attribute. For example, if you typed @tr Test/va, from the example above, you would see: Triggered. Test explodes. You get back your 10 Mark deposit for Test. Test has left. You may also pass variables on the stack from attribute to attribute, using trigger. Often, this is a must, since the stack is cleared when something new is triggered. The syntax is "@tr object/attribute=thing,thing,thing,etc." These new things become %0, %1, %2, etc., respectively, in the triggered register. Almost anything can be legally passed on the stack - function evaluations of any type, % arguments, numbers, strings, etc. ====================================== [ Example 4.2b: Sentence Reverser ] [ This object listens for four words and prints them out backwards. ] > @create Reverser Reverser created as object #25789 > @listen reverser=* says "* * * *" Set. > @ahear reverser=@tr me/va=%4,%3,%2,%1 [ Note that %0 is left out, since %0 is the * says - the person talking ] Set. > @va reverser="%0 %1 %2 %3 Set. > drop reverser Reverser has left. Reverser has arrived. Dropped. > "First second third fourth You say "First second third fourth Reverser says "fourth third second First" =========================================== 4.3 The queue and delayed execution The queue is the list of commands that the MUSH is going to execute. All commands are put into it. Most are evaluated quickly, in the order that they enter the queue (first to last), although @trigger takes at least one queue cycle to execute and @force at least two. Setting an attribute also takes time. One must be careful, when programming, that all commands are getting executed at the correct times. There is no hard and fast rule for this; experimentation is generally the only way to find out if your object is executing commands in the correct order. The queue may be checked by doing a @ps. If you have an infinite loop, this is likely to be very long. If you're not sure if an object of yours is infinite looping, @ps is a surefire way of checking. @ps separates the queue into four sections - Player, Object, Wait, and Semaphore. The player queue shows what you have triggered; the object queue shows what your objects have triggered. The Wait queue shows commands that will be executed in the future - commands that you have queued using @wait (explained below). The Semaphore queue shows semaphore countdowns (explained later). The total number of queued commands is also displayed. The default @ps switch is "@ps/brief". This shows the objects and the commands they are running. For the wait queue, it also shows the time to wait. For the semaphores, it shows the object that the command is waiting on, and if the semaphore is using the timer option, it also shows the remaining time. Finally, it displays the total count of queued commands in each of the four categories. "@ps/long" displays all the information that "@ps/brief" does, plus the enactor of the object, and any variables which are being passed on the stack for eventual execution as part of a @trigger. "@ps/summary" shows just the total count of queued commands. Note that @ps defaults to displaying the queue for the individual executing the @ps; only wizards may specify a player name or the "/all" switch. In the totals line, no matter what switches are specified, the numbers in each category are shown as Number1/Number2. The first number is the number of queued commands that you have in that category; the second number is the total number of commands queued in that category. Player and Object categories also have a "[#del]", where "#" is the number of commands deleted from the queue via @halt. * * * * * @ps in 1.50 is somewhat different. "@ps" with no arguments shows your personal queue - the objects and the commands they are running, and, for the wait queue, the time to wait. It also displays the total count of queued commands in each of the queues, in the format / . "@ps all" prints the queue for all players. Wizards can also do "@ps *" to get a queue for that player. In both cases, a queue count is provided. Anyone may do a "@ps count" to get a count of the number of queued commands. * * * * * Infinite loops on objects are dangerous. Every queued command costs 1/64th of a penny. Plus, if an object loops badly enough, it can severely slow down the game for others. If you have a loop, you can use @halt. It clears your personal queue. @halt clears your personal queue, and adds that new command to the queue. @halt = clears that object's queue and adds that new command to the queue. The other way of halting something is to set the HALT flag on it. An object set HALT is essentially inert - it does not @listen, @triggers and @force don't work on it, etc. Also, in 1.50, UFUN() and ZFUN() will return "#-1 OBJECT HALTED" (recursion in a UFUN or ZFUN will automatically set the object HALT). The @halt command in 1.50 is slightly different. If you, or one of your objects, does a "@halt", it wipes out your entire queue. There is no way to clear the queue commands on just one object. You can also do @halt =, which wipes out the player's entire queue and places the new command in it; if you are not a wizard, the player must be yourself. "@halt " in 1.50 with no new command also sets the object HALT. If you just want to stop an infinite loop, use "@halt" with no arguments. There is one command called @allhalt (1.50. In 2.0, it's @halt/all) which is wizard-only. It clears the queue for the entire MUSH, and is used in emergencies. All connected players receive the message, "Your objects have been globally halted by ." * * * * * The syntax of @wait is simple: @wait = There is another, more complex, type of @wait which is timed on objects; this type of @wait involves a "semaphore" and will be described later. @wait is very useful for trying to get objects to execute commands in the correct order, as well as for doing time-delayed sequences - for example, descriptions on a room that change every few hours. ============================= [ Example 4.3: Explosive [ This will create an object which explodes fifteen seconds after being dropped. It gives a warning five seconds before it explodes. ] > @create Explosive Explosive created as object #23083 > @drop explosive=You set down the explosive and ignite it. Set. > @adrop explosive=@wait 10=:pulses dangerously. It'll explode in another five seconds!;@wait 15={:explodes!;@destroy me} Set. > drop explosive Explosive has left. You set down the explosive and ignite it. [ 10 seconds pass ] Explosive pulses dangerously. It'll explode in another five seconds! [ another 5 seconds pass ] Explosive explodes! You get your 10 Marks deposit back for Explosive. Explosive has left. ============================ 4.4 Decision making: @switch @switch is the closest thing to IF-THEN-ELSE on a MUSH. It is similar to the CASE statement in many programming languages. Its syntax is @switch =,,,,,, @switch statements may be nested. One must be very careful about using commas and semi-colons when using @switch - any statements which contain either commas or semi-colons should be surrounded by curly braces { }. A comma will signal a new case/action, and a semi-colon the end of the @switch statement, if not in the curly braces. This is a commonly made mistake - when programming objects whose @switches do not appear to work, always check for misplaced commas or semi-colons. One thing to note is that the variable to switch on does not have to be evaluated within square brackets [ ]. Percent substitutions, like %va, are okay to switch on, as are functions simply stated, like words(v(va)). After the variable name is ALWAYS an equals sign. @switch %va=>1,:foo does NOT mean "if va is greater than or equal to one, :foo". It means "if va is strictly greater than one, :foo". The equals sign is simply part of the @switch syntax. If you want greater than or equal to, you will have to use the GTE() function. There are two option switches to @switch, /first and /all. In 2.0, which one is the default will depend on the MUSH ("@list options" to see). "@switch/all" performs the actions associated with all matching targets. In other words, if the targets are not mutually exclusive, more than one set of actions may be undertaken. Its 1.50 equivalent is the standard "@switch" command. "@switch/first" matches the first target it can, and executes the statements associated with that. Even if the targets are not mutually exclusive, only the actions associated with the first target matched will be executed. The 1.50 equivalent of this is the "@select" command. ============================= [ Example 4.4: Dog ] [ The dog will respond to simple commands that someone says ] > @create Dog Dog created as object #23084 > @listen dog=*"Dog, *" Set. > @ahear dog=@switch %1=sit,:sits down.,roll over,:rolls over obediently,play dead,:flops onto the ground. Set. > drop dog Dog has left. Dog has arrived. Dropped. > "Dog, sit You say "Dog, sit" Dog sits down. > "Dog, play dead" You say "Dog, play dead" Dog flops onto the ground. > "Dog, roll over You say "Dog, roll over" Dog rolls over obediently. ============================= 4.5 Other ways of triggering It is frequently useful to be able to trigger an object without having to pick it up, drop it, or have it listen for something. Therefore, MUSH provides for "using" objects. The attributes @use, @ouse, and @ause are associated with the "use" command. "use " triggers these three registers (note the absence of the @ sign in triggering). An object can only be used if there is something in the @ause register. The person who uses the object is shown the message in the @use; the other people in the room see the @ouse message. The @ause command list is executed. This, in essence, works just like "get" and "drop" - the command "use" has simply been added. ======================================== [ Example 4.4: Bubbly pie revisited ] [ @using the bubbly pie performs an "eating action" and destroy. ] > @create Bubbly pie Bubbly pie created as object #30216 > @ause pie=@emit %N gobbles down the bubbly pie.;@destroy me Set. > use pie You use Bubbly pie Elsa gobbles down the bubbly pie. You get your 10 Marks deposit back for Bubbly pie. Bubbly pie has left. ======================================== Another way to trigger an object is to set its @startup. The commands in the @startup attribute are executed whenever the MUSH is restarted. This is useful for objects that need to run continuously, such as clocks. Objects with a @startup attribute are automatically given the STARTUP flag, represented by "z". This flag is simply used for internal accounting and does not affect anything else. 4.6 User-defined commands Perhaps one of the most common ways of triggering an object, user-defined commands are the closest things to MUCK @action that MUSH provides. They allow other players to type "command " and have that execute just as if the command was part of the MUSH. Unlike MUCK, however, there are few global user-defined commands. One must be in the same room with, or carrying, the object on which the command is defined. The only exceptions to this are exits/commands defined on the "master room". See the wizard section of this manual for details. These commands may be set on any register or non-standard attribute. The syntax is: @ =$: The command may take arguments by using * or ?, etc., in a format similar to that use by @ahear/@listen. User-defined commands are matched on every object in the room or in your inventory, so you may want to avoid command names that might be extremely common. Commands on the MUSH are parsed in the order: exit names, defined MUSH commands (like @desc, page, etc.), then user-defined commands, then Master Room commands. You should be extremely careful not to define commands on an object like $p *:, since this will be parsed as "page" and it will be ignored by the object. Furthermore, note that many MUSHes have global commands which begin with '+' and mailers which use '-' as an editing indicator; thus, you should avoid starting your own commands with either of those characters. In 2.0, there are config options which determine two things: The first is the ability of an object to trigger its own $commands. The second is the ability to trigger $commands on players. One can, however, always trigger $commands on an object one is carrying or is in the same room. =============================== [ Example 4.6: Tray of Food ] [ This object is a tray of food which you can "eat", "drink" and "discard" ] > @create Tray of Food Tray of Food created as object #482 > @va food=$eat: @emit %N takes a slice of bread off the try and eats it. Set. > @vb food=$drink: @emit %N takes a cup of water off the tray and drinks it. Set. > @vc food=$discard: @emit %N discards %p tray of food;@destroy me Set. > eat Elsa takes a slice of bread off the tray and eats it. > drink Elsa takes a cup of water off the tray and drinks it. > discard Elsa discards her tray of food. You get your 10 Marks deposit back for Tray of Food. Tray of Food has left. ============================== Sometimes it's useful to be able to find out what $commands are triggered in a room. 1.50's @scan command allows you to check for a command match on objects that you control or that are set VISUAL. The syntax of this command is simply "@scan ". It checks for all possible matches on your location, its contents, yourself, your inventory, the zone or parent room of your location, your personal zone, and the master room. It will display the name of any objects which have commands which could match that string, followed by the number of commands matched in brackets. MudCore provides for similar functionality, via its '+scan' command. It checks for matches, starting from a specific object, and lists the attributes and command wildcard patterns which match (if you can examine the object), or the object which matches the commands (if you can't examine it). * * * * * One interesting and quite flexible command is "@verb". This command essentially allows you to define your own @attr/@oattr/@aattr triplets, allowing you to define your own "standard" verbs. This command is most useful for someone who is a wizard. This command is in the format: @verb =, , , , , , Most of those those fields should be self-explanatory; are the values to be passed on the stack, as %0-%9. For example, to simulate "drop" with a command like "put", you would use a user-defined command something like: $put *: @verb [v(0)]=[v(N)],DROP,Dropped.,ODROP,dropped [v(0)].,ADROP Under 2.0, both the victim and actor must be controlled. Under 1.50, either both victim and actor must be controlled, or the thing which triggered the verb must be AND the object which issued the @verb command must be able to read the attributes from . Essentially, though, one needs to be a wizard in order to make this command generally useful. It is, however, a rather nifty thing to play with. 4.7 An introduction to functions Functions are generally used to manipulate strings and other input, or to generate or retrieve something. They are called using: (,,) and evaluation often requires square brackets [ ] to be put around the function. It is imperative that the right number of arguments be passed to the function, and that the parentheses are correctly matched. You should always use %-substitutions instead of functions where possible, i.e., %va instead of v(va). Functions may be nested. Only one pair of square brackets is required around a given function call. Certain functions, such as V() and GET(), have already been introduced. Only a few functions require no arguments; TIME(), which simply returns the current time on the MUSH, is probably the most commonly used of these. All other functions require one or more arguments. The most commonly used, aside from the v, s, and get() functions, is the RAND() function. This generates a random integer between 0 and . There _is_ a limit to the number of arguments a function can take; you can find out what this is by asking a local wizard. This is generally 100. The limit is something to keep in mind if you are doing extremely large calls to a function like SWITCH(), which takes an arbitrary number of arguments. Functions used to access basic db info include NUM(), FLAGS(), OWNER(), LOC(), and MONEY(). These are publicly accessible, and give an object's database reference number, flags, owner, location (for a player), and money (also for a player). These functions will be discussed in more detail later. Other publicly accessible attributes include DESC, and are gotten using the GET() function. All attributes on an object set VISUAL are publicly accessible. Functions used to process lists will be covered later in this manual. The following functions are used for arithmetic: ADD(), SUB(), MUL(), DIV(). Note that SUB() does not exist in many versions of MUSH code; instead, one must add the negative of the second number. Some of these functions, such as SUB(), take ONLY two arguments. Others, like ADD(), can take multiple arguments (just like LISP arithmetic operators). For example, "add(2,3,4)" is equivalent to (and more efficient than) "add(2,add(3,4))". ============================= [ Example 4.7a: Abacus ] [ An object that performs arithmetic ] > @create Abacus Abacus created as object #19831 > @va abacus=$*+*: @emit The sum of %0 and %1 is [add(%0,%1)]. Set. > @vb abacus=$*-*: @emit The difference of %0 and %1 is [sub(%0,%1)]. Set. > @vc abacus=$*x*: @emit The product of %0 and %1 is [mul(%0,%1)]. Set. > @vd abacus=$*/*: @emit The quotient of %0 and %1 is [div(%0,%1)]. Set. > 1+2 The sum of 1 and 2 is 3. > 2x6 The product of 2 and 6 is 12. > 8-5 The difference of 8 and 5 is 3. > 9/3 The quotient of 9 and 3 is 3. ============================== Here's another example, demonstrating the combined use of @switch and RAND(), "use", and various %-substitutions. ====================================== [ Example 4.7b: Plush Shaav Doll ] [ To conserve space, 'Set.' messages after attribute sets have been omitted. ] > @create Life-size Plush Shaav Doll Life-size Plush Shaav Doll created as object #3895 > @desc doll=This is a plush doll nearly six feet in height. It's fuzzy and and cute, featuring the Grand Hierarch Shaav wearing his usual calm expression, although the effect is somewhat spoiled by the fluffy stuffing and bright green-button eyes. The life-sized doll is clothed in the black robes of the Grolims, and would probably seem to radiate evil if it didn't look so snuggly. It's probably made by the same people who made Belzoinks. > @succ doll=You prop up a life-sized plush doll of Shaav. > @osucc doll=grins evilly as %s props up a life-sized plush doll of Shaav. > @drop doll=You drop a life-sized plush doll of Shaav on its head. > @odrop doll=drops a life-sized plush doll of Shaav on its head. > @use doll=You pull a string on the doll's neck. > @ouse doll=pulls on a string on the plush Shaav doll's neck. > @ause doll=@switch rand(4)= 0, {:points a finger at %N and squeaks. "Die!"}, 1, {:screams:%tDeath!%tDestruction!%tChaos!}, 2, {:looks at %N for a moment, then booms to %o, "DOOM."}, 3, {:squeaks. "Mama!%b%bMama!%b%bMama!"} [ If Polgara (a female) types "use doll", she sees "You pull a string on the doll's neck", plus one of the following messages: ] Life-size Plush Shaav Doll points a finger at Polgara and squeaks. "Die!" Life-size Plush Shaav Doll screams: Death! Destruction! Chaos! Life-size Plush Shaav Doll looks at Polgara for a moment, then booms to her, "DOOM." Life-size Plush Shaav Doll squeaks. "Mama! Mama! Mama!" Note the use of "%b" and "%t" substitutions for blank spaces and tabs. Because "%t" inserts a literal tab character, the spacing will vary depending on where tab stops are set by the player's terminal. Also note that the @switch action clauses had to be enclosed in braces, since the statements used inside contained commas. ============================== 4.8 Do it! -- falcon control This section assumes that you have created the falcon as per section 2.9 of this manual. The object you will create in this example will be used to control it. <#FL> below refers to the dbref number of your falcon, and refers to the name of your falcon. The controller will give you the ability to force your falcon remotely to pose and think messages, return to you on command, and go to a player on command, using: ' to think a message, . to pose something, return to recall the falcon, and goto to go to a player's location. Issue the following commands: @create 's controller [ Then lock it, desc it, etc. ] @va controller=$'*: @fo <#FL>=:chirps << %0 >> [ This is used for "speech" ] @vb controller=$.*: @fo <#FL>=:%0 [ This is used for forcing the falcon to pose ] @vc controller=$fly *: @fo <#FL>={:soars into the air and flies off.; %0} [ This is used to have the falcon fly in a given direction ] @vd controller=$return: @fo <#FL>={:returns to %N.; @set me=!puppet; @tel me=owner(me); leave; :soars towards you!; @set me=puppet} [ This brings the falcon back to you, with appropriate messages. The INHERIT flag must be set in order for this to work. ] @ve controller=$goto *: @fo <#FL>={@switch loc(*%0)=#-1,{p =I can't find %0}, {:goes to find %0.; @tel me=loc(*%0); :soars towards you!}} [ This is used to go to the location of a player. It first checks to see if the player can be found - if the player does not exist or the player is set UNFINDABLE, #-1 is returned and the falcon pages the player with the fail message - and then, if the player exists, teleports to that player's location, with appropriate messages. ] INDEX OF SECTION II EXAMPLES: 3.1 Living Room 3.5 Home 4.1 Percent demonstration 4.2a GET_EVAL() vs. U() 4.2b Sentence Reverser 4.3 Explosive 4.4 Dog 4.5 Bubbly pie revisited 4.6 Tray of food 4.7a Abacus 4.7b Plush Shaav Doll 4.8 Falcon control