Help Entries starting with 'S'

• @scan[/<switch>] <command>

@scan gives you a list of all objects containing $commands (user-defined commands) which could match <command>. If given no switches, it checks you, your possessions, your location, objects in your location, the zone/zone master room of your location, your zone, and objects in the master room. It does NOT stop when it gets a match, but rather, finds all possible matches. It also tells how many commands on each object were matched, and what attributes they are in. It does NOT scan objects that you do not control and are not set VISUAL.

  This command can take four switches:
     /room     --   just matches on your location and objects in it.
     /self     --   just matches on you and anything you're carrying.
     /zone     --   just matches on zones of your location and yourself.
     /globals  --   just matches on objects in the master room.

• @search [<player>][<class>=<restriction>][,<begin>,<end>]

This command searches the database and lists objects which meet user specified search criteria. You can limit the scope of the search by specifying <begin> and <end> as the first and last dbrefs to search.

If a <player> argument is supplied, only objects owned by that player will be listed. If a <class> argument is supplied only objects of a certain class will be listed. Possible <class>es include TYPE, NAME, ZONE, PARENT, EXITS, OBJECTS (Or THINGS), ROOMS, PLAYERS, FLAGS, LFLAGS, POWERS, EVAL, EPLAYER, EROOM, EEXIT, and EOBJECT (Or ETHING).

If <class>=TYPE, possible <restriction>s include OBJECT (Or THING), ROOM, EXIT, PLAYER, GARBAGE. This shows all objects of the specified type.

If <class>=NAME, only objects whose name begin with the string <restriction> will be listed. If <class>=ZONE, only objects in the zone <restriction> will be listed. If <class>=PARENT, only children of parent <restriction> will be listed. For ZONE and PARENT, <restriction> must be specified as a dbref number.

'help @search2' for more.

If <class>=EXITS, OBJECTS, ROOMS, or PLAYERS, only objects of that type will be listed.

If <class>=FLAGS or LFLAGS, only objects with the list of flags specified by <restriction> will be listed. For FLAGS, flags to match should be given as a string of single flag letters, with appropriate case. For LFLAGS, flags to match should be given as a space-separated list of flag names.

If <class>=POWERS, only objects with the given power are listed. Only one power may be specified.

If <class>=EVAL, only objects for which <restriction> evaluates to a true boolean value will be listed. The token '##' in <restriction>, which is a function, is replaced by each dbref sequentially. Classes EPLAYER, EROOM, EEXIT, and EOBJECT work like EVAL but are restricted to a single type.

See "help @search3" for more.

If <class>=MINDB, only objects with dbrefs of <restriction> or higher will be listed. If <class>=MAXDB, only objects with dbrefs of <restriction> or lower will be listed.

If <class>=START, then @search will start returning results at the <restriction>th result.

If <class>=COUNT, then @search will only return up to <restriction> results.

For the class TYPE=PLAYER, and for PLAYER=<player-name>, anyone may obtain information on any player. In all other cases, wizards may obtain information about other players, and players who pass a ZMP's zone-lock may obtain information about the ZMP. This is computationally expensive, costing 100 pennies. It is generally faster than @find.

@search flags=Wc      <-- search for connected wizards.
@search type=room     <-- list all rooms owned by me.
@search zone=#50      <-- list all objects belong to zone #50.
@search Joe eval=1,100,200   <-- list objects from #100-#200 owned by Joe.
@search eval=gt(money(##),10)     <-- list all objects owned by me
worth more than 10 coins.

@select <string>=<expr1>,<action1>[,<exprN>,<actionN>]...[,<default>] This is similar to @switch, except it only executes the action associated with the first expression which matches <string> - the targets are mutually exclusive. If no target is matched, the default actions are executed. This is equivalent to "@switch/first".

&FOO thing = $foo *:@select %0=*a*,:acks,*b*,:bars,*c*,:cheeps,:glurps
foo abc
> thing acks
foo xxx
> thing glurps

The string "#$" in <action>'s will be expanded to the evaluated result of <string> before it is acted on.

If the /notify switch is given, a "@notify me" is queued after the selected <action>. This is useful for synchronization with semaphores.

If the /regexp switch is given, the expressions are case-insensitive regular expressions.

@set <object>=[!]<flag> [[!]<flag> ...] @<pre-defined attribute> <object>=<value> @set <object>=<attribute>:<value> @set <object>/<attribute>=[!]<atrflag>

  The first form sets (or unsets) flag(s) on <object>. See 'help flags'.
    Ex: @set me=VISUAL
  Flags may be specified by full name (recommended) or by flag character.
  Flags are set or reset in the order supplied.

  The second form sets a pre-defined attribute on <object>
    Ex: @fail Heavy Box=You can't pick that up.

  The third form sets an arbitrary attribute with <value> on <object>.
  You can also do this with &<attribute> <object>=<value>
    Ex: @set Test Object=random:This is a random attribute.
        &random Test Object=This is a random attribute.
  An important difference between these two forms is that @set will
  evaluate the <value> before setting it on <object>, while the
  &<attribute> form will not (and is usually what you want).

The fourth form sets (or unsets) an attribute flag on the specified attribute. See 'help attribute flags'.

• @sex <player>=<gender>

You can use this command to set yourself or any of your objects to be male, female, neuter, or plural. The SEX attribute is used for pronoun substitution by the MUSH, and anything not recognizable will be treated as neuter.

@sex me = Male @sex me = Female @sex me = Woman @sex me = They @sex me = Plural @sex me = No thank you (silly, but possible)

• @shutdown[/panic][/reboot][/paranoid]

@shutdown shuts down the game. It may only be used by Wizards.

@shutdown/panic performs a panic shutdown of the game, using a seperate database file, not the normal one. It may only be used by God.

@shutdown/reboot restarts the game without disconnecting the users.

If the /paranoid switch is added, the shutdown dump will be a paranoid dump (see @dump).

• @sitelock
• @sitelock/name <name>
• @sitelock <host-pattern>=<options>[,<name>]
• @sitelock[/<ban|register>] <host-pattern>
• @sitelock/check <host>
• @sitelock/remove <string>

The @sitelock command adds rules to the access.cnf file, controlling a host's level of access to the MUSH, or adds banned player names to the names.cnf file. Only Wizards may use @sitelock.

@sitelock without arguments lists all sites in access.cnf. Rules are processed in the order listed, and the first matching rule is applied. @sitelock/check tells you which rule will match for a given <host>.

@sitelock/name adds a name to the list of banned player names. Use !<name> to remove a name from the list.

@sitelock <host-pattern> = <options>[,<name>] controls the access options for hosts which match <host-pattern>, which may include wildcard characters "*" and "?". See help @sitelock2 for the list of options, and help @sitelock3 for an explanation about the name argument.

For backward compatibility, @sitelock/ban is shorthand for setting options "!connect !create !guest", and @sitelock/register is shorthand for options "!create".

  Sitelock allow/deny options:
   connect   --  allow this site to connect to non-guest players
   !connect  --  don't allow this site to connect to non-guest players
   guest     --  allow this site to connect to guest players
   !guest    --  don't allow this site to connect to guest players
   create    --  allow this site to create players
   !create   --  don't allow this site to create players
   default   --  allow any of the above
   none      --  don't allow any of the above
   !god      --  God can't connect from this site.
   !wizard   --  Wizards can't connect from this site.
   !admin    --  Wizards and Royalty can't connect from this site.

Allow/deny options not set are assumed to be allowed.

  Sitelock special options:
   register    -- allow this site to use 'register <name> <email>'
                  at the connection screen to register players.
                  Players will be emailed their character's password.
                  This should be used with !create to be effective.
   suspect     -- set all players who connect from this site SUSPECT.
   deny_silent -- don't log failed access attempts from this site.
   regexp      -- Treat the hostname pattern as a regular expression
                  instead of a wildcard pattern.

If you specify a character name after the options, the options are only checked if the host pattern matches, AND the character being checked for connect support matches the one you gave. Use it only with connect and !connect options, since they're the only ones where an existing character is used.

For example, to disallow anyone from connecting to 'Twink' from one domain, but to allow connections to the character from others, use something like:

@sitelock *.somesite.com=!connect,Twink

If you want to disallow connections to a character from anywhere, use @newpassword or @sitelock *=!connect,Twink.

@sitelock/remove will delete entries that were added with @sitelock if their host-pattern matches <string> exactly.

• @sql <query>

This command issues and SQL query if the MUSH supports SQL and can connect to an SQL server. You must be WIZARD or have the Sql_Ok power to use @sql.

Generally, the sql() function is more useful for coding, as it delimits its return values, but @sql is handy for INSERT-type queries and quick checks. If you pass arbitrary data to @sql, be sure you call sqlescape() on it (see the example in help sql()).

Example: @sql SHOW TABLES

• @squota <victim>[=[+|-]<amount>]

This is a wizard level command that is only available if the quota system is enabled. It reports the victim's owned objects, and sets the maximum number of objects s/he may own to <amount>. If no limit is specified, this shows current quota, and reminds you to set one. Using + or - you can add <amount> to the limit, or subtract it.

• @startup <object>=<actionlist>

Sets the list of actions on <object> that will happen whenever the MUSH is restarted. This lets you start up objects that need to be running continuously. It is also useful for use with @function.

• @stats [<player>]
• @stats/table
• @stats/chunks
• @stats/regions
• @stats/paging

In its first form, display the number of objects in the game broken down by object types. Wizards can supply a player name to count only objects owned by that player.

In its second form, display statistics on internal tables.

In the remaining forms, display statistics or histograms about the chunk (attribute) memory system.

• @success <object>[=<message>].

Sets the message that is shown to someone who successfully passes the basic lock of <object>. For things and players, this means picking them up. For exits, this means going through the exit.

  Ex.: @succ Box=You pick up the box.
       @succ Door=You walk through the door.

• @sweep [connected|here|inventory|exits]

@sweep gives you a list of all nearby objects that are listening, including the room you are in and the objects you are carrying. Most objects only listen for a particular string or phrase, so they normally do not pose a problem if you need privacy. You will have to be careful of players and puppets since they will hear everything you say and do. (And might post the same to r.g.m!) AUDIBLE exits are also shown on an ordinary sweep, if the room is also AUDIBLE. (Audible exits aren't active unless the room is audible).

The four command options can also be used as switches (i.e., you can use "@sweep/connected" instead of "@sweep connected"). If the connected flag is given, only connected players and puppets owned by connected players will be shown in the @sweep. The "here" and "inventory" flags check only your location or inventory, respectively. "exits" only checks for AUDIBLE exits.

  @switch [/<switch>] <string> = <expr1>, <action1> [,<exprN>, 
                                 <actionN>]... [,<default>]
  For those of you familiar with programming, this command acts like
  if/then/else or switch/case. It compares <string> against whatever
  each <expr> evaluates to. If <string> and <expr> match, the action list
  associated with that <expr> is carried out. If no match is found, the
  <default> action list is carried out. 

The string "#$" in <action>'s will be expanded to the evaluated result of <string> before it is acted on.

  @switch/all   will carry out the action lists for -all- of the 
                expressions that match <string>. This is the default.
  @switch/first will carry out the action list for only the -first-
                expression that matches <string>. This is the same as
                @select, and it is less computationally expensive than 
                /all in many cases.
  @switch/notify will cause a "@notify me" to be queued after 
                the selected <action>. 
  @switch/regexp will cause the expressions to be matched as case-insensitive
                 regular expressions.

(continued in help @switch2)

Examples: 
    &SWITCH_EX thing = $foo *:@switch %0=*a*,:acks,*b*,:bars,:glurps
    foo abc
    > thing acks
    > thing bars
    foo xxx
    > thing glurps

    &SWITCH_EX thing = $foo *:@switch/first %0=*a*,:acks,*b*,:bars,:glurps
    foo abc
    > thing acks

    &SWITCH_EX thing = $test:@switch hasflag(%#,PUPPET)=1,"Puppet!,"Not Puppet!
    test
    > thing says, "Not Puppet!"

• s(string)

This function performs evaluation on a string and returns that string. It should be considered extremely dangerous to use on a string that you don't have complete control over (i.e., on user input). As usual, %n is the name, %s the subjective pronoun, %o the objective, and %p the possessive. Functions are evaluated. It is important to note that the pronoun is that of the triggering object.

So, if the ve of an object were: "[s(This is %n)], and I were to type @trigger <object>/ve, it would return "This is <myname>", but if vf were @trigger me/ve, then triggering the vf makes the ve return "This is <object>"

Flag: SAFE (all types)

The SAFE flag protects objects from destruction. If the REALLY_SAFE option was set when the MUSH was compiled (see @config), the only way to destroy an object set SAFE is to explicitly reset the SAFE flag and then @dest it. If the REALLY_SAFE option is not set, @destroy/override (or @nuke) will override the SAFE flag and destroy the object.

• scan(<object>, <command>)
• scan(<command>)

This function works like @scan, and returns a space-separated list of dbref/attribute pairs containing $commands that would be triggered if <command> were run by <object>. You must control <object> or be See_All to use this function.

If no <object> is specified, this function works like @scan run by the function's executor.

• score

Displays how many pennies you are carrying. Helpful to see if any machines are looping. If they are, your pennies will be being rapidly drained. MUSH money may also be used for other purposes in the game.

• scramble(<string>)

This function scrambles a string, returning a random permutation of its characters. For example, "[scramble(abcdef)]" might return "cfaedb". Note that this function does not pay any attention to spaces or other special characters; it will scramble these characters just like normal characters.

• secs()

This function takes no arguments, and returns the number of elapsed seconds since midnight, January 1, 1970 UTC. UTC is the base time zone, formerly GMT. This is a good way of synchronizing things that must run at a certain time.

• secure(<string>)

This function returns <string> with all "dangerous" characters replaced by spaces. Dangerous characters are ( ) [ ] { } $ % , ^ and ; This can make output slightly ugly, but it's a good way of preventing other people from doing nasty things with your objects.

The most complicated thing about semaphores is their name. Before you try to use semaphores, you should first be familiar with the "@wait" command. If you are, then you know that normally, you type:

    @wait <number of seconds>=<action> 

and the action takes place after that number of seconds has passed. With a semaphore, you instead type:

    @wait <object>=<action>
    @wait <object>/<number of seconds before timeout>=<action>

and the action takes place after the object has been "notified" that its time for it to happen. You can also set a timeout -- if the object hasn't been notified by the time that number of seconds has passed, the action will take place. Any object (player, thing, exit, room) that you control or that is set LINK_OK can be used to wait actions on.

(continued in help semaphores2)

An object is notified using the "@notify" command. When you type "@wait <object>=<action>", you are adding one to the SEMAPHORE attribute on the object. When you type "@notify <object>", you are decreasing the SEMAPHORE attribute on the object by one. Whenever the attribute decreases, one of the actions waiting on the object takes place. The actions occur in the order they were added.

You can make the semaphore attribute of an object negative by @notify-ing it more times than things have been @wait-ed on it. If you do so, anything @wait-ed on the object will add one to the SEMAPHORE attribute and the action will take place immediately. You can also make all the actions waiting on an object take place right away by using "@notify/all", or wipe all the commands out and clear the SEMAPHORE attribute by using "@drain". Please note that all SEMAPHORE attributes are cleared out whenever the MUSH is restarted.

Semaphores can be used to make sure that events occur in the right order, or to make sure that two players can't use the same object at the same time.

(continued in help semaphores3)

It's important to remember that the actions will be carried out NOT by the object that they are being @waited on, but by whichever object entered the @wait.

Examples:

> @wait semaphore=:tests.
> @notify semaphore
Wizard tests.

> @wait timer/30=:waits 30 seconds.
[ 30 seconds passes. ]
Wizard waits 30 seconds.

See also: @wait, @drain, @notify (continued in help semaphores4)

Semaphores can be used to enforce mutual exclusion - to prevent the same object from being used simultaneously by two players. The basic strategy is to ensure that the object always has a SEMAPHORE of -1, to enclose commands in an @wait, and to conclude the set of commands with an @notify me:

> &doit obj = $doit: @wait me={&doer me = %N; @tr me/report}
> &report obj = "[v(doer)] did it!; @notify me
> @startup obj = @drain me; @notify me
> @notify obj
> ex obj/SEMAPHORE
SEMAPHORE [#1ic+]: -1
> doit
obj says "Talek did it!
> ex obj/SEMAPHORE
SEMAPHORE [#1ic+]: -1

If a second player types doit as well, the second player's command is put on the semaphore queue and not run until the @notify me at the end of the REPORT attribute. Note the STARTUP attribute - because semaphores are cleared when the MUSH starts up, you must insure that the object gets @notify'd once when it starts up. (Continued in help semaphores5)

Normally, semaphores use the SEMAPHORE attribute. However, other attributes can be used, as long as they follow a few simple rules: If the attribute is already set, it has to have the same owner (God) and flags as the SEMAPHORE attribute would (typically no_inherit, no_clone, and locked - see 'help @set' and '@atrlock'), and have a numeric or empty value. If it's not set, it can't be one of the built in attributes (See @list attribs) unless, naturally, it is SEMAPHORE.

See the help on @wait, @notify and @drain for details, but, briefly, you can use named semaphores with <object>/<attribute> where you would normally just use <object> in those commands. This means you can't have a un-timed semaphore on an attribute with a numeric name.

(Continued in help semaphores6)

An example:

> @wait me/semtest=think blah
> ex me/semtest
SEMTEST [#1ic+]: 1
> @ps
...
Semaphore Queue:
[#8/SEMTEST]Raevnos(#8P):think blah
...
> @notify me/semtest
Notified.
blah

This allows you to use one object to control many different things -- for example, fights in a turn-based combat sytem.

• sent(<player|descriptor>)

Returns the number of characters sent by a player during this connection as indicated by SESSION.

The caller can use the function on himself, but using on any other player requires privileged power such as Wizard, Royalty or SEE_ALL.

• SESSION

This admin-only form of WHO includes information on how much text has been received and sent to the connections. It has three fields:

Sent, which is the number of characters sent TO the mush from that connection. Recv, the number of characters sent FROM the mush to that connection, and Pend, the number of characters still waiting to be sent from the mush to the connection.

• set(<object>, <flag>)
• set(<object>/<attribute>, <attribute flag>)
• set(<object>, <attribute>:<value>)

This function is equivalent to @set, and can be used to switch flags, set attributes, and many other things. The two arguments to the function are the same as the arguments that would appear on either side of the '=' in @set. This function returns nothing.

The attribute setting ability of set() is deprecated. You should use attrib_set() instead; it's easier to read, and allows you to clear attributes, too.

• setdiff(<list1>, <list2>[,<delimiter>[, <sort type>[, <osep>]]])

This function returns the difference of two sets -- i.e., the elements in <list1> that aren't in <list2>. The list that is returned is sorted. Normally, alphabetic sorting is done. You can change this with the fourth argument, which is a sort type as defined in "help sorting". If used with exactly four arguments where the fourth is not a sort type, it's treated instead as the output separator.

> say setdiff(foo baz gleep bar, bar moof gleep)
You say, "baz foo"

• setinter(<list1>, <list2>[,<delimiter>[, <sort type>[,<osep>]]])

This function returns the intersection of two sets -- i.e., the elements that are in both <list1> and <list2>. The list that is returned is sorted. Normally, alphabetic sorting is done. You can change this with the fourth argument, which is a sort type as defined in "help sorting". If used with exactly four arguments where the fourth is not a sort type, it's treated instead as the output separator.

> say setinter(foo baz gleep bar, bar moof gleep)
You say, "bar gleep"

• setq(<register>, <string>[, ... ,<regN>, <stringN>])
• setr(<register>, <string>[, ... ,<regN>, <stringN>])

The setq() and setr() functions are used to copy strings into local registers. setq() returns a null string; it is a purely "side effect" function. setr() returns the value stored. Multiple registers can be assigned with a single setq() or setr(), with additional pairs of registers and values in the function's arguments. In this case, setr() returns the value stored in the first register listed. All arguments are evaluated before any registers are set; if you want to use the result of setting one register in setting another, use multiple setq()s.

There are thirty-six local registers, numbered 0 through 9 and A through Z. They are cleared at the start of each new queue cycle (i.e. whenever a new command is evaluated). They are most useful for storing complex function evaluations which are used repeatedly within a single command.

Registers set via setq() or setr() can be accessed via the r() function, or via the %qN percent-substitution.

See 'SETQ2' for examples of its use.

The setq() function is probably best used at the start of the string being manipulated, such as in the following example:

    &TEST object=[strlen(%0)]
    &CMD object=$test *:"[setq(0,u(TEST,%0))]Test. %0 has length %q0.
    test Foo
    > Object says, "Test. Foo has length 3."

In this case, it is a waste to use setq(), since we only use the function result once, but if TEST was a complex function being used multiple times within the same command, it would be much more efficient to use the local register, since TEST would then only be evaluated once. setq() can thus be used to improve the readability of MUSH code, as well as to cut down the amount of time needed to do complex evaluations.

Swapping the contents of registers can be done without writing to temporary registers by setting both registers at once, so the code:

    think setq(0,foo,1,bar)%q0%q1 - [setq(0,%q1,1,%q0)]%q0%q1

yields "foobar - barfoo".

See 'SETQ3' for scoping rules of setq().

The registers set by setq() can be used in later commands in the same thread. That is, the registers are set to null on all $-commands, ^-commands, A-attribute triggers, etc., but are then retained from that point forward through the execution of all your code. Code branches like @wait and @switch retain the register values from the time of the branch, so the code:

say setr(a,foo); @wait 0=say %qa; say setr(a,bar)

produces the following when executed by an object:

Object says "foo" Object says "bar" Object says "foo"

Standard attributes are set using @<attrib> <obj>=<value> Nonstandard attributes are set using &<attrib> <obj>=<value> Attributes may also be set using @set <obj>=<attrib>:<value> or the attrib_set() or set() functions.

Attributes are cleared using @<attrib> <obj> or &<attrib> <obj> or with @wipe or wipe().

  Note that if the empty_attrs configuration option is set 
  (@config empty_attrs to check), there is a difference between 
  clearing an attribute and setting an attribute to a null value:
    @va me       <--- wipes out my VA attribute
    @va me=      <--- sets my VA attribute to be empty

Empty attributes retain their flags and atrlock status. Wiped attributes are gone forever.

See also: ATTRIBUTES, NON-STANDARD ATTRIBUTES, @set, @wipe, attrib_set(), set(), wipe()

• setunion(<list1>, <list2>[,<delimiter>[, <sort type>[, <osep>]]])

This function returns the union of two sets -- i.e., all the elements of both <list1> and <list2>, minus any duplicate elements. Think of it as CAT() without words duplicated. The list returned is sorted. Normally, alphabetic sorting is done. You can change this with the fourth argument, which is a sort type as defined in "help sorting". If used with exactly four arguments where the fourth is not a sort type, it's treated instead as the output separator.

> say setunion(foo baz gleep bar, bar moof gleep)
You say, "bar baz foo gleep moof"
> say setunion(1.1 1.0, 1.000)
You say, "1.0 1.000 1.1"
> say setunion(1.1 1.0, 1.000, %b, f)
You say, "1.0 1.1"

• sha0(<string>)

Returns the SHA cryptographic hash of the string. See RFC 3174 for more information.

  Flag:  SHARED   (players) 

The SHARED flag is used to designate a player as a Zone Master. Objects owned by a Zone Master are controlled by anyone who passes the player's zone lock.

Some suggested uses of shared players:

    1. If you are working on a building project with several people, it
       may be useful to create a shared player and @lock/zone it to all of
       you.  That way, all of the players working on the project will be
       able to modify the building, as long as the shared player owns all
       the objects being built.

    2. If local wizards are desired, a shared player may be created and zone
       locked to the local wizards. Players building within that zone should
       be @chowning to the shared player, or logged in as it while creating
       objects. The local wizard will then be able to control anything within
       that domain as long as the object in question is owned by the shared
       player.

• shl(<number>, <count>)

Performs a leftwards bit-shift on <number>, shifting it <count> times. This is equivalent to mul(<number>,power(2,<count>), but much faster.

• shr(<number>, <count>)

Performs a rightwards bit-shift on <number>, shifting it <count> times. This is equivalent to div(<number>,power(2,<count>), but much faster.

• shuffle(<list>[,<delimiter>[, <osep>]])

This function shuffles the order of the items of a list, returning a random permutation of its elements. "[shuffle(foo bar baz gleep)]" might evaluate to "baz foo gleep bar".

• sign(<number>)

Essentially returns the sign of a number -- 0 if the number is 0, 1 if the number is positive, and -1 if the number is negative. Thus, SIGN(-4) is -1, SIGN(2) is 1, and SIGN(0) is 0.

• sin(<angle>[,<angle type>)

Returns the sine of <angle>, which should be expressed in the given angle type, or radians by default.

See 'HELP CTU()' for more on the angle type.

• slay <player/thing>

This is a Wizard-only command that kills objects without paying any insurance to the victims. It is used in places where 'suicide' should not pay.

(Su-ic-ide is pain-less... {MASH theme})

These commands can only be entered by a connected player through their client. They generally do things that only affect a specific connection and would be meaningless if run by an object or disconnected player.

  DOING	    IDLE      LOGOUT     OUTPUTPREFIX OUTPUTSUFFIX QUIT
  SESSION   WHO

In addition, the following commands can only be used at the login screen:

cd ch connect create

• sort(<word1> [... <wordN>][, <sort type>[,<delimiter>[, <osep>]]])

This sorts a list of words. If no second argument is given, it will try to detect the type of sort it should do. If all the words are numbers, it will sort them in order of smallest to largest. If all the words are dbrefs, it will sort them in order of smallest to largest. Otherwise, it will perform a lexicographic sort.

The second argument is a sort type. See 'help sorting'.

The optional third argument gives the list's delimiter character. If not present, <delimiter> defaults to a space. The optional fourth argument gives a string that will delimit the resulting list; it defaults to <delimiter>.

• sortby([<obj>/]<attrib>, <list>[,<delimiter>[, <output separator>]])

This sorts an arbitrary list according to the u-function <obj>/<attrib>. This u-function should compare two arbitrary elements, %0 and %1, and return zero (equal), a negative integer (element 1 is less than element 2) or a positive integer (element 1 is greater than element 2).

  A simple example, which imitates a normal alphabetic sort:
    > &ALPHASORT test=[comp(%0,%1)]
    > say [sortby(test/ALPHASORT,foo bar baz)]
    You say, "bar baz foo"

  A slightly more complicated sort. #1 is "God", #2 is "Amby", "#3" is "Bob":
    > &NAMESORT me=[comp(name(%0),name(%1))]
    > say [sortby(NAMESORT,#1 #2 #3)]
    You say, "#2 #3 #1"

Warning: the function invocation limit applies to this function. If this limit is exceeded, the function will fail _silently_. List and function sizes should be kept reasonable.

In functions where you can specify a sorting method, you can provide one of these sort types:

  Type    Sorts:
   a       Sorts lexicographically (Maybe case-sensitive).
   i       Sorts lexicographically (Always case-insensitive).
   d       Sorts dbrefs.
   n       Sorts integer numbers.
   f       Sorts decimal numbers.
   name    Sorts dbrefs by their names. (Maybe case-sensitive)
   namei   Sorts dbrefs by their names. (Always case-insensitive)
   conn    Sorts dbrefs by their connection time.
   idle    Sorts dbrefs by their idle time.
   owner   Sorts dbrefs by their owner dbrefs.
   loc     Sorts dbrefs by their location dbref.
   ctime   Sorts dbrefs by their creation time.

The special sort key attr:<aname> or attri:<aname> will sort dbrefs according to their <aname> attributes. For example: Separating by &factions or &species attrs. attr is probably case-sensitive, and attri is case-insensitive.

Whether or not the 'a' sort type is case-sensitive or not depends on the particular mush and its environment.

• sortkey([<obj>/]<attrib>, <list>[, <sort type>[,<delimiter>[, <osep>]]])

This function creates a list of keys by passing every element of <list> into the u-function given in <attrib>. The list is then sorted according to the sorting method in <sort type>, or is automatically guessed. (As per 'help sorting')

  This is equivalent to:
    > &munge_sort me=sort(%0,<sort type>)
    > munge(munge_sort,map(<attrib>,<list>),<list>)

    Only there is no risk with delimiters ocurring within the list.

  A simple example, which sorts players by their names:
    > @@ #1 is "God", #2 is "Amby", "#3" is "Bob"
    > &KEY_NAME me=name(%0)
    > say sortkey(key_name,#1 #2 #3)
    You say, "#2 #3 #1"

• soundex(<word>)

The soundex function returns the soundex pattern for a word. A soundex pattern represents the sound of the word, and similar sounding words should have the same soundex pattern. Soundex patterns consist of an uppercase letter and 3 digits.

> think soundex(foobar)
F160

For details of how the algorithm works, see 'help soundex2'.

  Here's how the soundex algorithm works:
  1. The first letter of the soundex code is the first letter of
     the word (exception: words starting with PH get a soundex
     starting with F)
  2. Each remaining letter is converted to a number:
      vowels, h, w, y ---------> 0
      b, p, f, v --------------> 1
      c, g, j, k, q, s, x, z --> 2
      d, t --------------------> 3
      l -----------------------> 4
      m, n --------------------> 5
      r -----------------------> 6
     At this stage, "foobar" is "F00106" 
  3. Strings of the same number are condensed. "F0106"
  4. All 0's are removed, because vowels are much less important
     than consonants in distinguishing words. "F16"
  5. The string is padded with 0's or truncated to 4 characters. "F160"
  That's it. It's not foolproof (enough = "E520", enuf = "E510") but
  it works pretty well. :)

• soundslike(<word>, <word>)
• soundlike(<word>, <word>)

The soundslike function returns 1 if the two words have the same soundex code (see 'help soundex()' for information), which means, in general, if they sound alike. For example:

> think soundslike(robin,robbyn)
1
> think soundslike(robin,roebuck)
0

• space(<number>)

  Prints <number> number of spaces. Useful for times when you want to
  be able to use lots of spaces to separate things. For example,
  "a[space(5)]b  would print, "Amberyl says, "a     b"".

  speak(<speaker>, <string>[, <say string>
                  [, [<transform obj>/]<transform attr>
                  [, [<isnull obj>/]<isnull attr>[, <open>[, <close>]]]]])

This function is used to format speech-like constructs, and is capable of transforming text within a speech string; it is useful for implementing "language code" and the like.

If <speaker> begins with &, the rest of the <speaker> string is treated as the speaker's name, so you can use it for NPCs or tacking on titles (such as with @chatformat).

When only <speaker> and <string> are given, this function formats <string> as if it were speech from <speaker>, as follows.

  If <string> is...  the resulting string is...
  :<pose>            <speaker's name> <pose>
  : <pose>           <speaker's name><pose>
  ;<pose>            <speaker's name><pose>
  |<emit>            <emit>
  "<speech>          <speaker's name> says, "<speech>"
  <speech>           <speaker's name> says, "<speech>"

If <say string> is specified, it is used instead of "says," / "says".

Continued in 'help Speak2'.

Examples:

> say [name(me)]
You say, "Wizard"
> @emit [speak(me, :tests.)]
Wizard tests.
> @emit [speak(me, : 's testing.)]
Wizard's testing.
> @emit [speak(me, ;'s testing.)]
Wizard's testing.
> @emit [speak(me, |Test.)]
Test.
> @emit [speak(me, "Test.)]
Wizard says, "Test."
> @emit [speak(me, Test.)]
Wizard says, "Test."
> @emit [speak(me, Test., yells:)]
Wizard yells: "Test."
> @emit [speak(&Fido the Wonder Dog,:woofs!)]
Fido the Wonder Dog woofs!
> @emit [speak(&Mr. President,:has been misunderestimated.)]
Mr. President has been misunderestimated.

Continued in 'help Speak3'.

If <transform> is specified (an object/attribute pair or attribute, as with map() and similar functions), the speech portions of <string> are passed through the transformation function.

Speech is delimited by double-quotes (i.e., "text"), or by the specified <open> and <close> strings. For instance, if you wanted <<text>> to denote text to be transformed, you would specify <open> as << and close as >> in the function call. Only the portions of the string between those delimiters are transformed. If <close> is not specified, it defaults to <open>.

The transformation function receives the speech text as %0, the dbref of <speaker> as %1, and the speech fragment number as %2. For non-say input strings (i.e., for an original <string> beginning with the :, ;, or | tokens), fragments are numbered starting with 1; otherwise, fragments are numbered starting with 0. (A fragment is a chunk of speech text within the overall original input string.)

Continued in 'help Speak4'.

Examples:

> @va me = "Fragment %2 is: %0"
> @emit speak(me, test, ,va)
Wizard says, "Fragment 0 is: test"
> @emit speak(me, "test, ,va)
Wizard says, "Fragment 0 is: test"
> @emit speak(me, "test, yells:, va)
Wizard yells: "Fragment 0 is: test"
> @emit speak(me, :tests. "Hi.", ,va)
Wizard tests. "Fragment 1 is: Hi."
> @emit speak(me, : 's testing. "Hi.", ,va)
Wizard's testing. "Fragment 1 is: Hi."
> @emit speak(me, ;'s testing. "Hi.", ,va)
Wizard's testing. "Fragment 1 is: Hi."
> @emit speak(me, |This is a test. "Hi.", ,va)
This is a test. "Fragment 1 is: Hi."
> @emit speak(me, :tests. "Hi." And... "Bye." The end., ,va)
Wizard tests. "Fragment 1 is: Hi." And... "Fragment 2 is: Bye." The end.
> @emit speak(me, :tests. "Hi." And... <<Bye.>> The end., ,va, , <<, >>)
Wizard tests. "Hi." And... "Fragment 1 is: Bye." The end.

Continued in 'help Speak5'.

If the result of transforming a given speech fragment is a null string, and <isnull> is specified (an object/attribute pair or attribute), that function is used evaluate an alternative result, with %0 as the dbref of <speaker>, and %1 as the speech fragment number.

The <isnull> functionality can be useful for gracefully handling cases where speech may be processed down to nothing, such as with language code where no words are successfully translated.

Consider this example, where the speech string may be randomly removed:

> &MUTTER_FN me = [ifelse(rand(2),"%0",)]
> &NONE_FN me = [capstr(subj(%0))] mutters something.
> @emit speak(me, :tests. "Hello there.", mutters:, MUTTER_FN, NONE_FN)
Wizard tests. "Hello there."
OR
Wizard tests. He mutters something.

Continued in 'help Speak6'.

Elegantly handling an empty string when the type of speech is a plain say is a bit more difficult. In order to facilitate this, when the speech type is a plain say, the '<speaker> says,' is only prepended to the output if the transformation of the first speech fragment produces something non-null. Also note that quotes are not placed around such speech automatically, to allow the user's code to insert whatever is appropriate.

Below is a more elegant version of the mutter example. Here, we find the use for say-speech fragments being numbered starting from 0 rather than 1 -- if the speech fragment number is 0, we know we haven't given any output yet.

> &MUTTER_FN me = [ifelse(rand(2),"%0",)]
> &NONE_FN me = [switch(%1,0,name(%0),capstr(subj(%0)))] mutters something.
> @emit speak(me, Hello there., mutters:, MUTTER_FN, NONE_FN)
Wizard mutters: "Hello there."
OR
Wizard mutters something.

Continued in 'help Speak7'.

Here's another example, where words between + signs are reversed, but those within double-quotes are untouched (demonstrating a technique useful in something where you want to allow users to mix ordinary speech with transformed speech).

> &REV_FN me = [switch(%2,0,backwards,[capstr(subj(%1))] says backwards)],
"[revwords(%0)]"
> @emit speak(me,:tests. "Normal speech." +Mixed up speech+ Success!, ,
REV_FN, ,+)
Wizard tests. "Normal speech." He says backwards, "speech up Mixed" Success!

• spellnum(<number>)

Given a number, return its written-out representation in words.

• splice(<list1>, <list2>, <word>[,<delimiter>])

This function splices <list1> and <list2> together. <list1> and <list2> are space-separated lists of words

If a word in <list1> is the same as <word>, it is replaced by the word in the corresponding position in <list2>. Both lists must have the same number of words.

> say [splice(foo bar baz,eek moof gleep,bar)]
You say, "foo moof baz"

Spoofing is the act of making other characters think that a person said or did something that they did not. This is very easy to accomplish, and has some good effects, which is why it is allowed. However, abusing it is very twinkish and will most likely get you in hot water with your wizards. Note that if you are being spoofed and want to know who is doing it, you can set yourself NOSPOOF and you will be notified who is making the @emits.

These functions perform queries or other operations on an SQL database to which the MUSH is connected, if SQL support is available and enabled.

  sql()         sqlescape()   mapsql()

• sql(<query string>[,<row delimiter>[,<field delimiter>]])

Performs an SQL query if the MUSH is configured to connect to an SQL database server. This function requires a WIZARD flag or the Sql_Ok power.

By default, SELECT queries will return their data space-separated. Usually, it's more useful to specify a character to delimit rows returned (and sometimes another character to delimit the fields/columns returned, if they may contain spaces).

<query string> is evaluated, so it's useful to either read it from another attribute with u() or use lit() to protect commas. If you will be interpolating user-provided values into the query, be careful to escape them with sqlescape(), like this:

     &SEL_GETID obj = SELECT id FROM mytable WHERE name = '[sqlescape(%0)]'
     &DOIT obj = $do *: ... [setq(0,sql(u(SEL_GETID,%0),~,|))] ...

A query that doesn't return any rows, such as a UPDATE or SELECT that has no matches will return a null string.

• sqlescape(<string>)

This function performs SQL-server-implemented escaping of strings. It's important to escape arbitrary data before passing it to the sql() function or @sql command to prevent SQL injection attacks.

If using a Sqlite3 database, the game must also have MySQL support compiled into the mush to use this function, since Sqlite3 does not provide a way to do this.

> think sqlescape(You don't say)
You don\'t say

When used in an SQL query, the results of an sqlescape() function should be enclosed in single quotes.

You must be a WIZARD or have the Sql_Ok power to use this function.

• sqrt(<number>)

Returns the square root of <number>. <number> cannot be negative.

• squish(<string>[,<character>])

This function removes the leading and trailing <character>s from a string, and condenses all inter-word <character>s to a single <character>. If no character is given, uses space.

Examples:

> say [squish(  foo bar  baz blech   eek )]
You say, "foo bar baz blech eek"
> say [squish(||a|| b|c|d, |)]
You say, a| b|c|d

• ssl(<player|descriptor>)

This function returns 1 if the player is using an SSL connection, and 0 otherwise. If SSL is disabled, it always returns 0. Players can check the SSL status of their own connection. The See_All power is required to check other connections.

For those unfamiliar with the term stack, it refers to a programming data structure that follows a LIFO (Last-In-First-Out) principle. The stack in MUSH holds the ten REGISTERS, which can be accessed via the V-function (v(0) through v(9)) or via %-substitution (%0 through %9).

• starttime()

Returns a string containing the time the MUSH first started up (not including @shutdown/reboots). The time is in the same format that the TIME() function returns.

> say starttime()
You say "Sat Dec  7 00:09:13 1991

• stddev(<number>[, ... , <numberN>])

Returns the sample standard deviation of its arguments.

• step([<obj>/]<attr>, <list>, <step>[,<delim>, <outsep>])

This function is similar to map(), except you can pass up to 10 elements of the list at a time, in %0 to %9. <step> must be between 1 and 10, with a step of 1 equivalent to map(). If the elements of the list can't be split up evenly, the last evaluation pads the missing values with empty values. If no output separator is given, the delimiter (Default is a space) is used.

Continued in step2

Flag: STICKY (all types)

If a thing or player is STICKY, it goes home when dropped (See HOMES). It also goes home when an object carrying it teleports or goes home, unless the object controls it. If a room is STICKY, its drop-to is delayed until the last person leaves (See DROP-TOs). This flag is meaningless for exits.

• strcat(<string1>[, ... , <stringN>])

Concatenates strings together, with no space between them. For example, strcat(foo bar,baz blech) will return the string "foo barbaz blech".

String functions take at least one string and return a transformed string, parts of a string, or a value related to the string(s).

  accent()      after()       align()       alphamin()    alphamax()
  art()         before()      brackets()    capstr()      case()
  caseall()     cat()         center()      comp()        chr()
  decompose()   decrypt()     delete()      digest()      edit()
  encrypt()     escape()      if()          ifelse()      foreach()
  lcstr()       left()        lit()         ljust()       merge()
  mid()         ord()         ordinal()     pos()         regedit()
  lpos()        regmatch()    repeat()      reverse()     right()
  rjust()       scramble()    secure()      sha0()        space()
  spellnum()    squish()      strcat()      strinsert()   stripaccents()
  stripansi()   strlen()      strmatch()    strreplace()  switch()
  trim()        ucstr()       wrap()

A string is simply a bunch of characters. A word is a string that begins and ends with the space character. A sentence is a string made up of smaller substrings that are words. Please note that a "word" or "sentence" in this technical sense does not have to make sense in English (or in any other language, for that matter). As far as mush functions and commands are concerned, this is a perfectly good sentence:

        Foozle 09blert bar baz foo.

• stringsecs(<timestring>)

The stringsecs() function takes a string of the form produced by timestring() and converts it back into seconds.

> say [stringsecs(5m 1s)]
You say, "301"

• strinsert(<string>, <position>, <insert>)

This function returns <string>, with <insert> added before <position> in <string>. Note that the first character in a string is numbered 0, not 1.

> think strinsert(barbaz, 0, foo)
foobarbaz
> think strinsert(Myname, 2, %b)
My name

• stripaccents(<string>)

Returns the string with accented characters converted to non-accented. As with the accent() function, this assumes the ISO 8859-1 character set.

• stripansi(<string>)

Returns the string with all ansi and HTML codes removed.

• strlen(<string>)

Returns the length of the string (The number of characters in it).

• strmatch(<string>, <pattern>[, <register list>])

This function is matches <pattern> against the entire <string>. It returns 1 if it matches and 0 if it doesn't. It is not case-sensitive, and <pattern> may contain wildcards.

If <register list> is given, there is a side-effect: Wildcards and patterns are stored in q-registers, in the order they are given. <register list> must be a space-separated list of digits or letters.

  strmatch(Foo bar baz,*Baz) will return 1.
  strmatch(Foo bar baz,*Foo) will return 0.
  strmatch(Foo bar baz,*o*a*) will return 1.
  strmatch(foo:bar,*:*,0 1) will return 1, and %q0 will be 'foo',
                            %q1 will be 'bar'

• strreplace(<string>, <start>, <length>, <text>)

Returns string with the <length> characters starting at <start> replaced by <text>. As with other string functions, the first character is at position 0.

> think strreplace(Fix teh typo, 4, 3, the)
Fix the typo

• sub(<num>, <num>)

Sub() subtracts the second number from the first.

• subj(<object>)

Returns the subjective pronoun - he/she/it - for an object.

  If the ENACTOR's gender is set, you can use these substitutions to get the
  right pronoun for him/her:
     %s = subjective pronoun: he, she, it, they
     %o = objective pronoun: him, her, it, them
     %p = possessive pronoun: his, her, its, their
     %a = absolute possessive: his, hers, its, theirs.

    Case makes a difference: %S will return He, She, It, They. If you need
    an actual % symbol, use %% to get it.

  Some attributes can be retrieved via substitutions:
     %va-%vz = the contents of the object's VA-VZ attributes, respectively
     %wa-%wz, %xa-%xz = as above, for WA-WZ and XA-XZ

(continued in help substitutions3)

  Other substitutions:
     %0-%9   = the contents of the REGISTERS 0-9, respectively
     %@ = the caller's dbref number. Initially same as %#, changes when 
          something like a U-FUNCTION is called.
     %! = the dbref number of the object the command is on.
     %L = the dbref of the ENACTOR's location.
     %c = text of the last command, _before_ evaluation.
     %u = text of the last $command, after evaluation, available to locks.
     %? = The current function invocation and depth counts.
     %+ = The number of arguments passed to the current ufun.
    %qN = the equivalent of r(N), a register set by a setq() function.

(continued in help substitutions4)

Example:

@sex me=male @drop box=%N just dropped %p box. drop box > Cyclonus just dropped his box.

Let's say that Cyclonus's dbref number is #10 and the box's dbref number is #11. The dbref # of the room Cyclonus is standing in is #13. When Cyclonus dropped the box above, these were the values of the following %-variables:

%N = Cyclonus %# = #10 %@ = #10 %! = #11 %L = #13

A "success" normally occurs when you attempt to do something that is restricted by an @lock and you pass the @lock. (Note that if no lock is set, you automatically pass it.) For example, the "basic" lock restricts who can pick up a player/thing or who can go through an exit. Whenever you successfully do either of these things, you will set off the basic success messages on the object whose lock you have just successfully passed.

Many other actions can also be locked -- see @lock and locktypes for more information. Many of these actions have standard attributes that you can set messages in for when someone succeeds.

Flag: SUSPECT (all types)

This flag is only settable by wizards. Players with this flag have their connects, disconnects, name changes, and kills reported to all connected wizards. Actions by any object with this flag are also logged to the MUSH log files.

@switch, @select, switch() and switchall() normally do wildcard matching between their first argument and the <expr>ession arguments, with the normal * and ? special characters. However, if one of the <expr>essions starts with < or >, a less than or greater than check is done instead of wildcard matching for that pair.

switch(X, >Y, A, B) returns A if X is greater than Y, and B if X is less than or equal to Y.

switch(X, <Y, A, B) returns A if X is less than Y, and B if X is greater than or equal to Y.

If X and Y are numbers, the test is like using gt() or lt(). gte() and lte() can be simulated by using Y'=Y-1 and Y'=Y+1.

If X and Y are non-numeric strings, the result of comp(X,Y) is used to determine which string is alphabetically before (Less than) the other.

If you need to have a leading < or > that's treated like a normal character in a wildcard match, use \\< or \\> (The \\ will turn into \ when the argument is evaluated, and then that single \ will stop the greater/less than check).

• switch(<string>, <expr1>, <list1>[, ... , <exprN>, <listN>] [, <default>])
• switchall(<string>, <expr1>, <list1>[, ... , <exprN>, <listN>][, <default>])
• case(<string>, <expr1>, <list1>[, ... , <exprN>, <listN>] [, <default>])
• caseall(<string>, <expr1>, <list1>[, ... , <exprN>, <listN>] [, <default>])

These functions match <string> against the <expr>essions, returning the corresponding <list>. If nothing is matched, the <default> is returned. Only the first matching expression counts (like @switch/first), and <list>s that are not returned are not evaluated.

Wildcard patterns are allowed in switch() and switchall(). case() and caseall() do a case-sensitive exact match, like member() or comp().

If the string "#$" appears in the <list> to be evaluated, it will be replaced with the evaluated value of <string> /before/ evaluation of <list>. This is not done in case() and caseall(), for TinyMUSH 3 compatibility.

switchall() and caseall() will return all the <lists> with matching <expr>ssions, without spaces between them, so they match similarly to @switch, while switch() and case() match more like @switch/first.

See 'HELP SWITCH WILDCARDS' for more, and see 'HELP SWITCH2' for examples.

  Examples of switch() and related functions:
    > say switch(test, *a*, foo, *b*, bar, *t*, neat, baz)
    You say, "neat"
    > say switchall(ack, *a*, foo, *b*, bar, *c*, neat, baz)
    You say, "fooneat"
    > say switch(moof, *a*, foo, *b*, bar, *t*, neat, baz)
    You say, "baz"
    > say switch(moof, *a*, foo, *b*, bar, *t*, neat, #$)
    You say, "moof"
    > say case(moof, *f, foo, moof, bar, baz)
    You say, "bar"

• SWITCHES

Commands can have "switches" which modify the behavior of the command. Switches are attached after the end of a command. For example, most people are familiar with the command

    @lock me=me

The "enter" switch to @lock allows you to lock who can enter:

    @lock/enter me=me

A command may have multiple switches:

    @pemit/noeval/silent me=Hi!

Help on the switches available for a command is available in the help file for that command. (If you are looking for information on @switch, see 'help @switch'.)