& help
This is the TinyMUSH 3 online help facility. (IMPORTANT: see 'help Revision'.)
Type 'help About Help' for help on using help, and other related details.
Type 'help Tutorial' for a "quick start" guide for first-time MUSHers.
Type 'help Syntax' for a brief explanation of the syntax of MUSH commands.
For a list of recent changes to the MUSH server, type 'help Patchlevel'.
---------------------------------------
Type 'qhelp' for the quick-reference help.
This is strongly recommended over the regular help,
unless you absolutely need all the gory details!
---------------------------------------
Type 'help Topics' for a more extensive list of help topics.
Many MUSHes also have local help files. Type '+help' to access them.
Most MUSHes also have local information files. Type 'news' to read them.
Wizards can type 'wizhelp' to read the administrator help files.
& Revision
The TinyMUSH 3 help facilities are currently under revision. When this
revision is complete, the help files will be divided into 'qhelp' (quick
help for the ordinary player who doesn't need every little subtlety and
possibility), and 'help' (very detailed explanations for the advanced
MUSH programmer).
Furthermore, the structure of help is being altered to group related
topics together, on the basis that people are usually looking for help
with concepts, trying to find "what" something does (often, trying to
find the name of a command, function, etc. that does what they want),
before they look at "how" that something does it.
As of this beta release, this rewriting is still ongoing. Thus, the
help files are a sometimes-confusing mixture of the old way and the
new way. Please be patient; this will get fixed.
& About Help
In all help entries, the following notations mean special things:
[text] - Text enclosed in []'s is optional. The []'s are never typed
in as part of the command.
<parameter> - A parameter for a command, usually a variable that you
fill in yourself. For example, <obj> usually means
the name or dbref of an object. The <>'s are never
typed in as part of the command.
<opt1 | opt2> - A parameter for a command that could be one of several
values. 'opt1' and 'opt2' are literal strings, in this
case, not <opt 1> and <opt 2> parameters.
See 'help Conventions' for common values of <parameter> abbreviations.
These conventions are important; please make sure you read this entry,
or some of the more complex command and function syntax might not make
any sense to you.
Continued in 'help About Help2'.
& About Help2
To read a help entry, type 'help <name of topic>'. You don't need to
type the complete topic name, just enough of it to make the word unique.
For instance, instead of typing 'help @switch', you can type 'help @swi'.
Topic names are not case-sensitive.
Almost all help entries are primarily intended as a reference guide,
not a tutorial. As such, they are intended to be as exhaustive as
possible, detailing exactly how things work.
The vast majority of players will not need the reams of detail contained
in many of the help entries. They are likely to find the QuickHelp ('qhelp')
and its short, simplified help entries for the frequently-encountered MUSH
commands and concepts to be much more helpful. Type 'qhelp' to get the
QuickHelp index. First-time players should type 'help Tutorial' for an
introduction to MUSHing.
If you are trying to learn how to code and build in MUSH, you might
also find external documentation to be more helpful. Some MUSHes have
a MUSH Manual online; type 'man' to access it, if it's available.
& Conventions
These help entries use a variety of abbreviations and conventions
when describing the <parameters> for commands, functions, and so
forth. In many cases, these <parameters> are quite standard
entities, and therefore will be notated in a shorthand. This
help entry describes those shortcuts.
<switch> A single switch to a command, modifying its behavior.
<switches> Equivalent to <switch 1>/<switch 2>/<switch 3>/<etc.>
Multiple switches to a command, modifying its behavior.
<pattern> A 'wildcard' pattern, i.e., one that contains '*' and '?'.
See 'help Wildcards' for details.
<regexp> A regular expression. See 'help Regexps' for details.
Continued in 'help Conventions2'.
& Conventions2
<str> A string, made up of arbitrary characters. The first
character in a string is numbered 0, the second character
in a string is numbered 1, and so forth.
<list> A number of strings, separated by a delimiter, <delim>.
Each string is called a 'word' or an 'element'. The first
element in a list is numbered 1, the second element in a
list is numbered 2, and so forth. 'cat dog bird' is a
space-delimited list with three words. 'cat|dog|bird' is
a '|'-delimited list.
<delim> A delimiter. A single character used to separate elements
in a list from one another.
<odelim> An output delimiter. A special type of delimiter.
<dels> Equivalent to <delim>[,<odelim>]
See 'help Delimiters' for more on delimiters and defaults.
Continued in 'help Conventions3'.
& Conventions3
<dbref> The dbref of an object.
<player> A player, specified by his full name, alias, or dbref.
Often, for a connected player, a partial name, as long
as it's unique, will be sufficient. 'me' is normally
also valid.
<obj> An object. Normally, an object can be referred to by its
dbref, or part of its name (or part of its name), or as
'me' or 'here' if appropriate; players can also be
referred to by *<player name>. Non-wizards without the
Long_Fingers power might not be able to manipulate objects
that are not near them. See 'help Matching' for details.
<mobile> Equivalent to <obj> but the object must be a player or
thing.
<attr> The full name of an attribute.
Continued in 'help Conventions4'.
& Conventions4
<o/a> Equivalent to <obj>/<attr>
An object/attribute pair, such as '#10/VA', referring to
the VA attribute on the object with the dbref #10.
<aref> Equivalent to [<obj>/]<attr>
An "attribute reference". This is an object/attribute pair,
where if the object is not specified, 'me' is implied. In
other words, '#10/VA' is a valid parameter for <aref>, as
is 'VA' (which implies 'me/VA').
<wild> A wildcard attribute. It matches every attribute (normally
on a specified object) whose name matches this wildcard
pattern.
& Syntax
The syntax of most MUSH commands takes one of following forms:
<command>
<command>[/<switches>]
<command>[/<switches>] <parameter 1>
<command>[/<switches>] <parameter 1> = <parameter 2>
<command>[/<switches>] <parameter 1> = <parameter 2>,[...,]<parameter N>
For example:
look
look/outside
@teleport #0
@teleport me = #0
@teleport/quiet me = #0
@open North;n = #0, South;s
Continued in 'help syntax2'.
& Syntax2
The help entries list the proper syntax for each command and function.
Most, but not all built-in MUSH commands begin with an '@' sign.
All built-in MUSH commands are not case-sensitive. Thus, 'look',
'LOOK', 'Look', and 'LooK' all indicate the same command, 'look'.
Many MUSHes have special local commands unique to that MUSH, as well.
By convention, such commands usually begin with a '+' sign.
& Attributes
With a handful of exceptions, help topics related to built-in
attributes have either grouped attributes under the commands or flags
that utilize them (especially true of "verb" attributes), or into
single entries that discuss closely related attributes. The
appropriate help entries to consult are listed below.
look: @desc set, @idesc, @succ set, @fail set
drop: @drop set, @dfail set
enter: @ealias, @enter set, @efail set, @oxenter
give: @gfail set, @rfail set
goto: @succ set, @fail set, @drop set
kill: @kill set
leave: @lalias, @leave set, @lfail set, @oxleave
page: @away, @idle, @reject
use: @use set, @ufail set
@clone: @aclone
@last: @last, @lastsite, @logindata
@mail: @amail, @mailsucc, @signature
@teleport: @tport set, @tfail set, @tofail set, @oxtport
Continued in 'help Attributes2'.
& Attributes2
@aconnect: @aconnect, @adisconnect
@forwardlist: @filter, @forwardlist, @infilter, @inprefix, @prefix
@listen: @listen, @aahear, @ahear, @amhear
Charges: @charges, @runout
Vendors: use of machines, @pay set, @cost
Moving: @move set
Individual attribute entries:
@allowance @comment @conformat @daily @exitformat
@exitto @nameformat @newobjs @sex @speechformat
@startup @timeout @va
All available attributes can be listed with '@list attributes'.
See 'help Attributes3' for a definition of what attributes are, a
definition of what verbs are, and how to set built-in attributes,
and how to set user-defined attributes.
& Attributes3
An "attribute" is a piece of data that's stored on an object, under a
specific name. For example, an object's description (what you see when
you 'look <obj>') is stored in its Desc attribute.
Attribute names are not case-sensitive, and must be under 32
characters long. In general, letters, numbers, underscores, dashes,
and periods can be safely used in attribute names, though there are
some other special characters permitted, as well.
To set an attribute on an object, use:
&<name of attribute> <obj> = <value>
MUSH also has a variety of built-in attributes, attributes which have
a special meaning to the MUSH server. To set the value of a built-in
attribute object on an object, use:
@<name of attribute> <obj> = <value>
For example, '@desc balloon = A red balloon.' would set the description
of a balloon object.
Continued in 'help Attributes4'.
& Attributes4
Attributes can have owners that are different from the owners of the
objects. Attributes can be locked, preventing anyone from changing
their value. Attributes can also have flags, which give the attributes
special properties. These flags can apply to a specific attribute on a
specific object ("attribute's flags"), or to all attributes with this
name on the MUSH ("attribute's access flags").
In brief, the syntax for the commands that alter attribute properties:
@chown <obj>/<attr> = <name of owner>
@lock <obj>/<attr>
@unlock <obj>/<attr>
@set <obj>/<attr> = <attribute flag>
@attribute/access <user-defined attribute> = <attribute access flag>
@admin attr_access = <built-in attribute> <attribute access flag>
See 'help Attribute Owners', 'help Attribute Flags', 'help @chown',
'help @lock', 'help @unlock', 'help @set', 'wizhelp @attribute', and
'wizhelp attr_access' for additional details.)
Continued in 'help Attributes5'.
& Attributes5
Some built-in attributes act in special ways when a player takes a
specific kind of action. They show a message to the player who took
the action, show a message to the other objects in the player's
location, and trigger a sequence of action commands. These attributes
are known as "verbs", or as '@attr/@oattr/@aattr sets' -- for the
message shown to the player, the message shown to Others, and the
Action taken, respectively.
For example, when you look at an object, the MUSH utilizes the
@desc / @odesc / @adesc attribute set (the Desc, Odesc, and Adesc
attributes, set by the @desc, @odesc, and @adesc commands). It
shows you, the player looking at the object, the Desc attribute
set on the object, evaluated (which expands percent-substitutions
and functions). It shows everyone else in your location the Odesc
attribute on the object, evaluated; it prepends your name to the
message. Then, it queues up for execution, the semi-colon-separated
list of actions given in the object's Adesc, which the object
then executes.
Continued in 'help Attributes6'.
& Attributes6
For example:
@desc balloon = A red balloon.
@odesc balloon = looks at a red balloon.
@adesc balloon = @emit The red balloon drifts away.
When you, a character named Figment, type 'look balloon', you are
shown the message 'A red balloon.' Everyone else in your location
sees, 'Figment looks at a red balloon.' The balloon object itself
queues the command '@emit The red ballon drifts away.' and a second
later, everyone in the balloon's location sees 'The red balloon
drifts away.'
You can avoid having the actor's name being prepended to an @o-attr
via the use of the 'no_name' attribute flag. For example:
@osucc exit = A breeze comes up and sweeps %N eastwards.
@set exit/osucc = no_name
Running actions from an @aattr costs charges from the @charges attribute,
and may trigger @runout. See 'help Charges' for details.
& Attribute Flags
Topic: Attribute Flags
The following are the possible attribute flags:
dark - Attribute which can only be seen by God. Global only. (d)
god - Attribute which can only be changed by God. Global only. (g)
hidden - Only those who are Wizards, Royalty, or have the attr_read
power, can see this attribute. (m)
wizard - Only Wizards, or those who have the attr_write power,
can set/change this attribute. (w)
visual - Anyone may see the attribute, including obtaining it with
a function such as get(). (V)
locked - Cannot be changed by anyone. Set via '@lock <obj>/<attr>'
and '@unlock <obj>/<attr>', not @set. Local only. (+)
const - Cannot be changed by anyone. Global only.
Continued in 'help Attribute Flags2'.
& Attribute Flags2
no_command - Prevent $-commands and ^-patterns defined in the attribute
from being performed. ($)
no_parse - When $-commands/^-listens are matched, the unparsed
(non-evaluated) string is used. Useful for MUSH editors.
Local only. (P)
case - Treat regular expression patterns as case-sensitive.
Affects $-commands, ^-listens, @filter, @infilter, and
@listen. Local only. (C)
regexp - Treat patterns as regular expressions rather than
wildcard glob patterns. Affects $-commands, ^-listens,
@filter, @infilter, and @listen. Local only. (R)
rmatch - Set wildcard matches into x-variables. Local only. (M)
now - Execute matches now, instead of queueing. Local only. (Q)
Continued in 'help Attribute Flags3'.
& Attribute Flags3
no_inherit - Prevents children of the object from obtaining the
attribute. From their perspective the attribute does not
exist. (I)
no_clone - Prevents attribute from being copied when an object is
cloned. Global only. (c)
default - Checks the attr_defaults object of the appropriate type
for the attribute, whenever attr/oattr/aattr invocation
is done (including @verb). See 'wizhelp attribute defaults'
for more information. Global only. (D)
html - When used as part of an Attr/OAttr/AAtr trio (as in @verb,
@enter, etc.), the Attr is not HTML-escaped (see Pueblo).
Local only. (H)
no_name - If used as an @o-attr (including with @verb), don't prepend
the name of the actor. Also affects @speechformat. (N)
Continued in 'help Attribute Flags4'.
& Attribute Flags4
structure - Contains structure data set via write(). Cannot be read
by other means. Local only. (S)
internal - Cannot be read or written to by any means. Used only
for attributes that should be directly altered by the
server itself. Global only.
ignore - Prevents the automatic creation of an @-command for a
built-in attribute. Global only.
Continued in 'help Attribute Flags5'.
& Attribute Flags5
The "global attribute" (the "definition" of all attributes on the MUSH
with a given name) has a set of flags that applies to all attributes
with that name. Each individual instance of an attribute (i.e., each
attribute that is set on an object) can also have flags. Some flags
are only checked locally; some flags are checked only globally; some
flags are checked both globally and locally.
The global flags of a user-defined attribute are changed via the command
'@attribute/access <user-defined attribute name> = <attribute flag>'.
Such changes are permanent.
The global flags of a built-in attribute are changed via the command
'@admin attr_access = <built-in attribute name> <attribute flag>'.
Such changes are not permanent, and must be put in the conf file
(with 'attr_access <built-in attribute name> <attribute flag>') for
permanence across startups.
The flags of an individual attribute are changed using the command
'@set <obj>/<attr>=<flag>'. The exception is the 'locked' flag.
& Attribute Owners
Topic: Attribute Owners
If you own an attribute, you can view it, lock/unlock it, and @chown
its ownership, even if you do not control the object that the
attribute is on; however, you cannot change or remove the attribute,
unless you control the object it's on.
When checking an attribute lock against an object, the lock will always
fail if the locked object is not owned by the same player as the attribute
being tested. The comparison specified in the lock is only performed if
the owner of the locked object also owns the attribute on the object
being checked.
& Tutorial
Topic: Tutorial
Coming soon.
& COMMANDS
Flag: COMMANDS ($)
When set on an object, when a command match is done, it checks the
object for attributes of the form '$<pattern>:<commandlist>'. If the
command matches the pattern, then <commandlist> is executed.
In other words, it checks the object for arbitrary user-defined
$commands.
Depending on your MUSH configuration, this flag might or might not
be necessary for User Commands to be checked.
See 'help User Commands' for more details.
& Command List
Messaging:
@@ @emit @eval @femit @fpose
@fsay @npemit @oemit @pemit page
pose say think whisper
Movement:
@teleport drop enter get give
goto home leave
Database alteration:
@alias @chown @chzone @clone @cpattr
@create @destroy @dig @edit @link
@lock @mvattr @name @open @parent
@power @quota @robot @set @unlink
@unlock @wipe
Continued in 'help Command List2'.
& Command List2
Program execution:
@dolist @drain @force @halt @notify
@program @ps @quitprogram @redirect @sql
@switch @trigger @verb @wait use
Other:
@cron @crondel @crontab @decompile @doing
@entrances @find @floaters @last @list
@listcommands @listmotd @password @reference @search
@stats @sweep examine inventory kill
look score version DOING INFO
LOGOUT OUTPUTPREFIX OUTPUTSUFFIX PUEBLOCLIENT QUIT
SESSION WHO
You are strongly encouraged to check if there is QuickHelp on something
before consulting the "regular" helpfile. Type 'qhelp' for an index
of QuickHelp topics and commands.
Type 'help <command name>' for details about a specific command.
& Topics
Help is available on the following topics:
About Help Attributes Attribute Owners
Attribute Flags Boolean Values Caller
Command List Comsys Conn Reasons
Control Conventions Costs
Credits Delimiters Enactor
Exits FAILURE FLAG LIST
FLAGS FUNCTION LIST FUNCTIONS
HOMES LINKING LISTENING
LISTS LOCAL REGISTERS Location
Locks LOOPING Matching
Modules MONEY Moving
OBJECT TYPES PARENT OBJECTS Patchlevel
PIPING PUEBLO PUPPETS
REGEXPS ROBBERY Scan Order
SEARCH CLASSES SEMAPHORES SPOOFING
STACK SUBSTITUTIONS SUCCESS
SWITCHES Syntax User Commands
Zone Control ZONE OBJECTS
& throw
& drop
Command: drop[/quiet] <exit>
drop[/quiet] <mobile>
When you drop an exit, it is removed from your list of carried exits,
and added to the exits from your current location; the exit behaves
just like an exit that was @open'd directly out of that location in
the first place. You can only drop exits in a location that you could
normally @open an exit out of.
Under normal circumstances, dropping an object removes the object from
your inventory, and places it in the contents of your current location.
If the object has a DropLock, you must be able to pass the lock (or be
a Wizard), in order to drop the object; if you can't drop the object,
then the object runs its @dfail verb set.
When you drop an object, several things occur. See 'help Moving' for
an expansion of some of these steps. The object being dropped is the
mover, its current location is you (the player dropping it), and its
destination is your current location (the room it's being dropped into).
Continued in 'help drop2'.
& drop2
The following happens when an object is dropped:
- The mover leaves its current location.
- The mover's destination is registered.
- The mover's @move verb set is run.
- The mover enters its destination.
- The mover is given the message, "Dropped."
- If the mover has a @drop set, you are shown that message; otherwise you
get the message, "Dropped."
- The drop is considered "quiet" if the /quiet switch was specified, and
you control the mover.
- If the drop is not quiet, everyone in the new location other than you
is shown the mover's @odrop (or "<your name> dropped <mover name>."
if it doesn't have one).
- If the drop is not quiet, the mover runs its @adrop.
- If the mover is STICKY, it is sent home, as are its KEY contents
(see 'help Movement Key').
- If the mover is not STICKY, the new location has a drop-to, and the new
location is not STICKY, then the mover is sent to the drop-to location,
and its KEY contents are sent home.
Continued in 'help drop3'.
& @dfail
& @odfail
& @adfail
& drop3
Example of a @dfail verb set:
@dfail sword = The sword has welded itself to your hand.
@odfail sword = tries to put down the sword but it leaps back into %p hand.
@adfail sword = @emit/room The cursed sword in [name(loc(me))]'s hand
gleams with unholy light.
Example of a @drop verb set:
@drop vase = You gently put down the delicate vase.
@odrop vase = gently puts down a delicate vase.
@adrop vase = :shatters.; @destroy/instant me
The @drop verb set of an exit is used when an object goes that exit; see
'help goto' for the details and an example.
& @ealias
& enter
Command: enter[/quiet] <mobile>
If you are in the same room as an object, you might be able to enter it.
There are two ways to do that: either type 'enter <mobile>' or type the
"enter alias" of the object. (Wizards and those with the Long_Fingers
power are also able to 'enter <dbref>' to enter objects in other locations.)
Enter aliases take the same format as exit names, with multiple aliases
separated by semi-colons. They are attributes, set with the command
'@ealias <mobile> = <enter aliases>'. For example, an "airplane" object
might be aliased as follows: @ealias airplane = plane;fly;board airplane
This would allow 'plane', 'fly', or 'board airplane' to be used in
order to enter the airplane object.
If you control the object being entered, and you specify the /quiet
switch, the move is treated as "quiet".
Continued in 'help enter2'.
& enter2
If the object is not ENTER_OK and you do not control it, then you
will be shown the object's @efail message if it has one, or
"Permission denied." if it does not. If the move is not quiet,
others in your location will be shown the object's @oefail,
and the object will run its @aefail.
If the object has an EnterLock and you do not pass that lock, then
will be shown the object's @efail message if it has one, or
"You can't enter that." if it does not. If the move is not quiet,
others in your location will be shown the object's @oefail,
and the object will run its @aefail.
Continue in 'help enter3'.
& enter3
If you can enter the object, then several steps occur; see 'help Moving'
for an expansion. You are the mover, the current location is the room
you're in, and the new location is the object you are entering.
The steps are:
- The mover leaves its current location.
- The mover's new location is registered.
- The mover's @move verb set is run.
- The mover enters its new location.
- Mover contents set KEY are sent home.
- The old room's drop-tos are activated.
Continued in 'help enter4'.
& @efail
& @oefail
& @aefail
& @enter
& @oenter
& @oxenter
& @aenter
& enter4
Example of an @efail verb set:
@efail car = The car's door is locked.
@oefail car = tries to open the car's door, but it is locked.
@aefail car = &LAST_FAIL me = [time()]
Example of an @enter verb set and @oxenter:
@enter car = You climb into the car and buckle your seatbelt.
@oenter car = joins you in the car, and buckles %p seatbelt.
@aenter car = @trigger me/START_ENGINE
@oxenter car = climbs into the car.
Note that when you enter an object, the @oxenter is shown to those
in the location you just left, and the @oenter is shown to those
in the object that you just entered.
& examine
Command: examine[/<switches>] <object>[/<wild-attrib>]
Displays all available information about <object>. <object> may be an
object, 'me' or 'here'. You must control the object to examine it, or it
must be set VISUAL. If you do not own the object, you will just see the
name of the object's owner, and optionally any public attributes and
attributes owned by you set on the object.
If an attribute is owned by a player other than the owner of the object,
the number of the attribute owner is shown in brackets immediately
following the attribute name. Flag letters may appear within the brackets
also, to indicate the status of the attribute; if the flag letters are
in parentheses, they indicate flags for the global definition of all
attribute with that name. See 'help @set2' for details.
If you specify a wildcarded attribute name, then only those attributes
that match are shown. So, 'exam me/v?' will show all your attributes that
start with v and are two characters long.
Continued in 'help examine2'.
& examine2
The following switches are available:
/brief - Don't show the attributes on the object.
/full - When examining an object you don't control, show any public
attributes set on the object in addition to the owner's name.
/owner - Show only the owner of the object.
/parent - Includes attributes that are not present on the object itself
but which are inherited from the object's parent.
/pretty - Pretty-print, in a format suitable for a MUSH unformatter.
/pairs - Shows matches in parentheses, brackets, and braces.
Each level ("nesting") of these is highlighted in a different
ANSI color (in order, green, yellow, cyan, blue, and magenta).
If an error is encountered, where the pairs don't match, the
offending character is highlighted in red. The rest of the
string is then printed out; no further pair-matching will
occur. Escaped-out characters are not highlighted or counted.
/debug - Wizards only. Displays additional information about the
object. Shows the Owner, Exits, Next, and Contents fields of
the object in numeric form only. Includes an attribute list.
See also: look, @decompile, VISUAL, ATTRIBUTE OWNERSHIP.
& take
& get
Command: get[/quiet] <exit>
get[/quiet] <mobile>
get[/quiet] <carrying mobile>'s <carried mobile>
When you get an exit, it is removed from the exits from your current
location, and added to your list of carried exits. This effectively
makes you the source of the exit; anyone inside you can then use the
exit to move to its destination. You can only get exits that you
control, or whose source is a location that you control.
When you get an object, it removes the object from the contents of its
current location, and places it in your inventory. You can use the 'get'
command to get objects from other's inventories, as long as you control
the possessor, or the possessor is set ENTER_OK and is not DARK or OPAQUE.
Checking the objects of a possessor is recursive; i.e., you can do:
get <top-level container>'s <next-level container>'s <etc.>'s <carried obj>
Continued in 'help get2'.
& get2
If the object you are trying to get has a basic Lock, you must be able
to pass the lock, in order to get the object. If you can't:
- You are shown the @fail of the object. If the object does not have
one set, you are told, "You can't take that from there." if you
are trying to get an object that someone else is carrying, or
"You can't pick that up." otherwise.
- If the /quiet switch was not specified, everyone in your location
sees the object's @ofail.
- If the /quiet switch was not specified, the object runs its @afail.
If your current location is not a room, you cannot 'get' anything
(including exits), unless you control your current location, or it
is set ENTER_OK. You can only get nearby things, unless you are
a Wizard or have the Long_Fingers power, in which case you can
get remote things via 'get <dbref>'.
Continued in 'help get3'.
& get3
If you successfully get an object, several steps happen. See
'help Moving' for the details of some of these steps. The object
that you have gotten is the mover, the old room is the location it
was taken from , and the destination is you. The move is considered
"quiet" if the /quiet switch was specified. The steps are:
- If the mover is being taken from someone else's inventory, its
current possessor is told, "<mover name> was taken from you."
- The mover leaves its current location.
- The mover's destination is registered.
- The mover runs its @move verb set.
- The mover enters its destination.
- The mover is told, "Taken."
- You are shown the mover's @succ message, or "Taken." if the mover
does not have one.
- If this is not quiet, those in your location see the mover's @osucc.
- If this is not quiet, the mover runs its @asucc.
Continued in 'help get4'.
& get4
Example of a @fail verb set on an object:
@fail table = The table is too heavy to lift.
@ofail table = strains to lift the table, but it is too heavy for %o.
@afail table = &LAST_TRY me = [time()]
Example of a @succ verb set on an object:
@succ sword = You wield the magic sword.
@osucc sword = wields a magic sword.
@asucc sword = @wait 10 = @emit The magic sword glows brightly.
& give
Command: give[/quiet] <recipient mobile> = <amount of money>
give[/quiet] <recipient mobile> = <gift mobile>
You can give money, or objects that you're carrying, to someone else,
as long as the recipient is not a Guest character. The recipient must
be nearby, unless you're a Wizard or have the Long_Fingers power,
in which case you can specify the recipient as *<player> or <dbref>.
If your gift (the right-hand side of the '=' sign) is a number, your
gift is assumed to be money; otherwise, it is assumed to be an object.
If you try to give someone a negative number, this is treated like
trying to take away money from them. You can only do this if you are a
Wizard or you have the Steal_Money power. Otherwise, you will be told,
"You must specify a positive number of <money name>."
Continued in 'help give2'.
& give2
If you are not a Wizard, and you try to give money to a player, you
will be told, "That player doesn't need that many <money nane>!" if
the amount they would have after your donation would exceed the
value of the configuration parameter earn_limit.
If you are not a Wizard, and you try to give money to someone else,
you must be able to pass their GiveLock. Otherwise, you are told,
"<recipient> won't take your money."
You must have sufficient money to cover the amount that you are giving
someone else. Wizards, those set IMMORTAL, and those with the
Free_Money power are considered to have infinite money.
If the recipient of money is a player, the /quiet switch suppresses
any messages; otherwise, you will be told that you have given the
player money, and the player will be told that you've given him money.
Continued in 'help give3'.
& give3
If the recipient of money is not a player, then this is considered
an attempt to "pay" a machine. See 'help @pay' for the details of
what happens when you do so.
If you try to give an object to someone else, the recipient must
be someone you control, or they must be set ENTER_OK. If not,
you will be told, "Permission denied."
If the object you're trying to give away has a GiveLock, and you don't
pass the lock, then you will be shown the object's @gfail (or the
message, "You can't give <gift> away." if the object doesn't have a
@gfail), the others in your location will be shown the object's
@ogfail, and the object will run its @agfail.
If the recipient has a ReceiveLock, and you don't pass the lock,
then you will be shown the recipient's @rfail (or the message,
"<recipient> doesn't want <gift>." if the recipient has no @rfail),
the others in your location will be shown the recipient's @orfail,
and the recipient will run his @arfail.
Continued in 'help give4'.
& give4
If you successfully give an object away, several steps happen. See
'help Moving' for the details of some of these steps. The gift
is the mover, the old room is the gift's former location (normally
your inventory), and the destination is the recipient. The move is
considered "quiet" if the /quiet switch was specified. The steps are:
- The mover leaves its current location.
- The mover's destination is registered.
- The mover runs its @move verb set.
- The mover enters its destination.
- Mover contents set KEY are sent home.
- If this is not quiet, the recipient is told, "<your name> gave you
<gift>."
- If this is not quiet, you are told, "Given."
- If this is not quiet, the gift is told, "<your name> gave you to
<recipient>."
- The mover runs its @drop verb set; you are considered the enactor.
- The mover runs its @succ verb set; the recipient is considered the enactor.
Continued in 'help give5'.
& @gfail
& @ogfail
& @agfail
& @rfail
& @orfail
& @arfail
& give5
Example @gfail verb set:
@gfail sword = The cursed sword leaps back into your hands.
@ogfail sword = tries to give away %p cursed sword, but it leaps back
into %p hands.
@agfail sword = @wait 10 = @emit The cursed sword gleams with unholy light.
Example @rfail verb set:
@rfail merchant = The merchant doesn't want your worthless trash.
@orfail merchant = fails to unload some worthless trash on the merchant.
@arfail merchant = :kicks %N out of his store.; @tel %# = home
& goto
Command: goto[/quiet] <exit>
The 'goto' is usually referred to by its alias, 'move'; i.e., you
can type 'move <exit>' instead of 'goto <exit>'. You can also
'goto home'; this is just like typing 'home' (see 'help home').
You can move directly through an exit by just typing the name of the
exit (or one of the aliases in the exit's full name). However, there
are some subtle differences in the way the server goes about looking
for an appropriate exit, depending on whether you type 'goto <exit>'
or just '<exit>'.
When you just type '<exit>', the server checks for a matching local
exit (one in your current location, whether directly there or
inherited from a parent room). If there isn't a match, then it
checks for a global exit (one in the master room). If there isn't
a match still, then it will check zone exits. If, at any of those
levels, multiple exits match, one of the matches will be chosen
at random.
Continued in 'help goto2'.
& goto2
When the configuration parameter move_match_more is not enabled,
'goto <exit>' only checks a matching local exit; if more than one
local exit is found, the message "I don't know which way you mean!"
will be returned. If move_match_more is enabled, 'goto <exit>'
checks for an exit match in the exact same way '<exit>' does.
If the config parameter exit_calls_move is enabled, typing '<exit>' is
exactly like typing 'goto <exit>'. In general, MUSH administrators
will only enabled this configuration if @addcommand or @hook has been
used to override or alter the standard behavior of movement.
Once an exit is matched, its endpoint (where it is @link'd to) is
checked. If the exit was @link'd to "variable", the endpoint is
determined at this point, by evaluating the @ExitTo on the exit.
Continued in 'help goto3'.
& goto3
The Lock of the exit is also checked, if it exists. If you are not able
to pass the lock, or the exit's endpoint is someplace invalid (such as
a Garbage object) then the following things occur:
- You are told the exit's @fail, or if it doesn't have one set,
"You can't go that way."
- Others in your location see the exit's @ofail, unless you specified
the /quiet switch or are DARK.
- The exit runs its @afail, unless you specified the /quiet switch,
or you are DARK and the dark_actions config parameter is not enabled.
If you do pass the lock, then a series of steps occur. See 'help Moving'
for an expansion of some of these. You are the mover, the location you
are leaving is the old room, and the endpoint of the exit is the
destination.
Continued in 'help goto4'.
& goto4
The move is considered "noisy", unless the mover is set TERSE and the
configuration parameter terse_shows_move_messages is disabled. The
move is considered "visible", unless the /quiet switch was specified,
or the mover is a Dark Wizard/Cloaker. The move is considered "active",
unless the /quiet switch was specified, or the mover is a Dark
Wizard/Cloaker and the dark_actions configuration parameter is not
enabled. The steps are as follows:
- If the move is noisy, the mover is shown the exit's @succ message.
- If the move is visible, everyone in the old room sees the exit's @osucc.
- If the move is active, the exit runs its @asucc.
- The mover leaves its current location.
- The mover's destination is registered.
- If the move is noisy, the mover is shown the exit's @drop message.
- If the move is visible, everyone in the destination sees the exit's @odrop.
- If the move is active, the exit runs its @adrop.
- The mover runs its @move verb set.
- The mover enters its destination.
- Mover contents set KEY are sent home.
Continued in 'help goto5'.
& goto5
Example of a @fail verb set on an exit:
@fail iron door = The door is stuck. You can't budge it.
@ofail iron door = attempts to open the iron door, but it's stuck.
@afail iron door = @wait 60 = @unlock me; @@ Silently "unstick" myself.
Example of a @succ verb set on an exit:
@succ iron door = You push open the heavy door, and walk through.
@osucc iron door = pushes open the iron door, and walks through.
@asucc iron door = @lock me = #0; @@ Silently lock myself.
Example of a @drop verb set on an exit:
@drop iron door = You emerge on the other side of the iron door.
@odrop iron door = walks in from the prison cell behind the iron door.
@adrop iron door = &LAST_USED me = [time()]
Most MUSHes have a building code that requires or strongly encourages
builders to put @osucc and @odrop messages on their exits. Many also
encourage the use of a @succ message on an exit. @drop messages are
rarely used on exits.
& home
Command: home
A mobile object can use the 'home' command to return to its home.
Note that typing 'home' or 'goto home' is different from typing
'@teleport home'; the latter is treated like a teleportation and
behaves like other teleportations (see 'help @teleport').
If an object is set FIXED, or its owner is set FIXED, and it is not
a Wizard or Royalty, it will not be able to use the 'home' command.
Otherwise, objects are always able to go home.
Continued in 'help home2'.
& home2
Several steps occur when an object uses the 'home' command. See
'help Moving' for an expansion of some of these. The mover is
the object going home, the old room is the object's current
location, and the destination is the object's home.
- Everyone in the old room sees, "<mover> goes home." unless the
mover is DARK, or the old room is DARK.
- The mover is told three times, "There's no place like home..."
- The mover leaves its current location.
- The mover's destination is registered.
- The mover runs its @move verb set.
- The mover enters its destination.
- Mover contents set KEY are sent home.
- The old room's drop-tos are activated.
& info
Command: INFO
This command is intended for the use of external automated programs. It
displays commonly-requested pieces of information about the MUSH, in
an easy-to-parse format. That format is as follows:
### Begin INFO <version>
Name: <MUSH name>
Uptime: <time started>
Connected: <number of players connected>
Size: <number of objects in the database>
Version: <server version>
### End INFO
<MUSH name> is whatever is returned by mudname(). (Conf param 'mud_name'.)
<time started> is whatever is returned by starttime().
<number of players connected> is equivalent to words(lwho()).
<size> is equivalent to first(stats()).
<server version> is a short version string.
& inventory
Command: inventory
Lists what you are carrying and how much money you have.
& kill
Command: kill <mobile> [=<cost>]
Attempts to kill the specified player or object. Killing costs <cost>
coins, which gives you a <cost>% chance of killing the player. Thus,
spending 100 coins always works, with some exceptions detailed below.
If you don't specify a cost, the default is 10 (for a 10% chance of
success). The victim, if killed, receives <cost>/2 coins in insurance.
Killing always fails if any of the following is true:
- The victim's location is set HAVEN, and you're not a Wizard.
- The victim controls his location, and you don't control his location.
- The victim is a Wizard, or has the Unkillable power.
- The victim is set IMMORTAL; alternatively, the victim's owner is set
IMMORTAL, and either the victim or his owner is set INHERIT.
Killing is generally considered rude, and some MUSHes disable it entirely.
It can, however, be useful if there's a looping object in a location that
you don't control, and you want to halt it and send it home.
Continued in 'help kill2'.
& @kill
& @okill
& @akill
& kill2
The following things happen when a kill is successful:
- If the killer is set SUSPECT, connected Wizards are notified of the kill.
- The victim is halted, just as if he had the @halt command run on him.
- The victim's @kill verb set is run.
- The victim is told who killed him.
- The mover leaves its current location.
- The mover's destination is registered.
- The mover runs its @move verb set.
- The mover enters its destination.
- Mover contents set KEY are sent home.
Example of a @kill verb set:
@kill guard = You villain! You killed a guard! The guard expires.
@okill guard = killed a guard. An alarm sounds in the distance.
@akill guard = &LAST_KILL me = %# [secs()]
& @lalias
& leave
Command: leave[/quiet]
If you are inside a mobile object, you might be able to leave it,
either by typing 'leave' or by typing one of its leave aliases.
If you leave an object, you will end up in that object's current
location.
Leave aliases take the same format as exit names, with multiple aliases
separated by semi-colons. They are attributes, set with the command
'@lalias <mobile> = <leave aliases>'. For example, an "airplane" object
might be aliased as follows: @lalias airplane = disembark;ground;out;o
This would allow 'disembark', 'ground', 'out', or 'o' to be used in
order to leave the airplane object.
Continued in 'help leave2'.
& leave2
If you control the object being left, and you specify the /quiet
switch, the move is treated as "quiet".
If the object has a LeaveLock and you do not pass that lock, then will
be shown the object's @lfail message if it has one, or "You can't leave."
if it does not. If the move is not quiet, others in your location will
be shown the object's @olfail, and the object will run its @alfail.
If you can leave the object, then several steps occur; see 'help Moving'
for an expansion. You are the mover, the current location is the object
you're in, and the new location is the object's own location.
The steps are:
- The mover leaves its current location.
- The mover's new location is registered.
- The mover's @move verb set is run.
- The mover enters its new location.
Continued in 'help leave3'.
& @lfail
& @olfail
& @alfail
& @leave
& @oleave
& @oxleave
& @aleave
& leave3
Example of a @lfail verb set:
@lfail plane = You don't have a parachute!
@olfail plane = thinks about jumping out of the plane without a parachute,
but wisely reconsiders.
@alfail plane = &LAST_FAIL me = [time()]
Example of a @leave verb set and @oxleave:
@leave car = You unbuckle your seatbelt, and climb out of the car.
@oleave car = unbuckles %p seatbelt and gets out, leaving you in the car.
@aleave car = &LAST_EXIT me = [time()]
@oxleave car = gets out of the car that's parked here.
Note that when you leave an object, the @oxleave is shown to those
in the location that you just entered (i.e., where the object is),
and the @oleave is shown to those in the object that you just left.
& LOGOUT
Command: LOGOUT
Disconnects you from your character without breaking the network connection
to the game. You may then log in to another character. The LOGOUT command
must be entered in all capitals.
See also: QUIT.
& look
Command: look[/<switches>] [<object>]
Displays the description of <object>, or the room you're in if you don't
specify an object. Specifying object as <name> or #<dbref> or 'me' or
'here' is legal. You can also use look to look at objects held by other
people, just use 'look <person>'s <object>'.
You may use the /outside switch to look at the location of your current
location (useful if you are inside a vehicle or other object). You may
also look at other objects in the 'outer' location, but you may not
use the possessive form with the /outside switch (ie: "look/outside
<person>'s <object>" won't work).
'read' is the same as 'look'.
See also: @adesc, @describe, @odesc.
& move
See 'help goto'. The 'move' command is an alias for 'goto'.
& Moving
Topic: Moving
There are a number of ways to move an object from one location to
another. Besides exits (described under 'help goto'), the @teleport,
home, enter, leave, get, drop, and give commands all cause objects to
move.
A number of steps occur whenever an object is successfully moved. Not
all types of movement cause all of these steps to be executed. These
"generic" steps are described in this help entry; the individual help
entries of movement commands detail which of these steps they use, and
when. (If an attribute is non-existent, nothing is shown/done.)
Continued in 'help Moving2'.
& @move
& @omove
& @amove
& Moving2
These steps are:
- The mover leaves its current location. ('help Movement Leave')
- The mover's destination is registered. ('help Movement Register')
- The mover enters its destination. ('help Movement Enter')
- Mover contents set KEY are sent home. ('help Movement Key')
- The old room's drop-tos are activated. ('help Movement Drop-To').
In all of these help entries, the moving object is referred to as the
"mover", the location being left is referred to a the "old room", and
the location being moved into is referred to as the "destination".
Whenever an object moves, its @move verb set is run at some point
in time during the process (see the individual help entries for when
this occurs for each command). An example @move verb set:
@move me = You fly off.
@omove me = flies off.
@amove me = &LAST_MOVED me = [time()]
& Movement Leave
Topic: Movement (object leaves its current location)
- The mover is shown the @leave attribute set on the old room, unless
the configuration parameter terse_shows_move_messages is disabled
and the mover is set TERSE.
- This leave is considered "quiet", if the /quiet switch was specified
to the movement command, or if none of the following is true:
- The old room has Wizard privileges.
- Neither the old room, nor the mover, are Dark.
- The mover can hear (see 'help Hearer') and is not a Dark Wizard/Cloaker.
- If the leave is not quiet, the @oleave is shown to other objects in the
old room.
- If the leave is not quiet, or the /quiet switch was not specified and
the dark_actions configuration parameter is enabled, the old room runs
its @aleave.
Continued in 'help Movement Leave2'.
& Movement Leave2
- If the leave is not quiet, the @oxenter of the destination is shown to
objects in the old room.
- If the move is not quiet, the mover is not Blind, the old room is not
Blind, and at least one of the following is true:
- The mover and the old room are not Dark.
- The mover can hear, and is not a Dark Wizard/Cloaker.
then objects in the old room see "<mover> has left."
& Movement Register
Topic: Movement (object's new location is registered)
- The mover's location is changed, i.e., the value returned by
'loc(<mover>)' becomes the dbref of the destination.
- The mover looks at its new location, just as if it had typed 'look here'.
(See 'help look' for a description of what that entails.)
- If the mover is a player, the mover has less money than is specified
by the configuraton parameter earn_limit, then the mover has a percentage
chance equal to the find_money_chance configuration parameter, to get
a single unit of money, receiving the message, "You found a <coin>!"
& Movement Enter
Topic: Movement (object enters its new location)
- The mover is shown the @enter attribute set on the destination, unless
the configuration parameter terse_shows_move_messages is disabled
and the mover is set TERSE.
- This enter is considered "quiet", if the /quiet switch was specified
to the movement command, or if none of the following is true:
- The old room has Wizard privileges.
- Neither the old room, nor the mover, are Dark.
- The mover can hear (see 'help Hearer') and is not a Dark Wizard/Cloaker.
- If the enter is not quiet, the @oenter is shown to other objects in the
destination.
- If the enter is not quiet, or the /quiet switch was not specified and
the dark_actions configuration parameter is enabled, the destination
runs its @aenter.
Continued in 'help Movement Enter2'.
& Movement Enter2
- If the enter is not quiet, the @oxleave of the old room is shown to
objects in the destination.
- If the move is not quiet, the mover is not Blind, the old room is not
Blind, the mover can hear, and the mover is not a Dark Wizard/Cloaker,
then objects in the destination see "<mover> has arrived."
& Movement Key
Topic: Movement (object contents set KEY are sent home)
For each object that is carried by the target (normally the mover): If
the target does not control the object, and the object is set KEY,
then the object is sent home.
& Movement Drop-To
Topic: Movement (drop-tos are activated)
The old room's drop-to is activated if all the following criteria
apply:
- The old room is of type ROOM.
- The old room has a valid drop-to. (See 'help @link'.)
- The old room is set STICKY.
- None of the objects that are in the room can hear (see 'help Hearer')
and are owned by connected players.
If the drop-to is activated, then all objects in the old room are
sent to the drop-to location (the room that the old room is @link'd to),
except for objects that are set STICKY, which are sent home instead.
Objects sent through a drop-to also lose any KEY contents (as per
'help Movement Key').
& @drop
& @odrop
& @adrop
See 'help drop' and 'help goto'.
& news
Command: news [<topic>]
Shows you the current news for the MUSH. It is highly recommended that
you check the news daily for new information. Otherwise, the wizards will
have no pity on you for messing up with the new commands.
& OUTPUTPREFIX
Command: OUTPUTPREFIX <string>
Causes <string> to be output on a line by itself before printing the
results of each command. This command is intended for use by external
robot programs, and may be restricted to players whose ROBOT flag is set.
The OUTPUTPREFIX command must be entered in all capitals.
See also; @robot, OUTPUTSUFFIX, ROBOT.
& OUTPUTSUFFIX
Command: OUTPUTSUFFIX <string>
Causes <string> to be output on a line by itself after printing the results
of each command. This command is intended for use by external robot
programs, and may be restricted to players whose ROBOT flag is set.
The OUTPUTSUFFIX command must be entered in all capitals.
See also; @robot, OUTPUTPREFIX, ROBOT.
& page
Command: page <list of players> = <message>
page = <message>
page <message> [if conf param page_requires_equals is 'no']
This command sends <message> to a list of players. If you do not specify
a player list, it defaults to the players you last paged. You may use
any combination of player names, player aliases, or partial names (strings
that uniquely match the start of a connected player's name).
If <message> begins with ':' or ';', it will be treated as a page-pose.
The recipients will see, "From afar, <your name> <message>" if you used
a ':', and "From afar, <your name><message>" if you used a ';'.
If <message> begins with '"', the " is ignored, and the rest of
the message paged normally.
If the /noeval switch is specified, functions and percent-substitutions
are not evaluated.
Continued in 'help page2'.
& page2
If your Idle attribute is set, and someone successfully pages you,
they are shown the contents of that attribute. This is useful when
you are away from your keyboard for a short while.
You can prevent certain players from paging you (or @pemit'ing to
you) with a PageLock. When someone attempts to page you or @pemit
to you, your PageLock is checked; if that person does not pass the lock,
they won't be able to do so. If you a Reject attribute set, they will
be shown the contents of that attribute.
Some common uses of PageLocks:
@lock/page me = =*Figment (Only Figment can page you.)
@lock/page me = !=*Figment (Everyone can page you, except for Figment.)
@lock/page me = !$*Figment (Figment and things he owns can't page you.)
@unlock/page me (Lets everyone page you.)
Continued in 'help page3'.
& page3
If someone tries to page you while you are not connected, and you have
your Away attribute set, they will be shown the contents of that attribute.
There are two special cases.
If you are paging someone, you do not pass their PageLock, their
connection is hidden (they are a Wizard, or have the Hide power, and
are set DARK), and you cannot see players whose connections are hidden
(you are not a Wizard or Royalty, and do not have the See_Hidden power),
you will be given their Away message rather than their Reject message.
If you are not a Wizard, you cannot page someone unless they can page
you back (i.e., you must not be page-locked against them). If you are
a Wizard, you can page someone who can't page you back, but you will
be warned that they can't page you back.
See also: @pemit, @lock
& :
& ;
& pose
Command: pose[/<switch>] <message>
:<message>
;<message>
Displays <message> to everyone in your current room, preceded by your name
and optionally a space. If you use the ':' command abbreviation, the
<message> is preceded by your name and a space; if you use the ';'
command abbreviation, or you use ': <message>' (rather than ':<message>'),
the <message> is preceded by your name, without a space.
Available switches:
/default - (default) Put a space between your name and the message
(i.e., display '<name> <message>').
/nospace - Don't put a space between your name and the message
(i.e., display '<name><message>').
/noeval - Don't evaluate <message>.
Continued in 'help pose2'.
& pose2
Examples:
> pose jumps for joy.
> :jumps for joy.
Figment jumps for joy.
> pose/nospace 's balloon pops.
> ;'s balloon pops.
> : 's balloon pops.
Figment's balloon pops.
See also: say, @emit
& PUEBLO
Topic: Pueblo
Pueblo is an HTML-based MU* client available from www.chaco.com.
Unless compiled without Pueblo support (on by default), TinyMUSH provides
these features to enable the use of Pueblo and HTML:
Commands: PUEBLOCLIENT @htdesc @vrml_url
Switches: @emit/html @pemit/html
Functions: html_escape() html_unescape()
url_escape() url_unescape() (see Pueblo Functions)
Flags: HTML
Attr flags: html
When you connect with Pueblo, it automatically uses the PUEBLOCLIENT
command to set your HTML flag. This causes most output from the mush
to be escaped into HTML that Pueblo can display. If you want to write
arbitrary HTML on the mush and have it sent unescaped to Pueblo users,
you'll need to apply the html attribute flag (see @htdesc for an
example).
& PUEBLOCLIENT
Command: PUEBLOCLIENT
This command notifies the MUSH that one is using a client that supports
the Pueblo extensions. Such a client normally sends this string
automatically; users probably will never need to type this.
See also: Pueblo.
& QUIT
Command: QUIT
Logs you out and disconnects you from the game. Must be in all capitals.
See also: LOGOUT.
& #
Command: #<number> <command>
Forces the object whose database number is <number> to perform <command>.
Example: '#1033 move north' forces object #1033 to go north (assuming that
you control it). The same restrictions that apply to @force also apply to
this command.
See also: @force.
& "
& say
Command: say[/noeval] <message>
"<message>
Says <message> out loud to everyone in your current room.
If you use say/noeval, the message is not evaluated.
You will see: You say, "<message>"
Everyone else in your location will see: <your name> says, "<message>"
Depending on how the MUSH is configured, it's possible that you as
well as everyone else will see: <your name> says, "<message>"
Also depending on MUSH configuration, the grammatically-correct comma
might not be present; this is true for historical reasons.
See also: pose, @emit
& score
Command: score
Displays how much money you have. Helpful to see if any machines are
looping.
See also: @ps, LOOPING.
& SESSION
Command: SESSION [<prefix>]
Displays detailed information on network sessions (connected players).
This can be useful when attempting to identify network problems.
Wizards, Royalty and those with the expanded_who power can see the
session information for all players (or for those players whose names
start with <prefix>); mortals can only see their own sessions.
Example:
> SESSION
Characters Input---- Characters Output---
Player Name On For Idle Port Pend Lost Total Pend Lost Total
Mortal 00:06 0s 16 0 0 44 156 0 2679
2 Players logged in.
The port is the file descriptor number of the connection; it can be used
by MUSHcode to reference specific connections.
Pending characters are those waiting to be acted on as commands (for input)
or waiting to be sent out over the network (output). Lost characters are
caused by overflowing the MUSH's input or output buffers.
Continued in 'help Session2'.
& SESSION2
A nonzero Input Pending count can indicate type-ahead or a client program
sending commands faster than the command scheduling parameters let them be
executed. Telnet sessions in character mode also show up with positive
Input Pending counts when the player is in the middle of typing a command.
A persistently large Output Pending count can indicate network issues
between the MUSH's site and the player's computer; alternatively, it
can mean that the player has performed a command that generated a lot of
output that hasn't been setn yet. The player performing the SESSION will
always have a non-zero Output Pending, since the output of the SESSIO
itself hasn't been sent out over the network yet.
A nonzero Input Lost count means that the player has typed a line longer
than what the MUSH can handle. This probably indicates a problem with
the player's client or terminal, such as accidental large cut-and-paste
or a stuck key on the keyboard, though deliberate malice is a possibility.
Continued in 'help Session3'.
& SESSION3
A nonzero Output Lost count normally indicates that the player performed
one or more commands that generated a great deal of output -- more than
the output buffer could hold. This may be the result of attempting to
examine a very large object, for isnstance. It may also indicate network
problems, or that the player is generating output faster than the network
or his client can process it.
See also: session(), ports(), WHO.
& think
Command: think <message>
You can use this command to send a private message to yourself. The
<message> string is evaluated. This command is equivalent to
'@pemit me = <message>'.
See also: @pemit, @eval
& @ause
& @ouse
& @use
& use
Command: use <object>
Uses <object>. Some objects will do interesting, useful, or dangerous
things when used; for instance, using a camera might result in a
picture being taken. Use of this mechanism has largely been superseded
by use of $-commands on objects.
Using an object runs its @use verb set: the player using the object
sees its @use message, the others in the player's location sees the
object's @ouse message with the player's name prepended, and the object
triggers its @ause action set.
Example of a @use verb set:
@use toy duck = You squeeze the rubber ducky. SQUEAK! It is now squished.
@ouse toy duck = squeezes the rubber ducky. SQUEAK!
@ause toy duck = @name me = Squished Rubber Ducky
& version
Command: version
Displays the version of MUSH that is running, the date it was last
compiled, the options it was compiled with, and a list of loaded
modules.
& whisper
Command: whisper <mobile> = <message>
Sends a message to a nearby object. Only that object will see the message.
Unlike page and @pemit, this command is not subject to PageLock checks.
If <message> begins with ':' or ';', it will be treated as a whisper-pose.
The recipient will see "You sense <your name> <message>" if you used a ':',
and "You sense <your name><message>" if you used a ';'. If <message>
begins with '"', the " is ignored, and the rest of the message whispered
normally.
See also: page, pose, say, @emit
& WHO
Command: WHO [<prefix>]
Displays a list of players currently connected to the MUSH. If
<prefix> is specified, only players whose names start with <prefix>
are listed.
The WHO report tells you how long a player has been connected for
(note that those who disconnect via LOGOUT keep their connect times),
and how long it's been since they last typed something. It also
shows a text message for each player, which they set via the @doing
command.
Wizards, Royalty, and those with the expanded_who power see a
different display with this command -- see 'wizhelp WHO' for details.
See also: @doing.
& &
Command: &<attribute> <object>[=<value>]
Synonym: @set <object> = <attribute>:[<value>]
Sets the attribute named <attribute> on <object> to <value>. If
<attribute> is not a predefined attribute (like ofail or va), then it is
created. Attributes so created are called user-named attributes.
Attribute names may only contain letters, numbers, and the characters
< -_.@#$^&*~?=+| >, and must start with a letter. The names of user-named
attributes may not be abbreviated (an attempt to get the value of the
attribute will fail, and an attempt to set will create a new attribute).
The & command may be used to set predefined attributes (in this instance,
'&<attr> <object>=<value>' is equivalent to '@<attr> <object>=<value>').
See also: @set.
& @@
Command: @@ <args>
This command does nothing. Thus, it's useful for putting comments into
MUSH program. Be careful that ()'s and {}'s in the (otherwise ignored)
arguments are nested correctly, lest your command-ending ; be trapped
inside.
Example:
@va me = $foobar *: @fo #1234=%0; @@ This controls my foobar puppet.
& @chown
Command: @chown[/nostrip] <object>[=<player>]
@chown <object>/<attr>[=<player>]
The first form changes the ownership of <object> to <player> (default is
to yourself). Objects may be things, rooms or exits. Unless you are a
Wizard or have the chown_anything power, the object you are @chown'ing
must have the CHOWN_OK flag set, and you must be able to pass its
ChownLock.
If you are neither a Wizard nor have the chown_anything power, to @chown
a thing, you must be carrying it, and refer very specifically to that
object, and to @chown a room, you must '@chown here = me'. Players cannot
be @chown'd; they always own themselves (unless they are robots).
@chown'ing an object automatically sets it HALT. If the /nostrip switch
is not specified, the objects is also stripped of all powers and special
flags (such as WIZARD, INHERIT, etc., as defined by a conf parameter;
see 'wizhelp stripped_flags' for details). If /nostrip is specified
by God, special flags and powers are not stripped; if anyone else
specifies /nostrip, only the WIZARD flag and powers will be stripped.
Continued in 'help @chown2'.
& @chown2
When an object is @chowned, all unlocked attributes on the object are
automatically @chowned as well, locked attributes remain owned by their
original owners.
The second form changes the ownership of the indicated attribute on <object>
to <player> (default is the owner of the object). You may only @chown
unlocked attributes. You may @chown unlocked attributes on objects that
you own to yourself, and you may also @chown attributes that you own on
objects owned by others to the owner of the object.
See also: @lock, @unlock, CHOWN_OK, ATTRIBUTE OWNERSHIP.
& @chzone
Command: @chzone[/nostrip] <object>[=<zone object>]
Changes the zone of <object> to <zone object>. If <zone object> is not
specified, the zone is reset to NOTHING. (If the <zone object> is "none",
the zone is also reset; this is a compatibility feature.)
@chzone'ing a player does not automatically change the zone of their
objects. Anyone may reset the zone of their own object, or re-zone it
to a zone object that they control. Only Wizards may @chzone an object
to an arbitrary zone object. Players may @chzone themselves to an
object they own; otherwise, only Wizards may @chzone players.
@chzone'ing a non-player object strips special flags (such as WIZARD,
INHERIT, etc.) from the object, as well as all powers, unless the
/nostrip switch is specified. If /nostrip is specified by God, special
flags and powers are not stripped; if anyone else specifies /nostrip,
only the WIZARD flag and powers will be stripped.
See also: ZONE OBJECTS
& @aclone
& @clone
Command: @clone[/<switches>] <object>[=<newname/cost>]
Creates an exact duplicate of <object> that is owned by you and (for things
and exits) puts it in your current location. You may have the object put
in your inventory (or your exitlist in the case of cloning exits) by using
the /inventory switch.
You may clone your own objects, plus VISUAL objects owned by others.
If <newname> is specified, it is used as the name instead of the
original name.
Object clones do not receive the powers of the original. Cloning does
duplicate flags, except for certain special flags (such as WIZARD,
INHERIT, and IMMORTAL). The INHERIT flag is not copied unless the
/inherit switch is specified. Other special flags are not copied to
the clone unless the /nostrip switch is specified (Wizards only).
Even if /nostrip is specified, the WIZARD flag is only copied if
you are God.
Continued in 'help @clone2'.
& @clone2
You own the clone, unless you specified the /preserve switch; if you
did so, and you control the owner of the original object, then the
clone will have the same owner as the original object.
If you clone a linked exit, an attempt is made to link the clone to the
same location. Except when using the /inventory switch, you can only clone
exits when you own your current location.
If you clone a room with a drop-to, an attempt is made to link the drop-to
to the same location.
If the owner of the new object is the same as the owner of the original
object, the new object will run its @aclone attribute. Otherwise, the
new object is set HALT.
The exits and contents of cloned objects are not cloned (i.e., cloning
is never recursive).
Continued in 'help @clone3'.
& @clone3
The following switches are available:
/cost - Treat the argument after the = as the cost of the new
object, not the name.
/inherit - Don't reset the INHERIT bit on the new object.
/inventory - Create the new object in your inventory (or your exitlist,
in the case of cloning exits).
/location - Create the new object in your location (default).
/nostrip - Don't strip special flags and powers from the clone.
(Wizards only.)
/parent - Set the new object's parent to be the template object and
don't copy the attributes.
/preserve - Keep the clone's owner the same as the original object's
owner. You must control the original object's owner.
Continued in 'help @clone4'.
& @clone4
Example @aclone:
@aclone Time Bomb = @wait 600=@trig me/va; @wait 10=@trig me/vb
@va Time Bomb = :EXPLODES with a thundering roar.; @destroy/instant me
@vb Time Bomb = :ticks.; @wait 10=@trig me/vb
See also: @create, @decompile, @destroy, VISUAL.
& @cpattr
@cpattr [<obj>/]<wild> = <obj1> [,<obj2>,<obj3>,...]
@cpattr [<obj>/]<wild> = <obj1>/<attr1> [,<obj2>/<attr2>,<obj3>/<attr3>,...]
The first form of this command copies attributes that match <wild>
wildcard pattern on <obj> (assumed to be the calling object, 'me',
if not explicitly specified), to the target objects specified in a
comma-separated list. The names of the attributes on the targets will
be the same as the original.
The second form of this command is used to copy attributes that match
<wild> on <obj> (assumed to be 'me' if not specified) to the target
object-attribute pairs specified in a comma-separated list. Note that
if <wild> matches multiple attributes, the last one is the one that
will end up set on the target objects.
For example, '@cpattr test/va = test/vb, cube/va, tribble/foo'
would copy the VA attribute from object "test" to VB on "test",
VA on "cube", and FOO on "tribble".
<objN> is matched as if you were performing a @set on it.
& @create
Command: @create <name> [=<cost>]
Creates a thing with the specified name. Creation costs either <cost>
or 10 coins, whichever is greater. The value of a thing is proportional
to its cost, specifically, value=(cost/5)-1. The value may not be greater
than 100, values that would be greater than 100 are rounded down to 100.
See also: @destroy, TYPES OF OBJECTS.
& @cron
Command: @cron <object>/<attribute> = <timestring>
This command causes <object> to execute the contents of <attribute>
(just as if a '@trigger <object>/<attribute>' had been done), at the
times specified by <timestring>. You must control <object> and be
able to read <attribute>.
The syntax of the @cron <timestring> is virtually identical to that of
Unix cron; it's a list of five space-separated fields, as follows:
<minute> <hour> <day of month> <month> <day of week>
Each component of <timestring> is the asterisk ('*'), or a
comma-separated list of numbers or number ranges (i.e., '5-7').
For instance, '2,5-7,10' means '2, 5, 6, 7, and 10'. The restrictions
on numbers is as follows: <minute> is a number between 0 and 59,
<hour> is a number between 0 and 23 (equivalent to 12 am to 11 pm),
<day of month> is a number between 1 and 31, <month> is a number
between 1 and 12 (January through December), and <day of week> is
a number between 0 and 6 (Sunday through Saturday).
Continued in 'help @cron2'.
& @cron2
The specification of a day may be made by either day of week, or day
of month. If both are specified, both are adhered to. In other words,
'0 3 1,15 * 2' indicates that the task is scheduled for 3 am on
Tuesdays, as well as the 1st and 15th of each month.
The '*' and ranges can be modified with a '/<number>', indicating the
"step size". For instance, '*/2' is equivalent to '0,2,4,6,8,10,12,...'
(up to 58), and '11-20/3' is equivalent to '11,14,17,20'.
Examples of timestrings:
Run every hour, on the hour: 0 * * * *
Run once every month, at 3:10 am the 1st: 10 3 1 * *
Run every fifteen minutes: 0,15,30,45 * * * * (also valid: */15 * * * *)
Run every five minutes starting at 3 past the hour: 3-59/5 * * * *
Run once a day, at 6 am: 0 6 * * *
Cron entries are not preserved over restarts. To make a cron entry
'permanent', it should be entered as part of a @startup on an object.
See also: @crondel, @crontab, @daily
& @crondel
@crondel <object>[/<attribute>]
If no <attribute> is specified, this command removes all cron entries
for <object>. If <attribute> is specified, this command removes all
cron entries associated with that object and attribute. You must
control <object>.
See also: @cron, @crontab, @daily
& @crontab
@crontab [<object>]
If <object> is specified, this command shows the cron entries
associated with that object. You must control <object>.
If <object> is not specified, this command shows all cron entries
(if you are a Wizard, Royalty, or have the see_queue power) or
all cron entries for objects you own (if you are not any of the
above).
See also: @cron, @crontab, @daily
& @decompile
Command: @decompile <object>[/<wildcard>] [=<newname>]
This dumps the sequence of commands needed to recreate that object. It
is useful for keeping off-MUSH records of your valuable objects, and for
transferring code from one MUSH to another. If you specify <newname>, then
the commands dumped will set attributes, locks, and flags on an object named
<newname> and will omit the command to create the object.
If <wildcards> are specified, only the specific attributes for the object
will be printed in decompile format. This allows you to decompile objects
that are larger than the output buffer limit, as well as simply decompile
parts of objects; if a wildcard pattern is given, only attributes will be
dumped (no flags, etc.) The wildcard pattern is identical to the type
used by the 'examine' command and the 'lattr()' function.
& @destroy
Command: @destroy[/<switches>] <object>
This command destroys <object> and refunds its cost of creation to its
owner. You must own <object> in order to @destroy it, unless its
DESTROY_OK flag is set, in which case anyone holding it may @destroy it.
Rooms, exits, and objects may be destroyed. The actual destruction is
delayed for up to ten minutes (or more, depending on the MUSH's specific
configuration); the GOING flag is set on these objects. Clearing the
GOING flag on the object spares it from destruction. Depending on the
configuration of the MUSH, DESTROY_OK objects may be an exception,
and would get immediately destroyed.
The @destroy command will not destroy objects with the SAFE flag set unless
the /override switch is specified. The DESTROY_OK flag overrides the
protection given by the SAFE flag. Players are always considered SAFE.
Objects not owned by the destroyer may be considered SAFE, depending
on the MUSH configuration (see 'wizhelp unowned_safe').
The following switches are available:
/instant - Immediately destroy the object.
/override - Negate protection offered by the SAFE flag.
See also: DESTROY_OK, SAFE.
& @dig
Command: @dig[/<switches>] <name> [= <exitlist> [, <exitlist>] ]
Creates a new room with the specified name and displays its number. This
command costs 10 coins. If the [= <exitlist>] option is used, an exit will
be opened from the current room to the new room automatically. If the
second <exitlist> option (after the comma) is specified, an exit from the
new room back to the current room with the specified [Exits] name is
opened. Either exit creation may fail if you do not have sufficient
rights to the current room to open or link the new exit.
Example: The command
@dig Kitchen = Kitchen;k;north;n,south;s
will dig a room called Kitchen, and open an exit called 'Kitchen' in your
current room. The ; symbol means that you may enter the exit by typing
'k', 'north' or 'n' also. This command also opens the exit 'south;s' from
'Kitchen' back to where you are. Only the first Exit name is displayed in
the Obvious exits list.
If you specify the /teleport switch, then you are @teleported to the
room after it is created and any exits are opened.
See also: @destroy, @link, @open, LINKING, TYPES OF OBJECTS.
& @doing
Command: @doing[/<switches>] [<message>]
Sets your doing message, which appears after your name in the WHO report.
The following switches are available:
/message - Sets your Doing string in the WHO report. (default)
/poll - Displays the current Doing poll from the WHO report.
/header - Wizards and those with the Poll power only. Sets the Doing
poll. If <message> is not specified, the header is reset
to Doing.
/quiet - Suppress 'Set.' notification. This switch can be used by
itself, or with either the /message or /header switches.
See also: WHO.
& @iter
& @dolist
Command: @dolist[/<switches>] [<delimiter>] <list>=<action>
<list> is a list of strings, which can be object numbers, attributes, or
arbitrary words. <action> is a command to perform once for each item in
<list>, replacing the special symbol ## with the corresponding item from
<list>, and the special symbol #@ with the position of the item in the
list. . By default, @dolist considers each item in <list> to be separated
with spaces. If you specify the /delimit switch, then each item is
considered to be separated by <delimiter>. <delimiter> must be a single
character.
Supported switches are:
/space - (Default) List elements are separated by spaces.
/delimit - List elements are separated by <delimiter>.
/notify - Queues a "@notify me" after all the @dolist'd commands.
/now - Commands are run immediately rather than placed on the queue.
'@iter' is the same as '@dolist/now'.
Continued in 'help @dolist2'.
& @dolist2
This command is particularly handy with lcon() and lexits(). A few examples:
@dolist [lcon(here)] = "[name(##)](##)
@dolist [lcon(here)] = @switch [get(##/last)]=*1990*,"[name(##)]
@va me = va vb vc
@dolist [get(me/va)] = @emit [get(me/##)]
@dolist 2 3 4 5=@emit [add(#@,##)]
@dolist Frodo Bilbo Gandalf = page ## = HELP!!!! I've fallen into a pit.
@dolist/delimit , {Frodo, Bilbo Baggins, Gandalf} = page ## = HELP!!!!
See also: iter(), DELIMITERS.
& @drain
Command: @drain <object>
Discards all commands waiting on the semaphore <object> and resets the
semaphore to its initial state.
See also: @notify, @ps, SEMAPHORES
& @edit
Command: @edit <object>/<wild-attr> = <search>,<replace>
@edit <object>/<wild-attr> = ^,<text>
@edit <object>/<wild-attr> = $,<text>
This command edits the contents of one or more attributes of an object,
eliminating the need to retype a long attribute in order to make a simple
change. In the first form, all occurrences of <search> in the specified
attribute of the named object are replaced with <replace>. Use curly
braces ({ and }) around <search> or <replace> if they contain commas.
The second and third form prepend and append <text> to the selected
attributes, respectively.
The output of this command ANSI-hilites the portion of the string
that was altered. Note that if there are already ANSI characters in
the string, the results of this highlighting may not reflect the
actual state of the edited string (since the highlight, by definition,
inserts a terminating ANSI 'normal' string).
If <wild-attr> contains wildcard characters, then all attributes that
match are edited.
See also: edit()
& \\
& @emit
Command: @emit[/<switches>] <message>
\<message>
This command shows <message> to everyone in your current location.
Available switches:
/here - (default) Shows the message to everyone in the same location
as you.
/room - Shows the message to everyone in your 'absolute location'.
(See 'help Location' for details.)
/noeval - Don't evaluate <message>.
/html - (Pueblo only) Shows the output in HTML format.
See also: @femit, @oemit, @pemit, NOSPOOF
& @entrances
Command: @entrances [[<object>][,<low>[,<high>]]]
Lists links from elsewhere to the specified object (default: your current
room). For rooms, exits and drop-to's, leading to the room and players
and objects whose home is in the room are listed. For players and objects,
lists exits leading to them. Because this command is computationally
expensive, it costs 100 coins. <low> and <high> can be used to indicate
where to start and stop the search, respectively.
You may only use this command on objects that you control.
Examples:
> @entrances <- all links to here
> @entrances object <- all links to object
> @entrances ,100,200 <- all links to here from #100 to #200
> @entrances me,1000 <- all links to me from #1000 and above.
See also: @link, @unlink.
& @eval
Command: @eval <arg>
This command does nothing other than evaluate <arg>, making it useful
for executing side-effect functions.
Example:
@va me=$test *: @eval [set(me,TEST:Set to %0)][pemit(%#,Testing %0.)]
& @femit
Command: @femit[/<switch>] <obj> = <message>
Forces <obj> to emit <message>. This command is similar to the command
'@force <obj> = @emit <message>', except that it will work so long as
you own the object, whereas @force may fail if the object has its INHERIT
flag set and the object performing the @force does not.
Available switches:
/here - (default) Sends the message to everyone in the same location
as <obj>.
/room - Sends the message to everyone in <obj>'s absolute location.
(See 'help Location' for details.)
/noeval - Don't evaluate <message>.
/spoof - Make <obj> the enactor.
See also: @emit, @fpose, @fsay, @force
& @fpose
Command: @fpose[/<switch>] <obj> = <message>
Forces <obj> to pose <message>. This command is similar to the command
'@force <obj> = :<message>', except that it will work so long as you
own the object, whereas @force may fail if the object has its INHERIT flag
set and the object performing the @force does not.
Available switches:
/default - (default) Put a space between the name of the object and
the message (i.e., send '<name> <message>').
/nospace - Don't put a space between the name of the object and the
message (i.e., send '<name><message>').
/noeval - Don't evaluate <message>.
/spoof - Make <obj> the enactor.
See also: @femit, @fsay, pose, @force
& @fsay
Command: @fsay[/<switch>] <obj> = <message>
Forces <obj> to say <message>. This command is similar to the command
'@force <obj> = "<message>', except that it will work so long as you
own the object, whereas @force may fail if the object has its INHERIT
flag set and the object performing the @force does not.
Available switches:
/noeval - Don't evaluate <message>.
/spoof - Make <obj> the enactor.
See also: @femit, @fsay, say, @force
& @find
Command: @find <name>[,<low>[,<high>]]
Displays the name and number of every room, thing, or player that you
control whose name matches <name>. Because the command is computationally
expensive, it costs 100 coins.
<low> and <high> may be used to restrict the range of objects that are
searched, if they are given then the search starts at object #<low> and ends
at object #<high>.
Examples:
> @find Lost Room
> @find Secret Device,12000,14000
See also: @search.
& @floaters
Command: @floaters[/all] [<player>]
Displays the name, dbref, and flags of "floating rooms", rooms that are
not connected via any exit paths to the starting room. Because this
command is computationally expensive, it costs what a @search costs.
If you do not specify the /all switch, or the name of a player, this
searches only for floating rooms owned by you.
If you specify the name of a player, this searches for floating rooms
owned by that player. You must control the player, or have permissions
to search anyone.
If you have permissions to search anyone, you can specify the /all
switch, which searches for all floating rooms in the database.
& @force
Command: @force[/<switch>] <player/object>=<command>
Forces the game to act as though <player/object> had entered <command>.
You may only force objects that you control. Objects may not force players
unless either the object or the player has their INHERIT flag set, and
objects that do not have their INHERIT flag set may not force objects that
do. If the victim is specified by number, you may use an alternate form
of the command, '#<number> <command>'.
If the /now switch is used, the command is run immediately rather than
being placed on the queue.
See also: puppets.
& @halt
Command: @halt[/<switches>] [<object | player>]
If the command '@halt' is given by itself, the player and all of his
objects that are currently running commands will be halted.
If the command '@halt <object>' is given, that object will be halted.
You must control <object>, or have the Halt power.
If the command '@halt <player>' is given, that player and all of his
objects that are currently running commands will be halted. You must
control <player>, or have the Halt power.
If the command '@halt/all' is given, all objects that are currently
running commands will be halted.
Use this command to stop runaway objects and infinite loops. The process
of halting an object involves removing all commands waiting to be run by
the object from the queue and refunding the queue deposit. The object
will also be set HALTED. Halting an object does not affect commands waiting
on it as a semaphore; use the @drain command to reset a semaphore.
See also: @drain, @notify, kill, HALTED, SEMAPHORES.
& @last
Command: @last <player>
This command displays a short 'connection history' for <player>, showing
recent successful and failed connection attempts, as well as the total
number of successful and failed connections.
You can only display information about yourself.
& @link
Command: @link <object>[=<dbref> | here | home | variable]
When used on a player or a thing, this command sets the object's home
to the indicated location. The destination must be owned by you or be an
ABODE room, or you must have the link_any_home power.
When used on a room, this command sets the room's drop-to, where objects
dropped in the room go. The destination must be a room that is either owned
by you or is LINK_OK.
For exits, this command sets the destination if the exit is currently
unlinked, and you control the destination or it is set LINK_OK. You can
@link an unlinked exit regardless of who owns it or the lock set on it;
you are made the owner if you successfully link to the destination.
Exits can also be linked to the special keyword "variable". The exit's
destination is determined by evaluating the ExitTo attribute on the exit,
when a player attempts to move through the exit. Only Wizards and those
with the link_variable power may link exits in this way, since it allows
the exit to essentially be linked to any destination.
{ 'help @link2' for more }
& @link2
Linking an exit costs 1 coin, and if the exit was owned by someone else,
you also reimburse the the former owner 1 coin (making the total cost to
you 2 coins).
If you are not a Wizard and do not have the link_to_anything power, in
order to link to an exit to a destination, you must pass its LinkLock
(even if you are the owner of that destination). Depending on the server
configuration, even Wizards might not be able to ignore LinkLocks.
Note that in all the above cases that it is the player performing the @link
command that must pass the LinkLock, not the object being linked.
Therefore, you should use the '$' lock qualifier if you want to prevent
specific players from linking to your LINK_OK locations, as simply locking
against '*<playername>' does not lock out their puppets.
See also: @dig, @open, @unlink, @exitto, DROP-TOS, HOMES, LINKING.
& @list
Command: @list [<option>]
Lists information from internal databases. Information is available
about the following options:
attributes - Valid object attributes.
attr_types - Default flags set on user-defined attributes
whose names match specific patterns.
commands - Commands that you may use (excluding the
attribute-setting commands as well as any exits, and
$-commands available).
config_read_perms - Config parameter read permissions (most will be blank,
meaning that anyone can read those parameters).
costs - The costs associated with many commands and actions.
default_flags - The flags that new objects receive by default
when created.
flags - The names and letters of all the flags.
functions - All the available functions.
Continued in 'help @list2'.
& @list2
options - Several global yes/no options.
params - Several global options and limits.
switches - What commands support switches and the switches
that they do support.
The information provided by the @list command is definitive, as it reads
the internal tables to produce the information it displays. Specifying
@list with no argument lists the options you may use.
Wizards have access to additional @list options; see 'wizhelp @list'.
& @listmotd
Command: @listmotd
Displays the current message-of-the-day. Note that it is displayed when
you connect to your character.
Wizards will also see the other specialized message-of-the-days.
See 'wizhelp param messages' for details.
& Locks
Locks are constructs that control the ability to do certain things,
such as move through an exit, or use an object. Every object can have
one lock of each type. Each lock's "key" is a string representing the
conditions under which the lock can be passed. Passing a lock is
considered "success"; failing to pass a lock is considered "failure".
Locks are set with the command '@lock[/<lock type>] <object> = <key>',
and unset with the command '@unlock <object>'.
Type 'help @lock keys' for an explanation of the syntax of lock keys.
Type 'help @lock locks' for a list of the different types of locks.
& @lock
Command: @lock[/<whichlock>] <object>=<key>
@lock <object>/<attrib>
The first form locks <object> to a specific key(s). Type 'help @lock keys'
for a list of the keys you may use.
<whichlock> indicates which lock you want to set on the object. If you
don't specify one, you set the Default lock. Type 'help @lock locks' for
a list of the locks you may set and what they are used for.
The second form locks the indicated attribute of the named object, so that
when the object is @chowned, the attribute will remain owned by you.
It may also be used when you own an attribute on an object that you do not
own, in this case it prevents the object's owner from @chowning the
attribute to himself, and prevents anyone from modifying or removing the
attribute.
See also: @chown, @unlock.
& @lock locks
You can set the following locks:
DefaultLock: Exits: controls who may traverse the exit to
its destination.
Rooms: controls whether the player sees the SUCC
or FAIL message for the room following the
room description when looking at the room.
Players/Things: controls who may GET the object.
ChownLock: All: controls who may @chown the object if the
object is CHOWN_OK.
ControlLock: All: controls which objects can Control this
object (only checked if CONTROL_OK flag
is set).
DarkLock: All: controls who is affected by the DARK
flag set on the object. If the object
is set DARK and you pass the DarkLock
(or if the object does not have a
DarkLock), it is Dark to you.
{ 'help @lock locks2' for more }
& @lock locks2
DropLock: Players/Things: controls who may DROP the object.
EnterLock: Players/Things: controls who may ENTER the object if the
object is ENTER_OK.
GiveLock: Players/Things: controls who may give the object.
HeardLock: All: controls who can hear a PRESENCE object.
HearsLock: All: controls what a PRESENCE object hears.
KnownLock: All: controls who can see a PRESENCE object.
KnowsLock: All: controls what a PRESENCE object sees.
LeaveLock: Players/Things: controls who may LEAVE the object.
LinkLock: All but Exits: controls who may link to the location if the
location is LINK_OK (for linking exits or
setting drop-tos) or ABODE (for setting
homes).
MovedLock: All: controls who notices a PRESENCE object's
movement.
MovesLock: All: controls what motion a PRESENCE object sees.
{ 'help @lock locks3' for more }
& @lock locks3
PageLock: Players: controls who may page the player.
ParentLock: All: controls who may make @parent links to the
object.
ReceiveLock: Players/Things: controls who may give things to the object.
SpeechLock: All but Exits: controls who may speak in this location
(only checked if the AUDITORIUM flag is
set on that location)
TeloutLock: All but Exits: controls who may teleport out of the
location.
TportLock: Rooms/Things: controls who may teleport there if the
location is JUMP_OK.
UseLock: All but Exits: controls who may USE the object, GIVE the
object money and have the PAY attributes
run, have their messages heard and possibly
acted on by LISTEN and AxHEAR, and invoke
$-commands stored on the object.
UserLock: All: Not used by MUSH, is intended to be used
in MUSH programming where a user-defined
lock is needed.
& @Lock keys
You may use the following keys when setting locks. For information about
a particular type of key, type 'help @lock <keytype>'.
Key Type Form in @Lock Command
---------- ------------------------------
Normal <object>
Is =<object>
Carry +<object>
Ownership $<object>
Indirect @<object>
Attribute <attribute>:<wildcard-pattern>
+<attribute>:<wildcard-pattern>
=<attribute>:<wildcard-pattern>
Evaluation <attribute>/<value>
Compound <key> & <key>
<key> | <key>
!<key>
( <key> )
& @lock attribute
ATTRIBUTE LOCKS:
Key: <attribute>:<pattern>
+<attribute>:<wildcard-pattern>
=<attribute>:<wildcard-pattern>
You may lock on whether a specific attribute on the player attempting to
pass the lock matches a pattern. Example: '@lock thing=sex:m*' will lock
thing to anyone whose sex starts with an M. Wild cards, greater than and
less than may be used, for example: '@lock a-f=name:<g' will lock the exit
a-f against any one whose name is higher than f.
Both the player testing the lock and every object in his inventory is
checked, the player passes the lock if any of those objects passes the lock.
If the attribute name is prefixed by a = then only the player is checked.
Similarly, if the attribute name is prefixed by a + then only objects in
the player's inventory are tested.
{ 'help @lock attribute2' for more }
& @lock attribute2
Note: you may lock against any attribute, but the locked object must be
able to read the attribute from the player attempting to pass the lock or
the lock will fail.
Examples:
> @lock men's room=sex:m*
> @lock a-f=name:<g
> @lock post office=email:*@*
See also: ATTRIBUTE OWNERSHIP, @lock evaluation.
& @lock evaluation
Topic: EVALUATION LOCKS
Key: <attribute>/<value>
Evaluation locks let you evaluate one of your attributes and compare the
result against a value stored in the lock. The result must be an exact
match (no wildcarding allowed, but uppercase and lowercase are considered
to be the same). When evaluating the attribute the enactor substitutions
(%#/%n/etc) are replaced with information about the player trying to pass
the lock, and 'me' and %! refer to the locked object or exit.
If you call an indirect lock and the indirect lock is an evaluation lock
(or is a compound lock that includes an evaluation lock), then the original
lock object is checked for the attribute first, followed by the object that
has the actual evaluation lock. If there are multiple levels of indirection
the intermediate locks are not checked.
{ 'help @lock evaluation2' for more }
& @lock evaluation2
Examples:
> @lock bank=checkmoney/1
> &checkmoney bank=[gt(money(%#),5000)]
Only people and objects with more than 5000 pennies may pass.
Note: this lock requires wizard privileges to read the worth of other
players.
> @lock divisible_by_five_club = checkdiv/0
> &checkdiv divisible_by_five_club = [mod(mid(%#,2,20),5)]
Only objects whose db-number is divisible by 5 may pass.
See also: @lock attributes.
& @lock indirect
Topic: INDIRECT LOCKS
Key: @<object>
You may reference the lock on another object and use the result of
evaluating that other object's lock. You pass an indirect lock if you
pass the default lock on <object>. This is especially useful if you
have a large number of objects or exits that want to have the same lock,
and you want to be able to update one object and have all the other
locks change at the same time.
<object> is searched for when you enter the @lock command and its
database number is stored in the lock, so something like
'@Lock north=@master.lock' is safe even if you are going to move master.lock
to another location.
Examples:
> @lock master.lock = me
> @lock north = @master.lock
> @lock south = @master.lock
North and south all reference the lock on master.lock, so you may change
the lock on all three exits by changing master.lock.
See also: @lock normal.
& @lock normal
Topic: NORMAL LOCKS
Key: <object>
You pass a normal lock if you either are the named object or if you carry
the named object. <object> may be the name or #number of a thing, a
playername prefixed by an asterisk (*<playername>), 'me', or 'here'.
Examples:
> @lock treasure room = secret key
> @lock private area = me
See also: @lock is, @lock carry.
& @lock is
Topic: IS LOCKS
Key: =<object>
You pass an is lock only if you are the named object.
Example:
> @lock mystical highway = =magic bus
Only the magic bus may travel down the mystical highway. You cannot
travel the highway if you are carrying the bus.
See also: @lock carry, @lock normal.
& @lock carry
Topic: CARRY LOCKS
Key: +<object>
You pass a carry lock if you are carrying the named object.
Example:
> @lock secret passage = +magic bus
You can only traverse the secret passage if you are carrying the
magic bus. The bus cannot enter the passage on its own (perhaps
when you are driving it).
See also: @lock is, @lock normal.
& @lock ownership
Topic: OWNERSHIP LOCKS
Key: $<object>
You pass an ownership lock if you have the same owner as <object>.
Examples:
> @lock mystuff=$me
Only objects you own may use the mystuff exit.
> @lock/page me = !$*TinyJerk
Neither TinyJerk nor any of his objects may page you.
See also: @lock normal.
& @lock compound
Topic: COMPOUND LOCKS
Key: <key> & <key>
<key> | <key>
!<key>
( <key> )
You can make complex locks by combining keys with the logical AND and OR
operators (& and ! respectively), or by using the NOT operator. You
may also group complex locks with parentheses.
Examples:
> @lock exit = me & !me
An impossible lock, nothing can be both you and not you.
> @lock message = me | *recipient
Both you and the player recipient may get the message.
& @mvattr
Command: @mvattr <object>=<old>,<new>[,<copy1>]...
This command moves attributes around on an object. The attribute <old> is
renamed <new> (and is copied to <copy1>, <copy2> and so on if specified).
If you cannot modify the <old> attribute (for instance if you are trying to
move the Last attribute, or if it were owned by another player), then a new
copy is made and the original is not removed.
See also: @set.
& @name
Command: @name <object> = <new name>
Changes the name of <object>. <object> can be a thing, player, exit, or
room, specified as <name> or #<dbref> or 'me' or 'here'.
See '@list options' as to whether or not a player name may contain
spaces.
& @notify
Command: @notify[/<switches>] <object>[/<attribute>][=<count>]
Notifies the semaphore <object>, running the first command that waited on
<object> using the semaphore-wait forms of the @wait command. If <count>
is specified, it indicates the number of times the semaphore is notified.
If there are no commands (or less than <count> commands) pending for
<object>, then subsequent @waits will not block until the semaphore count
reaches zero again. If <attribute> is specified, it notifies commands that
are blocking on an attribute other than the default 'Semaphore'.
The following switches are available:
/first - (default) Notify the first command waiting on the indicated
semaphore (or the first <count> commands).
/all - Notify all commands waiting on the semaphore and reset the
semaphore count to zero. <count> is ignored.
See also: @drain, @ps, @wait, SEMAPHORES
& @npemit
Command: @npemit[/<switches>] <obj>=<message>
Sends the unparsed contents of <message> to <obj>, in a fashion akin
to @pemit. This differs from @pemit/noeval in that <message> is completely
untouched -- no space compression is done.
@npemit can take the same switches as @pemit.
See also: @pemit
& @oemit
Command: @oemit[/<switches>] <mobile> = <message>
Emits <message> to everyone in <mobile>'s location, except for <mobile>.
Available switches:
/noeval - Send the message unparsed.
/speech - Explicitly mark the message as speech, causing PRESENCE
permissions to be checked.
/move - Explicitly mark the message as a movement message, causing
PRESENCE permissions to be checked.
See also: @emit, @pemit
& @pemit
Command: @pemit[/<switches>] <obj> = <message>
@pemit/list[/<switches>] <list of dbrefs> = <message>
Emits <message> only to <obj>, or to <obj>'s contents of the /contents
switch is given. If the /list switch is specified, this emits <message>,
to each object given in the <list of dbrefs>, or if the /contents switch
is also specified, to the contents of each object given in <list of dbrefs>.
If the config parameter pemit_far_players is enabled, objects can @pemit
to players that they are able to page (i.e., subject to PageLocks and
so forth); if it is disabled, objects cannot @pemit to players that are
not in the same location as they are.
If the config parameter pemit_any_object is enabled, objects can @pemit
to any object. Otherwise, objects can only @pemit to objects that they
control, or which are nearby. However, regardless, you cannot @pemit to
the contents of an object that you do not control.
Continued in 'help @pemit2'.
& @pemit2
Available switches:
/object - (default) Send the message to the named object.
/contents - Send the message to the contents of the named object.
/noeval - Send the message unparsed.
/speech - Explicitly mark the message as speech, causing PRESENCE
permissions to be checked.
/move - Explicitly mark the message as a movement message, causing
PRESENCE permissions to be checked.
/html - (Pueblo only) Send the message in HTML format.
/silent - (Provided for PennMUSH compatibility) No effect.
See also: @emit, @oemit, @npemit, page
& @open
Command: @open[/<switches>] <direction list> [=<number>[,<direction list>]]
Creates an exit in the specified direction(s). If <number> is specified,
it is linked to that room. Otherwise, it is created unlinked. You or anyone
else may use the '@link' command to specify where the unlinked exit leads.
Opening an exit costs 1 coin. If you specify <number>, linking costs 1 more
coin. You can specify a second direction list (after the comma), which is
automatically opened in the room that the new exit goes TO and which is
linked back to where you are. I.e. @open north;n=#1234,south;s
would open exit 'north;n' from here to #1234, and an exit 'south;s'
from #1234 to here, assuming you have rights to open exits and link to
the rooms in question.
The following switches are available:
/location - Create the exit in your location (default).
/inventory - Create the exit on yourself.
See also: @dig, @link, LINKING.
& @parent
Command: @parent <object> [=<parent>]
The command sets the parent of <object> to <parent> (or clears the parent
if <parent> is omitted. You must control <object>, and must own <parent>,
or <parent> must be set PARENT_OK.
See also: PARENT OBJECTS.
& PARENT OBJECTS
Topic: PARENT OBJECTS
Parent objects provide a way for several objects to inherit common
attributes, exits, and $-commands from a single object, so that changing
the parent object affects all of its children. When searching for
attributes or exits, first the object itself is checked, then the parent
is checked only if the object does not have what was searched for.
Any attribute the parent object has will be passed down to its children,
if they don't already have one. For instance, if the child object has no
description, it will inherit the description of its parent.
Any exits the parent object has will show up in the exit list of the
child, and may be used as normal exits.
The parent is searched for $-commands as well as the child, unless the
parent is uselocked against the player. The child's attributes take
precedence over the parent's; precedence is checked by attribute name,
NOT by $-command name.
{ 'help parent2' for more }
& PARENT2
Topic: PARENT OBJECTS (continued)
A parent object may itself have a parent, up to a configurable limit
(usually 10 levels). The parent need not be the same type as its children,
and flags and locks are not inherited from parent objects. You may not
create parent loops.
See also: @parent, parent().
& @password
Command: @password <old password>=<new password>
This command changes your password.
& @program
Command: @program <player> = <object>/<attribute>[:<prefix>]
This command allows player input to be sent directly to another command,
bypassing all other commands, built-in or otherwise. <player> will be
placed into program mode, and prompted with <prefix> if specified, as
well as a "> " input prompt. When the player next types something,
you (the person who initiated the @program) will execute the contents
of <object>/<attribute>, with the player's input as %0 and the player
as the enactor (%N, %#). Note that this is the value of the attribute
at the time the @program was initiated, NOT the value at the time the
player enters input.
The programming object must control <player>, or it or its owner must
have the Program power. It must also be able to see <attribute> on
<object>. <player> must be a connected player, and programs are cleared
when a player logs out.
Continued in 'help @program2'.
& @program2
A player currently within a program can have input processed normally
by prefixing that input with a '|', i.e., '|WHO' rather than 'WHO', etc.
Programs can also be aborted through the '@quitprogram' command; note
that if your input is currently being absorbed by a program, you will
need to type '|@quitprogram'.
Examples are given in 'help @program3'.
& @program3
An example:
] @va Object = $try it: @program %#=me/VB:Please enter some words.
] @vb Object = @emit Text '%0' entered by %N.; @program %#=me/VC
] @vb Object = @emit More text '%0' entered by %N. Done.
] try it
Please enter some words.
> here are some words
Text 'here are some words' entered by Wizard.
> even more words
More text 'even more words' entered by Wizard. Done.
Another example:
] @va Object1 = $try it: @program %#=Object2/VB:Try it out.
] @vb Object2 = :shows: Text '%0' entered by %N.
] try it
Try it out.
> testing this
Object1 shows: Text 'testing this' entered by Wizard.
& @quitprogram
Command: @quitprogram [<player>]
Terminates the @program being run by <player>. If <player> is not
specified, it is assumed to be the enactor.
Note that this command is issued for the player whose input is
being absorbed, not the object that is controlling the program.
Also note that if a player's input is currently being absorbed
by the @program, that the player needs to type '|@quitprogram'
rather than '@quitprogram' in order to get out of it.
See also: @program.
& @ps
Command: @ps[/<switches>] [<object | player>]
Lists information about the commands you have on each of the queues.
If <object> is specified, only commands run by <object> are listed; if
<player> is specified, only commands run by that player's objects are
listed. You must control <object> or <player>, or must have the
See_Queue power. This command is useful for identifying infinite loops.
By default, this displays the object running the command and the command
to be run. Commands scheduled to be executed at a later time (by the @wait
command) show the number of seconds until they will be executed and/or the
semaphore on which they are waiting. A summary of the total commands
listed, total queued, and, if privileged, total halted, is also included.
The following switches are available:
/brief - (default)
/long - Also display the name and dbref of the command's enactor
(object which caused it to be run) and the stack (%0 - %9).
/summary - Display just the queue counts.
/all - Wizards or those with the See_Queue power only. Display
the queue for everything, not just your own objects.
See also: @notify, @wait.
& @quota
Command: @quota
If quotas are enabled, this lists your total building quota and the
amount you have remaining. Creating objects, digging rooms, and
opening exits may all consume quota; use the '@list costs' command
to find out how much.
Wizards and those with the Quota power may set quotas and see other
people's quotas; see 'wizhelp @quota' for details.
See also: @create, @dig, @open.
& @redirect
Command: @redirect <object to redirect from>=<player to redirect to>
This command redirects output generated by the PUPPET, TRACE, and
VERBOSE flags. Any such output generated by <object> would, under
normal circumstances, be shown to the owner of <object>. If <object>
has been redirected, however, the output is instead shown to <player>.
If <player> is not specified, the object's current redirection is cleared.
You can do this if you control <object>, or you control <player>.
If <player> is specified, <object> must be controlled by you or be
set REDIR_OK, and you must control <player>. You cannot redirect output
to non-players.
See also: REDIR_OK.
& nrefs
& name references
& named references
& @reference
Command: @reference <reference name> = [<object>]
@reference/list [<player>]
A "name reference" (nref) is a mapping between a unique name and a dbref
number. There are global nrefs, whose names all start with an underscore
and can be used by any object on the MUSH, as well as "local" ("personal")
nrefs, which can only be used by objects owned by a specific player.
An nref is defined via '@reference <name> = <object>'. If <name> starts
with an underscore, it is globally defined; only Wizards can do this.
You must be able to examine <object>.
Name references can generally be used any time a dbref number can be
specified with '#<number>', using '#_<nref>'. For example, if you have
defined a personal nref called 'tool', which maps to #400, via
'@reference tool = #400', you can, anywhere you could use #400, instead
use '#_tool'. For example, to examine it, you could type 'ex #_tool'
rather than 'ex #400'.
Continued in 'help @reference2'.
& @reference2
If you are a wizard, helping to work on global code systems, it can be
useful if everyone uses nrefs rather than dbrefs to designate objects,
since this makes for easier code maintenance and simplifies the process
of sharing code between multiple MUSHes. For example, you could define
an nref for your global functions object #10, via '@reference _gfun = #10'.
Thereafter, 'u(#__gfun/SOME_ATTR)', '@trigger #__gfun/SOME_TRIG', and
so forth would all work.
There is no limit to the number of name references that a given object
may have. Resolving a name reference is, however, less efficient than
resolving a dbref. Thus, nrefs should only be used where dbref-independence
is especially desirable, or where indirection is already being performed;
for instance, if you store the dbref of your data object on the VD
attribute, and do things like 'u(%vd/STUFF)', an nref is preferable.
If you are distributing your MUSHcode publicly, use of nrefs is encouraged.
Short nref names are more efficient than long nref names. Thus, 'maildb'
is a good nref; 'mail_database_object' is less desirable.
Continued in 'help @reference3'.
& @reference3
References are not persistent between restarts; therefore, any references
that you want to permanently define (which will generally be all the ones
you use) should be placed in a @startup.
Global references can be listed via '@reference/list'. You can list
your own references via '@reference/list me'. You can list the
references of any player you control via '@reference/list <player>'.
Example:
> @create Data
Data created as object #58
> @va Data = Test
Set.
> @reference myobj = Data
Referenced.
> say [get(#_myobj/VA)]
You say, "Test"
& @robot
Command: @robot <name>=<password>
Creates a robot player owned by you. The robot has its ROBOT flag set, so
it may use the OUTPUTPREFIX and OUTPUTSUFFIX commands that most publicly
available robot programs require. This command costs 1000 coins.
Note that some sites do not restrict OUTPUTSUFFIX and OUTPUTPREFIX to
robots.
See also: OUTPUTPREFIX, OUTPUTSUFFIX, ROBOT, TYPES OF OBJECTS.
& @search
Command: @search [<player>] [<class>=<restriction>[,<low>[,<high>]]]
Displays information about objects that meet the search criteria.
Because this command is computationally expensive, it costs 100 coins.
<player> restricts the search to the named player, while <class>
and <restriction> control the objects listed. Type 'help search classes'
for a list of the classes you may use.
Except when getting lists of players ('@search type=player' or
'@search flags=P'), you may only search for objects that you own.
You may limit the range of the search with <low> and <high>, which specify
the objects to start and stop the search at, respectively. The default for
<low> is #0 and the default for <high> is the last object in the database.
Examples:
@search flags=PWc <-- search for connected wizards.
@search type=room <-- list all rooms owned by me.
@search eval=gt(money(##),10) <-- search for things worth more than 10.
@search type=room,100,300 <-- Rooms between #100 and #300, inclusive
@search object=Test,5000 <-- Things starting with Test from object
#5000 to the end of the database.
See also: @find, search(), SEARCH CLASSES.
& @set
Command: @set <object>=[!]<flag>
@set <object>=<attribute>:<value>
@set <object>=<attribute>:_<fromobj>/<fromattr>
@set <object>/<attr>=[!]<attrflag>
The first form sets (or clears) the indicated flag on <object>, the
second form sets the <attribute> attribute on <object> to <value>,
creating a new user-named attribute if there is no attribute named
<attribute>. The third form copies an attribute from another object, and
the fourth form sets (or clears) an attribute flag on the <attr> attribute
of <object>.
When setting attributes on an object, you may also use the command
'@<attribute> <object> = <value>' if the attribute is a predefined
attribute. You may also use the command '&<attribute> <object> = <value>'
to set either predefined attributes or user-named attributes. Either of
these is equivalent to the second form of the @set command.
See also: @lock, @lock, examine, FLAGS, ATTRIBUTE FLAGS.
& @sql
Command: @sql <SQL query string>
This command sends a SQL statement to an external SQL database and
returns the results. The user must be God or have the use_sql power
(note that even having a Wizard flag is not sufficient).
See 'help SQL2' for details and examples.
& @stats
Command: @stats[/all] [<player>]
Without any switches or additional arguments, this command displays
the number of objects in the database, and the dbref of the next item
that will be created. This version of the command is free.
@stats/all gives a breakdown by object types. If <player> is specified,
the breakdown for the named player is given. You may not list individual
counts for other players unless you control them or have the stat_any
power. These versions of the command are computationally expensive, and
cost the same as a @search.
See also: stats().
& @sweep
Command: @sweep[/<switches>]
This command tells you all of the objects, players, and exits that are
listening in the room you are currently in, as well as 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, puppets, and audible exits since they will hear
everything you say and do. There are several switches that may be used to
limit the type of listeners that are checked for. They are:
/here - Check the room I am in.
/inventory - Check my inventory.
/exits - Check exits in the room.
/commands - Check for objects that have $-commands set on them.
/connected - Check for connected players and their puppets.
/listeners - Check for objects with @listen set to something.
/players - Check for players and their puppets, whether or not they
are connected.
The default is to search for everything. If you specify one or more
switches from either category (either location or listener type then only
that location or listener type is checked.
See also: @listen, AUDIBLE, PUPPETS.
& @branch
& @switch
Command: @switch[/<switches>] <string>=<t1>,<c1> [,<tN>,<cN>]... [,<cD>]
Compares <string> against the targets <t1>, <t2>, etc, until a match is
found, at which time the corresponding action list of commands is performed.
Wildcards, and the < and > operators are allowed in the targets.
Depending on the setting of the config parameter switch_default_all, this
may result in the action list of all matching targets may be performed (the
targets are not mutually exclusive), or just the first matched target's
action list being performed. If no target matches, the default list <cD>
is executed. The evaluated value of <string> can be obtained as '#$'.
The following switches are available:
/all - Perform the actionlists associated with all targets that
match <string>.
/first - Perform only the actionlist associated with the first target
that matches <string>.
/now - If an actionlist is to be performed, do so immediately rather
than placing it on the queue.
'@branch' is the same as '@switch/now'.
& @teleport
Command: @teleport[/quiet] [<mobile>=] <destination obj>
@teleport[/quiet] [<mobile>=] <exit>
@teleport[/quiet] [<mobile>=] home
The first form of the @teleport command moves <mobile> (or you) to the
named room or thing, or if <destination obj> is specified as 'home',
to whatever location your home is. The second form is just like having
yourself (or <mobile>) move through <exit> by typing the name of the
exit. (Note that '@teleport home' is not equivalent to the 'home'
command.)
The /quiet switch suppresses most messages.
If you are set FIXED, or your owner is set FIXED, and you are not able
to teleport anywhere (you are not a Wizard or Royalty and you do not
have the Tel_Anywhere power), you cannot use the @teleport command.
Continued in 'help @teleport2'.
& @teleport2
You can teleport any object you control. You can also teleport objects
in locations that you control (thus allowing you to remove unwanted
objects from your own rooms). Wizards, Royalty, and those with the
Tel_Anything power can teleport anything. However, if the object does
not pass the TeloutLock of its current location, it cannot be teleported;
this failure to pass the lock will result in the @tofail verb set being run.
Teleporting through an exit, is just like moving through that exit.
Otherwise, a destination check is done. 'home' is always valid. Otherwise,
you must control the destination, or you must be able to teleport
anywhere, or the the destination must be JUMP_OK and the object being
teleported must pass the destination's TeleportLock. If none of these
criteria apply, then the @tfail verb set will be run.
If the config parameter fascist_teleport is enabled, you must also control
the absolute location of the destination, or that absolute location
must be JUMP_OK, or you must be able to teleport anywhere.
Continued in 'help @teleport3'.
& @teleport3
When you successfully teleport an object to another destination (not
through an exit), the following happens:
- If this isn't quiet (the /quiet switch was not specified to @teleport),
objects in the location being left (the "current location") are shown the
@oxtport message of the object being teleported (the "mover").
- The mover leaves its current location.
- The mover's destination is registered.
- If this is not quiet, the mover's @tport verb set is run, showing the
@otport to those in the mover's destination.
- The mover's @move verb set is run.
- The mover enters its destination.
- Mover contents set KEY are sent home.
- The old room's drop-tos are activated.
- The player who did the @teleport is sent the message, "Teleported."
See 'help Moving' for lengthier explanations of these steps.
Continued in 'help @teleport4'.
& @teleport4
Example of a @tport verb set plus @oxtport:
@tport me = You successfully teleported.
@otport me = teleports in.
@atport me = @eval set(me:LAST_TPORT,time())
@oxtport me = teleports away.
Example of a @tfail verb set:
@tfail here = A psychic barrier prevents you from teleporting there.
@otfail here = thinks about teleporting to [name(me)], but doesn't.
@atfail here = @pemit owner(me) = %N tried to teleport to [name(me)].
Example of a @tofail verb set:
@tofail here = A psychic barrier prevents you from teleporting out.
@otofail here = thinks about teleporting out of here, but doesn't.
@atofail here = @pemit owner(me) = %N tried to teleport out of [name(me)].
See also: JUMP_OK, FIXED, home, @lock
& @call
& @trigger
Command: @trigger[/<switches>] [<object>/]<attr> [=<param> [, <param>]... ]
Invokes an action list stored in an attribute on an object. The triggering
object becomes the enactor and the positional parameters %0 through %9
are set to the supplied parameters. If <object> is not specified, the
triggering object is searched for the attribute.
If the action list has the format of a $command or ^listen, everything
up to the first unescaped ':' is ignored. Thus, you can do the following:
&DO_TT obj = $tt *: @pemit %# = u(TABLETALK,%0)
&DO_PLUSTT obj = $+tt *: @trig me/DO_TT=%0
Running an action list via @trigger costs charges, just like triggering
the @a-action of an attr/oattr/attr set.
The @trigger command supports the following switches:
/quiet - Omit 'Triggered.' messages.
/now - Perform the action list immediately rather than placing
it on the queue.
'@call' is the same as '@trigger/now/quiet'.
See also: LOOPING.
& @unlink
Command: @unlink <room/exit>
This command removes drop-tos on rooms and clears the destination on exits.
Once unlinked, an exit may be taken over by anyone with the @link command.
See also: @link, LINKING.
& @unlock
Command: @unlock[/<whichlock>] <object>
@unlock <object>/<attrib>
The first form removes the lock on <object>, so that anyone may pass
through (if an exit) or pick it up (if a player or an object).
<whichlock> indicates which lock you want to remove from the object.
If you don't specify one, you unset the Default lock. Type
'help @lock locks' for a list of locks.
The second form clears the locked flag on the indicated attribute of the
named object. This allows the attribute to change ownership to the new
owner automatically when the object is @chowned, and allows the owner
of the object to @chown the attribute to themself or to overwrite it.
You must own the attribute to be unlocked, but you do not need to own the
object.
See also: @chown, @lock, ATTRIBUTE OWNERSHIP.
& @verb
Command: @verb[/<switches>] <victim>=<actor>,<what>,<def>,
<owhat>,<odef>,<awhat>,<args>
This command provides a way to do user-defined verbs with associated
@attr/@oattr/@aattr groups. Invoking it does the following:
<actor> sees the contents of <victim>'s <what> attribute, or
the <def> string if you can't read <victim>'s <what> attribute.
Everyone in the same room as <actor> sees the contents of
<victim>'s <owhat> attribute, with <actor>'s name prepended,
or <odef>, also with <actor>'s name prepended, if you can't read
<victim>'s <owhat> attribute.
If you control <victim>, then he executes the contents of his <awhat>
attribute.
By supplying up to nine <args>, you may pass those values on
the stack (i.e. %0, %1, %2, etc. up through %9).
You must control the actor, but need not control the victim. Note that
if you don't have the ability to read the appropriate attributes (whether
because you control the victim, he is VISUAL, or the attributes are set
VISUAL), the default messages will be used.
{ 'help @verb2' for more }
& @verb2
victim - The object that is searched for attributes, and which runs the
<awhat> attribute if it is found.
actor - The object that 'did' the verb, this is the value for %#/%n/etc
in substitutions, and this object's name is included in the
message to others in the same location.
what - The name of the attribute containing the message to be delivered
to the actor.
whatd - The message to deliver to the actor if the victim does not have a
<what> attribute, or if it cannot be read.
owhat - The name of the attribute containing the message (prefixed by the
actor's name, unless the no_name attribute flag is set on that
attribute) that is sent to everyone in the room with the actor.
owhatd - The message to deliver to others in the room with the actor if the
victim does not have an <owhat> attribute, or it cannot be read.
Prefixed by the actor's name unless /no_name switch is specified.
awhat - The name of the attribute that is to be executed by the victim.
args - The comma-separated arguments to be passed for substitution
(%0-%9). If there is more than one argument, enclose all the
arguments within curly braces. Any argument that contains an
embedded comma needs to be enclosed in curly braces as well.
{ 'help @verb3' for more }
& @verb3
If the /now switch is used, the <awhat> attribute is run immediately
rather than being placed on the queue.
Examples:
> &xtest test1=You just xtested test1.
> &oxtest test1=just xtested test1.
> &axtest test1="I was xtested. Yikes. Arg1=%0, Arg2=%1, Arg3=%2.
> @verb test1=me,xtest,XTEST DFLT,oxtest,OXTEST DFLT,axtest,{a,b c,de}
You just xtested test1.
test1 says, "I was xtested. Yikes. Arg1=a, Arg2=b c, Arg3=de."
> &xtest test1
> @verb test1=me,xtest,XTEST DFLT,oxtest,OXTEST DFLT,axtest,{a,b c,de}
XTEST DFLT
test1 says, "I was xtested. Yikes. Arg1=a, Arg2=b c, Arg3=de."
> @fo test1={@verb test1=me,xtest,XTEST D,oxtest,OXTEST D,axtest,{a,b,de}}
test1 just xtested test1.
test1 says, "I was xtested. Yikes. Arg1=a, Arg2=b, Arg3=de."
{ 'help @verb4' for more }
& @verb4
In addition to /now and /no_name, @verb takes three additional switches:
/move - Treat this message as if it were movement, for the purpose
of checking PRESENCE objects.
/known - Treat this message as if it were something seen, for the
purpose of checking PRESENCE objects.
/speech - Treat this message as if it were speech, for the purpose
of checking PRESENCE objects.
See also: locate().
& @wait
Command: @wait <seconds>=<command>
@wait <object>[/<seconds>]=<command>
@wait <object>/<attribute>=<command>
The first form of @wait executes <command> after <seconds> seconds.
The second form increments the semaphore count for <object> and executes
<command> after <object> is notified with the @notify command. If the
semaphore count for <object> is negative (because it has been notified more
times than it has been waited on), then <command> is run immediately.
If <seconds> is specified in the second form, the command is automatically
run after <seconds> seconds even if the semaphore isn't notified.
The third form is identical to the second, except that the semaphore
count is stored in the specified attribute, rather than Semaphore.
This command charges a deposit of 10 coins, which is refunded when
<command> is executed.
See also: @drain, @notify, @ps, SEMAPHORES.
& @wipe
Command: @wipe <object>[/<wild-attr>]
This command erases attributes from an object. All attributes that match
<wild-attr> (or all attributes, if <wild-attr> is not specified) are removed
from <object>. Attributes that you do not have permission to modify (such
as read-only or locked attributes) are not removed.
& Conn Reasons
When invoking an @aconnect or @adisconnect attribute, the server will
pass two parameters to the attribute.
In an @aconnect, '%0' can be used to obtain the connect reason,
which will be one of the following: 'guest' (connected as a guest),
'create' (created at login screen), 'connect' (connected normally),
or 'cd' (connected dark).
For @adisconnect, '%0' can be used to obtain the disconnect reason,
which will be one of the following: 'quit' (typed QUIT), 'logout'
(typed LOGOUT), 'netdeath' (player's end of the connection dropped),
'timeout' (idled out), 'boot' (@boot'd, @toad'd, or @destroy'd),
'shutdown' (game shutdown), 'nologins' (game full), or 'unknown'.
In both cases, the player's resulting number of open connections
is available as '%1'. That would be 1 on the player's first connection,
2 or more during a reconnect, 1 or more during a partial disconnect,
and 0 when the player has fully disconnected.
See also: @aconnect, @adisconnect.
& @aconnect
Command: @aconnect <object> = <command-list>
Attribute: Aconnect
Sets the actions to be taken by a player right after connecting to the
game. This attribute is only meaningful for players, and will never be
automatically triggered on other object types, with a few exceptions.
If the Global aconnects/adisconnects are executed, when a player logs
in, any Master Room object with an @aconnect on it runs that attribute,
with the player as the Enactor. Note that the object, NOT the connecting
player, executes that attribute.
Aconnects/adisconnects may also be executed by the zone of the player's
location if the ZMO is a thing, or by the contents of the ZMO if it is a
room.
Example: @aconnect me = check.my.mailbox
See also: @adisconnect, Conn Reasons, ZONE OBJECTS.
& @adescribe
Command: @adescribe <object> = <command-list>
Attribute: Adescribe
Sets the actions to be taken when <object> is looked at.
Example: @adesc kitten = :rubs against %n's legs affectionately.
See also: look, @desc, @idesc, @odesc.
& @adisconnect
Command: @adisconnect <object> = <command-list>
Attribute: Adisconnect
Sets the actions to be taken by a player right after disconnecting from
the game. This attribute is only meaningful for players, and will never be
automatically triggered on other object types, with a few exceptions.
If the Global aconnects/adisconnects are executed, when a player logs
out, any Master Room object with an @adisconnect on it runs that attribute,
with the player as the Enactor. Note that the object, NOT the connecting
player, executes that attribute.
Aconnects/adisconnects may also be executed by the zone of the player's
location if the ZMO is a thing, or by the contents of the ZMO if it is a
room.
Example: @adisconnect me = home
See also: @aconnect, Conn Reasons, ZONE OBJECTS.
& @afail
Command: @afail <object> = <command-list>
Attribute: Afail
Sets the commands to be performed by <object> when one of these events
occurs:
- For exits: Someone tries to traverse the exit but cannot because they
fail the exit's default lock or the exit is not linked.
- For players and things: Someone tries to pick up the object but cannot
because they fail the object's default lock.
- For rooms, players, and things: Someone looks around inside the room,
player, or thing and fails the object's default lock.
Example:
> @afail vase = :falls to the floor and smashes to pieces.;@destroy me
See also: @fail, @ofail, FAILURE.
& @alias
Command: @alias <player> = <name>[;<alias 2>;<alias 3>;<alias N>]
Attribute: Alias
Provides one or more alternate names by which the player is known. The
alternate name is only used for players when referenced as '*<name>' or
by commands that only take player names (such as page or @stats). This
attribute is not otherwise meaningful for non-players.
When setting an alias, the alias is checked to see that it is both a legal
player name and not already in use. Only if both checks succeed is the
alias set. To ensure that these checks are performed, this attribute can
be modified only through the @alias command (i.e., it cannot be changed
by @edit and similar commands).
& @asuccess
Command: @asuccess <object> = <command-list>
Attribute: Asucc
Sets the actions to be taken by an object when someone successfully picks
it up (because they passed the lock), by an exit when someone passes
through it, or when someone looks at a room and passes the room's lock.
Example: @asucc kitten = :climbs up your sleeve and nuzzles your face.
See also: @osucc, @success, SUCCESS.
& @aufail
Command: @aufail <object> = <command-list>
Attribute: Aufail
Sets the list of commands to be run when someone 'use's the object but
fails the object's use lock. Note that the other functions controlled
by the use lock (paying, listening, and $-commands) do not trigger
Aufail.
Example: @aufail robot = "I _told_ you to leave me alone; kill %n=100
See also: @oufail, @ufail, @use.
& @away
Command: @away <object> = <message>
Attribute: Away
This attribute is sent as a message to anyone who tries to page you when
you are not connected.
This attribute is only meaningful for players, and will never be
automatically referenced on other object types.
Example: @away me = Hey, I'm not even connected. So why are you paging me?
See also: @idle, @reject, page.
& @daily
Command: @daily <object> = <command list>
Attribute: Daily
This attribute is automatically triggered once per day, at whatever
hour is set by the config parameter events_daily_hour.
Doing a '@daily <object> = <commands>' is functionally equivalent
to doing '&SOME_ATTR <object> = <commands>', followed by
'@crondel <object>/SOME_ATTR' to avoid running daily events more
than once, and then a '@cron <object>/SOME_ATTR = 0 7 * * *'
(substitute whatever events_daily_hour is for '7').
@daily attributes are handled through the cron facility; they appear
in the @crontab schedule, and can be unscheduled by using @crondel
or clearing the @daily. Cron entries are automatically entered for
objects with an @daily, at startup time.
Changing events_daily_hour while the MUSH is running does NOT
re-schedule already-scheduled @daily triggers; it only affects
future sets of @daily.
See also: @cron, @crondel, @crontab
& @describe
Command: @describe <object> = <description>
Attribute: Desc
Sets the description for <object>, which others see when they look at the
object. Giving all your objects, rooms, and exits good descriptions is
considered to be good building practice.
Function references and %-substitutions are allowed in descriptions, and
are evaluated when someone looks at the object. In function references,
'me' refers to the object being looked at, while %-substitutions that refer
to the enactor (such as %n, %#, %p, etc) refer to the looker.
Examples:
<object> @desc vase = You see a delicate Ming vase.
<exit> @desc elevator = There is an elevator to the east.
See also: look, @adescribe, @odescribe.
& @fail
Command: @fail <object> = <message>
Attribute: Fail
Sets the failure message for <object>. This message is seen by the actor
when one of these events occurs:
- For exits: Someone tries to traverse the exit but cannot because they
fail the exit's default lock or the exit is not linked.
- For players and things: Someone tries to pick up the object but cannot
because they fail the object's default lock.
- For rooms, players, and things: Someone looks around inside the room,
player, or thing and fails the object's default lock.
Substitution and evaluation is performed on the message before it is shown.
Example:
> @fail table = It's too heavy to lift! <thing>
> @fail doorway = The doorknob does not turn. <exit>
See also: get, @afail, @ofail, FAILURE.
& @filter
Command: @filter <object> = <pattern>[, <pattern>...]
Attribute: Filter
This attribute specifies a series of patterns to be used to suppress
text normally forwarded by the AUDIBLE flag. If the desired pattern
contains a comma, the pattern may be enclosed in curly braces {}.
If the text matches a <pattern>, then the text is not forwarded.
<pattern> is a wildcard pattern, unless the object's @filter
attribute has been @set 'regexp', in which case a regular expression
match is done instead. This is case-insensitive, unless the object's
@filter attribute has been @set 'case'. Note that unless the attribute
has been @set 'no_parse', it will be evaluated, so special characters
in the regular expression, such as '[' and ']', will need to be escaped
out. For efficiency reasons, 'no_parse' should be set whenever possible.
Continued in 'help @filter2'.
& @filter2
Example:
> @fo me = {@create puppet; drop puppet; @set puppet = PUPPET}
> @fo me = {@create vehicle; drop vehicle; enter vehicle}
> @set here = AUDIBLE
> @filter here = Wizard tests.,Wizard waves to *
> :waves.
Wizard waves.
puppet> From a distance, Wizard waves.
> :tests.
Wizard tests.
> :waves to everyone.
Wizard waves to everyone.
> @filter here = ^Wizard waves \[5-9\] times\\.$
> @set here/filter = regexp
> :waves 3 times.
Wizard waves 3 times.
puppet> From a distance, Wizard waves 3 times.
> :waves 5 times.
Wizard waves 5 times.
See also: AUDIBLE, @forwardlist, @infilter, @inprefix, @prefix.
& @forwardlist
Command: @forwardlist <object> = <dbref-list>
Attribute: Forwardlist
Specifies a list of locations (specified by their db numbers) that are to
receive messages heard by <object> (filtered by the @filter attribute and
prefixed by the @prefix attribute). The messages are only forwarded if
<object> has its AUDIBLE flag set.
See also: @filter, @prefix, AUDIBLE.
& @htdesc
Command: @htdesc <object> = <message>
Attribute: HTDesc
Sets the HTML description for <object>. The HTML description of an object
will be shown to a player with the HTML flag. If not set, the regular
description in the Desc attribute is shown instead.
If you wish to place raw HTML in this attribute, you should set the html
attribute flag on it so that the contents will not be doubly htmlified.
Without the flag, any '<' characters would be translated to "<", which
means the browser would display a '<' character rather than beginning to
process a markup tag.
Function references and %-substitutions are evaluated in this attribute.
Example: @htdesc me = <IMG SRC="http://www.me.com/mypic.jpg">
@set me/htdesc = html
See also: Pueblo, @set.
& @idesc
Command: @idesc <object> = <message>
Attribute: Idesc
Sets the internal description for <object>. The internal description of an
object will be shown to any player entering it. If not set, the regular
description in the Desc attribute is shown instead.
Function references and %-substitutions are allowed in inside descriptions,
and are evaluated when someone fails to get or look at the object. In
function references, 'me' refers to the object being looked at, while
%-substitutions that refer to the enactor (such as %n, %#, %p, etc)
refer to the player doing the looking.
This attribute is only meaningful for players and things, and will never be
automatically triggered on other object types.
Example: @idesc car = You are sitting in the driver's seat of a Volkswagen
Beetle.
See also: enter, @describe, ENTER_OK.
& @idle
Command: @idle <object> = <message>
Attribute: Idle
This attribute is sent as a message to anyone who successfully pages you.
It can be used to tell someone who pages you when you will return
(if you are going to be away for a while).
This attribute is only meaningful for players, and will never be
automatically referenced on other object types.
Example: @idle me = At dinner. Back about 7PM.
See also: @away, @reject, page.
& @infilter
Command: @infilter <object> = <pattern>[, <pattern>...]
Attribute: Infilter
This attribute specifies a series of patterns to be used to suppress
text normally sent to the contents of <object> by @listen. If the desired
pattern contains a comma, the pattern may be enclosed in curly braces {}.
If the text matches a <pattern>, then the text is not sent.
<pattern> is a wildcard pattern, unless the object's @infilter
attribute has been @set 'regexp', in which case a regular expression
match is done instead. This is case-insensitive, unless the object's
@infilter attribute has been @set 'case'. Note that unless the attribute
has been @set 'no_parse', it will be evaluated, so special characters
in the regular expression, such as '[' and ']', will need to be escaped
out. For efficiency reasons, 'no_parse' should be set whenever possible.
Continued in 'help @infilter2'.
& @infilter2
Example:
> @listen sports car=*
> @fo test=enter sports car
test has left.
test> Sports Car(#383Q)
> :waves.
test> Wizard waves.
Wizard waves.
> @infilter sports = *waves*
> :waves.
Wizard waves.
> :knocks on the window.
test> Wizard knocks on the window.
Wizard knocks on the window.
See also: @filter, @inprefix, @listen, @prefix.
& @inprefix
Command: @inprefix <object> = <prefix text>
Attribute: Inprefix
This attribute, when set, will prefix all text that is sent to the contents
of <object> by @listen. The default is to have no prefix, the text is
forwarded unadorned.
Example:
> @listen sports car=*
> @fo test=enter sports car
test has left.
test> Sports Car(#383Q)
> :waves.
test> Wizard waves.
Wizard waves.
> @inprefix sports car = In the mundane world outside,
test> In the mundane world outside, Wizard waves some more.
Wizard waves some more.
See also: @filter, @infilter, @listen, @prefix.
& @aahear
& @ahear
& @amhear
& @listen
Attribute set: @listen, @ahear, @aahear, @amhear
The @listen attribute contains a pattern that the object listens for.
Any message that <object> receives -- such as those spoken, posed,
emitted, whispered, paged, as well as generated from actions, such
as movement -- is checked against the @listen attribute. When the object
hears something that matches the pattern, it triggers the appropritae
@ahear / @aahear / @amhear attribute, passing the stack (%0 - %9)
substitutions according to the results of the pattern match.
The pattern is normally a wildcard pattern, with %0 as the string that
matched the first wildcard in the @listen, %1 as the string that matched
the second wildcard, and so forth.
If the 'regexp' flag is set on the @listen, the pattern is treated as
a regular expression, with %0 as the entire matched expression, %1
as the first parenthesized expression, %2 as the second parenthesized
expression, and so forth. This match is case-insensitive, unless the
'case' flag is also set on the @listen.
Continued in 'help @listen2'.
& @listen2
The @ahear attribute is triggered only by messages that were not generated
by the listening object itself. This is the most commonplace way to use a
@listen, and is the safest, since it helps prevent infinite loops.
The @amhear attribute is triggered only by messages that were generated
by the listening object itself.
The @aahear attribute is triggered by all messages, whether or not the
listening object generated them.
Example:
> @listen object = * tests.
> @ahear object = say Someone else -- %0 -- tested!
> @amhear object = I tested!
> @aahear object = say Somebody that might be me -- %0 -- tested!
Continued in 'help @listen3'.
& @listen3
In addition to trigger attributes, the @listen pattern also determines
what messages "fall through" the object and are heard by its contents.
Messages that match the @listen, regardless of what object was responsible
for generating them, will be passed on to the listening object's contents
(which in turn can match the message via @listen, etc.), unless the
message matches the listening object's @infilter pattern. Messages that
are passed on are prepended by the listening object's @inprefix, if any.
Objects with a @listen attribute set are noted by the @sweep command.
See also: @sweep, @inprefix, @infilter, BOUNCE.
& @odescribe
Command: @odescribe <object> = <message>
Attribute: Odesc
Sets the message (prefixed by the player's name) that is shown to others in
the room when someone looks at <object>.
Example: @odesc vase = carefully inspects the vase.
See also: look, @adescribe, @describe, @idesc.
& @osuccess
Command: @osuccess <object> = <message>]
Attribute: Osucc
Sets the message (prefixed by the player's name) that is shown to others in
the room when someone picks up the named player or thing, goes through the
named exit, or looks at the room and passes the room's lock.
Setting Osuccess messages on all takeable objects and usable exits is
considered good building practice.
Examples: <object> @osucc vase = carefully picks up the vase.
<exit> @osucc doorway = opens the door and leaves the room.
The door closes behind %o with a click.
See also: get, look, @asuccess, @success, SUCCESS.
& @oufail
Command: @oufail <object> = <message>
Attribute: Oufail
Sets the message that others in the same room see when someone tries to
use object but fails the object's use lock. Note that the other functions
controlled by the use lock (paying, listening, and $-commands) do not
trigger Oufail.
Example: @oufail robot = tries to activate the robot, but to no avail.
See also: @aufail, @ufail, @use.
& @charges
& @runout
& Charges
Topic: Charges
Objects can be set to take a limited number of actions, and then take
a specified action list when it's gone past that limit.
When the @aattr from a verb set is run (such as the @adesc from the
@desc/@odesc/@adesc verb set, or invoked via @verb), or when an attribute
is @trigger'd, a check is performed for charges on the object performing
the action list.
If the Charges attribute exists on the object, charges are depleted before
the action list is run. If the Charges are greater than zero, then the
Charges attribute is reduced by 1, and the action list is run. If the
Charges are equal to or less than zero, then the action list in the
object's @runout action list is executed INSTEAD OF the original
attribute's specified action list (i.e., the @adesc, @trigger, etc.
will not run, and the @runout will execute instead).
Note that executing @runout does not clear the @charges attribute; it's
left as-is, which means subsequent invocations will trigger the @runout again.
Continued in 'help Charges2'.
& Charges2
For example:
> @charges balloon = 2
> @runout balloon = @emit The red balloon drifts out of sight.;
@destroy/instant me
> @adesc balloon = @emit The red balloon drifts away.
The third time the balloon is looked at, it will @emit the message, and
then @destroy itself (eliminating itself as a MUSH object).
& @pay
& @opay
& @apay
& @cost
& Vendors
Topic: Vendors
You can construct a "vending machine" -- an object which takes actions
when it is given a certain number of coins -- by using the @cost attribute
and the @pay/@opay/@apay verb set.
Set the @cost of the vending machine to however many coins you want it
to cost. The user will type 'give <vending machine> = <number>' to
activate the machine. If <number> is too low, they will be told it's
too little (but not by how much, so you need to let the user know the
price somehow, such as via the machine's @desc). If <number> is too
high, they will be given change. The money paid is given to the
vending machine's owner.
When the user gives the vending machine enough money, its @pay/@opay/@apay
verb set will be triggered. The user will see the @pay message, the others
in the location will see the @opay message, and the @apay action list will
be run.
Continued in 'help Vendors2'.
& Vendors2
Example:
> @cost machine = 10
> @pay machine = You receive a cup of coffee. You drink it. Mmmm.
> @opay machine = receives a cup of coffee, which %s drinks immediately.
> @apay machine = &LAST_USED me = %#
See also: give, Charges.
& @prefix
Command: @prefix <object> = <prefix text>
Attribute: Prefix
This attribute, when set, will be used as a prefix for all text forwarded
by the 'audible' flag on an object or exit. The default if this attribute
is not set is 'From <object name>,' for objects, and 'From a distance,'
for exits.
Example:
> @fo test=out
> @set #378=puppet
test> test grows ears and can now hear.
> :does something silly.
Wizard does something silly.
test> From a distance, Wizard does something silly.
> @prefix out=From some strange place
Set.
> :does something even sillier.
Wizard does something even sillier.
test> From some strange place Wizard does something even sillier.
See also: AUDIBLE, @filter, @forwardlist, @infilter, @inprefix.
& @reject
Command: @reject <object> = <message>
Attribute: Reject
This attribute is sent as a message to anyone who tries to page you but
you have prevented them from paging you via your page lock (@lock/page).
This attribute is only meaningful for players, and will never be
automatically referenced on other object types.
Example: @reject me = I _told_ you not to page me anymore...
See also: @away, @idle, page.
& @sex
Command: @sex <object> = <gender>
Sets the SEX attribute on an object. This is used to determine whic
pronouns to use when replacing %p, %o, %s, and %a parameters in
messages that apply to <object>. Genders that start with M or m are
considered male, those starting with F, f, W, or w are considered
female, those starting with P or p are considered plural, and anything
else is considered neuter.
Example: @sex me = female
@sex me = No thank you [Silly. Treated as neuter.]
& @speechformat
Attribute: Speechformat
A speechmodified object has the SPEECHMOD flag, and either has this
attribute set on it, or inherits this attribute from a parent.
This attribute allows you to personalize the format of the speech that
results when from the say, pose, @fsay, and @fpose commands.
When a speechmodified object uses those commands, its @speechformat
attribute is evaluated, with the message passed as %0, and the type
of speech passed as %1. The type is a single letter.
say (and @fsay and aliases such as ") passes a " as %1.
pose (and @fpose and aliases such as :) passes a : as %1.
pose/nospace (and @fpose/nospace, the ; alias, etc.) passes a ; as %1.
If a location has the SPEECHMOD flag, non-speechmodified objects in
that location have their speech formatted according to that location's
@speechformat, with the message passed as %0 and the speech type as %1.
(A personal @speechformat thus supercedes the location's @speechformat.)
Continued in 'help @speechformat2'.
& @speechformat2
If the evaluated string returned by @speechformat is empty, this is
treated as if the object did not have a @speechformat attribute at all,
unless the @speechformat attribute has the no_name attribute flag (thus
allowing @speechformat to entirely suppress speech if so desired).
In the event that the speaker does not have a @speechformat, its location
is checked for @speechformat; if there still isn't a non-empty string,
the normal default speech formats are used.
@speechformat obeys attribute defaults.
Note that the string generated by the @speechformat attribute is passed
through unchanged -- the speaker's name is not prepended.
Extremely complex speech transformations can be done by combining use of
@speechformat with the speak() function (pass it '%1%0' for the string).
The following example changes your say format to '<your name> murmurs
quietly, "<message>"', but leaves your pose format unchanged:
@speechformat me = [case(%1,",%N murmurs quietly\, "%0", )]
Continued in 'help @speechformat3'.
& @speechformat3
The following example essentially changes your name to '<your name> the
Magnificent' when you speak, and serves as a generic example of how
to write a @speechformat that just alters the format of your name:
@speechformat me = [switch(%1,",%N the Magnificent says\, "%0",
:,%N the Magnificent %0,
;,%N the Magnificent%0)]
@speechformat on locations can be used in order to enhance atmosphere.
Example, an underwater room where speech is affected:
@speechformat here = [case(%1,",%N mouths the
[case(words(%0),1,word,words)]\, "%0", )]
Example, a net object which holds a player captive inside:
@speechformat here = [case(%1,", ,%N struggles fruitlessly in the net.)]
Example, a room in complete darkness, where nothing can be seen:
@speechformat here = [case(%1,", ,Something rustles in the darkness.)]
See also: SPEECHMOD, speak()
& @startup
Command: @startup <object> = <command list>
Attribute: Startup
Sets a list of commands to be performed by <object> when the game is
started up. Typical actions include going home, cleaning visitors out of
a room, resetting a puzzle or complex object to its initial state, or
starting up an object that wants to run continuously.
Example: @startup me = @vz me=MUSH was last restarted at [time()].
@startup me = home
& @success
Command: @success <object> = <message>
Attribute: Succ
Sets the message that is shown to the player who successfully picks up the
named player or thing, goes through the named exit, or looks at the room
and passes the room's lock.
Example: <object> @succ vase = You carefully pick up the delicate vase.
<exit> @succ doorway = You open the door and walk through the
doorway.
See also: get, look, @asuccess, @osuccess, SUCCESS.
& @ufail
Command: @ufail <object> = <message>
Attribute: Ufail
Sets the message that someone sees when they try to use object but fail
the object's use lock. Note that the other functions controlled by the use
lock (paying, listening, and $-commands) do not trigger Oufail.
Example: @ufail robot = The robot pointedly ignores you.
See also: @aufail, @oufail, @use.
& @vrml_url
Command: @vrml_url <location> = <url>
Attribute: VRML_URL
Sets the URL of a VRML page to be shown to Pueblo users when they connect
in <location>.
See also: Pueblo, @htdesc.
& @conformat
Command: @conformat <object> = <contents format>
Attribute: ConFormat
Replaces the usual "Contents:" or "Carrying:" format when an object
is looked at, by a player-specified contents format. This is evaluated
as if it were a description or other similar message on the room, and
is passed no special parameters. The list of room contents that can
be seen by the viewing player is passed as %0.
One could change the format to 'Contents: Object1 Object2 Object3'
through '@conformat here = Contents: [iter(%0, name(##))]',
for example. More complex things are, obviously, possible.
See also: @exitformat, @nameformat
& @exitformat
Command: @exitformat <object> = <list of exits format>
Attribute: ExitFormat
Replaces the usual "Obvious Exits:" format when an object is looked
at, by a player-specified exits format. This is evaluated as if it
were a description or similar message on the room, and is passed no
special parameters. The list of exits that can be seen by the viewing
player is passed as %0.
One could change the format to 'Exits: Exit1 Exit2 Exit3' through
'@exitformat here = Exits: [iter(%0, name(##))]', for example.
See also: @conformat, @nameformat
& @nameformat
Command: @nameformat <object> = <name format>
Attribute: NameFormat
Replaces the usual name (or name, number, and flags) when a location
is looked at, by a player-specified name format. This is evaluated
as if it were a description or other similar message on the room, and
is passed no special parameters.
Example:
> @desc here=| There is nothing of interest here. |%r+[repeat(-,36)]+
> look
Limbo(#0R)
| There is nothing of interest here. |
+------------------------------------+
> @nameformat here=+---[ljust(< [name(me)] >,30,-)]---+
> look
+---< Limbo >------------------------+
| There is nothing of interest here. |
+------------------------------------+
See also: @conformat, @exitformat
& @exitto
Command: @exitto <object> = <function text>
Attribute: ExitTo
When an exit is variably linked, when a player attempts to move through
the exit, the @exitto attribute is evaluated. If the evaluation (with
the player considered as the enactor) results in a valid dbref for the
destination, the player is moved to that destination, just as if the
exit had been normally linked to that destination. Otherwise, the exit
is treated as unlinked.
For example, '@exitto random = [switch(rand(3),0,#0,1,#10,2,#50)]' would,
when a player attempted to go through it, randomly send the player to
either room #0, room #10, or room #50.
See also: @link
& MARKER
Flag: Marker0 (0), Marker1 (1) ... through Marker9 (9)
The ten "marker" flags are "user-defined" flags. Through the flag_name
and flag_access configuration parameters, the names of these flags, and
the permissions it takes to set/unset them, can be changed. Thus, the
exact names of the flags will vary on a per-MUSH basis, though Marker0
through Marker9 will always remain aliases for them, and their
one-character symbols are always 0 through 9. All user-defined flag
names are prefixed with an underscore (_), clearly differentiating
them from normal built-in flags.
Because the marker flags use numeric single-character designators,
when examining an object of type Thing with only marker flags,
there will be an underscore before the list of flags, to prevent
the flag "letters" from running into a dbref. For example,
object #3 with the flags Puppet and Marker0 shows up on an
'examine' as '#3p0'; object #3 with only the Puppet flag is
'#3p'; but object #3 with only the Marker0 flag is '#3_0'.
& ABODE
Flag: ABODE (A)
If a room is set ABODE, players can set their homes there,
and can set the homes of objects there. It does not mean that a
player can open an exit to that room, only that they can set their
home there.
& AUDIBLE
Flag: AUDIBLE (a)
When set on an object, player, or room everything from a say, pose, or emit
inside the object will be sent to every object in the location of that
object (except for rooms which have no location) as well as to all objects
mentioned in the object's Forwardlist attribute. When set on an exit,
everything from a say, pose, or emit in the room the exit is in will be
forwarded to the room the exit points to. In both cases the @prefix
attribute will be inserted in front of the text, or a default prefix if no
@prefix attribute is set. If the @filter attribute is present, it will be
used to suppress those messages matching any of the patterns specified.
See also: @filter, @forwardlist, @prefix.
& BLIND
Flag: BLIND (B)
When set on an object, when the object is moved, '<object> has arrived.'
and '<object> has left.' messages are not displayed to the locations that
the object is leaving and entering.
When set on a location, 'has arrived.' and 'has left.' messages are not
displayed when objects enter or leave the location.
The flag does NOT suppress @osucc, @odrop, etc. messages (unlike the DARK
flag).
This flag can only be set by Wizards.
& BOUNCE
Flag: BOUNCE (b)
When set on an object, this flag "bounces" anything that the object
hears to its contents (i.e., the contents hear the message also).
This is basically equivalent to giving the object a @listen of '*'
without an @ahear. It is, however, considerably more efficient than
doing so, and, moreover, can be set on player objects without
requiring the player_listen config directive to be enabled.
& CHOWN_OK
Flag: CHOWN_OK (C)
This flag, when set, allows you to transfer ownership to
another player. To set it, you must be carrying the object. You
also have to be in the room if you want to set this flag on rooms
or exits. After this flag is set, the new player may gain
ownership of the object by using the @chown command (See @chown).
Note that setting an object CHOWN_OK lets anyone on the game @chown it.
To restrict this (for example, if you intend a particular player to own
the object, but they aren't logged in right now), @lock the object's
ChownLock to the appropriate player.
& CONNECTED
Flag: CONNECTED (c)
This flag applies only to players and it shows if the
player is connected or not. Thus, each time you are connected to
the game, you should see the 'c' flag set, otherwise, you are DEAD!
You cannot reset this flag, and it is used internally by the code
for things like tabulating players for the WHO list, etc.
& DARK
Flag: DARK (D)
If a room is DARK, then no items are shown when a person
'looks' there. If a thing is DARK, then "look" does not list that
object in the room's Contents:, and if an exit is DARK, it doesn't
show up in the Obvious Exits: list.
Players, puppets, and objects that listen can be set DARK. However,
this flag has no effect unless that object has the Cloak power, or
that object has Wizard privileges and the visible_wizards configuration
parameter is disabled.
& DESTROY_OK
Flag: DESTROY_OK (d)
When set on an object, it allows any player to destroy
it as long as the object is not locked against them. This is good
for things like notes, whereby the recipient can destroy the note
after reading it, instead of having to look for you to destroy it.
The DESTROY_OK flag overrides the SAFE flag, so that you do not need to
give the /override switch to @destroy to destroy a thing that is both
DESTROY_OK and SAFE.
See also: @destroy, SAFE.
& ENTER_OK
Flag: ENTER_OK (e)
If an object or person is ENTER_OK, other players may enter the object
or person by using 'enter <object/person>. Players must also have the
ENTER_OK set if they wish to be able to receive things given to them by
other players via the 'give <player> = <object>' command. Note that
entering objects is also subject to Enter Locks.
& FREE
Flag: FREE (F)
This flag can only be set by Wizards. If an object is set FREE, it
ignores attribute defaults from a master object (as defined by
room_attr_defaults, thing_attr_defaults, etc.).
& GOING
Flag: GOING (G)
Used internally for the @destroy command, it is set on objects
that are set to be destroyed. In the event that a player decides
they don't want to destroy the object after all, then they can
simply set the object !GOING, and it will be spared destruction
(assuming that the periodic destroyed-object-cleanups hasn't
run yet, of course).
& HAVEN
Flag: HAVEN (H)
@set here=haven;@set me=haven. If a location is HAVEN, you
cannot kill in that location. The HAVEN flag no longer blocks pages or
@pemits, use @lock/page instead.
See also: @lock/page.
& KEY
Flag: KEY (K)
When set on an object, it prevents non-player objects from passing
locks on that object. Effectively, it prevents non-player objects
from picking it up, linking to it, giving to it, etc.
& LINK_OK
Flag: LINK_OK (L)
If a room is LINK_OK, anyone who passes its LinkLock can link exits
to it (but still not from it).
You may also @forwardlist to, @drain, and @notify any LINK_OK objet
whose LinkLock you past.
See @link.
& UNFINDABLE
Flag: UNFINDABLE (U)
If a player is set UNFINDABLE, he cannot be found by the loc() or room()
functions. Bummer.
If a room is set UNFINDABLE, players in that room (or inside objects
in the room) cannot be found by loc()/room().
& OPAQUE
Flag: OPAQUE (O)
When set on a player, it prevents other players from
seeing what you are carrying in your inventory. Only exception is
when the object you are carrying belongs to the other player
looking at you.
& PLAYER
Flag: PLAYER (P)
The PLAYER flag identifies you as a player. This flag cannot be reset by
any player, not even a Wizard. It is used mainly by the MUSH code to
identify your commands, check for validity of commands or locks etc.
Generally, just pretend it isn't even there.
& JUMP_OK
Flag: JUMP_OK (J)
When a room or thing is set JUMP_OK, then that location can be teleported
into by anyone.
See @teleport.
& PUPPET
Flag: PUPPET (p)
@set <object> = puppet. Causes an object to grow eyes and
ears, and relay all it sees and hears to its owner.
See: @force, PUPPETS
& PRESENCE
Flag: PRESENCE (^)
If an object is set PRESENCE, only things that pass its KnownLock
can see it, only things that pass its MovedLock can notice it move,
and only things that pass its HeardLock will hear its speech.
Furthermore, an object that is set PRESENCE only sees the things
that pass its KnowsLock, only notices the motion of things that
pass its MovesLock, and only hears the speech of things which pass
its HearsLock.
& ROOM
Flag: ROOM (R)
This flag is automatically set on rooms when you @dig a new
room. It cannot be changed. Rooms have the added advantage that
they can be saved from destruction by setting the room to !GOING
(see GOING).
& VISUAL
Flag: VISUAL (V)
When set on your object, it allows other players to examine it and
see all the object's attributes as if they owned the object. They
cannot make any changes to the object.
& QUIET
Flag: QUIET (Q)
This flag when set on yourself prevents you from hearing
the 'set' or 'triggered' messages from any objects you own. When
set on an object, only that object will not relay its messages.
& HALTED
Flag: HALTED (h)
While this flag is set, the object cannot perform any MUSH
actions, listen, be triggered, etc.
& GAGGED
Flag: GAGGED (j)
When set on a player, it disables him from doing anything
except moving and looking. He cannot talk, page, build, pose, get
or drop objects. (Yet another consequence of annoying the wizards.)
Only wizards can set this flag.
& STICKY
Flag: STICKY (S)
If a thing is STICKY, it goes home when dropped (see HOMES). If a room
is STICKY, its drop-to is delayed until the last person leaves (see
DROP-TOs). Only meaningful for things and rooms.
& TEMPLE
Flag: TEMPLE (T)
The TEMPLE flag is no longer a part of TinyMUSH.
& BUILDER
Flag: BUILDER (B)
This is now the Builder power.
& WIZARD
Flag: WIZARD (W)
If a person is WIZARD, they are unkillable, subject to fewer restrictions,
and able to use wizard commands; they "control" everything other than
the God character. In general, WIZARDs can do anything using #<number>
or *<player>. Only the God character can set and unset the WIZARD flag
of other players. No WIZARD can turn their own WIZARD flag off.
Objects owned by Wizards only have wizard privileges if their INHERIT
flags or set, or the owning Wizard has his INHERIT flag set (which
Wizards should never do, for security reasons).
& ROYALTY
Flag: ROYALTY (Z)
If a person is ROYALTY, they can see and examine things, and
teleport anywhere or anything, like a wizard can. They cannot modify
objects or players they do not control, and cannot use wizard commands.
This flag may only be set by a wizard.
& IMMORTAL
Flag: IMMORTAL (i)
Objects set immortal cannot be killed and don't use up money.
Only settable by wizards. This is useful when an object's location
shouldn't be changed by Joe Player, but you don't want to have to relink it
to its current location whenever it moves.
& FIXED
Flag: FIXED (f)
If this flag is set on an object, it can neither teleport nor go 'home'.
If this flag is set on a player, neither the player nor objects owned
by the player may teleport or go 'home'.
& UNINSPECTED
Flag: UNINSPECTED (g)
This is a 'marker' flag, typically set on rooms that need to be
inspected for conformance to building standards. It may only be
set by Wizards and Royalty.
& STAFF
Flag: STAFF (w)
This is a 'marker' flag, typically set on players who serve as Staff.
This confers no special abilities; it is, however, only settable by
Wizards.
& HEAD
Flag: HEAD (?)
This is a 'marker' flag, typically set on players who serve as
leadership of some sort. This confers no special abilities; it
is, however, only settable by Wizards.
& COMPRESS
Flag: Compress (.)
This flag doesn't do anything.
& AUDITORIUM
Flag: AUDITORIUM (n)
If this flag is set, SpeechLocks are checked on that object.
& VACATION
Flag: VACATION (|)
This flag can only be set by Wizards. It automatically unset when
a player logs on. Thus, it is useful for marking players who will
be gone for a long time and should not be removed from the database.
& VERBOSE
Flag: VERBOSE (v)
This flag causes all commands executed by the object having
the flag to be sent to the owner of the object. i.e.:
@create foo
@set foo=VERBOSE
@force foo="Hi.
foo] "Hi.
foo says, "Hi."
See also: TRACE
& INHERIT
Flag: INHERIT (I)
Under normal circumstances, objects owned by a player do not control
that player. If an object is set INHERIT, it can control its player.
If a player is set INHERIT, all of his objects can control him.
If a Wizard sets one of his own objects INHERIT, it has wizard powers.
If a Wizard is set INHERIT, all of his objects also have wizard powers;
this, for security reasons, is a very bad idea.
If an Immortal sets one of his own objects INHERIT, it will be treated as
immortal. If he sets himself INHERIT, all of his objects will be treated
as immortal.
See also: Control
& MONITOR
Flag: MONITOR (M)
When set, anytime the object hears something from someone who passes the
object's use lock, the object's attributes are scanned for attributes
of the form '^<pattern>:<commandlist>'. If the message matches the
wildcarded <pattern>, then <commandlist> is executed, substituting %0 for
the text that matched the first wildcard, %1 for the second, and so on.
All matching attributes are executed, not just the first.
Parents of MONITOR objects are never checked for ^-patterns.
See also: LISTENING.
& WATCHER
Flag: WATCHER (+)
When a player is set WATCHER, he will be notified anytime someone
connects or disconnects. Please note that players with this flag
will also see the connects/disconnects of players who are set DARK.
WATCHER is a restricted flag. Wizards can set it on anyone. Players
with the Watch_Logins power can set WATCHER on themselves (or anything
that they own, though this flag is meaningless for non-players).
& TRACE
Flag: TRACE(T)
When a thing is set TRACE, it will report to its owner the result of all
substitutions that it performs that change the original string. The order
for displaying nested evaluations (such as when evaluating the arguments to
a function) is a site-selected configuration parameter.
Example:
> @set object = trace
> @va object = say The result is [add(4,mul(3,%0))].
> @trig object/va = 7
object(#322)} '%0' -> '7'
object(#322)} 'mul(3,%0)' -> '21'
object(#322)} 'add(4,mul(3,%0))' -> '25'
object(#322)} 'The result is [add(4,mul(3,%0))].' -> 'The result is 25.'
object says, "The result is 25."
{ 'help trace2' for more }
& trace2
When trace output is displayed in top-down order (final evaluation first,
followed by the 'smaller' evaluations needed to perform it), then the total
number of trace output lines that may be produced by an evaluation is limited
to 200. Bottom-up trace output is not limited.
See also: VERBOSE.
& NOSPOOF
Flag: NOSPOOF(N)
This flag gives you mucho output when people @emit. It can be annoying,
but you'll know who's spoofing.
See also: @emit, @femit, @oemit, @pemit.
& PARENT_OK
Flag: PARENT_OK(Y)
If an object is set PARENT_OK, then any other object that passes the object's
ParentLock may make this object a parent of any object that it controls.
Caution: allowing others to use your objects as parents lets them read the
attributes on the object (as well as any parents of the object).
See also: @lock/parent.
& ORPHAN
Flag: ORPHAN(y)
If an object is set ORPHAN, the object does not inherit $-commands from
its parent(s), just like objects in the master room do not inherit
$-commands from their parents when a master-room object command match
is done.
This allows you to @parent a command object to a function object
without worrying about the overhead of scanning the function object
for $-commands.
& CONSTANT
Flag: CONSTANT(k)
Only God can set attributes on an object set CONSTANT. This includes
both setting attributes, changing attributes, and removing attributes.
This affects commands like @cpattr as well as @set. In effect, this
flag causes attributes on the object to be treated as if they were
locked.
& TICKLER
Flag: TICKLER(k)
An object that is set TICKLER is able to use the Tcl interpreter
functions. This flag can only be set by God.
See also: TCL.
& LIGHT
Flag: LIGHT(l)
An object or exit that is set LIGHT is visible even when inside a DARK
location. If an object is set both DARK and LIGHT, then its contents are
visible even though the object itself is not.
& MYOPIC
Flag: MYOPIC(m)
If you are set MYOPIC, then you are treated as if you did not own anything
when you use the LOOK command or when you automatically look at a location
when entering it. Other commands (such as EXAMINE) are not affected.
& TERSE
Flag: TERSE(q)
If you are set TERSE then you are not shown the description, success/failure
messages, contents, or exits of locations you enter. You must use the LOOK
or EXAMINE commands to see this information.
Others in the location still get the osucc/ofail messages and the asucc or
afail command list is still run.
See also: examine, look.
& REDIR_OK
Flag: REDIR_OK(>)
If set on an object, the object can be the subject of a @redirect
by a player who does not control that object.
This is useful if you are trying to debug an object in conjunction
with a non-Wizard player; if he wants to see what your object is
doing, you can set the object REDIR_OK, and he can use the @redirect
command on it to redirect it to himself.
& ROBOT
Flag: ROBOT(r)
If set on a player, indicates that the player is a robot and is allowed to
use the OUTPUTPREFIX and OUTPUTSUFFIX commands that many publicly available
robot programs require. Some MUSHes do not restrict access to the
OUTPUTPREFIX and OUTPUTSUFFIX commands.
See also: OUTPUTPREFIX, OUTPUTSUFFIX, @robot.
& SAFE
Flag: SAFE(s)
When set, requires the use of the /override switch to @destroy in order to
destroy the object. It does not prevent the destruction of the object,
but merely requires some additional effort. If a thing is set DESTROY_OK,
its SAFE flag is ignored and it may be destroyed without using the /override
switch.
See also: @destroy, DESTROY_OK.
& TRANSPARENT
Flag: TRANSPARENT (t)
If an exit is TRANSPARENT, then when you look at it you see the description
of the room on the other side of the exit in addition to the description
of the exit.
If a room is TRANSPARENT, exits are displayed in a "long" format,
showing their destinations.
& HTML
Flag: HTML (~)
If a player is set HTML, he can receive HTML output. This flag is
normally set by the invocation of a PUEBLOCLIENT command, and removed
upon disconnection.
See also: Pueblo.
& SLAVE
Flag: SLAVE (x)
If set on a player, neither the player nor any of his objects may perform
any commands that change the database. Some sites may restrict additional
commands. This flag may only be set or cleared by wizards.
& SUSPECT
Flag: SUSPECT (u)
When set on a player, causes connects, disconnects, name changes, kills,
and attempted kills to be reported to all connected wizards.
This flag is only visible and settable by wizards.
& SPEECHMOD
Flag: SPEECHMOD (")
If this flag is set, when the object attempts to say or pose (or is the
the target of @fsay or @fpose), it is checked for the @speechformat
attribute.
If this flag is set on a location, objects in that location are subject
to its @speechformat (though the speaker's own @speechformat takes priority).
Note that this flag is automatically set when @speechformat is set directly
on an object, and the flag is unset when @speechformat is removed from an
object. However, if you @parent an object to a parent, and you want
to inherit @speechformat functionality from the parent, you need to
set this flag on the child object. Similarly, if you remove the
@speechformat attribute from the parent, you should clear this flag from
that parent's children.
See also: @speechformat
& Control
Topic: Control
Most of the commands and functions that alter the database, and many
of the commands and functions that retrieve information about objects,
only work on objects that you control.
The rules for what objects control other objects are as follows:
1. You control all objects that you own.
2. Anything that you own, that has its INHERIT flag set, controls
all objects that you own (including you).
3. If you have your INHERIT flag set, all objects owned by you are
treated as if they have the INHERIT flag set on them, for the
purposes of control. Otherwise, anything that you own, that does
not have its INHERIT flag set, controls all objects that you own
that do not have their INHERIT flag set.
Continued in 'help Control2'.
& Control2
4. Wizards control all objects, regardless of whether or not they own
them, except for God. Objects owned by Wizards, that have the INHERIT
flag set on them, have Wizard powers. If a Wizard has his INHERIT
flag set, all of the objects he owns have Wizard powers; thus,
a Wizard should Never Ever set his INHERIT flag.
5. Objects with the Control_All power, control all objects, regardless
of whether or not they share the same owner.
6. God controls all objects, regardless of whether or not he owns them.
7. Anybody controls an unlinked exit, even if it is locked. Builders
should be careful.
8. If the 'have_zones' configuration parameter is enabled, zone control
is also a possibility. See 'help Zone Control' for the details.
& ZONE
Flag: ZONE (o)
When set on an object, it declares this object a "Zone". Anything
which is parented to an object set ZONE treats that parent object like
a local equivalent of the Master Room, provided that the configuration
option "local_master_rooms" is turned on. To be precise:
If a player types a command, and it is not an exit, built-in command,
or $command on an object nearby, if his current location is parented
to something set ZONE, the contents of that parent object will be
checked for $commands, in the same way that Master Room objects are
(i.e. the parents of the objects in the ZONE room are not checked for
$commands). If the ZONE object also has a parent which is set ZONE, then
the contents of that object will be checked, and so on.
If nothing is matched in this way, then, if the player himself
is parented to a ZONE object, that object's contents are checked.
"Secondary parents" are not checked for player zones. If still nothing
matches, only then will the global Master Room be checked.
Continued in 'help Zone2'.
& ZONE2
Most of the same caveats which apply to the global Master Room also apply
to ZONE objects (henceforth referred to as local master rooms). The number
of objects in the room should be kept to an absolute minimum. Objects
which do not have $commands on them should not be placed in the room.
Objects placed in a master room should only contain attributes with
$commands and other essentials (@startup, @forwardlist, and so forth);
data attributes should be placed on another object (parenting the commands
object to a data object is helpful, since master room checks do not
look at the parent for $commands).
Commands on objects in a local master room are run with the permissions
of that object. This enables an area to utilize a set of $commands that
might run with the permissions of different builders; furthermore, ZONEs
enable a single command object to be set INHERIT, if that sort of
permission is needed (since simply putting $commands directly on the
parent room causes those $commands to run with the permissions of the
child object).
& Zone Control
Topic: Zone Control
If the 'have_zones' configuration parameter is enabled, the following
additional rules apply for what objects control other objects.
(For the basic rules, see 'help Control'.)
One very important thing to note that if Object A can be controlled
because of a zone, and Object A can control Object B, then whoever
controls A effectively controls B, even though they cannot control
B directly.
All of the following criteria must be met in order for Object A to
control Target B:
1. Target B must not be a player.
2. Target B must have a zone set.
3. Target B must be set CONTROL_OK.
Continued in 'help Zone Control2'.
& Zone Control2
One of the following additional criteria must be met in order for
Object A to control Target B:
- If Target B's zone has a ControlLock set, and Object A passes it,
Object A controls Target B.
- If Target B's zone does not have a ControlLock set, or Object A
does not pass it, then a check is done to see if Object A controls
Target B's zone via zone control. This check is done recursively.
Note that this means that anyone who controls the top object in
a zone tree effectively controls everything below it, as long as
those zone objects are CONTROL_OK (since anyone who did so could
just add themselves to the ControlLock on those objects anyway).
Exercise caution when planning zones.
& Location
Topic: Location
Things and players are normally located inside rooms, but they can
be carried by other things and players (thus making their location
another thing or player).
All things and players have an "absolute location". The absolute
location is the room that they are "ultimately" located in, i.e.
the room that ultimately contains the chain of carried objects.
For example, if Player A is in Room X, and Player A is carrying
Object B, and Object C is inside Object B:
- The location of Player A is Room X.
- The location of Object B is Player A.
- The location of Object C is Object B.
- The absolute location of Player A, Object B, and Object C is Room X.
You can think of the "absolute location" as being where you'd be if
you kept typing 'leave' until you couldn't go any farther.
& CONTROL_OK
Flag: CONTROL_OK (z)
If an object is set CONTROL_OK, and the object is @zone'd to a valid
zone master object (ZMO), then anything that can pass the ControlLock
of the object's ZMO can control the object.
See also: ZONE OBJECTS
& ANSI
Flag: ANSI (X)
When set on a player, this flag will enable the player to see ANSI
control sequences, such as hilites and colors.
TinyFugue users who do not wish to see ANSI color should leave this flag
on, but '/set emulation=ansi_strip'. This saves the server some processing
work; if a user has the ANSI flag unset, the server has to go through
each line of text the user sees and strip the ANSI from it. Thus, if
a user can do it in-client, this is preferable.
See also: NOBLEED, ansi(), stripansi().
& NOBLEED
Flag: NOBLEED (-)
When set on a player, this flag will append an ANSI white character to
the normal ANSI 'normal' character, which will hopefully fix ANSI color
'bleed' (color extending into text it's not meant to extend into) on
most terminals. This flag should not be set unless necessary; it causes
the server to have to do some extra processing.
See also: ANSI, ansi(), stripansi().
& STOP
Flag: STOP (!)
This flag is only settable by Wizards. If one or more $commands are
matched on an object set STOP, no attempt will be made to match $commands
on further objects. See 'help Scan Order' for an exact list of the
matching order.
This flag is intended primarily for use on master-room and ZONE
local-master-room objects. The objects in the room should be
ordered, first to last, in order of probability of a match. Since
master-room objects typically have many commands on them, and
multiple matches on the same command are not used/desired, this
flag can save the needless computational expense of extra matching.
& User Commands
Topic: User Commands
User-defined commands, sometimes also known as $-commands or softcode
commands, are commands that are defined using MUSHcode.
All user-defined commands are defined by setting an attribute on an
object. Commands are defined by the format:
$<command string>: <action sequence>
When a user types a command, it will be matched against <command string>
and, if there's a match, then <action sequence> will be executed, where
<action sequence> is a semi-colon-separated list of commands to perform.
The match is normally a wildcard match (see 'help Wildcards'), but
if the attribute has the Regexp flag, then it is a regexp match
(see 'help Regexps). Regexp matches are case-insensitive, unless the
Case flag is set on the attribute. Any wildcards/regexp data matched
is available in the stack variables %0 through %9.
Continued in 'help User Commands2'.
& User Commands2
User-defined commands are normally lower in priority than exits and
built-in commands, when the MUSH server scans for available command
matches for user input. See 'help Scan Order' for the details.
The actions for user-defined commands are normally placed on the queue;
if the attribute has the Now flag, though, they are executed immediately.
User-defined commands can be turned into built-in commands via the
@addcommand command. See 'wizhelp @addcommand' for more information.
If the config parameter require_cmds_flag is enabled, an object must
have the COMMANDS flag to be scanned for non-@addcommand'd $-commands.
If an attribute is set No_Commands, it will not be checked for $-commands.
Continued in 'help User Commands3'.
& User Commands3
If the attribute has the Rmatch flag, wildcard-matched data is also
available in assigned local registers, specified by braces {} around a
variable name immediately following a wildcard. Rmatch cannot be used
in conjunction with a regexp match.
Regexp example:
> &DO_ATTACK object = $^attack (.+) with (.+)$: @emit %N attacks %1 with %2.
> @set object/DO_ATTACK = regexp
If the user types 'attack Bob with sword', %0 is the entire match string
('attack Bob with sword'), %1 is 'Bob', and '%2' is sword.
Wildcard example:
> &DO_ATTACK object = $attack * with *: @emit %N attacks %0 with %1.
If the user types 'attack Bob with sword', %0 is 'Bob' and '%1' is 'sword'.
Continued in 'help User Commands4'.
& User Commands4
Wildcard with rmatch example:
> &DO_ATTACK object = $attack *{target} with *{weapon}:
@emit %N attacks %q<target> with %q<weapon>.
> @set object/DO_ATTACK = rmatch
If the user types 'attack Bob with sword', %0 is 'Bob' and '%1' is 'sword',
r(target) (or the more efficientpercent substitution %q<target> ) is
also 'Bob', and r(weapon) (or %q<weapon> ) is also 'sword'.
It's not necessary to specify a register for every wildcard, if you
don't want it that way. For example:
> &DO_ATTACK object = $attack * with *{weapon}:
@emit %N attacks %0 with %q<weapon>.
> @set object/DO_ATTACK = rmatch
If the user types 'attack Bob with sword', %0 is 'Bob' and '%1' is 'sword',
plus r(weapon) (or %q<weapon> ) is also 'sword'.
& PIPING
Topic: PIPING
It is possible to "pipe" the output of one command to another, in a
fashion similar to that of a UNIX shell. The output from the first
command in a pipe is passed to the next command as the percent
substitution %| -- and the output from that command can be piped
into yet another command, and so forth.
The output of a pipe contains the raw ASCII codes which would normally
be directly output to the terminal. All pipe output is terminated with
a newline (equivalent of a '%r'). Raw output can be treated using
the translate() function.
The pipe symbol is ';|', and is used much like the standard semicolon
used to separate commands. As with the semicolon, the pipe symbol is
taken literally if entered from the terminal. The maximum number of
chained pipes defaults to 20.
See 'help Piping2' for examples.
& PIPING2
Examples of a pipe:
> &DO_SEEDESC me=$+seedesc *: look %0 ;| @pemit %#=--%r%|--
> +seedesc me
--
Wizard(#3PWc)
You see someone special.
--
& REGEXPS
Topic: REGEXPS (Regular Expressions)
The majority of matching in MUSH is done with wildcard ("globbing")
patterns. There is a second type of matching, using regular expressions,
that is available in certain circumstances.
For attributes that are $-commands or ^-listen-patterns, setting that
attribute "regexp" (with '@set <object>/<attribute>=regexp') causes
patterns to be matched using regular expressions rather than globbing.
In a regular expression match, the substring of the string which matched
the regexp pattern is %0; %1 through %9 are the substrings of the string
which matched parenthesized expressions within the regexp pattern.
Continued in 'help regexps2'.
& REGEXPS2
Regular expressions are extremely useful when you want to enforce
a data type. For example, if you have a command where you want a
player to enter a string and a number ('+setnum <player>=<number>',
for example), you might do it like this:
&DO_NUM Command Object=$^\+setnum (.+)=([0-9]+)$: @va me=Data: %1 = %2
@set Command Object/DO_NUM = regexp
Then, '+setnum cookies=30' would set VA to "Data: cookies = 30".
This eliminates your having to check to see if the player entered
a number, since the regular expression matches only numbers.
Furthermore, the '+' guarantees that there needs to be at least
one character there, so a player can't enter '+setnum cookies='
or '+setnum =10' or similarly malformed input.
The '+' sign in the command has to be escaped out, or it is taken as
a regexp token. Furthermore, the pattern-match has to be anchored
with ^ and $, or something like 'try +setnum cookies=30 now' would
also match. Regexps are case-sensitive; wildcard globbing is not.
Regular expression syntax is explained in 'help regexp syntax'.
& REGEXP SYNTAX
Topic: REGEXP SYNTAX
TinyMUSH supports regular expression syntax virtually identical to
the extended regular expressions supported by Perl 5.
See 'help regexp examples' for a very simple explanation of the basics.
TinyMUSH implements this functionality using the PCRE 2.04 library,
written by Philip Hazel <ph10@cam.ac.uk>, Copyright (c) 1997-1999
University of Cambridge. The remainder of this help entry is derived
from its manual pages. The supported functionality is equivalent to
Perl 5.005 regular expressions.
A regular expression is a pattern that is matched against a subject
string from left to right. Most characters stand for themselves in a
pattern, and match the corresponding characters in the subject.
Continued in 'help regexp syntax2'.
& REGEXP SYNTAX2
There are two different sets of meta-characters: those that
are recognized anywhere in the pattern except within square
brackets, and those that are recognized in square brackets.
Outside square brackets, the meta-characters are as follows:
\ general escape character with several uses
^ assert start of subject
$ assert end of subject
. match any character except newline
[ start character class definition
| start of alternative branch ("or")
( start subpattern
) end subpattern
? 0 or 1 quantifier (after a unit to quantify)
or, minimal match (after a quanitifier)
or, extends the meaning of ( after a (
* 0 or more quantifier
+ 1 or more quantifier
Continued in 'help regexp syntax3'.
& REGEXP SYNTAX3
Part of a pattern that is in square brackets is called a
"character class". It matches any character listed in the class.
In a character class, the only metacharacters are:
\ general escape character
^ negate the class, if the first character in the class
- indicates character range (e.g. A-Z, 0-4)
] terminates the character class
A backslash will escape most metacharacters, and can turn
some normal characters into generic character types:
\d any decimal digit
\D any character that is not a decimal digit
\s any whitespace character
\S any character that is not a whitespace character
\w any "word" character (letter, digit, or underscore)
\W any "non-word" character
Continued in 'help regexp syntax4'.
& REGEXP SYNTAX4
Quantifiers specify repetition of characters. They are:
{N} match exactly N of whatever came before
{M,N} match at least M but not more than N of whatever came before
* match 0 or more of whatever came before, equiv. to {0,}
+ match 1 or more of whatever came before, equiv. to {1,}
? match 0 or 1 of whatever came before, equiv. to {0,1}
Quantifiers are usually "greedy" -- they match as much as possible.
Adding a ? after a quantifier causes it to match as little as
possible instead.
Continued in 'help regexp syntax5'.
& REGEXP SYNTAX5
Outside a character class, a backslash followed by a digit greater
than 0 (and possibly further digits) is a back reference to a
capturing subpattern earlier (i.e. to its left) in the pattern,
provided there have been that many previous capturing left parentheses.
A back reference matches whatever actually matched the capturing
subpattern in the current subject string, rather than anything matching
the subpattern itself. Thus, the pattern:
(sens|respons)e and \1ibility
matches "sense and sensibility" and "response and responsibility",
but not "sense and responsibility".
Continued in 'help regexp syntax6'.
& REGEXP SYNTAX6
An assertion is a test on the characters following or preceding the
current matching point that does not actually consume any characters.
There are two kinds: those that look ahead of the current position in
the subject string, and those that look behind it.
An assertion subpattern is matched in the normal way, except that it
does not cause the current matching position to be changed. Lookahead
assertions start with (?= for positive assertions and (?! for
negative assertions. For example, lookbehind assertions start with
(?<= for positive asser- tions and (?<! for negative assertions.
Assertion subpatterns are not capturing subpatterns, and may not
be repeated, because it makes no sense to assert the same thing
several times. If an assertion contains capturing subpatterns within it,
these are always counted for the purposes of numbering the capturing
subpatterns in the whole pattern.
Continued in 'help regexp syntax7'.
& REGEXP SYNTAX7
There are also two useful backslash assertions:
\b word boundary
\B not a word boundary
A word boundary is a position in the subject string where the
current character and the previous character do not both match \w or
\W (i.e. one matches \w and the other matches \W), or the start
or end of the string if the first or last character matches \w,
respectively.
Continued in 'help rexpexp syntax8'.
& REGEXP SYNTAX8
Other, more complex features, such as conditional subpattern patching,
and embedded comments in regular expressions, are also supported.
Try a World-Wide Web search for PCRE, or consult a book on regular
expressions, for more details.
& REGEXP EXAMPLES
Topic: REGEXP EXAMPLES
The regexp pattern '.' is equivalent to the wildcard '?'; it matches
one and only one of an arbitrary character.
The regexp pattern '.+' is equivalent to the wildcard '*'; it matches
one or more arbitrary characters. To match zero or more arbitrary
characters, the regexp pattern is '.*'.
To match a string of numbers, use: [0-9]+
To match a string of letters only, use: [A-Za-z]+
See 'help regexp syntax' for a more detailed explanation.
& Boolean Values
Topic: Boolean Values
Boolean values are considered to be true (1) or false (0), as follows:
- All numbers are true, except for zero, i.e.:
t(0) => 0 t(1) => 1 t(532) => 1 t(-1987) => 1
- All dbrefs (#0 and higher) are true. #-1 and below are false.
Note that, for example, #1000 is true even if there aren't that
many objects in the database. Use isdbref() to check if a dbref
is actually valid. Also, lists of dbrefs are valid, as are other
strings starting with dbrefs other than '#-1 <string>':
t(#0) => 1 t(#1) => 1 t(#-1) => 0
t(#-5) => 0 t(#0 #3 #5) => 1 t(#1 #34 #6) => 1
t(#-1 NO MATCH) => 0 t(#-2 test) => 1 t(#-37 xx) => 1
t(#7 testing) => 1
- All other non-empty strings are true, i.e.:
t(foo) => 1 t() => 0
Continued in 'help Boolean Values2'.
& Boolean Values2
If the configuration parameter booleans_oldstyle is enabled (it is
disabled by default), the boolean value of dbrefs (strings that
start with a '#', effectively) is altered as follows:
- All numeric dbrefs other than #0 and #-1 are considered to be true.
- Anything non-numeric that has a '#' prefix is considered false.
This includes lists of dbrefs.
- Examples of results if booleans_oldstyle is enabled:
t(#0) => 0 t(#1) => 1 t(#-1) => 0
t(#-5) => 1 t(#0 #3 #5) => 0 t(#1 #34 #6) => 0
t(#-1 NO MATCH) => 0 t(#-2 test) => 0 t(#-37 xx) => 0
t(#7 testing) => 0
Functions such as andbool() and ifelse() use boolean values.
& Costs
Topic: Costs
Certain commands cost money to use, and you will not be able to use
them if you don't have enough funds.
Use the '@list costs' command to find out what these commands are,
and what they cost.
Commands run by objects have a random chance of costing you 1 unit
of money to execute. Thus, if an object runs endlessly, you might
run out of money.
You can check how much money you have by typing 'score'.
& CREDITS
Topic: CREDITS
TinyMUSH 3 is a fusion of TinyMUSH 2.2 and TinyMUX, and so we must
thank everyone associated with those projects, as well as the original
TinyMUSH 2.0 and its predecessors.
TinyMUSH 2.0 is derived from Larry Foard's TinyMUSH (which was itself
derived from TinyMUD, written by Jim Aspnes). TinyMUSH 2.0, written by
JT Traub (Moonchilde@PernMUSH) and Glenn Crocker (Wizard@TinyCWRU),
was a consolidation of features found in other servers, including
TinyMUSH, PernMUSH, TinyTIM, and, later, PennMUSH.
TinyMUSH 2.2 is primarily the work of Jean Marie Diaz (Ambar@PernMUSH),
Deborah Wilson-Hooker (Tyleet@TwoMoons), and Lydia Leong (Amberyl@PernMUSH).
TinyMUX is primarily the work of David Passmore (Lauren@From the Ashes).
Many, many people have contributed to TinyMUSH; our list of "thanks" is
by no means complete.
See 'help Credits2' for the list of names.
& CREDITS2
Significant code, ideas, bugfixes, and support have been contributed
over the years by many people, including, in alphabetical order:
Stephen Dennis Dean Gaudet Stephen J. Kiernan
Andrew Molitor T. Alexander Popiel Marcus Ranum
Alan Schwartz Jennifer Smith Russ Smith
Deborah Wilson-Hooker Airam@Generations Ambar@Pern
Coyote@TinyTIM Dreamline@Horizons Ethaniel@BTech3056
Evinar Furie@DungeonMUSH Harlock@StarWarsII
Hcobb@TinyTIM Jellan@Pern Kalkin@DarkZone
Kayan Telva@BTech3056 Mike@StarWars Miritha@Pern
R'nice@TinyTIM Sh'dow@Pern Sketch@TinyTIM
& Enactor
Topic: Enactor
The enactor is the object that caused an action list to be performed.
Examples:
- The player who types in a command that matches a user-defined $-command
is the enactor for the action sequence run by that $-command.
- The enactor of an Ahear action list is the object who said/emoted/etc.
the message that matched the Listen attribute.
- The enactor of an attribute that is run by the @trigger command is
the object that ran the @trigger command.
See 'help Substitutions' for a list of percent-substitions related to the
enactor. Also see 'help Caller', for some fine details on enactors and
function calls.
& CALLER
Topic: Caller
The caller is the object responsible for invoking a function. It is
normally equal to the enactor, except when a function defined by
@function is called, or the following functions are called:
edefault() get_eval() objcall() objeval()
u() udefault() ulocal()
These functions set the caller to be the object that is invoking
that particular function.
The caller is also set when an indirect lock is used in conjunction
with an evaluation lock; the user-function called by the evaluation
lock uses the locked object as the caller.
The caller's dbref can be accessed via the percent-substitution '%@'.
Checking the caller, especially in functions intended for global use,
is a more effective way to restrict permissions than checking the enactor.
Continued in 'help Caller2'.
& Caller2
Examples (assuming the player performing these actions is #1):
> &TEST_FN #10 = %! %@ %#
> &DO_TEST #9 = $test: @pemit %# = [u(#10/TEST_FN)] - [objeval(%! %@ %#)]
> test
#10 #9 #1 - #10 #9 #1
> @function testfn_nopriv = #10/TEST_FN
> @function/privileged testfn_priv = #10/TEST_FN
> &DO_TEST2 #9 = $test2: @pemit %# = [TestFN_NoPriv()] - [TestFN_Priv()]
> test2
#9 #9 #1 - #10 #9 #1
> &TEST #10 = 0[pemit(%#,enactor %# - me %! - caller %@)]
> @lock #10 = TEST/1
> @lock/telout here = @#10 (assuming "here" is #2)
> @tel #0
enactor #1 - me #10 - caller #2
You can't teleport out!
See also: ENACTOR, SUBSTITUTION.
& Exits
Topic: Exits
An exit links one location to another location, providing a way to travel
on the MUSH. Although normally used to link rooms together, exits can be
made to and from players and objects. The location that you are traveling
from is the exit's source; the location that you travel to (where the
exit is "linked to") is the exit's destination.
You can pick up an exit that you control, or which is in a location
that you control. You can drop an exit anywhere that you control;
if you have the Open_Anywhere power, you can drop an exit anywhere.
The source of an exit can also be changed via the @teleport command.
If an exit is set DARK it will not show up in the list of obvious exits in
a room.
Continued in 'help Exits2'.
& Exits2
Exits are sometimes used for "bogus commands", to intercept a command
and display a message or take some action, without needing to define
a user-defined command ('$-command') on an object. To use an exit
for this purpose, open an exit so its destination is 'here', and lock
it against everyone. Then, set its @fail, @ofail, and/or @afail
appropriately.
For example:
> @open sit = here
> @lock sit = #0
> @fail sit = You sit down.
> sit
You sit down.
See also: @link, @open.
& FAILURE
Topic: FAILURE
You fail to use a player or a thing when you cannot take it (because it's
lock fails). You fail to use an exit when you cannot go through it
(because it is unlinked or locked). You fail to use a room when you fail
to look around (because it's locked).
See also: get, look, @afail, @fail, @lock, @ofail, STRINGS.
& FLAGS
Topic: FLAGS
Everything in the universe of this MUSH (Rooms, Exits, Things, Players,
etc) are represented in the same way at the program level. A room merely
has the room flag set and a player has the player flag set. In addition,
flags also give objects abilities or qualities. For instance, a wizard
has the wizard flag set. That is what lets the program know he may use
wizard abilities. An object or room may have the dark flag set. In the
case of an object, this makes the object invisible to normal eye-sight.
In the case of a room, the room becomes too dark to see other objects or
players. To get a list of the flags that are available, type '@list flags'
or 'help flag list'. For more specific information on a particular flag,
request help on the flag's name, as in 'help ENTER_OK'.
& FLAG LIST
Topic: FLAG LIST
A - Abode B - Blind C - Chown_OK D - Dark
E - Exit F - Free G - Going H - Haven
I - Inherit J - Jump_OK K - Key L - Link_OK
M - Monitor N - Nospoof O - Opaque P - Player
Q - Quiet R - Room S - Sticky T - Trace
U - Unfindable V - Visual W - Wizard X - Ansi
Y - Parent_OK Z - Royalty a - Audible b - Bounce
c - Connected d - Destroy_OK e - Enter_OK f - Fixed
g - Uninspected h - Halted i - Immortal j - Gagged
k - Constant l - Light m - Myopic n - Auditorium
o - Zone p - Puppet q - Terse r - Robot
s - Safe t - Transparent u - Suspect v - Verbose
w - Staff x - Slave y - Orphan z - Control_OK
! - Stop $ - Commands ^ - Presence - - NoBleed
~ - HTML > - Redir_OK ? - Head | - Vacation
+ - Watcher " - SpeechMod
See 'help Marker' for help on user-defined flags (0 through 9).
For information on a particular flag, type 'help <flagname>'.
& FUNCTIONS
Topic: FUNCTIONS
Functions are specialized commands used to manipulate strings and other
input. The format for a function is of this form: [fun-name(<input>)]
Although usually the []'s indicate an input that is optional, in this case
they are necessary and tell the MUSH that this is a function, although
nested functions (like [first(rest(This is a nice day))] returns 'is') do
not require more than one pair of []'s. Nested brackets may be used when
it is necessary to insert a function call in the middle of an argument,
like [get(me/[get(me/vz)])], which returns the contents of the attribute
named in the VZ attribute.
For help on a particular function, type 'help <functionname>'. You may
need to include the parentheses with the function name, ie.
'help <functionname>()'. Type 'help function list' or '@list functions'
for a list of the available functions. 'help function classes' will show
a list of the functions broken down into classes.
See also: @list functions, FUNCTION CLASSES, FUNCTION LIST, DELIMITERS.
& FUNCTION LIST
Topic: FUNCTION LIST
See the following help topics for the relevant function lists:
Attribute Functions: retrievel of attribute-related information.
Comsys Functions: available only when the comsys is enabled.
List Functions: manipulation of lists.
Math Functions: math and logic.
Misc Functions: miscellaneous utilities.
Object Functions: retrieval of object-property-related information.
Pueblo Functions: available only when Pueblo is enabled.
Side-Effect Functions: side-effect functions.
Stack Functions: manipulation of object stacks.
String Functions: manipulation of strings.
Structure Functions: manipulation of data structures.
Variable Functions: manipulation of object-associated variables.
See 'help <function name>' for more information about a specific function.
& FUNCTION CLASSES
See "help function list".
& ATTRIBUTE FUNCTIONS
Topic: Attribute Functions
aposs() default() edefault() eval()
get() get_eval() grep() grepi()
hasattr() hasattrp() lattr() nattr()
obj() objcall() objeval() poss()
regrep() regrepi() subj() u()
udefault() ulocal() v() wildgrep()
xget() zfun()
& OBJECT FUNCTIONS
Topic: Object Functions
andflags() children() con() conn()
controls() doing() elock() elockstr()
entrances() exit() flags() findable()
fullname() hasflag() hasflags() haspower()
hastype() hears() home() idle()
inzone() knows() lastaccess() lastcreate()
lastmod() lcon() lexits() lparent()
loc() locate() lock() lwho()
mail() mailfrom() money() moves()
name() nearby() next() num()
objmem() orflags() owner() parent()
pfind() playmem() pmatch() ports()
programmer() rloc() room() search()
sees() session() stats() type()
visible() where() writable() xcon()
zone() zwho()
& SIDE-EFFECT FUNCTIONS
Topic: Side-Effect Functions
command() create() force() link()
set() tel() trigger() wait()
wipe()
& LIST FUNCTIONS
Topic: List Functions
choose() columns() ctables() delimit()
elements() extract() filter() filterbool()
first() fold() grab() graball()
group() index() insert() itemize()
iter() isfalse() istrue() last()
ldelete() ldiff() ledit() linter()
list() lnum() loop() lpos()
lrand() lunion() map() match()
matchall() member() mix() munge()
remove() replace() regrab() regraball()
regraballi() regrabi() rest() revwords()
rtables() setdiff() setinter() setunion()
shuffle() sortby() sort() splice()
step() table() tables() until()
whenfalse() whentrue() while() words()
& MATH FUNCTIONS
Topic: Math and Logic Functions
Logic:
eq() gt() gte() lt()
lte() neq() ncomp()
not() t()
and() or() xor()
andbool() notbool() orbool() xorbool()
cand() cor() candbool() corbool()
Miscellaneous:
add() abs() ceil() dec()
dist2d() dist3d() div() e()
exp() fdiv() floor() floordiv()
inc() ladd() land() landbool()
lmax() lmin() ln() log()
lor() lorbool() max() min()
modulo() mul() pi() power()
remainder() round() sign() sqrt()
sub() trunc()
Continued in 'help Advanced Math Functions'.
& ADVANCED MATH FUNCTIONS
Topic: Advanced Math Functions
Bitfield manipulation:
band() bnand() bor()
shl() shr()
Trigonometry:
acos() acosd() asin() asind()
atan() atand() cos() cosd()
sin() sind() tan() tand()
Vectors:
vadd() vdot() vmul() vsub()
vdim() vmag() vunit()
& MISC FUNCTIONS
Topic: Miscellaneous Functions
case() ccount() cdepth() config()
connrecord() convsecs() convtime() die()
fcount() fdepth() hasmodule() helptext()
ifelse() localize() mudname() nonzero()
oemit() pemit() r() rand()
remit() restarts() restarttime() s()
secs() setq() setr() speak()
sql() starttime() subeval() switch()
switchall() time() timefmt() version()
& STRING FUNCTIONS
Topic: String Functions
after() alphamax() alphamin() ansi()
ansipos() art() beep() before()
border() capstr() cat() cborder()
center() chomp() comp() decrypt()
delete() edit() encrypt() escape()
foreach() isdbref() isnum() isword()
lcstr() left() lit() ljust()
merge() mid() nescape() nsecure()
null() pos() rborder() regedit()
regediti() regeditall() regeditalli() regmatch()
regmatchi() repeat() reverse() right()
rjust() secure() scramble() space()
squish() strcat() streq() stripansi()
strlen() strmatch() strtrunc() translate()
trim() ucstr() valid() wildmatch()
wordpos() @@()
& STRUCTURE FUNCTIONS
Topic: Structure functions
Every object can be associated with a number of data structures. A
data structure consists of an arbitrary number of components (elements);
each component has a data type. An object can have multiple instances
of each data structure that has been defined for it; each instance is
associated with data. These data structures provide the ability to
abstract, to some extent, the manipulation of data.
The structure functions are:
construct() destruct() load() linstances()
lstructures() modify() read() structure()
unload() unstructure() write() z()
All of these functions operate on the calling object; to manipulate
structures on other objects, wrap the function calls in an objeval().
There is a configurable maximum number of structure definitions per
object, typically 100. There is also a configurable maximum number of
instances per object, typically 100. Always destruct() unneeded instances!
& VARIABLE FUNCTIONS
Topic: Variable functions
Every object has the ability to be associated with a number of temporary
variables. These variables can be arbitrarily named, and persist until
the game is restarted. Functions are used to set and retrieve these
variables, and all operate directly on the object making the function
call; to manipulate variables on other objects, wrap the call in an
objeval(). With the exception of lvars() and x(), all the functions
operate strictly via side-effects, and return an empty string.
The variable functions are:
clearvars() let() lvars() regparse()
regparsei() setx() store() wildparse()
x() xvars()
There is a configurable maximum number of variables per object,
typically 50. If an attempt is made to set more than 50 variables,
it will fail silently. See 'wizhelp variables_limit' for details.
& STACK
Topic: STACK
Command lists that are run on objects can have up to 10 stack values
named %0 through %9 (or [v(0)] through [v(9)]). Stack values can be set
by the @trigger command, or by matching wildcard characters in the Listen
attribute (in the case of the Ahear, Aahear, and Amhear attributes).
Example:
> @listen item = * foo *
Set.
> @ahear item = "-->[v(1)]<-- bar -->[v(0)]<--
Set.
> say Fee fie foo fum
You say, "Fee fie foo fum"
item says, "-->fum"<-- bar -->Wizard says, "Fee fie<--"
& STACK FUNCTIONS
Topic: Stack functions
Every object has the ability to store a single stack of data, referred
to as an "object stack" (distinguishing it from the "command stack",
i.e. %0 - %9). Object stacks can store an arbitrary number of strings,
and are meant to be used for temporary variable storage; they are not
preserved across restarts.
The stack functions are:
dup() empty() items() lstack()
peek() pop() popn() push()
swap() toss()
All stack functions require the caller to control the object.
There is a configurable maximum number of stack items per object,
usually 50, beyond which point attempts to push additional items onto
the stack will fail silently; see 'wizhelp stack_limit' for details.
Continued in 'help Stack Funcs2'.
& STACK FUNCS2
A "stack" is a last-in, first-out (LIFO) data structure. You can think
of a piece of data stored in a stack as being equivalent to a plate
with something written on it. The first plate you put in goes on the
bottom of the pile. The second plate goes on top of the first plate,
the third plate goes on top of the second plate, and so forth. When
you go to pick up a plate, the top plate is the last plate you put
on the stack (the third plate, in this example).
Putting a piece of data on top of the stack is calling "pushing" data
onto the stack. Taking a piece of data off the top of the stack is
called "popping" data off the stack. Pieces of data on a stack are
frequently referred to as "items".
Items in a stack are numbered top to bottom, starting with zero.
That means that the top item on the stack is item 0, the next
item down is item 1, and so forth. A stack with N items is therefore
numbered 0 to N-1.
& PUEBLO FUNCTIONS
Topic: Pueblo Functions
The functions html_escape(), html_unescape(), url_escape(), and
url_unescape() are only available when Pueblo support is enabled.
HTML escapes affect these symbols:
< becomes < > becomes >
& becomes & " becomes "
URL escapes affect these symbols (which are converted to hex):
< > # % { } | \ ^ ~ [ ] ' ; / ? : @ = & " +
Spaces are also converted to '+' by url_escape().
See also: Pueblo.
& Delimiters
Topic: Delimiters
A large number of MUSH functions allow the specification of a list
delimiter. Some allow this only for the input list; some also allow
an output delimiter to be specified.
The default delimiter is a space. The list "1 2 3" consists of three
elements (1, 2, and 3), space-delimited. The list "1-2-3" also
consists of the same three elements, but is dash-delimited.
In the case where an input delimiter is specified, but an output
delimiter is not, the output delimiter will default to the input
delimiter, rather than defaulting to a space, EXCEPT for iter()
and related functions, where the output delimiter defaults to space.
Input delimiters are single characters or (usually) multi-character
strings. Output delimiters can usually also be @@ (null delimiter:
just string all the output together, with no separator between each
item), as well as multi-character strings, including '%r'.
See examples: iter(), map(), filter()
& HOMES
Topic: HOMES
Every thing or player has a home. This is where players when they go home,
or things with the STICKY flag set go when dropped. Homes are set with the
@link command. A thing's home defaults to the room where it was created, if
you control that room, or your home. You can link an exit to send players
home with '@link <dir>=home'. Drop-tos can also be set to 'home'.
See also: @link, DROP-TO, STICKY.
& LINKING
Topic: LINKING
You can link to a room if you control it, or if it is set LINK_OK or ABODE.
Being able to link means you can set the homes of objects or yourself to
that room if it is set ABODE, and that you can set the destination of exits
to that room if it is LINK_OK.
See also: @link, ABODE, LINK_OK.
& LISTENING
Topic: LISTENING
Thee are two ways to listen for something in a room. The easiest way
is to use a combination of @listen and @ahear/@aahear/@amhear. The
second way is to use a "^" pattern in an attribute, similar to the way
"$" is used for user-defined commands. The attribute takes the form:
'^<pattern>:<action>'.
The ^-pattern check is only performed on objects with their MONITOR flag
set. The criterion for triggering a pattern-listen is the same as that for
triggering an @ahear - the object cannot trigger its own listen patterns.
All matching attributes have their <action>s performed, not just the first.
Also, attributes with the no_command flag set are not checked for ^-patterns,
and neither are objects' parents.
Example:
> @va test = ^* says, "foo *":say I got a foo with %1!.
Set.
> @set test=monitor
test grows ears and can now hear.
> say foo bar
You say, "foo bar"
test says, "I got a foo with bar!."
See also: @ahear, @listen, @set.
& LISTS
Topic: LISTS
A list is a string, usually stored in an attribute (currently any of the
va-vz attributes), which is a series of words, separated by one or more
spaces. The following would be a list (denoted on the ends by ', which is
not actually in the string): 'one two three four five'. The functions
first(), rest(), cat(), member(), and remove(), all work on lists.
See also: cat(), first(), member(), remove(), rest().
& LOCAL REGISTERS
Topic: LOCAL REGISTERS
There are at least ten local registers, numbered 0 through 9, and
there might be, depending on the MUSH's configuration, up to 26
additional local registers, "numbered" A through Z. These registers
can be accessed in a very fast, CPU-efficient manner.
Registers can also be named, such as "test". It's somewhat less efficient
to use a name, but it also makes code more readable. Register names must
begin with a letter, and can contain only letters, numbers, or the
punctuation characters _, -, ., and #. A register name cannot be more
than 31 characters long. The total number of these that can be set by
an action is limited by a global configuration parameter, register_limit.
The local registers are normally cleared at the start of each command,
but are preserved across the commands that compose an actionlist, as
well as commands that directly trigger actionlists, such as @switch,
@trigger, and @dolist, as well as @program.
Continued in 'help Local Registers2'.
& LOCAL REGISTERS2
Local registers are most useful for storing complex function evaluations
which are used repeatedly within a single actionlist; their use can
improve the readability of MUSH code, and cuts down the amount of
compute time needed.
Local registers are set via the setq() and setr() functions, as well as
a variety of speciaized functions, such as regmatch(). Local registers
are read via the r() function or the %q substitution.
See also: setq(), setr(), SUBSTITUTIONS.
& LOOPING
Topic: LOOPING
Looping in an object can have its good parts and its bad parts. The good
part is when you activate part of a program multiple times to exhaustively
perform an operation. This is usually done by:
@va object = <list of commands>;@trigger me/vb
@vb object = @switch <test> = <false>,@trigger me/va,<otherwise go on>
Looping can be a problem when it goes on without stopping. The @ps command
can be used to see if you are looping. Beware! A looping machine that
isn't @halt'ed will drain your money supply while you are away!
See also: @halt, @ps.
& Me
& Here
& Matching
Topic: Matching
When you type a command or utilize a function that references an
object, such as '[flags(<object>)]', 'look <object>', 'get <object>',
or '@teleport <object to move> = <destination object', the MUSH looks
for a 'match' to that object. The 'locate()' function allows you
direct access to the matching procedures, for your own MUSHcode.
There are subtle differences in the matching procedures for each command
or function, depending on what makes sense in that specific context.
In general, though, a match is performed as follows:
- The keyword 'me' is checked. 'me' refers to you.
- The keyword 'here' is checked. 'here' refers to your current location.
- A check for a dbref, in the form of '#<number>', is performed. The
dbref must map to a valid, non-Garbage object.
Continued in 'help Matching2'.
& Matching2
- The keyword 'home' is checked. 'home' refers to your home.
- A check for a player, in the form of '*<player name or alias>', is
performed.
- If something has been matched, the match attempt stops, successfully.
- A match against exits is performed. This is matched against all
components of the exit name (i.e., if the exit is 'north;n;out;o',
'north', 'n', 'out', and 'o' all match that exit). In some
circumstances, exits are checked for in the parent objects, also.
Exits you're carrying are checked before exits in your location.
Priority is given to exits that aren't locked against you.
- A match against the names of objects in your location is performed.
Partial names are okay; i.e., 'bal' will match 'balloon'.
- A match against the names of objects you're carrying is performed.
Partial names are okay; i.e., 'bal' will match 'balloon'.
& Modules
Topic: Modules
The capabilities of the core MUSH server can be extended via the use of
runtime-loadable modules. These modules include the comsys, mail system,
and any other optional functionality that a specific MUSH might wish to
utilize. For instance, a MUSH might wish to extend its functionality with
a "hard-coded" 3-D space system, or a webserver.
The list of loaded modules can be obtained via the 'version' command.
& MONEY
Topic: MONEY
You need money to build within the game, to run programmed objects or use
certain other commands, or to buy things from vendors set up by other
players. You can get money via one or more of these methods:
1. You receive a daily allowance for each day you connect.
2. You have a chance of finding money as you wander around areas that
other people have built.
3. Some MUSHes may implement a place where you can sell valuable objects
for money.
See also: @list costs, COSTS.
& PUPPETS
Topic: PUPPETS
An object is made into a puppet by doing '@set <object>=puppet', once an
object is a puppet it will relay all that it sees and hears to its master.
All objects created by a puppet are owned by its master, when puppets spend
or earn money, they use their master's money supply. In order to prevent
puppets from screwing up puzzles, objects may have the KEY flag set, this
will prevent puppets from picking the object up. A puppet may be commanded
by its master by '@force <object>=command', or by the shorthand version,
'#<number of puppet> command'. The puppet flag is handy for debugging, as
it allows you to see the result messages your object generates.
Example:
@force fred="hi there. -or- #4342 "hi there.
See also: VERBOSE.
& ROBBERY
Topic: ROBBERY
Robbing is not allowed on this MUSH. If you really need money, ask your
friendly neighborhood wizard.
See also: MONEY.
& search classes
Topic: SEARCH CLASSES
You may use the following classes in @search commands and search()
function calls. Note that classes cannot be combined.
TYPE - Restricts to objects of the indicated type (OBJECTS, ROOMS,
EXITS, PLAYERS, GARBAGE). THINGS may be used as an alias
for OBJECTS.
NAME - Restricts to objects whose names start with <restriction>.
OBJECTS - A combination of TYPE=OBJECT and NAME=<restriction>.
THINGS - An alias for OBJECTS.
ROOMS - A combination of TYPE=ROOM and NAME=<restriction>.
EXITS - A combination of TYPE=EXIT and NAME=<restriction>.
PLAYERS - A combination of TYPE=PLAYER and NAME=<restriction>.
FLAGS - Restricts to objects which have the flags listed in
<restriction> set. Flags should be abbreviated by their
single-letter designations (see 'help Flag List').
Continued in 'help Search Classes2'.
& Search Classes2
EVAL - Evaluates the restriction for each object, replacing ##
with the object's database number. Evaluations that return
TRUE (ie, not 0 or #-1) are selected. If you use this within
a search(), you must escape out brackets and the like.
EOBJECT - A combination of TYPE=OBJECT and EVAL=<restriction>.
ETHING - An alias for OBJECT.
EROOM - A combination of TYPE=ROOM and EVAL=<restriction>.
EEXIT - A combination of TYPE=EXIT and EVAL=<restriction>.
EPLAYER - A combination of TYPE=PLAYER and EVAL=<restriction>.
UEVAL - Evaluates the restriction for each object, for the u-function
specified by an object/attribute pair, i.e., 'ueval=me/TEST',
passing the object's dbref as %0. Evaluations that return
boolean-true are selected.
UOBJECT - A combination of TYPE=OBJECT and UEVAL=<restriction>.
UTHING - An alias for OBJECT.
UROOM - A combination of TYPE=ROOM and UEVAL=<restriction>.
UEXIT - A combination of TYPE=EXIT and UEVAL=<restriction>.
UPLAYER - A combination of TYPE=PLAYER and UEVAL=<restriction>.
& SEMAPHORES
Topic: SEMAPHORES
Semaphores may be used for synchronizing complex objects or for enforcing
mutual exclusion. You may use any object you own or any LINK_OK object as
a semaphore, and any type of object (thing, room, player, or exit) may be
used.
The semaphore state of an object is shown by the Semaphore attribute (which
is read-only); a positive number indicates the number of commands awaiting
notifies, and a negative number indicates the number of waits on that
semaphore that will not block.
Use the '@wait <object>' form of the @wait command to request a command be
delayed until <object> is notified with the @notify command. The @drain
and @notify/all commands clear the semaphore on <object>, either
discarding or executing all pending commands. Remember that the
object performing the @wait executes the command, not the object used
as a semaphore.
{ 'help semaphores2' for more }
& semaphores2
You may also combine the semaphore and timer options of @wait with
'@wait <object>/<timeout> = <command>' If the time period expires before
the semaphore is notified, then the command is executed and the semaphore
count is decremented, just as if the command had been run because the
semaphore had been notified.
Examples: <simple> @wait semaphore="Foo
@notify semaphore
<mutex lock> @va mutex lock=@wait me=@trig me/vb
@vb mutex lock="Got it!;@notify me
@startup mutex lock=@notify me
<timed wait> @wait timer/60 = "Sixty Second Timer.
In the above examples you will say "Foo" after semaphore is notified,
you will say "Got it" when you have the mutual exclusion lock mutex lock
(You could have also modified object registers that need to be protected
from concurrent update), and you will say "Sixty Second Timer." either when
timer is notified or after sixty seconds pass.
See also: @drain, @notify, @wait.
& SPOOFING
Topic: SPOOFING
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. Note that the NOSPOOF flag
allows players to see exactly who is spoofing what.
Example:
... From TinyJerk's perspective ...
> @emit Wizard is a jerk!
Wizard is a jerk.
... From Wizard's perspective, Wizard is set NOSPOOF ...
[TinyJerk(#226)] Wizard is a jerk!
> @boot tinyjerk
You booted TinyJerk off!
TinyJerk has disconnected.
1 connection closed.
... TinyJerk's perspective again ...
Wizard gently shows you the door.
*** Disconnected ***
& SUBSTITUTIONS
Topic: SUBSTITUTIONS
All messages may contain %-substitutions, which evaluate to gender-specific
pronouns if the player's gender is set or to other useful information.
Information returned is based on the player that caused the message to be
displayed, not the object that stored the message or which is running the
action list.
Simple format substitutions:
%r = Carriage return / newline.
%t = Tab character.
%b = A single blank space.
%% = The literal '%' character.
%\ = The literal '\' character.
Continued in 'help Substitutions2'.
& Substitutions2
Substitutions related to the enactor (the object which caused the
action to be executed, or the message to be displayed):
%# = Enactor's dbref.
%n, %N = Enactor's name. Equiv: name(%#)
%s, %S = Subjective pronoun: he, she, it, they. Equiv: subj(%#)
%o, %O = Objective pronoun: him, her, it, them. Equiv: obj(%#)
%p, %P = Possessive pronoun: his, her, its, their. Equiv: poss(%#)
%a, %A = Absolute possessive pronoun: his, hers, its, theirs.
%l = Dbref of enactor's location. Equiv: loc(%#)
For those substitutions that have either lower-case or upper-case
forms, using the upper-case letter will capitalize the first letter
of the result; i.e., '%S' returns 'He', 'She', 'It', or 'They'.
Continued in 'help Substitutions3'.
& Substitutions3
Other substitutions:
%! = Dbref of the object holding the message or running the
action list ('me').
%@ = Dbref of the caller. Except in u()-type functions, same as %#.
%0-%9 = Value of positional parameter/stack location 0 through 9.
%q0-%qz = Value of registers 0-9 and A-Z. Equiv: r(0) - r(z)
%q=<var> = The <angle brackets> are literal. Named register. Equiv: r(var)
%va-%vz = Contents of attributes VA through VZ. Equiv: v(va) - v(vz)
%=<var> = The <angle brackets> are literal. Contents of an attribute.
Equiv: v(<var>) (no <>), i.e., %=<test> is equivalent to
v(test) or get(me/test)
%_<var> = Value of a variable set via setx(). Equiv: x(<var>)
Normally, this is a single-letter variable name, but if
the name is enclosed in angle brackets, multi-letter variable
names can be used. '%_<foo>' is equivalent to 'x(foo)'.
%x<code> = ANSI color substitution.
%m = Text of the last command executed.
%c = Depending on configuration, equivalent to either %m or %x.
Note: %<whatever> is equivalent to [v(<whatever>)], but is more efficient.
See also: CALLER, GENDER, V(), ANSI().
& SUCCESS
Topic: SUCCESS
You successfully use a player or a thing when you take it (because you
passed the lock). You successfully use an exit when you go through it.
You successfully use a room when you look around and the room is not locked
against you.
See also: get, look, @asuccess, @lock, @osuccess, @success.
& SWITCHES
Topic: SWITCHES
Some commands have command switches associated with them that can be used
to modify their behavior. For instance, switches on the @ps command
control the amount of information displayed, and switches on the @switch
command indicate whether to perform all actionlists whose targets match
the search string, or just the first.
See also: @list.
& OBJECT TYPES
Topic: OBJECT TYPES
There are 4 types of objects: things, players, exits, and rooms. The first
letter following an object's ID number indicates the type: P(layer),
E(xit), R(oom), otherwise, thing. Things are inanimate objects that can
be carried. Players are animate objects that can move and carry. Exits
are the means by which objects move from room to room. Rooms are locations
that contain objects and linked exits.
& Scan Order
Topic: Scan Order
When you submit a command to be executed by MUSH (whether by typing it in or
by having a machine run it, the following steps are performed, in sequence.
If the command matches something in a step, the matching actions are
performed and the walk down the list stops.
- If the command was typed in, it is checked against the uppercase-only
commands (QUIT, WHO, etc). If so, the command is executed.
- The first letter of the command is checked to see if it is a single-
character command (", :, etc). If so, %-substitution and function
evaluation may be performed (depending on the command), and the command
is executed.
- A check is performed to see if any modules have intercepted the
command. In particular, if the comsys module is enabled, the command
is checked to see if it is one of the player's channel aliases. If so,
the comsys command is executed.
Continued in 'help Scan Order2'.
& Scan Order2
- The command is checked to see if it is the 'home' command. If so, the
player or object performing the command goes home.
- The command is checked against the exits in its current room. If one
matches, the player is moved through the exit. If more than one exit
matches, one is picked randomly from the exits for which the player
passes the lock; if the player does not pass any locks, then the exit
to be tried is picked randomly.
- The command is checked against exits in the Master Room. Multiple
exit matches are resolved as per above.
- The first word of the command is checked to see if it is an internal
built-in MUSH command, or something which has been @addcommand'd.
If it is a built-in, the remainder of the command is broken up into
arguments; %-substitution and function evaluation may be performed
on the (split up) arguments; if an @addcommand, evaluation is not
performed. The command is then executed.
Continued in 'help Scan Order3'.
& Scan Order3
- %-substitution and function evaluation is performed on the command.
All subsequent attempts to match will be against this evaluated string.
- The command is checked against leave aliases on the player's current
location. If matched, the player leaves.
- The command is checked against the enter aliases for objects in the
player's current location. If matched, the player enters the object.
- An attempt to match $commands is performed, in the following order:
The player himself (if configuration permits), objects in the player's
location, the player's location itself, and objects in the player's
inventory. All that match are performed, unless a match was made
on a STOP-set object (see 'help STOP').
Continued in 'help Scan Order4'.
& Scan Order4
- If local-master-room checking is enabled, and the ZONE flag is
set on the parent room of the player's location, objects in that
room are checked for $command matches. STOP applies as above.
- If zones are enabled, and the ZMO of the player's location is a room,
the command is checked against the exits of the ZMO. Multiple matches
are resolved as per normal exit movement.
- If zones are enabled, and the ZMO of the player's location is a room,
objects in that room are checked for $command matches. STOP applies.
- If zones are enabled, and the ZMO of the player's location is not a
room, the ZMO itself is checked for $command matches. STOP applies.
- If local-master-room checking is enabled, and the ZONE flag is set
on the parent of the player, objects in that parent's location are
checked for $command matches. STOP applies as above.
Continued in 'help Scan Order5'.
& Scan Order5
- If zones are enabled, the player's ZMO is checked for $command matches.
STOP applies as above.
- All objects in the master room are checked for $commmand matches.
STOP applies as above.
- The master room itself is checked for $command matches. STOP applies.
- Another check is performed for modules intercepting the command.
If nothing has been matched, a 'Huh?' message is returned.
Continued in 'help Scan Order6'.
& Scan Order6
Note: Commands that can cause other commands to be executed (such as @wait,
@switch, @trigger, etc) never perform substitution on their arguments, they
leave the evaluation to the command that is to be executed. This prevents
most of the problems with getting objects to perform unintended commands by
putting a ';', '}', or ',' in an argument. The @force command is an
exception in that it evaluates its argument, so it should be used with
caution (preferably by never using it to pass information that someone else
entered, use @trigger instead).
Also, the construct '$xx *:%0' does not work (and is very dangerous
programming), use '$xx *:@force me=%0' if you need this functionality.
& Zones
See 'help Zone' for the Zone flag and local master room information,
and 'help Zone Objects' for multi-control objects using the CONTROL_OK
flag and ControLock.
& Zone Objects
Topic: Zone Objects
Zones are areas of the MUSH which may be controlled by many people.
Essentially, they allow group ownership of objects. The have_zones
config parameter must be enabled.
The default zone is NOTHING. Any building done by a player defaults
to belonging to the same zone that the player belongs to.
Every zone is defined by a Zone Master Object (ZMO). The ZMO is an
ordinary MUSH object owned by some player. A wizard may change the
zone of an object or player to a ZMO.
If the ZMO is a room, it is called a "Parent room." Most of the
statements about ZMOs also apply to parent rooms; for details,
see the help topic PARENT ROOMS.
Continued in 'help Zone Objects2'.
& Zone Objects2
Anyone who can pass the Control lock of the ZMO has control over all
objects in that zone that are set CONTROL_OK. This, in essence, gives
that player wizard powers within that zone. For this reason, one must
be extremely careful with the Control locks of ZMOs!
Also, $commands on a ZMO are treated as global within that zone.
The game attempts to match $commands for the ZMO of the player's
location, as well as $commands for the player's own zone.
& V()
Function: v(<string>)
The V function can be used as an alternative for percent (%) substitution
and also as a replacement for get(me/<arg>). If the argument is two
characters long or longer and starts with a letter, then the object
performing the v() call (and its parent, if necessary) is searched for the
named attribute, and its value is returned if possible. Otherwise, a
percent substitution is performed on the argument (so that v(o) is
equivalent to %o, for instance). The percent form (%o in the previous
example) is preferred as it is faster, and there are no longer any security
problems associated with it. Note that attributes with single-character
names cannot be retrieved with v().
A percent-substitution is available for the equivalent of v()'s ability
to retrieve an attribute: %=<var>, where the variable named <var> is
literally enclosed within angle-brackets. For instance, v(test) is
equivalent to %=<test> (and to get(me/test), as well).
See also: GENDER, SUBSTITUTION, PARENT OBJECTS.
& wordpos()
Function: wordpos(<string>, <charpos>[, <delim>)
Returns the number of the word within <string> where the character position
<charpos> falls. Spaces between words are treated as belonging to the word
that follows them. If <charpos> is not within the string, the value #-1 is
returned. Both words and characters are numbered starting at 1.
<delim> may be used to specify a delimiter other than a space.
Example:
> say wordpos(This is a test, 4)
You say, "1"
> say wordpos(This is a test, 5)
You say, "2"
> say wordpos(This is a test, 6)
You say, "2"
> say wordpos(This is a test, 20)
You say, "#-1"
& type()
Function: type(<object>)
Returns a string indicating the object type of <object>, either EXIT,
PLAYER, ROOM, or THING.
Example:
> say type(me)
You say, "PLAYER"
> say type(here)
You say, "ROOM"
& hasflag()
Function: hasflag(<object>[/<attribute>],<flag>)
Returns true if object <object> has the flag named <flag> set on it,
or, if <flag> is PLAYER, THING, ROOM, or EXIT, if <object> is of
the specified type.
You may not be able to retrieve information for objects that you
cannot examine.
With an object-attribute pair, this can also be used to check for the
attribute flags "dark", "hidden", "html", "visual", "no_command",
"no_inherit", "no_parse", "locked", "wizard", and "god".
Example:
> say hasflag(me, wizard)
You say, "0"
> say hasflag(me, connect)
You say, "1"
See also: hasflags(), andflags(), orflags(), hastype(), haspower()
& HASFLAGS()
Function: hasflags(<object>, <flag list 1>[, <flag list 2>, <flag list N>])
This function returns 1 if <object> has all the flags in <flag list 1>,
or all the flags in <flag list 2>, and so forth (up to eight lists).
Otherwise, it returns 0.
A flag list consists of a list of types (PLAYER, THING, ROOM, EXIT) or
flag names; if an item begins with '!', rather than checking if the
object has the flag, it checks for the object NOT having the flag.
You can think of this being approximately equivalent to:
or(andflags(<obj>,<list 1>),[...],andflags(<obj>,<list N>))
(if andflags() took flag names rather than flag letters, of course.)
For instance, hasflags(#5, player royalty, thing inherit !puppet, wizard)
would return 1 if #5 is an object of type PLAYER with the ROYALTY flag,
or if #5 is an object of type THING with the INHERIT flag but not the
PUPPET flag, or if #5 has the WIZARD flag.
See also: hasflag(), hastype(), andflags(), orflags()
& ANDFLAGS()
Function: andflags(<object>,<list of flags>)
This function returns 1 if <object> has all the flags in a specified list,
and 0 if it does not. The list is specified with a single letter standing
for each flag, like the output of the FLAGS() function. A '!' preceding
a flag letter means "not flag".
Thus, ANDFLAGS(me,WD) would return 1 if I was set WIZARD and DARK.
ANDFLAGS(me,W!Dc) would return 1 if I was set WIZARD, not DARK, and
CONNECTED.
If a letter does not correspond to any flag, <object> doesn't have it,
so the function returns 0. There can be an arbitrary number of flags.
Do not put spaces between flag letters.
See also: hasflag(), hasflags(), orflags()
& ORFLAGS()
Function: orflags(<object>,<list of flags>)
This function returns 1 if <object> has at least one of the flags in a
specified list, and 0 if it does not. The list is specified with a
single letter standing for each flag, like the output of the FLAGS()
function. A '!' preceding a flag letter means "not flag".
Thus, ORFLAGS(here,JA) would return 1 if my location is set JUMP_OK
or ABODE. ORFLAGS(me,D!c) would return 1 if I am DARK or not CONNECTED.
If a letter does not correspond to any flag, <object> doesn't have it,
so it is simply ignored. There can be an arbitrary number of flags. Do
not put spaces between flag letters.
See also: hasflag(), hasflags(), andflags()
& delete()
Function: delete(<string>,<first>,<len>)
Returns <string>, but with <len> characters starting after the character
at position <first> removed. In other words, this function copies <first>
characters, skips <len> characters, and then copies the remainder of the
string.
Example:
> say delete(abcdefgh, 3, 2)
You say, "abcfgh"
> say delete(Would you like coffee or perhaps tea?, 15, 18)
You say, "Would you like tea?"
& lock()
Function: lock(<object>[/<whichlock>])
Returns the named lock on <object>. If you don't specify the lock to get,
the default lock is returned. You must control <object>.
& elock()
Function: elock(<object>[/<whichlock>], <actor>)
Checks if <actor> would pass the named lock on <object>. You must be
nearby, or control, at least one of the objects. Returns 0 or 1, or
#-1 with an error string.
See also: elockstr()
& elockstr()
Function: elockstr(<locked object>, <actor>, <lock string>)
Checks if <actor> would pass a lock on <locked object> with syntax
<lock string>. You must be nearby, or control, <actor>. You must
control <locked object>. Returns 0 or 1, or #-1 with an error string.
Example:
> say elockstr(me, #4, #4|#5)
You say, "1"
See also: elock()
& LWHO()
Function: lwho()
Returns a list of the db numbers of connected players.
Example:
> WHO
Player Name On For Idle Doing
Mortal 00:11 0s
Evinar 00:12 6m
Wizard 00:32 6s
3 Players logged in.
> say lwho()
You say, "#226 #271 #1"
See also: WHO, conn(), idle().
& OBJ()
Function: obj(<object>)
Returns the proper objective pronoun (him, her, it, them) for referring to
<object>, based on the object's Sex attribute. You must either control
or be near <object>.
& POSS()
Function: poss(<object>)
Returns the proper possessive pronoun (his, her, its, their) for referring
to <object>, based on the object's Sex attribute. You must either control
or be near <object>.
& APOSS()
Function: aposs(<object>)
Returns the proper absolute possessive pronoun (his, hers, its, theirs) for
referring to <object>, based on the object's Sex attribute. You must either
control or be near <object>.
& SUBJ()
Function: subj(<object>)
Returns the proper subjective pronoun (he, she, it, they) for referring to
<object>, based on the object's Sex attribute. You must either control
or be near <object>.
& NEARBY()
Function: nearby(obj1,obj2)
Tests if obj1 is near obj2 (if it is in the same location, in obj2's
inventory, or is obj2's location). You must control either obj1 or obj2, or
be near either one of them, if both of these tests fail then 0 is returned.
This function returns 1 if the two objects are nearby and 0 if not.
& GET()
Function: get(<object>/<attribute>)
The get function fetches the specified attribute from the named object.
It can be used to get attributes from objects you own, public and visual
attributes of objects near you, and public and visual attributes other
than the description of players wherever they may be. If the attribute is
not present on <object>, its parent is searched for the attribute.
A percent-substitution equivalent to 'get(me/<attribute>)' is available.
This is '%=<attribute>', where the name of the attribute is literally
enclosed in angle brackets. For instance, 'get(me/test)' is equivalent
to '%=<test>', and to 'v(test)'.
Example:
> read me
> say get(me/desc)
See also: get_eval().
& GET_EVAL()
Function: get_eval(<object>/<attribute>)
The get_eval function returns the specified attribute from the named object
(just like the get function), except that function references and
%-substitutions have already been performed. In function references,
'me' refers to the object being looked at, and %-substitutions that refer
to the enactor (such as %n, %#, etc) refer to the object making the get_eval
call. If the attribute is not present on <object>, its parent is searched
for the attribute.
Example:
> @va test = This is a get_eval test on %n. The vb is [get(me/vb)]
> @vb test = VB from test
> @vb me = VB from me
> say get(test/va)
You say, "This is a get_eval test on %n. The vb is [get(me/vb)]"
> say get_eval(test/va)
You say, "This is a get_eval test on Foobar. The vb is VB from test"
See also: get().
& DEFAULT()
Function: default(<obj>/<attr>,<default case>)
This function returns the value of <obj>/<attr>, as if retrieved via
the get() function, if the attribute exists and is readable by you.
Otherwise, it evaluates the default case, and returns that.
Note that the default case is only evaluated if the attribute does
not exist or cannot be read.
This is useful for code that needs to return the value of an attribute,
or an error message or default case, if that attribute does not exist.
Examples:
> &TEST me=apple orange banana
> say default(me/Test, No fruits!)
You say, "apple orange banana"
> &TEST ME
> say default(me/Test, No fruits!)
You say, "No fruits!"
See also: get(), get_eval(), u(), edefault(), udefault().
& EDEFAULT()
Function: edefault(<obj>/<attr>,<default case>)
This function returns the evaluated value of <obj>/<attr>, as if
retrieved via the get_eval() function, if the attribute exists and
is readable by you. Otherwise, it evaluates the default case, and
returns that. The default case is only evaluated if the attribute
does not exist or cannot be read.
Example:
> &TEST me=You have lost [rand(10)] marbles.
> say edefault(me/Test,You have no marbles.)
You say, "You have lost 6 marbles."
> &TEST me
> say edefault(me/Test,You have no marbles.)
You say, "You have no marbles."
See also: get(), get_eval(), u(), default(), udefault().
& UDEFAULT()
Function: udefault([<obj>/]<attr>,<default case>[,<arg>]...)
This function returns the value of the user-defined function
as defined by <attr> (or <obj>/<attr>), as if retrieved via
the u() function, with <args>, if the attribute exists and is
readable by you.
Otherwise, it evaluates the default case, and returns that. The
default case is only evaluated if the attribute does not exist
or cannot be read.
Examples:
> &TEST me=[center(%0,5,*)]
> say udefault(Test,-- BOOM --,ACK)
You say, "*ACK*"
> &TEST me
> say udefault(me/Test,-- BOOM --,ACK)
You say, "-- BOOM --"
See also: get(), get_eval(), u(), default(), edefault().
& TIME()
Function: time()
Gives you the current time.
WARNING! This is the time on the machine that the mud is running on, and
not where you are.
Example:
> say time()
You say, "Thu Dec 19 09:48:06 1991"
See also: convsecs(), convtime(), secs().
& TIMEFMT()
Function: timefmt(<format>[, <time in seconds>])
This function returns a formatted time. If <time in seconds> is not
specified, the current time is used. This is based on the local time
zone of the MUSH's host machine.
The supported time format codes are listed below. Depending on the host
machine's operating system, not all of the codes below might be supported;
see the host system's documentation for strftime(3C). The less-common
codes are marked with a '*', below.
Example:
> say timefmt(Today is $A. The year is $Y. It is $B $d.)
You say, "Today is Sunday. The year is 2001. It is January 14."
Day of week codes:
$a - Abbreviated, Sun-Sat $A - Full, Sunday-Saturday
$w - Numeric, 0-6, Sunday is 0
Continued in 'help timefmt2'.
& timefmt2
Day of month codes:
$d - 01-31 $e - 1-31, field width of 2 (*)
Month codes:
$b - Abbreviated, Jan-Dec $B - Full, January-December
$m - Numeric, 01-12
Year codes:
$y - Two-digit year, 00-99 $Y - Four-digit year
$C - Century number
Time codes:
$H - Hour of 24-hour day, 00-23 $I - Hour of 12-hour day, 01-12
$M - Minutes, 00-59 $S - Seconds, 00-60
$p - AM/PM (*) $P - am/pm (AM/PM on some systems)
$z - GMT offset, i.e. -0800 (*) $Z - Time zone name, i.e. PST
Continued in 'help timefmt3'.
& timefmt3
Year-related time codes:
$j - Day number of year, 001-366
$U - Week of the year, 00-53, Sunday is the first day of week 1
$W - Week of the year, 00-53, Monday is the first day of week 1
Pre-formatted strings:
$c - Date and time, comparable to results of convtime()
$D - Date equivalent to $m/$d/$y (*)
$r - Twelve-hour time representation, probably $I:$M:$S $p (*)
$R - Time format equivalent to $H:$M (*)
$x - Date, in format appropriate to local timezone
$X - Time, in format appropriate to local timezone
$$ - Literal '$' character
& RAND()
Function: rand(<num>)
Rand returns an integer between 0 and num-1.
Example:
> say rand(10)
You say, "6"
> say rand(10)
You say, "1"
> say rand(10)
You say, "4"
> say rand(10)
You say, "9"
> say rand(10)
You say, "1"
& DIE()
Function: die(<number of times to roll die>, <number of sides on die>)
This function simulates rolling dice. It "rolls" a die with a given
number of sides, a certain number of times, and sums the results.
For example, 'die(2,6)' would roll "2d6" -- two six-sided dice,
generating a result in the range 2-12.
& EXIT()
Function: exit(<object>)
Exit returns the first exit on the list of exits in the object. Dark exits
are not listed, unless you own the object. Unlike LEXITS(), this function
does not provide information about exits in parent objects.
See also: con(), lcon(), lexits(), next().
& ABS()
Function: abs(<number>)
Returns the absolute value of its argument.
<number> may be a floating point number, and a floating point result
is returned.
Examples:
> say abs(4)
You say, "4"
> say abs(-4)
You say, "4"
> say abs(0)
You say, "0"
& MAX()
Function: max(<number1>,<number2>[,<numberN]...)
Returns the largest integer from among its arguments.
Up to 30 arguments may be specified.
<numberN> may be a floating point number, and a floating point result
is returned.
Examples:
> say max(2,4)
You say, "4"
> say max(-100,50,0,25)
You say, "50"
See also: min(), lmax()
& MIN()
Function: min(<number1>,<number2>[,<numberN]...)
Returns the smallest integer from among its arguments.
Up to 30 arguments may be specified.
<numberN> may be a floating point number, and a floating point result
is returned.
Examples:
> say min(2,4)
You say, "2"
> say min(-100,50,0,25)
You say, "-10"
See also: max(), lmin()
& ADD()
Function: add(<number1>,<number2>[,<numberN>]...)
Returns the result of adding its arguments together.
You may add up to 30 numbers in one add() call.
<numberN> may be a floating point number, and a floating point result
is returned.
Example:
> say add(2,4)
You say, "6"
> say add(5,3,7,-4)
You say, "11"
See also: ladd(), div(), mod(), mul(), sub().
& SUB()
Function: sub(<number1>,<number2>)
Returns the result of subtracting <number2> from <number1>.
The numbers may be floating point numbers, and a floating point result
is returned.
Example:
> say sub(5,2)
You say, "3"
See also: add(), div(), mod(), mul().
& MUL()
Function: mul(<number1>,<number2>[,<numberN>]...)
Returns the result of multiplying its arguments together.
<numberN> may be a floating point number, and a floating point result
is returned.
Example:
> say mul(3,5)
You say, "15"
> say mul(3,5,-2)
You say, "-30"
See also: add(), div(), fdiv(), mod(), round(), sub(), trunc().
& DIV()
Function: div(<number1>,<number2>)
Returns the integer quotient from dividing <number1> by <number2>,
rounded towards zero. <numberN> may be a floating point number, and
an integer result is returned.
Example:
> say div(15,3)
You say, "5"
> say div(16,3)
You say, "5"
> say div(17,3)
You say, "5"
> say div(18,3)
You say, "6"
> say div(-17,3)
You say, "-5"
This function may also be called as idiv().
See also: floordiv(), remainder(), add(), fdiv(), mod(), mul(), round(),
sub(), trunc().
& FLOORDIV()
Function: floordiv(<number1>,<number2>)
Returns the integer quotient from dividing <number1> by <number2>,
rounded down (towards zero if positive, away from zero if negative).
<numberN> may be a floating point number, and an integer result is
returned.
Example:
> say floordiv(15,3)
You say, "5"
> say floordiv(16,3)
You say, "5"
> say floordiv(17,3)
You say, "5"
> say floordiv(18,3)
You say, "6"
> say floordiv(-17,3)
You say, "-6"
See also: div(), modulo(), add(), fdiv(), mul(), round(), sub(), trunc().
& FDIV()
Function: fdiv(<number1>,<number2>)
Returns the floating point quotient from dividing <number1> by <number2>.
<number> may be a floating point number, and a floating point result is
returned.
Results:
> say fdiv(15,3)
You say, "5"
> say fdiv(16,3)
You say, "5.333333"
> say fdiv(17,3)
You say, "5.666667"
> say fdiv(18,3)
You say, "6"
> say fdiv(-17,3)
You say, "-5.666667"
> say fdiv(10,3.5)
You say, "2.857143"
See also: See also: add(), div(), mod(), mul(), round(), sub(), trunc().
& MOD()
Function: mod(<integer1>,<integer2>)
This is an alias for the remainder() function by default.
& MODULO()
Function: modulo(<integer1>,<integer2>)
Returns the smallest integer with the same sign as <integer2> such that
the difference between <integer1> and the result is divisible by <integer2>.
This is similar to remainder() except for the sign rule. Note that for
nearly all integers, x = y * floordiv(x,y) + modulo(x,y).
Example:
> say modulo(15,3)
You say, "0"
> say modulo(16,3)
You say, "1"
> say modulo(17,3)
You say, "2"
> say modulo(18,3)
You say, "0"
> say modulo(-17,3)
You say, "1"
> say modulo(17,-3)
You say, "-1"
See also: remainder(), div(), floordiv(), fdiv(), mul(), round(),
add(), sub(), trunc().
& REMAINDER()
Function: remainder(<integer1>,<integer2>)
Returns the smallest integer with the same sign as <integer1> such that
the difference between <integer1> and the result is divisible by <integer2>.
This is similar to modulo() except for the sign rule. Note that for nearly
all integers, x = y * div(x,y) + remainder(x,y).
Example:
> say remainder(15,3)
You say, "0"
> say remainder(16,3)
You say, "1"
> say remainder(17,3)
You say, "2"
> say remainder(18,3)
You say, "0"
> say remainder(-17,3)
You say, "-2"
> say remainder(17,-3)
You say, "2"
See also: modulo(), div(), floordiv(), fdiv(), mul(), round(),
add(), sub(), trunc().
& DIST2D()
Function: dist2d(x1, y1, x2, y2)
Returns the integer distance between the Cartesian points in two dimensions
(x1,y1) and (x2,y2).
Example:
> say dist2d(0,0,3,4)
You say, "5"
See also: dist3d()
& DIST3D()
Function: dist3d(x1, y1, z1, x2, y2, z2)
Returns the integer distance between the Cartesian points in three
dimensions (x1,y1,z1) and (x2,y2,z2).
Example:
> say dist3d(0,0,0,10,15,20)
You say, "27"
See also: dist2d()
& VADD()
vadd(<vector>,<vector>[,<delim>][,<output delim>])
Returns the sum of two vectors. A vector is a list of numbers
separated by spaces or a delimiter, and may have any number of
dimensions.
Examples:
> @pemit me=vadd(1 2 3,4 5 6)
5 7 9
> @pemit me=vadd(0|0|0,1|2|3,|,-)
1-2-3
& VDIM()
vdim(<vector>[,<delim>])
Returns the dimensions of a vector.
Example:
> @pemit me=vdim(1 2 3 4)
4
& VDOT()
vdot(<vector>,<vector>[,<delim>][,<output delim>])
Returns the dot product of two vectors. The dot product of two
vectors is a scalar. (a,b,c) * (x,y,z) = aw + bx + cz
Example:
> @pemit me=vdot(1 2 3,2 3 4)
20
& VMAG()
vmag(<vector>[,<delim>]
Returns the magnitude of a vector, using a euclidean distance metric.
That is, for vector a b c d, returns sqrt(a^2+b^2+c^2+d^2).
Example:
> @pemit me=vmag(3 4)
5
& VMUL()
vmul(<vector|number>,<vector|number>[,<delim>][,<output delim>])
Returns the result of either multiplying a vector by a number (scalar
multiplication), or an elementwise multiplication of two vectors.
Examples:
> @pemit me=vmul(1 2 3,2)
2 4 6
> @pemit me=vmul(1 2 3,2 3 4)
2 6 12
& VSUB()
vsub(<vector>,<vector>[,<delim>][,<output delim>])
Returns the difference between two vectors.
Example:
> @pemit me=vsub(3 4 5,3 2 1)
0 2 4
> @pemit me=vsub(6-4-2,5-2-0,-)
1-2-2
& VUNIT()
vunit(<vector>[,<delim>][,<output delim>])
Returns the unit vector (a vector of magnitude 1), which points
in the same direction as the given vector.
Examples:
> @pemit me=vunit(2 0 0)
1 0 0
> @pemit me=vmul(vunit(5 6 7),vmag(5 6 7))
5 6 7
& INC()
Function: inc(<number>)
Returns <number>, incremented by 1 (the <number>, plus 1). It is
equivalent to add(<number>, 1) but is faster and more efficient.
Decimal places will be truncated.
See also: dec(), add(), sub().
& DEC()
Function: dec(<number>)
Returns <number>, decremented by 1 (the <number>, minus 1). It is
equivalent to sub(<number>, 1) but is faster and more efficient.
Decimal places will be truncated.
See also: inc(), add(), sub().
& LADD()
Function: ladd(<list of numbers>[,<delim>])
Adds a list of numbers together.
Examples:
> say [ladd(1 3 5 -1)]
You say, "8"
> say [ladd(1:2:3,:)]
You say, "6"
See also: add().
& LMIN()
Function: lmin(<list of numbers>[,<delim>])
Obtains the smallest number out of a list of numbers (i.e., the minimum).
Example:
> say [lmin(3, 1.1, 5)]
You say, "1.1"
See also: min().
& LMAX()
Function: lmax(<list of numbers>[,<delim>])
Obtains the largest number out of a list of numbers (i.e., the minimum).
Example:
> say [lmax(3.2, 1 , 5)]
You say, "5"
See also: max().
& LAND()
Function: land(<list of strings>[,<delim>])
Takes a list of strings, and returns 1 if all words in the string are
non-zero numbers, and 0 otherwise.
Example:
> say [land(1 3 x 5)]
You say, "0"
> say [land(2 -1 4)]
You say, "1"
See also: and().
& LANDBOOL()
Function: landbool(<list of strings>[,<delim>])
Takes a list of strings, and returns 1 if all the words in the string
have a boolean true value, and 0 otherwise.
Example:
> say [landbool(1 x #2)]
You say, "1"
> say [landbool(1 x 0)]
You say, "0"
See also: andbool().
& LOR()
Function: lor(<list of strings>[,<delim>])
Takes a list of strings, and returns 1 if at least one of the words in
the string is a non-zero number, and 0 otherwise.
Example:
> say [lor(1 x 5)]
You say, "1"
> say [lor(x 0 #2)]
You say, "0"
See also: or().
& LORBOOL()
Function: lorbool(<list of strings>[,<delim>])
Takes a list of strings, and returns 1 if at least one of the words in
the string has a boolean true value, and 0 otherwise.
Example:
> say [lorbool(0 x #2)]
You say, "1"
See also: orbool().
& FIRST()
Function: first(<string>[, <delim>])
Returns the first word of a string, that is, everything to the left
of the first space in the string, or the entire string if there are
no spaces in the string.
<delim> may be used to specify a word delimiter other than a space.
Example:
> say first(This is a test)
You say, "This"
> say first(Would you like coffee, or perhaps tea)
You say, "Would"
> say first(List&with&nonstandard&delimiters,&)
You say, "List"
See also: rest(), last().
& REST()
Function: rest(<string>[, <delim>])
The rest function takes a string, returns all the string except the first
word, that is, everything to the right of the first space, or an empty
string, or the empty string if there are no spaces in the string.
<delim> may be used to specify a word delimiter other than a space.
Example:
> say rest(This is a test)
You say, "is a test"
> say rest(Would you like coffee, or perhaps tea)
You say, "you like coffee, or perhaps tea"
> say rest(List!with!different!delimiters,!)
You say, "with!different!delimiters"
See also: first(), last().
& LAST()
Function: last(<string>[, <delim>])
Returns the last word of a string, that is, everything to the right
of the last space in the string, or the entire string if there are no
spaces in the string.
<delim> may be used to specify a word delimiter other than a space.
Example:
> say last(This is a test)
You say, "test"
> say last(Happy-Fun-Test-Thing,-)
You say, "Thing"
See also: first(), rest().
& LASTACCESS()
Function: lastaccess(<object>)
Returns the time, in seconds, of when <object> was last accessed.
You must have permission to examine <object>.
An object is consider "accessed" when an attribute is fetched from it.
& LASTCREATE()
Function: lastcreate(<object>, <type>)
Returns the dbref of the last object of <type> that was created by
<object>. You must control <object>.
In general: If <type> is 'R', it will be the dbref of the object's most
recent @dig. If it is 'E', it will be the dbref of the object's most
recent @open. If it is 'T', it will be the dbref of the object's most
recent @create. If it is 'P', it will be the dbref of the object's
most recent @pcreate.
Note that @clone will set the 'most recent' in accordance with the
type of the object being cloned.
& LASTMOD()
Function: lastmod(<object>)
Returns the time, in seconds, of when <object> was last modified.
You must have permission to examine <object>.
An object is consider "modified" when an attribute is set upon it,
when a flag or power is set/unset on it, or when it is the target
of @name, @chown, @chzone, @link, or @parent. (Note that the object
receiving ownership, being zoned to, linked to, or parented to,
etc., is not considered modified -- only the object whose owner,
zone, link, or parent is changing is considered modified.)
& OBJMEM()
Function: objmem(<object>[/<attribute pattern>])
If no attribute pattern is specified, this returns the number of bytes
of memory consumed by an object, including both attribute text and
object overhead.
If an attribute wildcard pattern is specified, this returns the number
of bytes of memory consumed by attribute text for those attributes on
<object>. To just get a count of the number of bytes used by all
attribute text on an object, use 'objmem(<object>/*)'. You must be
able to read an attribute in order to check its size.
& STRLEN()
Function: strlen(<string>)
Returns the number of characters in <string>.
Example:
> say strlen(This is a test)
You say, "14"
> say strlen(Would you like coffee, or perhaps tea)
You say, "37"
& MID()
mid(<string>, <first>, <length>)
Mid returns a segment of the string, the <length> characters to the
right of the <first> character. Note that the first character in a
string is numbered zero, and not one.
& COMP()
comp(<string1>, <string2>)
Comp compares two strings. It returns 0 if they are the same, 1 if
string2 is less than/precedes alphabetically string1, and -1
otherwise.
& S()
s(string)
This function performs pronoun substitution in a string, as well as
function evaluation, and then returns that string. As usual, %n is
the name, %s the subjective pronoun, %o the objective, %p the possessive,
and %a the absolute possessive. It is important to note that the pronoun
is that of the triggering object (the enactor).
Example:
> @va object = %S is [name(%#)]
> @vb object = $test: @pemit %#=%va
> test
%S is [name(%#)]
> @vb object = $test: @pemit %#=[s(%va)]
> test
He is Wizard
See also: subeval(), objeval().
& SUBEVAL()
This function is similar to S(), but it performs only pronoun substituion
in a string; it does not perform function evaluation.
Example:
> @va object = %S is [name(%#)]
> @vb object = $test: @pemit %#=%va
> test
%S is [name(%#)]
> @vb object = $test: @pemit %#=[s(%va)]
> test
He is Wizard
> @vb object = $test: @pemit %#=[subeval(%va)]
He is [name(%#)]
See also: s(), objeval().
& LEFT()
Function: left(<string>, <number>)
This function returns the first <number> characters from the left-hand
side of <string>.
Example:
> say left(flipper,3)
You say, "fli"
See also: right(), mid()
& RIGHT()
Function: right(<string>, <number>)
This function returns the last <number> characters from the right-hand
side of <string>.
Example:
> say right(foobarbaz,4)
You say, "rbaz"
See also: left(), mid()
& LPOS()
Function: lpos(<string>, <characters>[, <odelim>])
This function returns a list of the positions that one or more <characters>
occupy in <string>, with the first character of the string being 0.
(Note that this differs from the pos() function, but it consistent with
functions such as mid().)
If <characters> is null, a space is assumed.
Example:
> say lpos(a-bc-def-g,-)
You say, "1 4 8"
> say lpos(a_b*cde,*_)
You say, "1 3"
& POS()
Function: pos(<string to search for>, <string to search within>)
This function returns the position that <string to search for>
begins in <string to search within>. Positions are numbered
starting at 1 (unlike other string functions, which start from 0).
If <string to search for> is not found, the function returns #-1.
ANSI is ignored.
Example: pos(man,superman) returns 6
& MATCH()
Function: match(<string>, <pattern>[, <delim>])
This function matches <pattern> against each word of <string>, returning
the number of the first word that matches. If no words match then 0 is
returned. The case of the characters being matched is not significant.
The pattern may contain the wildcards '*' and '?'. '?' matches any one
character, while '*' matches any number of characters, including none.
So 's?x' would match 'sex' or 'six', but not to 'socx', but 's*x' would
match any of them.
<delim> may be used specified to specify a delimiter other than a space.
Examples:
> say match(This is a test, test)
You say, "4"
> say match(This is a test, is)
You say, "2"
> say match(This is a test, *is*)
You say, "1"
> say match(This is a test, *not*)
You say, "0"
> say match(This is a test, is a)
You say, "0"
See also: LISTS, member(), matchall(), strmatch().
& MATCHALL()
Function: matchall(<string>,<pattern>[,<delim>][,<output delim>])
This function works identically to the match() function, save that it
returns all matches, not just the first: It returns the index numbers of
all words in the list <string> which match <pattern>. If none match, an
empty string is returned.
The output delimiter for this function works differently than other list
functions -- if not specified, it defaults to a space, NOT to the input
delimiter.
Examples:
> say matchall(This is a test of a test,test)
You say, "4 7"
> say matchall(apples|bananas|oranges|pears,*a*e*,|)
You say, "1 3"
> say matchall(apples bananas oranges pears,*a*e*, ,+)
You say, "1+3"
See also: LISTS, match(), strmatch().
& STRMATCH()
Function: strmatch(<string>,<pattern>)
This function matches <pattern> against the entire <string>, returning 1
if it matches and 0 if it does not. The case of the characters being
matched is not significant.
The pattern may contain the wildcards '*' and '?'. '?' matches any one
character, while '*' matches any number of characters, including none.
So 's?x' would match 'sex' or 'six', but not to 'socx', but 's*x' would
match any of them.
Examples:
> say strmatch(This is a test,*Test)
You say, "1"
> say strmatch(This is a test,*This)
You say, "0"
> say strmatch(This is a test,*is*is*)
You say, "1"
See also: match(), member(), wildmatch(), regmatch(), regmatchi().
& WILDMATCH()
Function: wildmatch(<string>,<pattern>,<register list>)
This function matches <string> against the wildcard pattern <pattern>,
returning 1 if it matches and 0 if it does not. There is a side-effect:
the portions of the string which match the wildcards will be set into
the specified local registers, in the order they were specified in
the list. <register list> can be a list of one through nine registers.
If the specified register is -1 or otherwise invalid, the substring
is not copied into a register.
For example, if <string> is 'cookies=30', and <pattern> is '*=*',
then the first substring is 'cookies' and the second substring is '30'.
If <register list> is '3 5', then %q3 will become 'cookies' and %q5
will become '30'. If <register list> was '-1 5', then the 'cookies'
substring would simply be discarded, thogh %q5 would still be '30'.
See also: strmatch(), regmatch(), regmatchi(), wildparse().
& REGMATCH()
Function: regmatch(<string>,<regexp>[,<register list>])
This function matches the regular expression <regexp> against the
entirety of <string>, returning 1 if it matches and 0 if it does not.
If <register list> is specified, there is a side-effect: any
parenthesized substrings within the regular expression will be set
into the specified local registers, in the order they were specified
in the list. <register list> can be a list of one through nine registers.
If the specified register is -1 or otherwise invalid, the substring is
not copied into a register.
For example, if <string> is 'cookies=30', and <regexp> is '(.+)=([0-9]*)'
(parsed; note that escaping may be necessary), then the 0th substring
matched is 'cookies=30', the 1st substring is 'cookies', and the 2nd
substring is '30'. If <register list> is '0 3 5', then %q0 will become
"cookies=30", %q3 will become "cookies", and %q5 will become "30".
If <register list> was '0 -1 5', then the "cookies" substring would
simply be discarded.
See 'help regexp syntax' for an explanation of regular expressions.
& REGMATCHI()
Function: regmatchi(<string>,<regexp>[,<register list>])
This function works identically to regmatch(), except that the
matching is not case-sensitive, i.e., 'A' and 'a' are automatically
equivalent to 'A|a'.
& WILDPARSE()
Function: wildparse(<string>,<pattern>,<list of variable names>)
This side-effect function matches the wildcard pattern <pattern>
against the entirety of <string>; if there's a match, it places
the wildcard-matched substrings into the corresponding named
variables. <list of variable names> can be up to ten strings.
For example, if <string> is 'cookies=30', and <pattern> is '*=*',
then the first substring is 'cookies' and the second substring is '30'.
If <list> is 'a b', then the variable 'a' will become 'cookies' and
the variable 'b' will become '30'.
See also: setx(), x(), strmatch(), wildmatch(), regparse(), regparsei().
& REGPARSE()
Function: regparse(<string>,<regexp>,<list of variable names>)
This side-effect function matches the regular expression <regexp>
against the entirety of <string>; if there's a match, it places
the parenthesized substrings within the regular expression, into
the corresponding named variables. <list of variable names> can be
up to ten strings.
For example, if <string> is 'cookies=30' and <regexp> is '(.+)=([0-9]*)'
and <list> is 'x y z', the the 0th substring matched is 'cookies=30'
(which is set into the named variable 'x'), the 1st substring is
'cookies' (set into 'y'), and the 2nd substring is '30' (set into 'z').
See 'help regexp syntax' for an explanation of regular expressions.
See also: regparsei(), wildparse().
& REGPARSEI()
Function: regparsei(<string>,<regexp>,<list of variable names>)
This function works identically to regparse(), except that the
matching is not case-sensitive, i.e., 'A' and 'a' are automatically
equivalent to 'A|a'.
See also: regparse(), wildparse().
& STREQ()
streq(<string 1>,<string 2>)
This function returns 1 if <string 1> and <string 2> are the same
(case-insensitive), and 0 if they are not. Whitespace is ignored.
Examples:
> say streq(This Is A Test,this is a test)
You say, "1"
> say streq(testing,test)
You say, "0"
See also: strmatch(), comp().
& ELEMENTS()
elements(<list of words>,<list of numbers>[,<delim>][,<output delim>])
This function returns the words in <list of words> that are in the
positions specified by <list of numbers>. Optionally, a list delimiter
other than a space can be specified, for both input and output.
Examples:
> say elements(Foo Ack Beep Moo Zot,2 4)
You say, "Ack Moo"
> say elements(Foof|Ack|Beep|Moo,3 1,|)
You say, "Beep|Foof"
> say elements(Foof|Ack|Beep|Moo,3 1,|,-)
You say, "Beep-Foof"
& EXTRACT()
extract(<string>, <first>, <length>[, <delim>])
Extract returns a string of length words, starting with the first
word. Unlike letters, the first word in a string is number 1,
instead of 0.
<delim> may be used to specify a delimiter other than a space.
Examples:
> say extract(This is a really neat example, 4, 2)
You say, "really neat"
> say extract(Another@funky@test@for@extract, 3, 3, @)
You say, "test@for@extract"
See also: index(), insert(), ldelete(), replace().
& INDEX()
Function: index(<list>,<character>,<first>,<length>)
This function is similar to EXTRACT(), except that an item in the
list may be more than one word; instead of a space being used to
separate items in the list, <character> is used. The function returns
<length> items starting from that in the <first> position. Trailing
spaces are trimmed. The comma cannot be used as the <character> separator.
Example:
> say [index(Cup of Tea | Mug of Beer | Glass of Wine, |, 2, 1)]
You say, "Mug of Beer"
See also: extract().
& GRAB()
Function: grab(<list>, <pattern>[, <delim>])
This function matches <pattern> against each word in <list>, returning
the first word that matches. If no words match, then an empty string
is returned. The match is not case-sensitive, and wildcard characters
are permitted. <delim> may be used to specify a list delimiter other
than a space.
Examples:
> say grab(This is a new test,?e*)
You say, "new"
> say grab(Holodeck:#10~Airlock:#58~Dorm:#12~Brig:#83,Airlock:*,~)
You say, "Airlock:#58"
See also: LISTS, graball(), match(), matchall().
& GRABALL()
Function: graball(<list>, <pattern>[, <delim>[, <output delim>]])
This function matches <pattern> against each word in <list>, returning
a list of <output delim>-separated words that match. If no words match,
then an empty string is returned. The match is not case-sensitive, and
wildcard characters are permitted. <delim> may be used to specify a
list delimiter other than a space.
Examples:
> say graball(This is a new test,?e*)
You say, "new test"
> say graball(Holodeck:#10~Airlock:#58~Dorm:#12~Brig:#83,*i*:*,~,|)
You say, "Airlock:#58|Brig:#83"
See also: LISTS, grab(), match(), matchall().
& REGRAB()
& REGRABI()
Function: regrab(<list>, <regexp>[, <delim>])
Function: regrabi(<list>, <regexp>[, <delim>])
These functions match the regular expression <regexp> against each
word in <list>, returning the first word that matches. If no words
match, then an empty string is returned. <delim> may be used to
specify a list delimiter other than a space.
The regrab() match is case-sensitive; the regrabi() match is not.
Examples:
> say regrab(This is a new test,is)
You say, "This"
> say regrab(This is a new test,^is)
You say, "is"
> @va me = ^A.+:#\d+
> say regrab(Holodeck:#10~Airlock:#58~Dorm:#12~Brig:#83,%va,~)
You say, ""
> say regrabi(Holodeck:#10~Airlock:#58~Dorm:#12~Brig:#83,%va,~)
You say, "Airlock:#58"
& REGRABALL()
& REGRABALLI()
Function: regraball(<list>, <regexp>[, <delim>[, <output delim>]])
Function: regraballi(<list>, <regexp>[, <delim>[, <output delim>]])
This functions match the regular expression <regexp> against each word
in <list>, returning a list of <output delim>-separated words that
match. If no words match, then an empty string is returned. <delim>
may be used to specify a list delimiter other than a space.
The regraball() match is case-sensitive; the regraballi() match is not.
Examples:
> say regraball(This is a new test,is)
You say, "This is"
> @va me = ^[A-Z].+:#1\d+
> say regraballi(Holodeck:#10~Airlock:#58~Dorm:#12~Brig:#83,%va,~,_)
You say, "Holodeck:#10_Dorm:#12"
& GROUP()
Function: group(<list>, <groups>[, <delim>[, <odelim>][, <group delim>]])
This function sorts a <list> into <groups> number of groups. <list> is
space-separated by default, <delim>-separated if specified. The elements
of the returned list are <odelim>-separated (defaults to <delim>); the
groups are separated by <group delim> (defaults to <odelim>).
Examples:
> @va = apple banana kiwi orange peach pear plum strawberry
> think group(%va, 3)
apple orange plum banana peach strawberry kiwi pear
> think group(%va, 3, ,-,|)
apple-orange-plum|banana-peach-strawberry|kiwi-pear
The function is most useful when re-ordering output for display, such as
when you want a list to display vertically-sorted into columns rather than
horizontally-sorted into columns.
Continued in 'help Group2'.
& GROUP2
For instance, if you had a list @va, 'apple banana kiwi orange peach pear
plum strawberry', and you did 'table(%va, 25)' to display it in three
columns, you would get:
apple banana kiwi
orange peach pear
plum strawberry
Suppose you wanted to alphabetize vertically rather than horizontally,
though. You would use 'table(group(%va, 3), 25)', which would result in:
apple orange plum
banana peach strawberry
kiwi pear
See also: step()
& FLAGS()
flags(<object>)
flags(<object>/<attrib>)
The first form of the flags() function returns a string consisting of
the flags set on the object, as a one-word string, subject to restrictions
on the visibility of flags.
The second form returns the flags of an attribute on the named object.
You must have permission to see the attribute.
& NUM()
num(<object>)
Returns the dbref number of the object, which must be in the same
room as the object executing num.
See also: locate().
& CON()
con(<object>)
Con returns the first object in the list of objects carried by
thing. Just the first, and only the first. See NEXT.
& LOC()
Function: loc(<object>)
Returns the number of the location where <object> is. You must either
control the object or be nearby for it to work. When used on an exit it
returns the destination of the exit. You can also use loc() to find the
location of players that are not set UNFINDABLE.
Example:
> look
Mortal's Room(#367R)
A bare room with nothing in it but a bed and a chair.
Contents:
hat(#368)
> say loc(me)
You say, "#367"
> enter hat
hat(#368)
Contents:
cat(#325)
> say loc(me)
You say, "#368"
> say loc(here)
You say, "#367"
See also: rloc(), room(), where().
& RLOC()
Function: rloc(<object>,<levels>)
This function may be used to get the location of an object's location
(for which you would previously use 'loc(loc(<object>))', which fails if you
don't control <object>'s location). <levels> indicates the number of
nested 'loc' calls to make, so 'loc(loc(<object>))' could be replaced with
'rloc(<object>,2)'. If rloc() encounters a room, the dbref of the room
is returned.
You must either control the object or be nearby for it to work. When used
on an exit it returns the destination of the exit. You can also use rloc()
to find the location of players that are not set UNFINDABLE.
rloc(<object>,0) is the same as num(<object>), and rloc(<object>,1) is the
same as loc(<object>).
See also: loc(), where().
& WHERE()
Function: where(<object>)
This function returns the "true" location of an object. You must control
the object or be near it in order for it to work. For players and things,
the "true" location is the normal location of the object. For exits, the
"true" location is the source room. For rooms, it is #-1.
See also: loc(), rloc().
& OWNER()
Function: owner(<object>)
owner(<object>/<attrib>)
The first form of the owner() function returns the dbref of the owner of the
object. The object must either be yours or nearby.
The second form returns the owner of an attribute on the named object.
You must own either the object or the attribute.
& NAME()
name(<dbref>)
This function returns the name of the indicated object. When called with
an exit it returns the only the first alias.
See also: fullname().
& FULLNAME()
Function: fullname(<dbref>)
This function returns the full name of the indicated object. This is the
same as name() in all cases except when <dbref> is an exit, then all the
aliases are returned as well.
See also: name().
& NEXT()
next(<thing>)
If thing is an exit in a room, then next will return the next
nondark exit in the list of exits for that room. If thing is an
object, then next will return the next object in the inventory list
that the object is in. Otherwise, it returns a '#-1' string.
& SHL()
shl(<number>, <count>)
This function returns the result of leftwards bit-shifting
<number> by <count> times.
This is equivalent to mul(<number>, power(2, <count>)), but is
faster.
Example:
> say [shl(16, 2)]
You say, "64"
See also: shr(), band(), bnand(), bor().
& SHR()
shr(<number>, <count>)
This function returns the result of rightwards bit-shifting
<number> by <count> times.
This is equivalent to div(<number>, power(2, <count>)), but is
faster.
Example:
> say [shr(16, 2)]
You say, "4"
See also: shl(), band(), bnand(), bor().
& BAND()
band(<number>, <number>)
Intended for use on a bitfield, this function performs a binary AND
between two numbers.
For example, the number 80 is equivalent to the binary representation
(divided into groups of four numbers, for easier reading), 0010 1000.
The bits for "16" and "64" are "on", but no other bits are on.
This function is most useful for checking if a bit in a given bitfield
is "on". If it is, the function returns the value of that bit;
[band(80,16)] or [band(80,64)] would return true values (16 or 64,
respectively), while [band(80,32)] would return zero, a false value.
See also: shl(), shr(), bnand(), bor().
& BNAND()
bnand(<number>, <number>)
Intended for use on a bitfield, this function performs a binary AND
between a number and the complement of another number. This function
is most useful for turning off bits in a bitfield.
See also: shl(), shr(), band(), bor().
& BOR()
bor(<number>, <number>)
Intended for use on a bitfield, this function performs a binary OR
between two numbers. It is most useful for "turning on" bits in a
bitfield.
See also: shl(), shr(), band(), bnand().
& ANDBOOL()
Function: andbool(<boolean1>,<boolean2>[,<booleanN>]...)
Takes two or more booleans, and returns 1 if they are all each equivalent
to true(1).
See also: BOOLEAN VALUES, t(), orbool(), notbool(), xorbool(), and().
& ORBOOL()
Function: orbool(<boolean1>,<boolean2>[,<booleanN>]...)
Takes two or more booleans, and returns 1 if at least one is equivalent
to true(1).
See also: BOOLEAN VALUES, t(), andbool(), notbool(), xorbool(), or().
& T()
Function: t(<boolean>)
Takes a boolean value, and returns 0 if it is false, and 1 if it is
true.
See also: BOOLEAN VALUES, notbool(), andbool(), orbool(), xorbool().
& NOTBOOL()
Function: notbool(<boolean>)
Takes a boolean value, and returns its inverse. So, if the input is
equivalent to true(1) it returns a 0, and if the input is equivalent to
false(0), it returns a 1.
See also: BOOLEAN VALUES, t(), andbool(), orbool(), xorbool(), not().
& XORBOOL()
Function: xorbool(<boolean1>,<boolean2>[,<booleanN>]...)
Takes two or more booleans, and returns 1 if an odd number of them are
equivalent to true(1).
See also: BOOLEAN VALUES, t(), andbool(), notbool(), orbool(), xor().
& AND()
Function: and(<number1>,<number2>[,<numberN>]...)
Takes two or more strings, and returns 1 if they are all non-zero
numbers.
See also: land(), andbool(), or(), xor(), not()
& OR()
Function: or(<number1>,<number2>[,<numberN>]...)
Takes two or more strings, and returns 1 if at least one is a non-zero
number.
See also: lor(), orbool(), and(), xor(), not()
& NOT()
Function: not(<number>)
If the input is a non-zero number, returns 0. If it is 0 or the
equivalent (such as a non-numeric string), returns 1.
See also: notbool(), and(), or(), xor()
& XOR()
Function: xor(<number1>,<number2>[,<numberN>]...)
Takes two or more strings, and returns 1 if an odd number of them
are non-zero numbers.
See also: xorbool(), and(), or(), not()
& CAND()
& COR()
& CANDBOOL()
& CORBOOL()
Function: cand(<number1>,<number2>[,<numberN>]...)
Function: cor(<number1>,<number2>[,<numberN>]...)
Function: candbool(<boolean1>,<boolean2>[,<booleanN>]...)
Function: corbool(<boolean1>,<boolean2>[,<booleanN>]...)
These "short-circuit conditional" functions are equivalent to and(),
or(), andbool(), and orbool(), respectively, except they stop evaluating
their arguments when a conclusion is reached (the first zero/false for
and-checks, the first non-zero/true for or-checks).
Example:
> say [cor(0[setq(0,#1)],0[setq(0,#2)],1[setq(0,#3)],1[setq(0,#4)])]%q0
You say, "1#3"
> say [candbool(#234[setq(0,_1)],#-1[setq(0,_2)],foo[setq(0,_3)])]%q0
You say, "0_2"
& gt()
Function: gt(<number1>,<number2>)
Takes two numbers, and returns 1 if and only if <number1> is greater than
<number2>, and 0 otherwise. Warning: passing anything but numbers will
produce unexpected results, as non-numeric strings usually are treated
as numeric 0.
Example:
> say gt(4,5)
You say, "0"
> say gt(5,5)
You say, "0"
> say gt(6,5)
You say, "1"
> say gt(foo, bar)
You say, "0"
See also: lt(), lte(), gte(), eq(), neq(), ncomp(), comp().
& gte()
Function: gte(<number1>,<number2>)
Takes two numbers, and returns 1 if and only if <number1> is greater than
or equal to <number2>, and 0 otherwise. Warning: passing anything but
numbers will produce unexpected results, as non-numeric strings usually are
treated as numeric 0.
Example:
> say gte(4,5)
You say, "0"
> say gte(5,5)
You say, "1"
> say gte(6,5)
You say, "1"
> say gte(foo, bar)
You say, "1"
See also: lt(), lte(), gt(), eq(), neq(), ncomp(), comp().
& lt()
Function: lt(<number1>,<number2>)
Takes two numbers, and returns 1 if and only if <number1> is less than
<number2>, and 0 otherwise. Warning: passing anything but numbers will
produce unexpected results, as non-numeric strings usually are treated
as numeric 0.
Example:
> say lt(4,5)
You say, "1"
> say lt(5,5)
You say, "0"
> say lt(6,5)
You say, "0"
> say lt(foo, bar)
You say, "0"
See also: lte(), gte(), gt(), eq(), neq(), ncomp(), comp().
& lte()
Function: lte(<number1>,<number2>)
Takes two numbers, and returns 1 if and only if <number1> is less than or
equal to <number2>, and 0 otherwise. Warning: passing anything but numbers
will produce unexpected results, as non-numeric strings usually are treated
as numeric 0.
Example:
> say lte(4,5)
You say, "1"
> say lte(5,5)
You say, "1"
> say lte(6,5)
You say, "0"
> say lte(foo, bar)
You say, "1"
See also: lt(), gte(), gt(), eq(), neq(), ncomp(), comp().
& eq()
Function: eq(<number1>,<number2>)
Takes two numbers, and returns 1 if they are equal and 0 if they are not.
Warning: passing anything but numbers will produce unexpected results,
as non-numeric strings usually are treated as numeric 0.
Example:
> say eq(1,-1)
You say, "0"
> say eq(5,5)
You say, "1"
> say eq(foo, bar)
You say, "1"
See also: lt(), lte(), gte(), gt(), neq(), ncomp(), comp().
& neq()
Function: neq(<number1>,<number2>)
Takes two numbers, and returns 1 if they are not equal and 0 if they are
equal. Warning: passing anything but numbers will produce unexpected
results, as non-numeric strings usually are treated as numeric 0.
Examples:
> say neq(1,-1)
You say, "1"
> say neq(5,5)
You say, "0"
> say neq(foo, bar)
You say, "0"
See also: lt(), lte(), gte(), gt(), eq(), not(), ncomp(), comp().
& ncomp()
Function: ncomp(<number1>, <number2>)
This function returns 0 if the two numbers are equal, 1 if the first
number is greater than the second number, and -1 if the first number
is less than the second number.
This function is useful for writing sortby() routines and other
instances where it is useful to have a numerical counterpart to
the comp() function.
See also: lt(), lte(), gte(), gt(), eq(), neq(), not(), comp().
& cat()
Function: cat(<string>[,<stringN>])
cat returns a string made up of the contents of string1 through stringN,
with each string separated from its neighbors by a space.
Example:
> say cat(this is, a test)
You say, "this is a test"
> say cat(This is,another,test of the,CAT function)
You say, "This is another test of the CAT function"
& member()
Function: member(<list>, <word>[, <delim>])
Member takes a list and a word, and returns the position of that word
within the list. If the word does not occur in the list, then 0 is
returned. Unlike match(), member() does not check for wildcarding,
and the cases of <list> and <word> are significant. A word is defined as
a string which has no interior spaces. So 'hello' would be one word,
while 'hello there' would be two.
<delim> may be used to specify a delimiter other than a space.
Example:
> say member(This is a member test, member)
You say, "4"
> say member(This is a member test, Member)
You say, "0"
> say member(This is a member test, *e*)
You say, "0"
> say member(This is a member test, is a)
You say, "#-1 CAN ONLY TEST ONE ELEMENT"
See also: LISTS, match(), strmatch().
& remove()
Function: remove(<list>, <word>[, <delim>])
Remove takes a list and a word, and returns the list, with the word deleted
from it. <delim> may be used to specify a delimiter other than a space.
Example:
> say remove(this is a test, is)
You say, "this a test"
> say remove(You can't remove, this)
You say, "You can't remove"
> say remove(You can't remove multiple words, You can't)
You say, "#-1 CAN ONLY DELETE ONE ELEMENT"
> say remove(How about an o-separated list, w ab, o)
You say, "Hout an o-separated list"
& RESTARTS()
Function: restarts()
Returns a number indicating the number of times that the MUSH has
been restarted (in the sense of @restart, not a shut down and
start up). When the MUSH is started, this number is 0; each time
the MUSH is @restart'd, this number increments by 1.
This is useful if you have, for example, things executed via
@startup that should behave differently depending on whether
or not the MUSH is starting "fresh" (with no players logged in,
likely meaning things should be reset to "clean" states, etc.).
& RESTARTTIME()
Function: restarttime()
Returns a string which is the time the MUSH last restarted. The time
is in the same format as the TIME() function returns.
See also: restarts(), starttime(), convtime().
& STARTTIME()
Function: starttime()
Returns a string which is the time the MUSH last rebooted. The time
is in the same format as the TIME() function returns.
Example:
> say starttime()
You say, "Sat Dec 7 00:09:13 1991
See also: restarttime(), convtime().
& SECS()
Function: secs()
Returns the number of elapsed seconds since midnight, January 1, 1970.
This is an easy way to time things.
Example:
> say secs()
You say, "692636020"
... wait a bit ...
> say secs()
You say, "692636043"
See also: convsecs(), convtime(), time().
& WORDS()
words(<string>[, <delim>])
Returns the number of words in <string>. <delim> may be used to specify
a delimiter other than a space.
Example:
> say words(This is a test)
You say, "4"
say words(Would you like coffee or perhaps tea?)
> You say "7"
say words(This:is:a:colon:separated:list,:)
> You say "6"
& VERSION()
Function: version()
Returns a string which contains various version information for the MUSH
you're on.
Example:
> version
TinyMUSH Beta version 2.0 patchlevel 0 #3
Build date: Thu Dec 5 10:10:07 EST 1991
> say version()
You say, "TinyMUSH Beta version 2.0 patchlevel 0 #3"
& CCOUNT()
& CDEPTH()
& FCOUNT()
& FDEPTH()
Functions: ccount(), cdepth(), fcount(), fdepth()
ccount() -- Returns the current command invocation counter.
cdepth() -- Returns the current command recursion counter.
fcount() -- Returns the current function invocation counter.
fdepth() -- Returns the current function recursion counter.
These functions are useful for attempting to trap overflows in your
softcode before the "hard" server limits are violated. You can obtain
those limits via config() -- respectively, command_invocation_limit,
command_recursion_limit, function_invocation_limit, and
function_recursion_limit.
Example:
> @va me = [ifelse(gt(fdepth(),5), %0, add(%0,u(va,inc(%0))))]
> say [u(va,1)]
You say, "6"
(Note that because the fdepth() call is two levels deep, the 'real'
recursion level it's checking of the u() is actually 3.)
& HASMODULE()
Function: hasmodule(<module name>)
Returns 1 if the named module is currently installed, and 0 if it
has not.
& HELPTEXT()
Function: helptext(<help command>, <entry>)
Returns the text of the entry indexed as <entry> in the external
indexed helpfile accessed via <help command>. Essentially,
'think [helptext(<help command>, <entry>)]' is the equivalent
of typing '<help command> <entry>'.
For instance, 'helptext(help, say)' would obtain the text of
'help say'. This is pre-formatted for display; to get a more
"raw" form, wrap the call in translate().
Normal permissions are enforced; i.e., the invoker of this
function must normally have access to <help command>. Also,
the evaluation of the entry text is carried out as normal,
as controlled by the conf parameters helpfile / raw_helpfile.
& HOME()
Function: home(<object>)
Returns the object's home.
Example:
> exam me
Mortal(#226Pc)
Type: PLAYER Flags: CONNECTED
Desc:Just a plain, old boring Mortal. You know.
Owner: Mortal Key: VA:foobar Clams: 920
Last:Thu Dec 19 08:57:21 1991
Home: Mortal's Room(#367R)
Location: The Town Square
> say home(me)
You say, "#367"
& MONEY()
Function: money(<object>)
Returns an integer equal to the amount of money <object> has (if it is a
player) or is worth (otherwise).
Example:
> score
You have 1052 clams.
> say money(me)
You say, "1052"
> exam sac test
Sac Test(#287V)
Type: THING Flags: VISUAL
Owner: Beaker Key: *UNLOCKED* Clams: 20
Home: Limbo(#0RLDAJ)
Location: The Town Square
> say money(sac test)
You say, "20"
& XCON()
Function: xcon(<object>, <element number>, <number of objects>[, <odelim>])
Returns an <odelim>-separated (space-separated by default) list of
contents of <object>, starting from the <element number>'d object
contained, up to <number of objects>. This is useful for contents
lists where a normal lcon() call would exceed the maximum buffer
length for function output.
Example:
> i
t1(#366)
t2(#411)
t3(#700)
t4(#108)
radio(#223)
The Wizard's Pointy Hat(#188SO)
You have 42463 clams.
> say xcon(me,3,3)
You say, "#700 #108 #223"
& LCON()
Function: lcon(<object>[, <odelim>])
Returns a space-separated list (<odelim>-separated if specified)
of the contents of <object>.
Example:
> i
t1(#366)
radio(#223)
The Wizard's Pointy Hat(#188SO)
You have 42463 clams.
> say lcon(me)
You say, "#366 #223 #188"
See also: lexits(), @dolist.
& LEXITS()
Function: lexits(<loc>[, <odelim>])
Returns an <odelim>-separated (space-separated by default) list of the
exits in <loc> and its parents.
Dark exits are not returned unless you have permissions to examine them.
Example:
> look here
The Town Square
You are in the town square. All around you .....
Obvious exits:
foo up southeast sw north
> say lexits(here)
You say, "#302 #10 #9 #8 #6"
See also: lcon(), @dolist, PARENT OBJECTS.
& ENTRANCES()
Function: entrances([<loc>[,<type>[,<low>[,<high>]]]])
Returns a space-separated list of links from elsewhere to the specified
location (default: your current room). The results may include exits and
drop-to's leading to <loc> as well as players and objects whose home is
<loc>. Unlike @entrances, does not report parent/child linkage (see
children()). Use <type> to restrict the types of entrances examined (may
use these letters: E (exit), T (thing), R (room), P (player); default
is A (all)). Because this command is computationally expensive, it costs
100 coins. <low> and <high> can be used to indicate where to start and
stop the search, respectively. This function is provided for PennMUSH
compatibility.
You may only use this command on locations that you control, or else the
results will be limited to items you can examine.
Examples:
> say entrances() <- all links to here
> say entrances(object) <- all links to object
> say entrances(here,tp) <- everything that lives here
> say entrances(me,a,1000) <- all links to me from #1000 and above.
See also: @entrances, @link, link(), children(), lexits().
& SECURE()
Function: secure(<string>)
nsecure(<string>)
Returns <string> after replacing the characters [](){};,%\$ with spaces.
This prevents strings entered by players from causing undesired side
effects when used, such as making your object perform unintended commands
or give out information to which you have access. Note that this function
is only needed when the resulting string is to be passed through the @force
command or be used as an attribute for an object (like the success message
for a mail message object).
> @va me=Sneak a peek at Wiz's desc... [get(#1/desc)]
> say secure(%va)
You say, "Sneak a peek at Wiz's desc... get #1/desc "
> say secure($foobar:this {is} a really, tough ; test.)
You say, " foobar:this is a really tough test."
Note: 'say secure(Sneak a peek at Wiz's desc... [get(#1/desc)])' does not
produce the expected result because the argument is evaluated BEFORE being
processed by secure(), therefore the [get()] call has already been
performed. To avoid prior evaluation of the string, use nsecure().
See also: escape().
& ESCAPE()
& NESCAPE()
Function: escape(<string>)
nescape(<string>)
Returns <string> after adding an escape character (\) at the start of the
string and also before each of the characters %;[]{}\ that appear in the
string. This prevents strings entered by players from causing undesired
side effects when used, such as making your object perform unintended
commands or give out information to which you have access. Note that this
function is only needed when the resulting string is to be passed through
the @force command or be used as an attribute for an object (like the
success message for a mail message object). This function has the
advantage over the secure() function in that the string the user sees
after evaluating it is the same as the original string.
Example:
You say, "\Sneak a peek at Wiz's desc... \[get(#1/desc)\]"
Note: 'say escape(Sneak a peek at Wiz's desc... [get(#1/desc)])' does not
produce the expected result because the argument is evaluated BEFORE being
processed by escape(), therefore the [get()] call has already been
performed. To avoid prior evaluation of the string, use nescape().
See also: secure().
& LIT()
Function: lit(<string>)
Returns the string literally -- unparsed and unevaluated.
& TRANSLATE()
Function: translate(<string>[,<type>])
If given a type of '1' or 'p' (for "percent substitutions"), this
function takes <string> and converts all raw ANSI color codes and
other special characters to MUSH substitutions. This is the default.
If given a type of '0' or 's' (for "strip"), this function takes
<string> and strips all raw ANSI color codes and other special
characters.
& ANSI()
Function: ansi(<codes>,<string>)
This allows you to highlight a string using ANSI terminal effects. The
string is terminated with a "return to normal" code, and the codes are
utilized in the order they are specified. The codes are:
f - flash i - inverse
h - hilite n - normal
u - underline
x - black foreground X - black background
r - red foreground R - red background
g - green foreground G - green background
y - yellow foreground Y - yellow background
b - blue foreground B - blue background
m - magenta foreground M - magenta background
c - cyan foreground C - cyan background
w - white foreground W - white background
For example, "ansi(fc, Test)" would hilight "Test" in flashing cyan.
Continued in 'help ansi2'.
& ANSI2
The percent substitution %x<color code> can be used instead of ansi().
For example, the equivalent to [ansi(rBf,Color!)] would be:
%xr%xB%xfColor!%xn
However, note that these are not exactly equivalent. The ansi() function
"compacts" ANSI codes, taking advantage of the fact that the ANSI standard
allows multiple ANSI attributes to be specified within an ANSI control
string. Thus, if you are trying to @edit or edit() a string with ANSI
characters embedded via the ansi() function, for instance, you may not
be able to edit the ANSI sequence directly. If you need to be able to
do this (for instance, to change the equivalent of '%xg' into '%xy'),
you should use the %x-substitutions instead.
The %xn (to return to normal) is not necessary, but if it is not specified,
the ANSI color codes will continue to the end of the string.
See also: ANSI, NOBLEED, stripansi().
& STRIPANSI()
Function: stripansi(<string>)
Strips the ANSI control sequences from a string.
See also: ANSI, NOBLEED, ansi().
& ANSIPOS()
Function: ansipos(<string>,<charpos>[,<type>])
Returns the color of the character within <string> where the character
position <charpos> falls. Characters are numbered starting at 0.
If <type> is '0' or 'e' for "escape", the color will be returned as
actual escape codes that will bleed into any further output of
the current evaluation.
If <type> is '1' or 'p' for "percent", the color will be returned as
percent-substitution codes (e.g. %xr).
If <type> is '2' or 'a' for "ansi()", the color will be returned as
letters suitable for use with the ansi() function. This is the
default.
Example:
> say ansipos(%xr%xB%xfColor!%xn,3)
You say, "frB"
See also: ANSI, ansi(), stripansi()
& BORDER()
Function: border(<text>,<width>[,<left margin fill>[,<right margin fill>]])
This function takes a string of <text>, and arranges the words in a
left-justified, word-wrapped paragraph of width <width>. Each line is
preceded by <left margin fill>, and ended with <right margin fill>
(if specified). If the line is shorter than <width>, it is padded out
with spaces. Newlines are supported ('%r'), and ANSI substitutions are
preserved correctly, but tabs are converted to a single space. Words whose
length exceeds <width> are broken into multiple pieces.
Example:
> @va me=++[repeat(-,20)]++%r[border(%0,18,**%b,%b||)]%r++[repeat(-,20)]++
> think u(va,apple orange kiwi grape%rbanana strawberry plum pear)
++--------------------++
** apple orange kiwi ||
** grape ||
** banana strawberry ||
** plum pear ||
++--------------------++
& RBORDER()
Function: rborder(<text>,<width>[,<left margin fill>[,<right margin fill>]])
This function takes a string of <text>, and arranges the words in a
right-justified, word-wrapped paragraph of width <width>. Each line is
preceded by <left margin fill>, and ended with <right margin fill>
(if specified). If the line is shorter than <width>, it is padded out
with spaces. Newlines are supported ('%r'), and ANSI substitutions are
preserved correctly, but tabs are converted to a single space. Words whose
length exceeds <width> are broken into multiple pieces.
Example:
> @va me=++[repeat(-,20)]++%r[rborder(%0,18,**%b,%b||)]%r++[repeat(-,20)]++
> think u(va,apple orange kiwi grape%rbanana strawberry plum pear)
++--------------------++
** apple orange kiwi ||
** grape ||
** banana strawberry ||
** plum pear ||
++--------------------++
& CBORDER()
Function: cborder(<words>,<width>[,<left margin fill>[,<right margin fill>]])
This function takes a string of <text>, and arranges the words in a
centered, word-wrapped paragraph of width <width>. Each line is
preceded by <left margin fill>, and ended with <right margin fill>
(if specified). If the line is shorter than <width>, it is padded out
with spaces. Newlines are supported ('%r'), and ANSI substitutions are
preserved correctly, but tabs are converted to a single space. Words whose
length exceeds <width> are broken into multiple pieces.
Example:
> @va me=++[repeat(-,20)]++%r[cborder(%0,18,**%b,%b||)]%r++[repeat(-,20)]++
> think u(va,apple orange kiwi grape%rbanana strawberry plum pear)
++--------------------++
** apple orange kiwi ||
** grape ||
** banana strawberry ||
** plum pear ||
++--------------------++
& MUDNAME()
Function: mudname()
Returns the name of the MUD. This is usually (but not necessarily) the name
that appears in the various mud lists, and is the name that the mud is
listed under in reports from RWHO servers (that is, if the mud sends its
WHO information to an RWHO server).
Example:
> say mudname()
You say, "TestMUSH"
& CAPSTR()
Function: capstr(<string>)
Returns <string> with the first character capitalized. If the first
character is not a letter, this function returns the string unmodified.
Example:
> say capstr(this is a string I want capitalized)
You say, "This is a string I want capitalized"
See also: lcstr(), ucstr().
& LCSTR()
Function: lcstr(<string>)
Returns <string> with all letters converted to lowercase.
Example:
> say lcstr(This is something I want to TEST)
You say, "this is something i want to test"
See also: capstr(), ucstr().
& UCSTR()
Function: ucstr(<string>)
Returns <string> with all letters converted to uppercase.
Example:
> say ucstr(This is a test, really!)
You say, "THIS IS A TEST, REALLY!"
See also: capstr(), lcstr().
& LNUM()
Function: lnum(<number>[,<other>][,<output delim>])
If only given one argument, this function returns a list of numbers from
0 to <number>-1. <number> must be at least 1.
If given at least two arguments, this function returns a list of numbers
from <number> to <other>. If <other> is less than <number>, the list
will return in descending order. Negative integers are permissible.
<sep> is used as the separator character, if given.
Examples:
> say lnum(5)
You say, "0 1 2 3 4"
> say lnum(3,7)
You say, "3 4 5 6 7"
> say lnum(4,-2)
You say, "4 3 2 1 0 -1 -2"
> say lnum(2,6,|)
You say, "2|3|4|5|6"
& LRAND()
Function: lrand(<range bottom>,<range top>,<times>,[,<output delim>])
Returns a list with <times> elements separated by <output delim> (or
a space if not specified), of random numbers between <range bottom>
and <range top>.
For instance, 'lrand(3, 6, 5)' would generate five random numbers
in the range 3 - 6 (i.e., 3, 4, 5, or 6), such as '4 6 3 5 6'.
See also: rand(), die(), lnum()
& LATTR()
Function: lattr(<object>[/<wild-pattern>][, <odelim>])
Returns a list of the attributes set on <object>. If <wild-pattern> is
given, only attributes matching it are returned.
Example:
> exam me
Mortal(#226Pc)
....
VC:Mon Sep 9 12:09:01 1991
VE:baz
Last:Thu Dec 19 08:57:21 1991
VV(#2+):Foof!
Domain:Abusees
....
> say lattr(me)
You say, "Desc VC VE Last VV Domain"
> say lattr(me/v*)
You say, "VC VE VV"
See also: @dolist.
& NATTR()
Function: nattr(<object>[/<wild-pattern>])
Returns the number of attributes set on <object>. If <wild-pattern> is
given, only attributes matching it are returned.
Slightly faster, but equivalent to, words(lattr(<object>[/<wild-pattern>]))
& REVERSE()
Function: reverse(<string>)
Reverses the order of the characters of <string>.
Examples:
> say reverse(This is a test)
You say, "tset a si sihT"
> say reverse(This is a test, Really...)
You say, "...yllaeR ,tset a si sihT"
> say reverse(A man, a plan, a canal -- Panama!)
You say, "!amanaP -- lanac a ,nalp a ,nam A"
See also: revwords().
& REVWORDS()
Function: revwords(<string>[, <delim>])
Reverses the order of the words of <string>. A word is considered to be
any sequence of nonblank characters, separated by blanks, so punctuation
characters that follow a word are considered part of the word.
<delim> may be used to specify a delimiter other than a space.
Examples:
> say revwords(This is a test, Really...)
You say, "Really... test, a is This"
> say revwords(Was it a cat I saw?)
You say, "saw? I cat a it Was"
See also: reverse().
& BEFORE()
Function: before(<string1>, <string2>)
Returns the portion of <string1> that occurs before <string2>. If <string2>
does not occur in <string1>, the entire string is returned.
If you want to return the portion of the string after the first space,
use the first() function instead.
Examples:
> say before(This is a test,a)
You say, "This is "
> say before(This is a test,is)
You say, "Th"
> say before(This is a test, nope)
You say, "This is a test"
See also: after(), first(), rest().
& AFTER()
Function: after(<string1>, <string2>)
Returns the portion of <string1> that occurs after <string2>. If <string2>
does not occur in <string1>, a null string is returned.
If you want to return the portion of the string after the first space,
use the rest() function instead.
Examples:
> say after(This is a test,a)
You say, " test"
> say after(This is a test,is)
You say, " is a test"
> say after(This is a test, nope)
You say, ""
See also: before(), first(), rest().
& ROOM()
Function: room(obj)
Returns the number of the room that <obj> is in, or would be in if it
executed LEAVE commands until it got to a room. You can find out the
containing room of objects you own, nearby objects, and findable players.
Example:
> i
You are carrying:
hat(#368)
cat(#325)
> look
Mortal's Room(#367R)
A bare room with nothing in it but a bed and a chair.
> say I am in [room(me)], the cat is in room [room(cat)].
You say, "I am in #367, the cat is in room #367."
> @fo hat=get cat
cat has left.
> say The cat is in [loc(#325)] within room [room(#325)].
You say, "The cat is in #368 within room #367."
See also: loc(), UNFINDABLE.
& SEARCH()
Function: search([<player>] [<class>=<restriction>[,<low>[,<high>]]])
The search() function returns a list of objects that match the search
criteria, which are the same as with the @search command. This function
costs as much as the @search command, so repeated use is expensive.
Caution: if you use the [ and ] characters in an Eval selection you will
need to escape them. Consider using Ueval instead.
Examples:
> say search()
You say, "#226 #289 #325 #364 #368 #369"
> say search(eval=\[eq(money(##),1)\])
You say, "#289 #325 #364 #368 #369"
> &TEST me = eq(money(%0),1)
> say search(ueval=me/TEST)
You say, "#289 #325 #364 #368 #369"
> say search(player=wizard)
You say, "#1"
See also: @search, SEARCH CLASSES.
& STATS()
Function: stats([<player>])
This function returns information about the number of objects on the MUSH,
much like the @stats command. If the argument is omitted or is 'all', then
the stats for the entire MUSH are returned, otherwise the stats for the
named player are returned. You may not get stats for other players unless
you control them or have the stat_any power.
The stats are returned as a set of 8 numbers, in the same order as reported
by the @stats command: total objects, rooms, exits, things, players, then
objects of unknown type, GOING objects, and garbage. Unknown and GOING
objects are converted to garbage during @dbck, and thus were counted as
garbage in the past. This command costs as much as the equivalent @stats
command (ie: '@stats/all' or '@stats <player>', not the free '@stats').
Continued in 'help stats2'.
& stats2
Examples:
> @stats me
7 objects = 0 rooms, 0 exits, 5 things, 1 players.
(0 unknown, 1 going, 0 garbage)
> say stats(me)
You say, "7 0 0 5 1 0 1 0"
> say stats()
You say, "379 51 165 134 20 0 2 7"
> @stats/all
379 objects = 51 rooms, 165 exits, 134 things, 20 players.
(0 unknown, 2 going, 7 garbage)
See also: @stats.
& ITEMIZE()
Function: itemize(<list>[,<delim>[,<conjunction>[,<punctuation>]]])
This function creates a word-list, punctuated by <punctuation> and,
if there are three or more elements in the list, with <conjunction>
before the last word. <list> is a <delim>-separated list of words,
where <delim> defaults to a space and can be any valid input delimiter.
<conjunction> is an arbitrary string, and defaults to the word "and".
<punctuation> can be any valid output delimiter, and defaults to a comma.
Examples:
itemize(a) ==> a
itemize(a b) ==> a and b
itemize(a b c) ==> a, b, and c
itemize(a b c,,or) ==> a, b, or c
itemize(a b c,,or,;) ==> a; b; or c
itemize(a b,,,;) ==> a b
itemize(a<>b<>c<>d<>e,<>,+==|,->) ==> a-> b-> c-> d-> +==| e
& ITER()
Function: iter(<list>, <eval>[, <delim>[, <output delim>]])
<list> is a <delimiter>-separated list of arbitrary strings. <eval> is a
string that is to be evaluated once for each item in <list>, replacing
the special symbol ## with the corresponding item from <list>, and
the special symbol #@ with the position of the item in the list.
The special tokens can be escaped out, i.e., '\##' returns a literal '##'.
A list of the results of these evaluations is returned to the caller; if
<output delim> is specified, it is used; otherwise, a space is used.
Multiple iter()s and list()s can be nested, with the ## and #@ tokens
evaluating appropriately at each level. The nesting level can also
be obtained, using the '#!' token or the ilev() function; the first call
to iter(), list(), whentrue(), or whenfalse() is level 0, the next is
level 1, and so forth. itext() and inum() can be used to retrieve the
##/#@-equivalent values at other nesting levels.
Continued in 'help ITER2'.
& ITER2
The effect is very similar to @dolist, except that the results are made
into a list and returned, not executed. Note that @dolist's use of ##
and #@ conflicts with iter()'s, though.
Examples:
> say [iter(This is a test,strlen(##))]
You say, "4 2 1 4"
> say [iter(1|2|3,#@/[add(##,1)],|,-)]
You say, "1/2-2/3-3/4"
> say [iter(lcon(me),name(##),,+)]
You say, "apple+banana+orange"
> say [iter(1-2-3-4,inc(##),-,@@)]
You say, "2345"
> say [iter(1 2 3 4,inc(##),%b,%r)]
You say, "2
3
4
5"
See also: @dolist, parse(), list(), istrue(), isfalse(), whentrue(),
whenfalse(), loop(), ilev(), itext(), inum(), map(), DELIMITERS.
& LIST()
Function: list(<list>, <eval>[, <delim>])
This function behaves identically to iter(), but, instead of returning
a list of words, it returns each result on a separate line, outputting
it directly to the enactor. The result of the function itself is an
empty string.
Example:
> say "[list(apples bananas oranges,#@ - ## - [strlen(##)])]"
1 - apples - 6
2 - bananas - 7
3 - oranges - 7
You say, ""
> @eval list(lnum(1,5),## - #@ - #! - [iter(lnum(##),##:#@:#!)])
1 - 1 - 1 - 0:1:2
2 - 2 - 1 - 0:1:2 1:2:2
3 - 3 - 1 - 0:1:2 1:2:2 2:3:2
4 - 4 - 1 - 0:1:2 1:2:2 2:3:2 3:4:2
5 - 5 - 1 - 0:1:2 1:2:2 2:3:2 3:4:2 4:5:2
See also: iter(), parse(), loop().
& ILEV()
Function: ilev()
Returns the nesting level of iter(), list(), whentrue() and whenfalse().
Equivalent to the substitution '#!' when used within one of those
functions.
See also: itext(), inum().
& ITEXT()
Function: itext(<level>)
Returns the '##'-equivalent substitution text at the appropriate nesting
<level> of iter(), list(), whentrue() and whenfalse(). 'itext(0)' is
equivalent to '##'.
If used outside one of those functions, or with a nesting level that
is too deep, this function returns a null string.
See also: ilev(), inum().
& INUM()
Function: inum(<level>)
Returns the '#@'-equivalent substitution text at the appropriate nesting
<level> of iter(), list(), whentrue() and whenfalse(). 'inum(0)' is
equivalent to '#@'.
If used outside one of those functions, or with a nesting level that
is too deep, this function returns 0.
See also: ilev(), itext().
& LOOP()
Function: loop(<list>, <eval>[, <delim>])
This function behaves identically to parse(), but, instead of returning
a list of words, it returns each result on a separate line, outputting
it directly to the enactor. The result of the function itself is an
emtpy string.
This function is also otherwise identical to list(), except that
successive calls of it cannot be nested. The replacement of the
'##' and '#@' tokens is "blind", i.e., it simply goes through the
evaluation string without regard for nesting. As a result, it handles
escapes in a different manner than iter().
This function is provided for backwards compatibility.
See also: iter(), parse(), list(), map().
& ISTRUE()
Function: istrue(<list>, <eval>[, <delim>[, <output delim>]])
<list> is a <delimiter>-separated list of arbitrary strings. <eval> is a
string that is to be evaluated once for each item in <list>, replacing
the special symbol ## with the corresponding item from <list>, and
the special symbol #@ with the position of the item in the list.
The special tokens can be escaped out, i.e., '\##' returns a literal '##'.
An <output delim>-separated list is returned of those elements for
which the evaluation returns boolean-true. Essentially, this is like
an inline filterbool() whose syntax similar to iter().
Examples:
> say istrue(1 2 3 4 5,mod(##,2))
You say, "1 3 5"
> say istrue(1-2-3-4-5,mod(##,2),-,.)
You say, "1.3.5"
See also: filterbool(), isfalse(), iter(), filter()
& ISFALSE()
Function: isfalse(<list>, <eval>[, <delim>[, <output delim>]])
<list> is a <delimiter>-separated list of arbitrary strings. <eval> is a
string that is to be evaluated once for each item in <list>, replacing
the special symbol ## with the corresponding item from <list>, and
the special symbol #@ with the position of the item in the list.
The special tokens can be escaped out, i.e., '\##' returns a literal '##'.
An <output delim>-separated list is returned of those elements for
which the evaluation returns boolean-false. Essentially, this is like
a reverse inline filterbool() whose syntax similar to iter().
Examples:
> say isfalse(1 2 3 4 5,mod(##,2))
You say, "2 4"
> say isfalse(1-2-3-4-5,mod(##,2),-,.)
You say, "2.4"
See also: filterbool(), istrue(), iter(), filter()
& WHENTRUE()
Function: whentrue(<list>, <eval>[, <delim>[, <output delim>]])
This function is basically 'iter() as long as the results are
boolean true'. <list> is processed element by element, and <eval>
is evaluated with the element substituted for the '##' token. Each
result of an evaluation is appended to the output list. Processing
on the list stops when all the elements have been processed, or
the result of an evaluation is no longer boolean-true. (However,
note that the result is appended to the output BEFORE the boolean
check is done.)
Example:
> say [whentrue(1 2 0 2 1,##)]
You say, "1 2 0"
See also: iter(), BOOLEAN VALUES.
& WHENFALSE()
Function: whenfalse(<list>, <eval>[, <delim>[, <output delim>]])
This function is basically 'iter() as long as the results are
boolean false'. <list> is processed element by element, and <eval>
is evaluated with the element substituted for the '##' token. Each
result of an evaluation is appended to the output list. Processing
on the list stops when all the elements have been processed, or
the result of an evaluation is no longer boolean-false. (However,
note that the result is appended to the output BEFORE the boolean
check is done.)
Example:
> say [whenfalse(0 #-1 1 2,##)]
You say, "0 #-1 1"
See also: iter(), BOOLEAN VALUES.
& LOCATE()
Function: locate(<looker>,<string>,<where>)
The locate function is used to look for an object from the perspective of
<looker> (You must own <looker>). The database number of the item that
is found is returned. The <where> parameter specifies a list of places to
look, from this list:
a - Look for absolute references (#<number>)
c - Look for exits carried by <looker> (and by <looker>'s parents).
e - Look for exits in <looker>'s location (and the location's parents).
h - Look for 'here', which matches <looker>'s location.
i - Look in <looker>'s inventory.
m - Look for 'me', which matches <looker>.
n - Look for <looker>'s neighbors (other objects in the same location).
p - Look for player names prefixed by a '*'
* - Look for everything in the above list.
{ 'help locate2' for more }
& locate2
You may also specify qualifiers in <where> to help resolve possible
ambiguities:
E - Prefer exits over other types.
L - Prefer unlocked exits over locked exits.
P - Prefer players over other types.
R - Prefer rooms over other types.
T - Prefer things over other types.
V - Report "Can't find..." and "Which one..." errors to <looker>.
X - Select randomly if search finds multiple ("ambiguous") matches.
If nothing matches, the value #-1 is returned. If more than one thing
matches, but nothing matches exactly, the value #-2 is returned. If more
than one thing exactly matches, one is chosen at random. If you specify
more than one type preference (E, P, R, or T), then the last one entered
is the one that is obeyed. The default is for no type to be preferred.
( 'help locate3' for more )
& LOCATE3
Examples:
> i
test1(#378)
test(#376)
You have 42463 clams.
> look
Nullspace(#250R)
test1(#382)
> say locate(me,test,i)
You say, "#376"
> say locate(me,test,n)
You say, "#382"
> say locate(me,test1,in)
You say, "#378"
> say locate(me,test1,in)
You say, "#382"
> say locate(me,tes,in)
You say, "#-2"
> say locate(here,tes,*)
You say, "#382"
> say locate(me,out,e)
You say, "#252"
> say locate(me,here,*)
You say, "#250"
See also: num(), PARENT OBJECTS.
& EDIT()
Function: edit(<string>,<from>,<to>)
This function edits <string>, replacing all occurrences of the substring
<from> with the string <to>. If <from> is '$', then <to> is appended to
<string>, while if <from> is '^', then it is prepended. edit()'s arguments
can have ANSI characters embedded within them. However, because MUSH
typically appends a terminating 'normal' ANSI string to strings, the
terminating 'normal' is stripped for <from> and <to>. If you really need
a 'normal', you should put '%xn%xn' at the end of the string.
Examples:
> say edit(This is a test,is,x)
You say, "Thx x a test"
> say edit(Atlantic,^,Trans)
You say, "TransAtlantic"
> say translate(edit(FOO-%xrBAR-BAZ,%xrB,%xyB),p)
You say, "FOO-%xyBAR-BAZ%xn"
> say translate(edit(FOO-BAR-BAZ,BAR,%xyBAR%xn%xn),p)
You say, "FOO-%xyBAR%xn-BAZ"
See also: @edit.
& LEDIT()
Function: ledit(<original>, <find>, <replace>[, <delim>[, <output delim>]])
This function is a mass find-and-replace on a list, and can often take
the place of multiple nested calls to edit(). <original>, <find>,
and <replace> are lists of words separated by <delim> (defaults to
a space).
The function iterates through each word of <original>. If the word
is in <find> (an exact match -- case-sensitive, no wildcards), it
is replaced by the word in the corresponding position of <replace>
(and if <replace> has fewer words than <find>, and thus there is
no word in the corresponding position, that word will be null).
If the word is not in <find>, then the original word is simply kept.
The output list is separated by <output delim>.
Examples:
> say [ledit(apple banana lime plum,banana plum,yellow purple)]
You say, "apple yellow lime purple"
> say [ledit(apple|banana|lime|plum,banana|lime,yellow,|,+)]
You say, "apple+yellow++plum"
See also: edit(), replace()
& REGEDIT()
& REGEDITI()
& REGEDITALL()
& REGEDITALLI()
Function: regedit(<original string>,<regexp>,<replacement string>)
Function: regediti(<original string>,<regexp>,<replacement string>)
Function: regeditall(<original string>,<regexp>,<replacement string>)
Function: regeditalli(<original string>,<regexp>,<replacement string>)
These functions search <original string> for a portion that matches
<regexp>, and replaces that portion with <replacement string>, with
$<number> in <replacement string> expanded to the corresponding
matching parenthesized sub-expression of <regexp>; $0 is the entire
matched section.
regedit() replaces just the first match; regeditall() replaces all
matches. The versions ending in 'i' are case-insensitive.
If you need to place numerals in the replacement string immediately
following a sub-expression result, use curly braces, e.g., ${1}0 is
the first sub-match followed by a 0, but $10 is the tenth sub-match.
See "help regedit2" for examples.
& REGEDIT2
Examples:
> @va me = (.)est
> say regedit(this test is the best string,%va,$1rash)
You say, "this trash is the best string"
> say regeditall(this test is the best string,%va,$1rash)
You say, "this trash is the brash string"
> say regedit(this needs 2 tons of escaping, %(%\d+%), $%{1%}0)
You say, "this needs 20 tons of escaping"
& OBJEVAL()
Function: objeval(<object>,<expression>)
This function allows you to evaluate <expression> from the viewpoint of
<object>. You must own <object>, or have Wizard powers. If you do not,
the function defaults to evaluating from your viewpoint.
This function is useful for securing privileged objects which need
to evaluate attributes on things owned by other, or otherwise restrict
access to privileged information. For example, it's useful for a global
'+who' object to call the LWHO() function from the viewpoint of the
enactor (i.e, a 'objeval(%#,lwho())' call), so that if the player is
mortal, DARK wizards are hidden, but if the player is a wizard, DARK
wizards appear on the list.
& U()
Function: u([<obj>/]<attr>[,<arg>]...)
The u function evaluates an attribute, either from the object performing the
function or from another object you own, passing in arguments and returning
the result.
When evaluating the fetched attribute, %# refers to the original enactor and
not the 'calling' object, and 'me' refers to the object that supplied the
attribute.
Examples:
> @va me=Word is [extract(v(vb),add(%0,1),1)], arg2 is %1.
> @vb me=This is a test of the u function.
> say u(va,4,Testing 123)
You say, "Word is of, arg2 is Testing 123."
> say u(va,7)
You say, "Word is function., arg2 is ."
> say u(me/va,6,Foobar)
You say, "Word is u, arg2 is Foobar."
See also: ulocal(), udefault(), objcall(), s(), get(), get_eval(), map()
& ULOCAL()
Function: ulocal([<obj>/]<attr>[,<arg>]...)
The ulocal() function is almost identical to u() in function: it
evaluates an attribute, either from the object performing the function,
or another object that you control or has the same owner as you, passing
in arguments and returning the result. When evaluating the fetched
attribute, %# refers to the original enactor and not the 'calling' object;
'me' refers to the object that supplied the attribute.
However, unlike the u() function, the local registers r(0) through r(z)
(%q0 - %qz) are preserved in their initial state. This means that functions
"below" the level of the u() can reset local registers for temporary
calculations, without needing to worry about "clobbering" the original
values.
This makes ulocal() particularly useful for global or shared code which
calls arbitrary u() functions, where local register values need to be
preserved from accidental user clobbering.
See "help ulocal2" for examples.
& ULOCAL2
Example of ulocal():
> &FRUIT me=apples bananas oranges pears
> &SUB-FUNCTION me=[setq(0,v(FRUIT))][extract(%q0,match(%q0,%0),1)]
> &TOP-FUNCTION me=[setq(0,are delicious!)][ulocal(SUB-FUNCTION,%0)] %q0
> say u(TOP-FUNCTION,b*)
You say, "bananas are delicious!"
If SUB-FUNCTION had been called with u() instead of ulocal():
> &TOP-FUNCTION me=[setq(0,are delicious!)][u(SUB-FUNCTION,%0)] %q0
> say u(TOP-FUNCTION,b*)
You say, "bananas apples bananas oranges pears"
In this second example, in SUB-FUNCTION, %q0 was set to "apples bananas
oranges pears", so that when the u() "returned" and TOP-FUNCTION evaluated
%q0, this is what was printed. In the first example, ulocal() reset the
value of %q0 to its original "are delicious!"
See also: u(), setq(), r(), localize()
& OBJCALL()
Function: objcall(<victim>, [<obj>/]<attr> [,<arg1>, ..., <argN>])
This function evaluates <attribute> on <object>, passing in arguments
on the stack, from the viewpoint of <victim>. The <attribute> is
read using your permissions, and <obj>, if not specified, defaults
to you, NOT <victim>. You must own <object> or have Wizard powers;
if you do not, the function defaults to evaluating from your viewpoint.
This is useful when you want an object to execute a u-function, using
its own privileges, but you do not want to make the text of the
u-function visible to the object.
See also: u(), objeval()
& SPEAK()
Function: 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.
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>"
The conf parameter say_uses_comma is respected (using "says," or "says").
If <say string> is specified, it is used instead of "says," / "says".
Continued in 'help Speak2'.
& 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."
Continued in 'help Speak3'.
& 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'.
& 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'.
& 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'.
& 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'.
& 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!
& SWITCH()
Function: switch(<str>[,<pat1>,<res1>]...[,<dflt>])
The switch() function compares <str> against <pat1>, <pat2>, etc (allowing
* to match any number of characters and ? to match any 1 character), and
returns the corresponding <resN> parameter for the first <patN> pattern
that matches. If none match, then the default result <dflt> is returned.
The evaluated value of <str> can be obtained as '#$'. If switch() and
switchall() are nested, the nest level can be obtained with '#!'.
Example:
> say switch(c,*a*,A,*b*,B,*c*,C,*d*,D,E)
You say, "C"
> say switch(f,*a*,A,*b*,B,*c*,C,*d*,D,E)
You say, "E"
> say switch(cab,*a*,A,*b*,B,*c*,C,*d*,D,E)
You say, "A"
> say switch(f,*a*,A,*b*,B,*c*,C,*d*,D)
You say, ""
> say switch(words(foo bar baz),0,No words,1,1 word,#$ words)
You say, "3 words"
See also: @switch, switchall(), match().
& SWITCHALL()
Function: switch(<str>[,<pat1>,<res1>]...[,<dflt>])
The switchall() function compares <str> against <pat1>, <pat2>, etc.
(allowing * to match any number of characters and ? to match any 1
character), and returns the corresponding <resN> parameters (without
any delimiters) for all <patN> patterns that match. If none match,
then the default result <dflt> is returned. The evaluated value of
<str> can be obtained as '#$'. If switchall() and switch() are
nested, the nest level can be obtained with '#!'.
Example:
> say switchall(c,*a*,A,*b*,B,*c*,C,*d*,D,E)
You say, "C"
> say switchall(dab,*a*,A,*b*,B,*c*,C,*d*,D,E)
You say, "ABD"
> say switchall(f,*a*,A,*b*,B,*c*,C,*d*,D,E)
You say, "E"
See also: @switch, switch(), match().
& NONZERO()
Function: nonzero(<condition>,<string if non-zero>[,<string if zero>])
If <condition> is non-zero (defined as a non-null string that is
not the number zero, '0'), then the <string if non-zero> is returned.
Otherwise the <string if zero> is returned. Those two strings are not
evaluated until appropriate (i.e., if the string is non-zero, the
string-if-zero will not be evaluated, and vice versa). <string if
zero> may be omitted, in which case it is treated as an empty string.
Examples:
> say [nonzero(0,not zero,zero)] - [nonzero(1,not zero,zero)]
You say, "zero - not zero"
> say [nonzero(,not null,null)] - [nonzero(foo,not null,null)]
You say, "null - not null"
See also: ifelse(), switch(), case().
& IFELSE()
Function: ifelse(<condition>,<string if true>[,<string if false>])
If <condition> is true (defined as a true boolean), then the
<string if true> is returned. Otherwise, the <string if false>
is returned. The true and false strings are not evaluated until
appropriate (i.e., if the condition is true, the string-if-false
will not be evaluated, and vice versa). <string if false> may be
omitted, in which case it is treated as an empty string.
Examples:
> say [ifelse(1,true,false)] - [ifelse(0,true,false)]
You say, "true - false"
> say [ifelse(test,true,false)] - [ifelse(,true,false)]
You say, "true - false"
> say [ifelse(#5,true,false)] - [ifelse(#-1,true,false)]
You say, "true - false"
> say [ifelse(1,one)] - [ifelse(0,zero)]
You say, "one - "
See also: nonzero(), switch(), case(), BOOLEAN VALUES.
& LOCALIZE()
Function: localize(<expression>)
This function evalutes <expression> in a 'local' scope; this means
that the r-registers are preserved before <expression> is evaluated,
and restored after the evaluation. This allows the <expression>
embedded within to access the previous values of the r-registers,
without causing side-effects further "up" the code by altering the
value of those r-registers outside the scope of the <expression>'s
block of code.
See also: ulocal(), objeval(), s().
& SPACE()
Function: space(<count>)
Returns the number of indicated spaces. If <count> is missing, negative,
or cannot be converted to a number, one space is returned. This function
is useful when you want to pass a single space (or more than one) as a
function to an argument, because normally leading and trailing spaces are
stripped from function arguments.
Examples:
> say space(4)
You say, " "
> say edit(Foo bar bletch, space(), X)
You say, "FooXbarXbletch"
& PARENT()
Function: parent(<obj>)
Returns the parent of <obj>. Returns #-1 if <obj> cannot be found or
if you do not own <obj> and it is not set VISUAL.
Example:
> say parent(me)
You say, "#-1"
> say My va is [v(va)].
You say, "My va is "
> @parent me=test
Parent set.
> say parent(me)
You say, "#323"
> say My va is [v(va)].
You say, "My va is Testing 123"
See also: @parent, PARENT OBJECTS.
& SIGN()
Function: sign(<number>)
Returns -1, 0, or 1 depending on whether its argument is negative, zero, or
positive (respectively).
Example:
> say sign(-4)
You say "-1"
> say sign(4)
You say "1"
> say sign(0)
You say "0"
> say sign(-1)
You say "-1"
& CONN()
Function: conn(<player>)
Returns the number of seconds that <player> has been connected. If <player>
is not connected then -1 is returned. If <player> is connected more than
once, the longest connect time is returned. <player> can be the name of
a player, or a port number (from SESSION).
Example:
> WHO
Player Name On For Idle Doing
Wizard 00:04 1m
Mortal 00:11 0s
Evinar 00:12 6m
Wizard 00:32 6s
3 Players logged in.
> say conn(wiz)
You say, "251"
> say conn(e)
You say, "770"
> say conn(frobozz)
You say, "-1"
See also: WHO, idle(), lwho().
& IDLE()
Function: idle(<player>)
Returns the number of seconds that <player> has been idle. If <player>
is not connected then -1 is returned. If <player> is connected more than
once, the smallest idle time is returned. <player> can be the name of
a player, or a port number (from SESSION).
Example:
> WHO
Player Name On For Idle Doing
Wizard 00:04 1m
Mortal 00:11 0s
Evinar 00:12 6m
Wizard 00:32 6s
3 Players logged in.
> say idle(wiz)
You say, "6"
> say idle(e)
You say, "371"
> say idle(frobozz)
You say, "-1"
See also: WHO, conn(), lwho().
& CONVSECS()
Function: convsecs(<seconds>)
This function converts seconds to a time string, based on how many
seconds the number is after Jan 1, 1970.
Example:
> say secs()
You say, "709395750"
> say convsecs(709395750)
You say, "Wed Jun 24 10:22:54 1992"
This function may also be called as secs2time().
See also: convtime(), secs(), time().
& CONVTIME()
Function: convtime(<time string>)
This functions converts a time string to the number of seconds since
Jan 1, 1970. A time string is of the format: Ddd MMM DD HH:MM:SS YYYY
where Ddd is the day of the week, MMM is the month, DD is the day
of the month, HH is the hour in 24-hour time, MM is the minutes,
SS is the seconds, and YYYY is the year.
If you supply an incorrectly formatted string, it will return -1.
Example:
> say time()
You say, "Wed Jun 24 10:22:54 1992"
> say convtime(Wed Jun 24 10:22:54 1992)
You say, "709395774"
This function may also be called as time2secs().
See also: convsecs(), secs(), time().
& CONFIG()
Function: config(<parameter name>)
This function returns the value of the named configuration parameter,
whether this is a parameter built into the core MUSH server, or a
parameter from a module.
Not all configuration options can be obtained this way; some are protected
for security reasons, while others don't have a single simple value
(access directives, for instance).
& CONNRECORD()
Function: connrecord()
This function returns the record for the number of connected players
(the '<number> record' that the WHO command displays).
& SHUFFLE()
Function: shuffle(<word1> <word2> <...<wordN>[,<delim>][,<output delim>])
This function shuffles the order of words in a list, returning a random
permutation of its elements.
Example:
> say shuffle(foo bar baz gleep)
You say, "baz foo gleep bar"
> say shuffle(foo-bar-baz-gleep,-,+)
You say, "baz+foo+gleep+bar"
& SCRAMBLE()
Function: scramble(<string>)
This function scrambles a string, returning a random permutation of its
characters. Note that this function does not pay any attention to spaces
or other special characters; it will scramble these characters just like
normal characters.
Example:
> say scramble(abcdef)
You say, "cfaedb"
See also: SHUFFLE()
& SORT()
Function: sort(<list>[, <sort type>[, <delim>][, <output delim>])
Takes a list of words, numbers, or dbref, and sorts them into ascending
order. Lexicographic order is used for words, and numeric order is used
for numbers and dbrefs.
<sort type> may be used to specify the type of sort to perform (use 'd'
for dbref, 'n' for integer numeric, 'f' for floating numeric, 'i' for
case-insensitive alphanumeric, and 'a' for alphanumeric). If omitted
or left blank, the sort() function will automatically determine the
type of sort to perform; if the input list elements are of mixed types,
an alphanumeric sort is selected (case-insensitive alphanumeric is
never automatically used).
If delimiters are specified, they are used to separate items in the list.
You may specify them without a sort type by passing a null <sort type> .
Continued in 'help sort2'.
& SORT2
Examples:
> say sort(This is a test)
You say, "This a is test"
> say sort(98 99 100 101)
You say, "98 99 100 102"
> say sort(foo-bar-bletch,,-,+)
You say, "bar+bletch+foo"
> say sort(e D a c B)
You say, "B D a c e"
> say sort(e D a c B,i)
You say, "a B c D e"
& SETDIFF()
& LDIFF()
Function: setdiff(<list1>, <list2>[, <delim>][, <output delim>])
Function: ldiff(<list1>, <list2>[,<sort type>][,<delim>][,<output delim>])
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.
If delimiters are specified, they are used to separate the lists.
For ldiff(), an optional sort type, like the sort() function takes, can
be provided. Note that if you specify a sort type of 'i', 'f', or 'd',
and your lists have non-appropriate items in them, the result will be
garbage, with missing or duplicate items. If no sort type is specified,
an appropriate one will be deduced.
Example:
> say setdiff(foo baz gleep bar, bar moof gleep)
You say, "baz foo"
> say setdiff(foo-baz-gleep-bar, bar-moof-gleep,-,+)
You say, "baz+foo"
See also: setinter(), setunion(), sort().
& SETINTER()
& LINTER()
Function: setinter(<list1>, <list2>[, <delim>][, <output delim>])
Function: linter(<list1>, <list2>[,<sort type>][,<delim>][,<output delim>])
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.
If delimiters are specified, they are used to separate the lists.
For linter(), an optional sort type, like the sort() function takes, can
be provided. Note that if you specify a sort type of 'i', 'f', or 'd',
and your lists have non-appropriate items in them, the result will be
garbage, with missing or duplicate items. If no sort type is specified,
an appropriate one will be deduced.
Example:
> say setinter(foo baz gleep bar, bar moof gleep)
You say, "bar gleep"
> say setinter(foo-baz-gleep-bar, bar-moof-gleep,-,+)
You say, "bar+gleep"
See also: setdiff(), setunion(), sort().
& SETUNION()
& LUNION()
Function: setunion(<list1>, <list2>[, <delim>][, <output delim>])
Function: lunion(<list1>, <list2>[,<sort type>][,<delim>][,<output delim>])
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 duplicated words. The list returned is sorted.
For lunion(), an optional sort type, like the sort() function takes, can
be provided. Note that if you specify a sort type of 'i', 'f', or 'd',
and your lists have non-appropriate items in them, the result will be
garbage, with missing or duplicate items. If no sort type is specified,
an appropriate one will be deduced.
If delimiters are specified, they are used to separate the lists.
Example:
> say setunion(foo baz gleep bar, bar moof gleep)
You say, "bar baz foo gleep moof"
> say setunion(foo-baz-gleep-bar, bar-moof-gleep,-,+)
You say, "bar+baz+foo+gleep+moof"
See also: setdiff(), setinter(), sort().
& MERGE()
Function: merge(<string1>,<string2>,<character>)
This function merges <string1> and <string2>, depending on <character>.
If a character in <string1> is the same as <character>, it is replaced
by the character in the corresponding position in <string2>. The two
strings must be of the same length.
Spaces need to be treated specially. A null character is considered to
equal a space, for <character>.
Examples:
> say merge(AB--EF,abcdef,-)
You say, "ABcdEF"
> say merge(AB[space(2)]EF,abcdef,)
You say, "ABcdEF"
See also: splice().
& REPEAT()
Function: repeat(<string>,<number>)
This function simply repeats <string>, <number> times. No spaces are
inserted between each repetition.
Example:
> say repeat(Test, 5)
You say, "TestTestTestTestTest"
& SPLICE()
Function: splice(<list1>, <list2>, <word>[, <delim>][, <output delim>])
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.
Delimiters other than a space may be specified.
Example:
> say splice(foo bar baz,eek moof gleep,bar)
You say, "foo moof baz"
> say splice(foo-bar-baz,eek-moof-gleep,bar,-,+)
You say, "foo+moof+baz"
See also: merge().
& PI()
Function: pi()
Returns the value of the trigonometric constant pi to nine decimal places.
Example:
> say pi()
You say, "3.141592654"
See also: acos(), asin(), atan(), cos(), sin(), tan().
& E()
Function: e()
Returns the value of the numeric constant e to nine decimal places.
Example:
> say e()
You say, "2.718281828"
See also: exp(), ln(), log(), power().
& SIN()
& SIND()
Function: sin(<radians>)
Function: sind(<degrees>)
Returns the sine of <radians> or <degrees>, respectively.
Examples:
> say sin(0) --- [sind(0)]
You say, "0 --- 0"
> say sin(fdiv(pi(),2)) --- [sind(90)]
You say, "1 --- 1"
> say sin(fdiv(pi(),4)) --- [sind(45)]
You say, "0.707107 --- 0.707107"
> say sin(fdiv(pi(),6)) --- [sind(30)]
You say, "0.5 --- 0.5"
See also: acos(), asin(), atan(), cos(), pi(), tan().
& COS()
& COSD()
Function: cos(<radians>)
Function: cosd(<degrees>)
Returns the cosine of <radians> or <degrees>, respectively.
Examples:
> say cos(0) --- [cosd(0)]
You say, "1 --- 1"
> say cos(fdiv(pi(),2)) --- [cosd(90)]
You say, "0 --- 0"
> say cos(fdiv(pi(),4)) --- [cosd(45)]
You say, "0.707107 --- 0.707107"
> say cos(fdiv(pi(),6)) --- [cosd(30)]
You say, "0.866025 --- 0.866025"
See also: acos(), asin(), atan(), pi(), sin(), tan().
& TAN()
& TAND()
Function: tan(<radians>)
Function: tand(<degrees>)
Returns the tangent of <radians> or <degrees>, respectively.
Examples:
> say tan(0) --- [tand(0)]
You say, "0 --- 0"
> say tan(1) --- [tand(1)]
You say, "1.557408 --- 0.017455"
> say tan(fdiv(pi(),4)) --- [tand(45)]
You say, "1 --- 1"
See also: acos(), asin(), atan(), cos(), pi(), sin().
& ASIN()
& ASIND()
Function: asin(<number>)
Function: asind(<number>)
Returns the arcsine of <number>, expressed in radians or degrees,
respectively. <number> must be between -1 and 1.
Examples:
> say asin(0) --- [asind(0)]
You say, "0 --- 0"
> say asin(1) --- [asind(1)]
You say, "1.570796 --- 90"
> say asin(0.707101) --- [asind(0.707101)]
You say, "0.78539 --- 44.999532"
> say asin(0.5) --- [asind(0.5)]
You say, "0.523599 --- 30"
See also: acos(), atan(), cos(), pi(), sin(), tan().
& ACOS()
& ACOSD()
Function: acos(<number>)
Function: acosd(<number>)
Returns the arc-cosine of <number>, expressed in radians or degrees,
respectively. <number> must be between -1 and 1.
Examples:
> say acos(0) --- [acosd(0)]
You say, "1.570796 --- 90"
> say acos(1) --- [acosd(1)]
You say, "0 --- 0"
> say acos(0.707101) --- [acosd(0.707101)]
You say, "0.785406 --- 45.000468"
> say acos(0.866025) --- [acosd(0.866025)]
You say, "0.5236 --- 30.000046"
See also: asin(), atan(), cos(), pi(), sin(), tan().
& ATAN()
& ATAND()
Function: atan(<number>)
Function: atand(<number>)
Returns the arctangent of <number>, expressed in radians or degrees,
respectively.
Examples:
> say atan(0) --- [atand(0)]
You say, "0 --- 0"
> say atan(1) --- [atand(1)]
You say, "0.785398 --- 45"
> say atan(1.557408) --- [atand(1.557408)]
You say, "1 --- 57.295784"
See also: acos(), asin(), cos(), pi(), sin(), tan().
& FLOOR()
Function: floor(<number>)
Returns the largest integer less than or equal to <number>. <number> may be
a floating point number, and an integer result is returned.
Examples:
> say floor(5)
You say, "5"
> say floor(5.2)
You say, "5"
> say floor(5.8)
You say, "5"
> say floor(-5)
You say, "-5"
> say floor(-5.2)
You say, "-6"
See also: ceil(), div(), mod(), round(), trunc().
& CEIL()
Function: ceil(<number>)
Returns the smallest integer greater than or equal to <number>. <number>
may be a floating point number, and an integer result is returned.
Examples:
> say ceil(5)
You say, "5"
> say ceil(5.2)
You say, "6"
> say ceil(5.8)
You say, "6"
> say ceil(-5)
You say, "-5"
> say ceil(-5.2)
You say, "-5"
See also: div(), floor(), mod(), round(), trunc().
& TRUNC()
Function: trunc(<number>)
Returns the value of <number> after truncating off any fractional value.
<number> may be a floating point number, and an integer result is returned.
Examples:
> say trunc(5)
You say, "5"
> say trunc(5.2)
You say, "5"
> say trunc(5.8)
You say, "5"
> say trunc(-5)
You say, "-5"
> say trunc(-5.2)
You say, "-5"
See also: div(), floor(), mod(), round().
& ROUND()
Function: round(<number>,<places>)
Rounds <number> to <places> decimal places. <number> may be
a floating point number, and an integer result may be returned.
Examples:
> say round(5,0)
You say, "5"
> say round(5.123,1)
You say, "5.1"
> say round(9.8765,3)
You say, "9.877"
> say round(5.5,0)
You say, "6"
> say round(-5.5,0)
You say, "-6"
See also: div(), floor(), mod(), trunc().
& SQRT()
Function: sqrt(<number>)
Returns the square root of <number>. <number> may be a floating point
number, and a floating point result is returned. <number> may not be
negative.
Examples:
> say sqrt(2)
You say, "1.414214"
> say sqrt(100)
You say, "10"
> say sqrt(0)
You say, "0"
> say sqrt(-1)
You say, "#-1 SQUARE ROOT OF NEGATIVE"
See also: power().
& POWER()
Function: power(<number>, <power>)
Returns the result of raising <number> to the <power>'th power.
<number> may not be negative. <number> and <power> may be floating point
numbers, and a floating point result is returned.
Examples:
> say power(2,3)
You say, "8"
> say power(9, 0.5)
You say, "3"
> say power(100,pi())
You say, "1919487.587204"
> say power(5, 0)
You say, "1"
> say power(0, 0)
You say, "1"
> say power(2,-3)
You say, "0.125"
> say power(-2,3)
You say, "#-1 POWER OF NEGATIVE"
See also: exp(), ln(), log(), sqrt()
& LN()
Function: ln(<number>)
Returns the result of taking the natural logarithm (base e) of <number>.
<number> may be a floating point number, and a floating point result
is returned.
Examples:
> say ln(0)
You say, "#-1 LN OF NEGATIVE OR ZERO"
> say ln(1)
You say, "0"
> say ln(e())
You say, "1"
> say ln(10)
You say, "2.302585"
See also: e(), exp(), log(), power().
& LOG()
Function: log(<number>[,<base>])
If <base> is not specified, this returns the result of taking the
common logarithm (base 10) of <number>. If <base> is specified,
then this returns the result of taking the log base <base> of
<number>. To take the natural log of a number, make its base e().
<number> may be a floating point number, and a floating point result
is returned.
Examples:
> say log(0)
You say, "#-1 LOG OF NEGATIVE OR ZERO"
> say log(1)
You say, "0"
> say log(100)
You say, "2"
> say log(e())
You say, "0.434294"
> say log(32,2)
You say, "5"
See also: e(), exp(), ln(), power().
& EXP()
Function: exp(<power>)
Returns the result of raising the numeric constant e to <power>.
<power> may be a floating point number, and a floating point result
is returned.
Examples:
> say exp(0)
You say, "1"
> say exp(1)
You say, "2.718282"
> say exp(2)
You say, "7.389056"
See also: e(), log(), ln(), power().
& PARSE()
Function: parse(<list>, <eval>[, <delim>][, <output delim>])
This function behaves identically to iter(), except that successive
calls of it cannot be nested. The replacement of the '##' and '#@'
tokens is "blind", i.e., it simply goes through the evaluation string
without regard for nesting. As a result, it handles escapes in a
different manner than iter().
This function is provided for backwards compatibility.
See also: iter(), map(), list(), loop().
& sees()
Function: sees(<object>,<victim>)
If <victim> would show up in the list of room contents, if <object>
was looking at <victim>'s location, this function returns 1; note
that <object> never sees himself in the contents so if <object> and
<victim> are the same this function returns 0.
This function checks a lot of things: whether or not the object is a
disconnected player, the status of the Light and Dark flags (including
the status of any DarkLocks), whether or not <object> can examine
<victim>'s location, and more.
If either <object> or <victim> are not valid objects, this function
returns 0.
& findable()
Function: findable(<object>,<victim>)
Returns 1 if <object> can locate <victim>, or 0 otherwise. This checks
wizard status of <object>, UNFINDABLE status of <victim>, and other
related factors.
& visible()
Function: visible(<object>,<victim>[/<attr>])
Returns 1 if <object> can examine <victim>, or 0 otherwise. If
<object> or <victim> do not exist, 0 is returned.
If an object-attribute pair is provided, 1 is returned if <object>
can see <attr> on <victim>. If <attr> is not present on <victim>,
1 is returned if <object> can examine <victim>.
& writable()
Function: writable(<object>,<victim>/<attr>)
Returns 1 if <object> can set <victim>'s <attr>, or 0 otherwise. If
<object> or <victim> do not exist, 0 is returned. Note that this
check does not take into account whether or not <attr> is @lock'd.
& controls()
Function: controls(<object>,<victim>)
Returns 1 if <object> controls <victim>, 0 otherwise.
Examples:
> say controls(me,me)
You say "1"
> say controls(me,#1)
You say "0"
> say controls(#1,me)
You say "1"
See also: CONTROL.
& map()
Function: map([<obj>/]<attr>, <list>[, <delim>][, <output delim>])
This function is nearly identical to an iter() operating on u() function.
Each member of <list> is passed to the result of fetching <attr> as %0,
and the member's position in the list is passed as %1. The results are
used to form a new list. <delim> (the input delimiter) is used to
separate strings within the list. The results are separated by
<output delimiter> if it is specified, or by <input delimiter> if
it is not. The input delimiter defaults to a space if not specified.
Examples:
> &ADD_ONE object=add(%0,1)
> say map(object/add_one,1 2 3 4 5)
You say "2 3 4 5 6"
> say map(object/add_one,1 2 3 4 5,,-)
You say "2-3-4-5-6"
> say map(object/add_one,1-2-3-4-5,-,+)
You say "2+3+4+5+6"
> say map(object/add_one,1 2 3 4 5,-,@@)
You say "23456"
See also: filter(), fold(), iter(), step(), u().
& filter()
Function: filter([<obj>/]<attr>, <list>[, <delim>][, <output delim>])
This function evaluates the contents of <attr> for each element of
<list>, passing it in as %0, and its position within the list as %1.
An <output delim>-separated list is returned of those elements for
which the evaluation returns the value 1.
<delim> and <output delim> may be used to specify delimiters other than
spaces.
Examples:
> &IS_ODD object=mod(%0,2)
> say filter(object/is_odd,1 2 3 4 5)
You say, "1 3 5"
> say filter(object/is_odd,1-2-3-4-5,-)
You say, "1-3-5"
> say filter(object/is_odd,1 2 3 4 5,,+)
You say, "1+3+5"
> say filter(object/is_odd,1-2-3-4-5,-,.)
You say, "1.3.5"
See also: filterbool(), istrue(), isfalse(), u(), map(), fold()
& filterbool()
Function: filter([<obj>/]<attr>, <list>[, <delim>][, <output delim>])
This function works identically to filter(), except that it returns
all elements of the list for whom the evaluation returns a boolean
truth value.
Example:
> &IS_JUMPOK object=[hasflag(%0,Jump_OK)]
> say filterbool(object/IS_JUMPOK,#10 #25 #-1 #6)
You say, "#25 #6" [assuming those rooms are jump_ok]
See also: filter(), istrue(), isfalse()
& fold()
Function: fold([<obj>/]<attr>, <list>[, <base-case>[, <delim>])
This function iteratively processes a list through a function, feeding
the result of one step into the next step as %0, passing in the next
element from the list as %1. The position of the element in the list is
passed as %2.
If a base case is provided, it is used as the initial %0. If not, the first
list element is passed as %0 and the second is passed as %1, and subsequent
iterations proceed normally (in this case, %2 is initially 1, and the
next iteration makes it 3, since it's the third element geting processed).
<delimiter> may be used to specify a delimiter other than space, but you
must specify a base case in order to specify the delimiter.
Examples:
> &REP_NUM object=[%0][repeat(%1,%1)]
> say fold(object/rep_num,1 2 3 4 5,->)
You say, "->122333444455555"
> &ADD_NUMS object=add(%0,%1)
> say fold(object/add_nums,1 2 3 4 5)
You say, "15"
See also: u(), iter(), map(), filter()
& RJUST()
Function: rjust(<string>, <length>[, <fill>])
This function pads a string with leading <fill>, or with spaces if no
fill string is given, "right-justifying" so the result is <length> long.
If <string> is longer than <length>, the <string> is returned; it is not
truncated.
Examples:
> say -[rjust(foo,6)]-
You say, "- foo-"
> say %r0[rjust(foo,6)]7%r01234567
You say, "
0 foo7
01234567"
> say =[rjust(bar,5,.)]=
You say, "=..bar="
> say [rjust(foo,9,-=-)]
You say, "-=--=-foo"
See also: ljust(), strlen().
& LJUST()
Functions: ljust(<string>, <length>[, <fill>])
This function pads a string with trailing <fill>, or with spaces if no
fill string is given, "left-justifying" so the result is <length> long.
If <string> is longer than <length>, the <string> is returned; it is not
truncated.
Examples:
> say -[ljust(foo,6)]-
You say, "-foo -"
> say %r0[ljust(foo,6)]7%r01234567
You say, "
0foo 7
01234567"
> say =[ljust(bar,5,.)]=
You say, "=bar..="
> say [ljust(foo,9,-=-)]
You say, "foo-=--=-"
See also: rjust(), strlen().
& LINK()
Function: link(<object>,<destination>)
This side-effect function links an object to a location, behaving
identically to the command '@link <object>=<destination>'.
& TEL()
Function: tel(<object>,<destination>)
This side-effect function teleports an object from one place to another,
behaving identically to the command '@tel <object>=<destination>'.
& WIPE()
Function: wipe(<object>[/<wild-attr>])
This side-effect function erases some or all attributes from an object,
behaving identically to the command '@wipe <object>[</wild-attr>]'.
& SET()
Function: set(<arg 1>,<arg 2>)
This acts identically to the command '@set <arg 1>=<arg 2>'. An
empty string is always returned, regardless of the success or
failure of the attempted set.
Common cases of use of this function:
set(<object>,[!]<flag>)
set(<object>,<attribute>:<value>)
set(<object>,<attribute>:_<fromobj>/<fromattr>)
set(<object>/<attr>,[!]<attrflag>)
& R()
Function: r(<number or letter>)
The r() function is used to access "local reigsters", and returns
the contents of the specified register.
This is equivalent to the substitution %q<number> or %q<letter>;
i.e., "r(0)" == "%q0", "r(x)" == "%qx", etc., or to the substitution
%q<name> (where the angle-brackets are literal), i.e.,
"r(test)" == "%q<test>".
Use of the %q substitution is faster. However, there are instances
where parsing considerations make r() necessary. For instance, the
contents of angle-brackets are not evaluated. Thus, if you have
registers called a0 through a9, and you want to access all of
them, 'iter(lnum(10), %q<a##>)' will not work; you need to use
'iter(lnum(10), r(a##))'.
See also: LOCAL REGISTERS, setq(), setx(), store(), x().
& SETQ()
Function: setq(<number, letter, or name>,<string>[,...,<varN>,<stringN>])
The setq() function is used to copy strings into local registers.
It returns a null string; it is a purely "side effect" function.
setq() can take multiple variable name - value pairs.
Example:
> &TEST me=Test on [mudname()] at [time()].
> say [setq(0,u(TEST))]'[r(0)]' has length [strlen(r(0))].
You say, "'Test on TestMUSH at Tue Feb 23 17:00:51 1993.' has length 45."
> say Test.[setq(a,Test,tmp,on,9,TestMUSH)] %qa %q<tmp> %q9.
You say, "Test. Test on TestMUSH."
See also: LOCAL REGISTERS, setr(), r(), setx(), store(), x().
& SETR()
Function: setr(<number, letter, or name>,<string>)
This function behaves identically to the setq() function, except
that it returns the string being copied in the register.
Example:
> &TEST me=Test on [mudname()] at [time()].
> say '[setr(0,u(TEST))]' has length [strlen(%q0)].
You say, "'Test on TestMUSH at Tue Feb 23 17:00:51 1993.' has length 45."
See also: LOCAL REGISTERS, setq(), r(), setx(), store(), x().
& SETX()
Function: setx(<variable name>,<value>)
This function sets the value of a variable associated with the
calling object. Using an empty <value> will unset the variable. For
reasons of memory consumption, variables should ALWAYS be explicitly
unset when they are not immediately needed. This function does not
return anything.
Example:
> say Testing [setx(temp,abc)][x(temp)] - [strlen(x(temp))].
You say, "Testing abc - 3."
See also: store(), x(), VARIABLE FUNCTIONS.
& STORE()
Function: store(<variable name>,<value>)
This function sets the value of a variable associated with the
calling object. Using an empty <value> will unset the variable. For
reasons of memory consumption, variables should ALWAYS be explicitly
unset when they are not immediately needed.
This function returns <value> -- i.e., it behaves just like setx(),
except that it returns <value> rather than returning nothing, making
the setx() : store() relationship equivalent to the setq() : setr()
relationship.
See also: setx(), x(), VARIABLE FUNCTIONS.
& X()
Function: x(<variable name>)
This function retrieves a temporary variable associated with the object
making the function call.
The variable can also be retrieved via the more efficient percent
substitution, For variable names of a single letter or digit (A - Z,
0 - 9), this is %_<variable name> -- x(a) is equivalent to %_a, x(0) is
equivalent to %_0, and so forth. Multi-letter variable names can also
be accessed in this way, if the variable name is enclosed in angle
brackets -- x(foo) is equivalent to %_<foo>, x(test) is equivalent
to %_<test>, etc.
See also: setx(), store(), lvars(), setq(), setr(), r().
& XVARS()
Function: xvars(<list of variables>,<list of strings>[,<delim>])
This side-function takes the list of strings, and sets each string into
the corresponding variable from the list. If <list of strings> is empty,
then all variables in the list will be unset. If <delim> is specified, the
list of strings is considered to be <delim>-separated; the list of
variables is always space-separated.
Example:
> say [xvars(foo bar baz,apple peach cherry)][x(foo)]-[x(bar)]-[x(baz)]
You say, "apple-peach-cherry"
> say [xvars(foo bar baz,apple|peach|cherry,|)][x(bar)]
You say, "peach"
See also: x(), setx(), store(), let(), lvars(), clearvars(), regparse().
& LET()
Function: let(<list of variables>,<list of strings>,<expression>[,<delim>])
This side-effect function does three things:
First, it takes the list of strings, and sets each string into the
corresponding variable from the list. If <list of strings> is
empty, then the values of the variables will be unchanged. If <delim> is
specified, the list of strings is considered to be <delim>-separated;
the list of variables is always space-separated. Then, it evaluates
<expression>. Finally, it restores the original values of the
<list of variables>. If <list of variables> is empty, the function
does nothing.
This is useful for temporary variable use and cleanup, as it effectively
allows variables to be passed-by-value, and limits their scope to the
local "block" of the let() -- it functions in a way roughly akin to the
way localize() does for r-registers.
Continued in 'help let2'.
& LET2
Examples:
> say [setx(foo,old)][x(foo)]*[let(foo z,new A,[x(z)] [x(foo)])]*[x(foo)]
You say, "old*A new*old
> say [setx(a,old)]%_a - [let(a b c,1|2|3,%_a+%_b+%_c,|)] - %_a
You say, "old - 1+2+3 - old"
See also: x(), setx(), store(), regparse().
& LVARS()
Function: lvars()
Returns a space-separated list of all variable names associated with
the calling object. This is potentially computationally expensive and
should be avoided if possible.
See also: x(), setx(), store(), lvars(), clearvars().
& CLEARVARS()
Function: clearvars()
Unsets all variables associated with the calling object. This is
potentially computationally expensive, and should be avoided if
possible.
See also: x(), setx(), store(), lvars().
& OEMIT()
Function: oemit(<target>, <string>)
This side-effect function sends a message to everyone in <target>'s
location with the exception of <target>, just as if the command
'@oemit <target> = <string>' had been invoked.
See also: pemit(), remit().
& PEMIT()
Function: pemit(<list of dbrefs>,<string>)
This side-effect function sends a message to the list of dbrefs, just
as if the command '@pemit/list <list of dbrefs>=<string>' had been
invoked.
See also: oemit(), remit().
& SQL()
Function: sql(<SQL statement>[, <delim>][, <field delim>])
This function sends a SQL statement to an external SQL database and
returns the results. The user must be God or have the use_sql power
(note that even having a Wizard flag is not sufficient). If there is
a problem with executing the SQL statement, the function returns #-1.
If multiple rows are returned, each row will be delimited by <delim>;
if <delim> is not specified, a space will be used. If multiple fields
are returned, each field will be delimited by <field delim> if specified,
or <delim> if not, or a space by default.
Note that MUSH treats parentheses and commas as special characters
within functions. You may need to be careful about escaping special
characters.
Continued in 'help SQL2'.
& SQL2
The nature of what constitutes a valid SQL statement will depend on
the type of back-end SQL database. Note that the character ' is used
for quotes around field values. Thus, if your value for a field contains
quote marks, make sure to escape them out (use \' to do this).
Example (using mSQL syntax, see 'help mSQL' for details):
> @sql CREATE TABLE test( player_name char(16) not null,
race char(8) not null, dbref_num int )
> @sql CREATE UNIQUE INDEX idx_by_dbref ON test (dbref_num)
> @sql INSERT INTO test (player_name, race, dbref_num)
VALUES('Nos', 'Vampire', 4)
> @sql INSERT INTO test VALUES('Rufus', 'Werewolf', 672)
> @sql INSERT INTO test VALUES('Caine', 'Vampire', 389)
(The above commands all output, "SQL query touched 1 row.")
Continued in 'help SQL3'.
& SQL3
(Example continued)
> SELECT player_name, dbref_num FROM test WHERE race='Vampire'
Row 1, Field 1: Nos
Row 1, Field 2: 4
Row 2, Field 1: Caine
Row 2, Field 2: 389
> &VAMPS me = SELECT player_name, dbref_num FROM test WHERE race='Vampire'
ORDER BY player_name
> say [sql(v(VAMPS))] -- [sql(v(VAMPS),|)]
You say "Caine 389 Nos 4 -- Caine|389|Nos|4"
> @sql UPDATE test SET race='Vampire' WHERE dbref_num=672
SQL query touched 1 row.
> say [sql(v(VAMPS),|,)] -- [sql(v(VAMPS),|,/)]
You say "Caine 389|Nos 4|Rufus 672 -- Caine/389|Nos/4|Rufus/672"
Continued in 'help SQL4'.
& SQL4
Because connectivity between the MUSH and the external SQL database is
not guaranteed (there could be network issues, issues with the database
server, etc., and no atomic way to test to ensure that connectivity is
up and functioning), one must be careful to check for the #-1 return
code (which indicates an error, including possibly the database
connection being unavailable) when reading or writing data from the
external SQL database.
This functionality is most useful if you have a need to export MUSH
data to the outside world, or vice versa. You should NOT use the
external database as the preferred storage mechanism; for the vast
majority of MUSH applications, the game's own internal database
access is significantly faster. Indeed, because of this, if you have
data in the SQL database that you use very frequently within the
game, you should store that data within the game as well, and simply
mirror it to the SQL database as it changes.
& REMIT()
Function: remit(<list of dbrefs>,<string>)
This side-effect function sends a message to the list of dbrefs, just
as if the command '@pemit/list/contents <list of dbrefs>=<string>' had
been invoked.
The function takes its name from the '@remit' command, which is an
alias for '@pemit/contents'.
See also: pemit(), oemit().
& SQUISH()
Function: squish(<string>[,<character>])
This function will trim multiple occurrences of <character> (or a space, if
<character> is not specified) down to a single occurrence of <character>.
This is useful for getting rid of big internal spaces, and the like.
Examples:
> @force me=@va me=Test\[space(5)\]Test (which becomes 'Test Test')
> say squish(%va)
You say, "Test Test"
> say squish(---ack-----oof---,-)
You say, "-ack-oof-"
See also: trim()
& TRIM()
Function: trim(<string> [,<trim style> [,<trim string>]])
This function will trim trailing and/or lead characters on the string
that you specify. <trim character> specifies the character to trim (default
is space), and <trim style> tells the kind of trimming to perform (default
is trim both sides of the string).
The following values for <trim style> are recognized:
'b' : Trim both ends of the string (default)
'l' : Trim the left end of the string.
'r' : Trim the right end of the string.
Note: anything else specified for <trim style> will trim both sides.
Example:
> say trim(;;;Wacka;;;,b,;)
You say, "Wacka"
> say trim(%b%b%b Polly Parrot %b%b%b%b,r)
You say, " Polly Parrot"
> say trim(-*-Trim Rules!-*-,l,-*-)
You say, "Trim Rules!-*-"
See also: center(), ljust(), rjust().
& CENTER()
Function: center(<string>, <width>[, <fill>])
This function will center a string in a string <width> characters wide,
using <fill> for padding on either end of the string for centering.
If no fill string is specified then a space is used. If <string> is
longer than <width> characters, the string is returned unmodified.
Example:
> say center(a,5,-)
You say, "--a--"
> say center(*BAMF*,15)
You say, " *BAMF* "
> say center(ZAP,9,-=-)
You say, "-=-ZAP-=-"
See also: ljust(), rjust().
& INSERT()
Function: insert(<list>, <pos>, <word>[, <sep>])
This function inserts a word into <list> so that the word becomes the
<pos>'th element of the list, and all subsequent list elements are moved
down. This means that it appears between the <pos-1>'th and <pos>'th
elements of the original list. This function may not be used to append
a word to a list.
<delim> may be used to specify a delimiter other than a space.
Examples:
> say insert(This is a test, 4, new)
You say, "This is a new test"
> say insert(Yet@Another@List, 3, Funky, @)
You say, "Yet@Another@Funky@List"
See also: extract(), ldelete(), replace().
& REPLACE()
Function: replace(<list>, <pos>, <word>[, <sep>])
This function inserts a word into <list> so that the word becomes the
<pos>'th element of the list, and the word previously in that position
is removed. This means that it appears between the <pos-1>'th and
<pos+1>'th elements of the original list, replacing the word at that
position. This function may not be used to append a word to a list.
<delim> may be used to specify a delimiter other than a space.
Examples:
> say replace(This is a test, 4, quiz)
You say, "This is a quiz"
> say replace(Yet@Another@Mundane@List, 3, Funky, @)
You say, "Yet@Another@Funky@List"
See also: extract(), insert(), ldelete().
& LDELETE()
Function: ldelete(<list>, <pos>[, <sep>])
This function removes a word from <list> by position.
<delim> may be used to specify a delimiter other than a space.
Examples:
> say ldelete(This is not a test, 3)
You say, "This is a test"
> say ldelete(Yet@Another@Mundane@List, 3, @)
You say, "Yet@Another@List"
See also: extract(), insert(), replace().
& ISDBREF()
Function: isdbref(<string>)
This function will return 1 if the string passed to it is a valid dbref.
To be a valid dbref the string must begin with '#' and be followed by an
integer. Also, the dbref must exist in the current database as a valid
object. If the object fails either of these criteria, then a 0 is
returned.
Example:
> say isdbref(#-1)
You say, "0"
> say isdbref(#1)
You say, "1"
> say isdbref(This is not a dbref)
You say, "0"
& ISNUM()
Function: isnum(<string>)
This function will return 1 if the argument is a valid number and 0
if it is not.
Example:
> say isnum(22223.0000)
You say, "1"
> say isnum(77)
You say, "1"
> say isnum(22 L)
You say, "0"
>say isnum(Bad Numbers!)
You say, "0"
& ISWORD()
Function: isword(<string>)
This function will return 1 if every character in <string> is a letter,
and 0 if this is not true.
Example:
> say isword(Test)
You say, "1"
> say isword(Test123)
You say, "0"
& FOREACH()
foreach([<object>/]<attribute>,<string>[,<start token>][,<end token>])
Maps a function onto a string.
Each character in <string> has the user-defined function of the first
argument performed on it; the character is passed to the function as
%0, and the position of the character in the string is passed as %1
(with the first character being position 0). The results are concatenated.
If <start token> is specified, only characters that occur after that
single-character token will be evaluated, though characters prior to
that will be copied. If <end token> is also specified, characters that
occur after that single-character token will not be evaluated, though
they will be copied. The tokens themselves are not copied.
Continued in 'help foreach2'.
& FOREACH2
The tokens can be alternated, so that things not between them are
copied but not evaluated. The tokens can also be the same character.
Note that only the occurrence of the tokens in their specific start
and end contexts will cause them to be skipped. This means, for
example, if an end token is encountered before a start token is
encountered, the end token will be copied as-is.
Examples:
> &add_one me=[add(%0,1)]
> say [foreach(add_one, 54321)]
You say, "65432"
> say [foreach(add_one,12<34>56,<,>)]
You say, "124556"
> say [foreach(add_one,12#34#56,#)]
You say, "1245167" [The add() counts '#' as '0'.]
> say [foreach(add_one,12<34>56,#,>)]
You say, "12<34>45"
& MIX()
mix([<object>/]<attribute>,<list 1>,<list 2>[,<list N>][,<delim>])
This function is similar to MAP(), except that it takes the elements
of several lists, one by one, and passes them to the user-defined function
as %0, %1, %2, etc.respectively, for elements of <list 1>, <list 2>, etc.
<delim> is used to separate elements; if it is not specified, it defaults
to a space. The lists do not need to have the same number of elements;
shorter lists will be padded out with nulls. If more than two lists are
specified, the last argument MUST be a delimiter.
Examples:
> &add_nums me=[add(%0,%1)]
> say [mix(add_nums,1 2 3 4 5,2 4 6 8 10)]
You say "3 6 9 12 15"
> say [mix(add_nums,1:3:5:7,0:2:4:6,:)]
You say "1:5:9:13"
> &add_nums me=[add(%0,%1,%2,%3,%4)]
> say [mix(add_nums,1 2,3 4,5 6,7 8,9 10,)]
You say "25 30"
& STEP()
step([<object>/]<attribute>,<list>,<step size>[,<delim>[,<output delim>]])
This function takes elements of <list>, <step size> elements at a time,
and passes them to the function defined by <attribute>, as %0, %1, %2,
etc. The number of elements in the list does not need to be evenly
divisible by the step size. If no delimiters are provided, a space is
used as the delimiter. The step size must be at least 1, and no greater
than 10. Calling this function with a step size of 1 is equivalent to
using map().
Example:
> &print_line me = %r%0 -- %1 -- %2
> say [step(print_line,1 2 3 4 5 6 7 8,3)]
You say, "
1 -- 2 -- 3
4 -- 5 -- 6
7 -- 8 --"
& DOING()
doing(<player>)
This function returns the @doing string of a connected player. If the
player does not exist, or is not connected, this function returns an
empty string. <player> can be the name of a player, or a port number
(from SESSION).
& PROGRAMMER()
programmer(<player name>)
This function returns the dbref of the object which is calling a @program
on a player, where the player is specified by player name or by dbref.
If the target player is not connected, or is not in a @program, this
function returns #-1. You must be able to examine the player, or
this function returns #-1.
& PORTS()
ports(<player name>)
This function returns the list of descriptors ("ports") that a player,
specified by full player name, or by dbref, is connected to. Only Wizards
may use this function; if a user lacks the privileges, or the player is
not connected, an empty list is returned. Otherwise, a list of ports is
returned in order of most recent connection to least recent connection.
These ports correspond to those given by the SESSION command.
& SESSION()
session(<player>)
This function returns a list of three numbers associated with a port:
the number of commands entered this session, the bytes of input entered
this session, and the bytes of output received this session.
<player> can be the name of a player, or a port number.
You must have the Expanded_Who power, be a Wizard or Royalty, or control
the player whose port that is, in order to obtain this information.
Port numbers can be obtained via the ports() function. To get the
session info associated with a player's most recent connection, use
'session(first(ports(<player>)))'. To get the session info associated
with a player's oldest connection, use 'session(last(ports(<player>)))'.
See also: ports(), SESSION, WHO
& HASATTR()
hasattr(<object>,<attribute>)
Returns '1' if <object> has named <attribute> (and the attribute can be
seen by the invoker), or 0 if not. If the specified object is invalid,
"#-1 NO MATCH" will be returned. Note that this does not check the
<object>'s parents for the presence of the attribute; use hasattrp()
to do that.
& SORTBY()
sortby([<obj>/]<attrib>,<list>[,<delimiter>][,<output delim>])
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.
& MUNGE()
munge([<object>/]<attribute>,<list 1>,<list 2>[,<delim>][,<output delim>])
This function takes two lists of equal length. It passes the entirety of
<list 1> to the user-defined function as %0, and the input delimiter
as %1. Then, this resulting list is matched with elements in <list 2>,
and the rearranged <list 2> is returned. This is useful for doing things
like sorting a list, and then returning the corresponding elements in the
other list. If a resulting element from the user-defined function doesn't
match an element in the original <list 1>, a corresponding element from
<list 2> does not appear in the final result.
For example: Consider attribute PLACES, which contains "Fort Benden Ista",
and another attribute DBREFS, which contains the dbrefs of the main JUMP_OK
location of these areas, "#20 #9000 #5000". We want to return a list of
dbrefs, corresponding to the names of the places sorted alphabetically. The
places sorted this way wouuld be "Benden Fort Ista", so we want the final
list to be "#9000 #20 #5000". The functions, using munge(), are simple:
> &sort_alpha me=[sort(%0)]
> say [munge(sort_alpha,v(places),v(dbrefs))]
& ALPHAMAX()
Function: alphamax(<string1>, <string2>, ..., <stringN>)
Takes up to ten strings, and returns the string which is
lexicogrpahically biggest.
& ALPHAMIN()
Function: alphamin(<string1>, <string2>, ..., <stringN>)
Takes up to ten strings, and returns the string which is
lexicogrpahically smallest.
& ART()
Function: art(<string>)
This function returns the proper article, "a" or "an", based on
whether or not <string> begins with a vowel.
& BEEP()
Function: beep()
This function simply outputs the beep charater, which will "ring the
bell" on terminals with sound. Only Wizards may use this function.
& CASE()
Function: case(<str>[,<pat1>,<res1>]...[,<dflt>])
This function is similar to switch(), save that it looks for an exact
match between the patterns and the string, rather than doing a 'wildcard'
match (case-insensitive match with '*' and '?'), and the '#$' token
replacement is not done. It performs marginally faster than switch().
See also: @switch, switch(), ifelse(), match().
& CHILDREN()
Function: children(<object>[, <odelim>])
This function returns a list of objects that are parented to <object>.
It may only be used by Wizards or Royalty.
& CHOOSE()
Function: choose(<list of elements>, <list of weights>[, <delim>])
This function returns an element from <list of elements>, according to
a weighted random choice provided by <list of weights>. <list of elements>
is a <delim>-separated list (or space-separated if no delimiter is
provided). <list of weights> is a space-separated list of numbers.
For instance, 'choose(abc def ghi jkl, 10 5 3 2)' has a 50% chance of
returning abc, a 25% chance of returning def, a 15% chance of returning
ghi, and a 10% chance of returning jkl.
& COLUMNS()
Function: columns(<list>, <width>[, <delim>[, <indent>]])
This function displays <list> formatted into columns <width>-characters
wide; i.e., each element of <list> will appear in a column <width> wide.
As many columns as possible will be fit onto the screen, which is
considered to be 78 characters wide; thus, you can calculate the number
of columns that will appear by dividing 78 by <width>.
If a string is too long for the width of a column, the string will
be truncated to fit.
If <indent> is specified, each line will be indented by that number
of spaces.
If <delim> is specified, it will be as an input delimiter only; i.e.,
the delimiter will be used to separate the elements of the list, but
will not appear in the output.
& TABLE()
Function: table(<list>[,<field width>[,<line length>
[,<list delim>[,<field sep>)[,<fill>]]]])
This function returns the elements of the <list delim>-delimited list
<list>, in a tabular format. The only non-optional parameter is <list>,
which is space-delimited by default.
<field width> specifies how wide each column of the table is; it defaults
to 10 characters. <line length> specifies how wide the entire table is;
it defaults to 78 characters. The number of columns is equal to
(line length) / (field width + field sep width).
<field sep> is the output delimiter to be used between columns of the
table; the default is a space. <fill> is the single character used to
pad out a field; the default is a space.
Any word which is too long for the column width is truncated.
Any embedded newlines ('%r') will cause a new table row to be started.
ANSI does not bleed into the padding or field separator, and even if
a word is truncated, the next word will start with the correct ANSI state.
Continued in 'help table2'.
& TABLE2
Examples:
> @va me = apple orange kiwi grape banana strawberry plum pear
> think table(%va)
apple orange kiwi grape banana strawberry plum
pear
> think table(%va,10,33,,|,.)
apple.....|orange....|kiwi......
grape.....|banana....|strawberry
plum......|pear......
> @va me = apple orange kiwi grape banana%rstrawberry plum pear
> table(u(va),10,33,,|,.)
apple.....|orange....|kiwi......
grape.....|banana....
strawberry|plum......|pear......
& TABLES()
Function: tables(<word list>,<field widths>[,<lead string>[,<trail string>
[,<list delim>[,<field sep>[,<fill>]]]]])
This function returns the elements of the <list delim>-delimited list
<word list>, in a tabular format, with the elements left-justified
within each column. The only two non-optional parameters are <word list>
(space-delimited by default), and <field widths>. <field widths> is a
space-delimited list of column widths.
<lead string> is a string to prepend every row of the table with.
<trail string> is a string to append to the end of every row of the
table. If <trail string> is specified, if the number of words in
the list is not evenly divisible by the number of columns, blank
columns will be inserted to make up a full line.
<field sep string> is the output delimiter which will be used between
the columns of the table. The default is a single space. <fill> is the
single character used to pad out a field; the default is a space.
Continued in 'help tables2'.
& TABLES2
Any word which is too long for the column width is truncated.
Any embedded newlines ('%r') will cause a new table row to be started.
ANSI does not bleed into the padding or field separator, and even if
a word is truncated, the next word will start with the correct ANSI state.
Examples:
> @va me = apple orange kiwi grape banana strawberry plum pear
> think tables(%va,3 4 5)
app oran kiwi
gra bana straw
plu pear
> @va me = apple orange kiwi grape banana%rstrawberry plum pear
> think tables(u(va),8 10 6,=+%b,%b+=,,%b||%b,.)
=+ apple... || orange.... || kiwi.. +=
=+ grape... || banana.... || ...... +=
=+ strawber || plum...... || pear.. +=
& RTABLES()
Function: rtables(<word list>,<field widths>[,<lead string>[,<trail string>
[,<list delim>[,<field sep string>[,<fill>]]]]])
This function is identical to tables(), except that the elements of
<word list> are right-justified within each column.
& CTABLES()
Function: ctables(<word list>,<field widths>[,<lead string>[,<trail string>
[,<list delim>[,<field sep string>[,<fill>]]]]])
This function is identical to tables(), except that the elements of
<word list> are centered within each column.
& COMMAND()
Function: command(<command>[,<arg 1>[,<arg 2>]])
This function executes <command> with the given arguments. <command>
is presently limited to @chown, @clone, @destroy, @link, @lock, @name,
@parent, @teleport, @unlink, @unlock, and @wipe.
For example, to get the equivalent of '@name object = new', you
would use '@eval command(@name,object,new)'.
If you have overridden any of these commands via @addcommand, you
will not be able to access that command via this function.
& CREATE()
Function: create(<object name>, <cost>[, <type>])
This creates an object named <object name>, with the specified <cost>.
This object is normally a thing. If the optional <type> parameter is
'r', it will be a room; if it is 'e', an exit; it assumed to default
to 't', thing.
'create(<object>,<cost>,t)' is equivalent to '@create <object>=<cost>'.
'create(<object>,<cost>,r)' is equivalent to '@dig <object>'.
'create(<object>,<cost>,e)' is equivalent to '@open <object>'.
See also: @create, @dig, @open
& CEMIT()
Function: cemit(<channel>, <message>)
Equivalent to '@cemit/noheader <channel> = <message>'. This sends
<message> to the named <channel>, if you own the channel, or have the
Comm_All power or are a Wizard. The channel header is not prepended
to the message.
& COMALIAS()
Function: comalias(<player>)
Returns a list of a player's comsys aliases.
& COMDESC()
Function: comdesc(<channel>)
Returns the description of that channel.
& COMHEADER()
Function: comheader(<channel>)
Returns the header of that channel.
& COMINFO()
Function: cominfo(<player>, <alias>)
Returns the name of the channel that <player> has aliased as <alias>.
& comlist
Command: comlist
Displays all of your comsystem aliases, the channels that they are
associated with, and whether or not you are 'on' (listening) to each
of them. It also shows the titles associated with each alias.
See also: comtitle, addcom, comsys aliases, delcom.
& COMLIST()
Function: comlist([<output delimiter>])
Returns an <output delimiter>-separated list of the names of all channels
in the comsystem. If no delimiter is specified, a space will be used.
& COMOWNER()
Function: comowner(<channel>)
Returns the dbref of the owner of the channel.
& comtitle
Command: comtitle <alias>=<title>
This command allows you to prefix your name on a channel with a title,
or, if the channel if set Spoof, allows you to replace your name on
that channel with a title.
Titles are associated with specific aliases, so if you have multiple
aliases associated with a single channel, you can have different titles
for each alias.
For example:
> comtitle pub=The Great and Powerful
Title set to 'The Great and Powerful' on channel Public.
> pub :waves to everyone.
[Public] The Great and Powerful Foobar waves to everyone.
See also: comlist, addcom, comsys aliases, delcom.
& COMTITLE()
Function: comtitle(<player>, <alias>)
Returns the title that <player> has set in association with that
comsys <alias>.
& CWHO()
Function: cwho(<channel>)
Returns a list of dbrefs, of the players who are connected, and are
on that channel.
& CWHOALL()
Function: cwhoall(<channel>)
Returns a list of dbrefs of everything that is on that channel.
& DECRYPT()
Function: decrypt(<text>,<key>)
Decrypts <text> using <key>. <key> should be the same one used to encrypt
the text, and is case sensitive.
& ENCRYPT()
Function: encrypt(<text>,<key>)
Encrypts <text> using <key>. The text can only be unlocked with <key>, and
<key> is case-sensitive.
& EVAL()
Function: eval(<object>,<attribute)
eval(<string>)
The first form of this function is identical to get_eval(), but
splits the <object> and <attribute> into two arguments, rather
than having an <object>/<attribute> pair. It is provided for
PennMUSH compatibility.
The second form of this function simply evaluates <string>.
& GREP()
& GREPI()
Function: grep(<object>, <attrs>, <string>[, <odelim>])
Function: grepi(<object>, <attrs>, <string>[, <odelim>])
This function returns a list of attributes on <object>, where the
contents of the attribute contain <string>. <attrs> is a wildcard
attribute pattern; to search all attributes on the object, use '*'.
Please note that this function does parse its arguments; thus,
any 'special' characters in <string> need to be escaped out.
grep() does a case-sensitive search. grepi() is not case-sensitive.
& REGREP()
& REGREPI()
Function: regrep(<object>, <attrs>, <regexp>[, <odelim>])
Function: regrepi(<object>, <attrs>, <regexp>[, <odelim>])
This function returns a list of attributes on <object>, where
the contents of the attribute match the regular expression
pattern <regexp>. <attrs> is a wildcard attribute pattern; to
search all attributes on the object, use '*'.
Please note that this function does parse its arguments; thus,
any 'special' characters in <string> need to be escaped out.
regrep() does a case-sensitive search. regrepi() is not
case-sensitive.
& WILDGREP()
Function: wildgrep(<object>, <attrs>, <pattern>[, <odelim>])
This function returns a list of attributes on <object>, where
the contents of the attribute match the wildcard pattern <pattern>.
If you are searching for <pattern> in the middle of the contents,
remember to use '*<pattern>*'; i.e., to search for all attributes
containing the wildcard pattern 'test?_fn', you should specify
'*test?_fn*' as <pattern>. <attrs> is a wildcard attribute pattern;
to search all attributes on the object, use '*'.
Please note that this function does parse its arguments; thus,
any 'special' characters in <string> need to be escaped out.
& HASATTRP()
Function: hasattrp(<object>, <attribute>)
Returns '1' if <object> or its parent(s) has the named <attribute>
(and the attribute can be seen by the invoker), or 0 if not. If the
specified object is invalid, "#-1 NO MATCH" will be returned.
To check only the object itself for the attribute, use hasattr()
instead.
& HASPOWER()
Function: haspower(<object>, <power>)
Returns 1 if <object> has the power <power> set on it, and 0 otherwise.
You must be able to examine <object>.
& HASTYPE()
Function: hastype(<object>, <type>)
Returns 1 if <object> is of type <type>, and 0 otherwise. Valid
types are: ROOM, EXIT, THING, and PLAYER. If an invalid type is
given, the function returns #-1.
& INZONE()
Function: inzone(<object>)
Returns a list of room dbrefs, in the zone defined by <object>.
This function can only be used by Wizards and Royalty.
& LPARENT()
Function: lparent(<object>[, <odelim>])
This function returns the list of dbrefs of the object's "parent
chain", including itself: i.e., its own dbref, the dbref of the
object it is @parent'd to, its parent's parent (grandparent),
and so forth. Note that the function will always return at least one
element, the dbref of the object itself.
This function will not show the parents of objects that the player
cannot examine.
& PLAYMEM()
Function: playmem(<player>)
Returns the sum total of the size, in bytes, of all objects in the
database that are owned by <player> (equivalent to doing an objmem()
on everything that player owns). You must be a Wizard, or have the
Search power, in order to use this on another player.
& PMATCH()
Function: pmatch(<player>)
Given the partial name of a player, it returns that player's dbref
number. This partial name completion works identically to the partial
name completion of the "page" command - i.e. it first attempts to match
the normal names of all players (connected or not), and if that fails,
it tries to match the partial names of connected players. If no player
is matched, it returns "#-1". If more than one match is possible for
a partial name, it returns "#-2".
pmatch() will also accept *<player> or #<dbref>. If given a non-player
dbref, pmatch() will return #-1.
& PFIND()
Function: pfind(<object>)
If <object> is a dbref, if the dbref is valid, that dbref will be returned.
If the dbref is not valid, #-1 will be returned.
If given the name of a player, the player name will be looked up. This
includes checking the connected players that the caller can see on the
WHO list, for partial matches to the name. If the entire player name
is found, or a unique partial match is found, the dbref of that player
will be returned. Otherwise, #-1 NO MATCH will be returned.
& STRCAT()
Function: strcat(<string1>, <string2>, ..., <stringN>)
Concatenates between two and ten strings together, with no spaces
between them. This function is provided for PennMUSH compatibility.
Example:
> say [strcat(foo,bar,baz)]
You say, "foobarbaz"
& STRTRUNC()
Function: strtrunc(<string>, <number>)
This function truncates <string> to a length of <number> characters.
If <number> is greater than the length of <string>, this simply
returns <string>.
See also: mid(), delete(), left(), right()
& VALID()
Function: valid(<category>,<string>)
This function is provided for PennMUSH compatibility, along with the
PennMUSH help entry:
The valid() function checks to see if <string> is a valid member of
<category>, and returns 1 if it is, 0 if not, and #-1 if an
invalid category is used.
The categories are:
name Test for a valid object name.
attrname Test for a valid attribute name.
playername Test for a valid player name that can be set with
@name or @alias.
Examples:
> think valid(name,Foobar)
1
> think valid(attrname,Foo bar)
0
& XGET()
Function: xget(<object>, <attribute>)
This function is identical to get(), except that it breaks <object>
and <attribute> into two separate arguments, rather than having
<object>/<attribute>.
This function is provided for PennMUSH compatibility.
& ZFUN()
Undocumented.
& ZONE()
Function: zone(<object>)
Returns the dbref of <object>'s zone (the dbref of the master object
which defines the zone).
& ZWHO()
Function: zwho(<object>)
Returns a list of the dbrefs of players who are in the zone defined
by <object>. This function can only be used by Wizards and Royalty.
& CHOMP()
Function: chomp(<string>)
If <string> ends with a carriage-return/newline ('%r'), that trailing
carriage-return/newline will be chopped off. This is particularly useful
for nibbling extra newlines off piped ('%|') output.
& FORCE()
Function: force(<object>, <action>)
This side-effect function behaves identically to the command
'@force <object>=<action>'.
Note that <action> is threaded normally onto the command queue, and
is thus not instantaneously executed.
& NULL()
Function: null(<string>)
This function returns an empty string, effectively "eating" <string>.
<string> is still evaluated, though. This is useful if you're doing
something involving side-effects and want to obliterate that output.
See also: @@()
& @@()
Function: @@(<string>)
This function returns an empty string, effectively "eating" <string>.
<string> is not evaluated. This is useful for embedding comments
in code.
See also: null()
& TRIGGER()
Function: trigger(<object>/<attribute>,<arg 0>,<arg 1>,...,<arg N>)
This side-effect function behaves identically to the command
'@trigger <object>/<attribute>=<arg 0>,<arg 1>,...<arg N>'
Note that the triggered actions are threaded normally onto the command
queue, and are thus not instantaneously executed.
& WAIT()
Function: wait(<timer>,<command>)
This side-effect function behaves identically to the command
'@wait <timer>=<command>'. See 'help @wait' for the possible forms
that <timer> can take.
& WHILE()
while([<uobj>/]<uattr>,[<cobj>/]<cattr>,<list>,<str>[,<delim>[,<output d>]])
This function evaluates the elements of <list>, until a termination
condition is reached or the end of the list is reached.
[<uobj>/]<uattr> is an attribute or object/attribute pair, like the first
argument of map(). The <list> is passed to that function element-by-element
(based on the input <delim> delimiter) as %0, and the position of the
element as %1, just as if map() were being called, and the output is
returned <output d>-delimited, again just as if map() were being called.
However, for each element, after that evaluation is done, a second
evaluation is done, to check a "termination value". [<cobj>/]<cattr>
is an attribute or object/attribute pair, again like map(), and the
same list elements are passed to that function as %0 (and the position
of the elements as %1). However, the result of this evaluation is not
kept; instead, it is compared to <str>, and if it matches exactly
(case-sensitive, no wildcards), then no further elements of the list
are processed.
Continued in 'help while2'.
& WHILE2
If the contents of [<uobj>/]<uattr> and [<cobj>/]<cattr> are the
same, the element is not evaluated twice; the result of the first
evaluation is directly compared against <str>. (Note that the
two object/attributes don't have to be the same -- just their
contents need to be the same, since this function treats the
pair like map(), not like u().)
Examples:
> &EVAL_FN me = [reverse(%0)]
> &COND_FN me = [strlen(%0)]
> say [while(EVAL_FN,COND_FN,foo bar meep flibble baz,4)]
You say, "oof rab peem"
> SAY [while(EVAL_FN,COND_FN,foo|bar|meep|flibble|baz,4,|,-)]
You say, "oof-rab-peem"
& UNTIL()
Function: until([<uobj>/]<uattr>, [<cobj>/]<cattr>,
<list 1>[, <list 2>[, <list N>]],
<regexp>, <delim>, <output delim>)
This function evaluates the elements of one or more lists, until the
result of an evaluation matches a regular expression, or the end of
the longest list is reached (shorter lists are padded out with nulls).
It is similar to while(), except that it can take more than one list,
the terminating condition is a regular expression rather than a
case-insensitive string comparison, and the delimiter and output
delimiter are mandatory.
[<uobj>/]<uattr> is an attribute or object/attribute pair. The lists
are passed element-by-element (based on the input <delim> delimiter)
as %0, %1, %2, etc., just as if mix() were being called, and the
output is returned delimited by <output delim>.
Continued in 'help until2'.
& UNTIL2
For each element, after that evaluation is done, a second evaluation
is done, to check a "termination value". [<cobj>/]<cattr> is an
attribute or object/attribute pair, again like mix(), and the
same list elements are passed to that function as %0, %1, %2, etc.
However, the result of this evaluation is not kept; instead, it is
compared to the regular expression <regexp>, and if true, then
no further elements of the list are processed.
If the contents of [<uobj>/]<uattr> and [<cobj>/]<cattr> are the
same, the element is not evaluated twice; the result of the first
evaluation is directly matched against <regexp>. (Note that the
two object/attributes don't have to be the same -- just their
contents need to be the same, since this function treats the
pair like map(), not like u().)
Example:
> &EVAL_FN me = [add(%0,%1)]
> &COND_FN me = [sub(%1,%0)]
> say [until(EVAL_FN,COND_FN,0 1 2 3,4 2 1 0,-,,|)]
You say, "4|3|3"
& HEARS()
& KNOWS()
& MOVES()
Functions: hears(<object>, <actor>)
knows(<object>, <actor>)
moves(<object>, <actor))
These functions return 1 if <object> can detect <actor> doing something,
and 0 if not. If either <object> or <actor> is not a valid object, 0 is
returned.
hears(): Can <object> hear <actor> when <actor> speaks?
If <object> is set PRESENCE, <actor> must pass its HearsLock.
If <actor> is set PRESENCE, <object> must pass its HeardLock.
knows(): Can <object> see <actor>?
If <object> is set PRESENCE, <actor> must pass its KnowsLock.
If <actor> is set PRESENCE, <object> must pass its KnownLock.
moves(): Can <object> notice <actor> moving?
If <object> is set PRESENCE, <actor> must pass its MovesLock.
If <actor> is set PRESENCE, <object> must pass its MovedLock.
See also: PRESENCE
& PUSH()
Function: push([<object>,]<data>)
Pushes an item (the arbitrary string <data>) onto the top of an
object's stack. If <object> is not specified, the calling object is
assumed. An empty string is returned.
For example, if the current stack is (top to bottom) 4, 3, 2, 1,
and a 'push(5)' is used, the new stack becomes 5, 4, 3, 2, 1.
See also: STACK FUNCTIONS.
& DUP()
Function: dup([<object>,][<position>])
Duplicates an item from <object>'s stack, placing it on top of the
stack. If <object> is not specified, the calling object is assumed.
If <position> is not specified, the top item is assumed. Positions
are counted from top to bottom, starting from zero.
Example:
> say [lstack()]
You say, "5 4 3 2 1"
> say [dup()][lstack()]
You say, "5 5 4 3 2 1"
> say [dup(me,4)]
You say, "2 5 5 4 3 2 1"
See also: STACK FUNCTIONS.
& SWAP()
Function: swap([<object>])
Swaps the top two items on <object>'s stack. If <object> is not
specified, the calling object is assumed. The stack must have
at least two items on it. This function returns an empty string.
Example:
> say [lstack()]
You say, "4 3 2 1"
> say [swap()]
You say, "3 4 2 1"
See also: STACK FUNCTIONS.
& POP()
Function: pop([<object>,]<position>)
Pulls an item from <object>'s stack. If <object> is not specified, the
calling object is assumed. If <position> is not specified, the top item
is popped off. Otherwise, the item in <position> (counting down from the
top item being position 0) is pulled. The function returns that item.
Example:
> say [lstack()]
You say, "6 5 4 3 2 1"
> say [pop()]
You say, "6"
> say [lstack()]
You say, "5 4 3 2 1"
> say [pop(me,3)]
You say, "2"
> say [lstack()]
You say, "5 4 3 1"
See also: popn(), STACK FUNCTIONS.
& POPN()
Function: popn(<object>,<position>,<N items>[,<delim>])
Pulls one or more items from <object>'s stack, returning the value
of those items in a <delim>-separated list. If <delim> is not
specified, a space is assumed.
See also: pop(), STACK FUNCTIONS.
& TOSS()
Function: toss([<object>,]<position>)
Silently removes an item from <object>'s stack. Essentially, it behaves
identically to pop(), except that it always returns an empty string,
instead of the value of that item on the stack.
Example:
> say [lstack()]
You say, "6 5 4 3 2 1"
> say [toss()]
You say, ""
> say [lstack()]
You say, "5 4 3 2 1"
> say [toss(me,3)]
You say, ""
> say [lstack()]
You say, "5 4 3 1"
& EMPTY()
Function: empty([<object>])
Empties the stack on <object>, clearing all items from it. If <object>
is not specified, the calling object is assumed. This function returns
an empty string.
See also: STACK FUNCTIONS.
& LSTACK()
Function: lstack([<object>][,<delim>])
This function returns the items on <object>'s stack in the form of
a <delim>-separated list. The items are returned in top-to-bottom
order. If <object> is not specified, the calling object is assumed.
If <delim> is not specified, a space is assumed. This function does
not modify the stack.
See also: STACK FUNCTIONS.
& ITEMS()
Function: items([<object>])
This function returns the number of items in <object>'s stack. If
<object> is not specified, the calling object is assumed.
See also: STACK FUNCTIONS.
& PEEK()
Function: peek([<object>][,<position>])
This function returns the value of an item on <object>'s stack.
If <object> is not specified, the calling object is assumed. If
<position> is not specified, the top item is assumed. Positions
are counted down from the top, with the top item being position
zero; i.e., the second item on the stack is position 1, and so
forth. This function does not modify the stack.
Example:
> say [lstack()] -- [peek()]
You say, "5 4 3 2 1 -- 5"
> say [peek(me,3)]
You say, "2"
> say [lstack(Object)] -- [peek(Object)]
You say, "c b a -- c"
See also: STACK FUNCTIONS.
& @power
Command: @power <object>=[!]<power>
This is a command that allows the granting of special powers to objects of
any type.
See also: powers list
& powers list
announce Can use the @wall command.
attr_read Can read attributes that have the 'hidden' flag.
attr_write Can write to attributes that have the 'wizard' flag.
boot Can use the @boot command.
builder Can build, if the builder power is enabled.
chown_anything Can @chown anything to anyone.
cloak Can be DARK and unseen, even if a listening object.
comm_all Like a wizard with respect to channels.
control_all Can modify any object in the database. (God-set only.)
expanded_who Sees the wizard-formatted WHO, and SESSION commands.
find_unfindable Can locate unfindable people.
free_money Unlimited money.
free_quota Unlimited quota.
guest Is this a guest character?
halt Can @halt anything, and @halt/all.
hide Can set themselves DARK.
idle No idle timeout.
link_any_home Can @link an object to any home.
link_to_anything Can @link an exit to any (non-variable) destination.
link_variable Can @link an exit to "variable".
{ 'help powers list2' for more }
& powers list2
long_fingers Can get, look, whisper, etc from a distance.
no_destroy Cannot be @toad'ed.
open_anywhere Can @open an exit from any location.
poll Can set the @poll.
prog Can use @program on players other than themself.
quota Can set quotas and view anyone's quota.
search Can @search anyone.
see_all Can examine and see attributes like a wizard.
see_hidden Can see hidden (DARK) players on WHO, etc.
see_queue Can @ps/all or @ps any player.
stat_any Can @stat any player.
steal_money Can give negative money.
tel_anywhere Can teleport anywhere.
tel_anything Can teleport anything (includes tel_anywhere)
unkillable Cannot be killed with the 'kill' command.
use_sql Can call the SQL() function. (God-set only.)
watch_logins Can set or reset the WATCHER flag on themselves.
See also: @power
& comsys
Commands for the MUSH comsystem:
addcom allcom comlist comtitle clearcom
delcom
@cboot @ccreate @cdestroy @cemit @channel
@clist @cwho
See 'help comsys intro' for an introduction to the comsys.
See 'help comsys aliases' for details on how to use comsys aliases.
See 'help <name of command>' for details on specific commands.
& comsys intro
Topic: Comsys Intro
Depending on the configuration of the MUSH, there may be public and
private chat channels available. Normally, new players automatically
join the "Public" channel upon creation (default alias 'pub'), while
guest characters join the "Guests" channel when they connect (default
alias 'g').
Each player may associate a given channel with one or more aliases.
Typically, one talks on a channel using '<alias> <message>'. For
example, the default alias for the Public channel is normally 'pub',
allowing you to type 'pub Hello.' to say "Hello." to everyone on
the Public channel. However, if you want your alias to be something
else, you can change it.
Channels can be used by both players and things, though there can be
restrictions placed on who can join, receive, and transmit on a channel.
These restrictions can be imposed by object type, or they can be locks.
Continued in 'help comsys intro2'.
& comsys intro2
The comsys commands you will find most useful are the following:
'@clist' -- Lists all available channels.
'comlist' -- Lists all the channels you are on, and their aliases.
Channel names and aliases are case-sensitive. You
can have more than one alias for a channel.
'<alias> who' -- Lists the people on the channel associated with <alias>.
For example, if your Public channel alias is 'pub', then
'pub who' will list everyone on the Public channel.
'<alias> on' -- Begin listening to the channel associated with <alias>.
'<alias> off' -- Stop listening to the channel associated with <alias>.
'<alias> <msg>' -- Say a message to the channel associated with <alias>.
The ':' and ';' pose-tokens can be used.
You can add an alias using 'addcom <alias>=<channel>'; if this is the
first alias you have for that channel, you will automatically join that
channel. You can remove an alias using 'delcom <alias>'; if this is the
only alias you have for that channel, you will automatically leave it.
Continued in 'help comsys intro3'.
& comsys intro3
For example:
> pub off
You leave channel Public.
> pub on
[Public] Foobar has joined this channel.
> pub who
-- Players --
Foobar(#23PWc)
Wizard(#1PWc)
-- Objects --
-- Public --
> pub Hello world!
[Public] Foobar says, "Hello world!"
See the individual help entries for comsys commands for details.
& @cboot
Command: @cboot[/quiet] <channel>=<object>
This command is restricted to Wizards, those with the Comm_All power,
and the owner of <channel>. It removes <object> from <channel>,
deleting all of <object>'s alias for <channel>. <object> can be
specified as a dbref, *<player>, or the name of a nearby object.
The object will be notified who booted it off the channel. Other
people on the channel will also be notified that you have booted
the object off the channel, unless the /quiet switch is specified,
in which case, it will be treated like the object had simply left
the channel.
& addcom
Command: addcom <alias>=<channel>[,<title>]
This command adds <alias> as an association for <channel>; if you
specify <title>, messages to that channel using that alias will
prefix <title> to your name. You can have multiple aliases for a
channel. You can have different titles for each aliases.
If this is your first alias for <channel>, you will join <channel>.
Note that the on/off status of <channel> is not affected by adding
additional aliases.
See also: delcom, comlist, comtitle, comsys aliases.
& comsys aliases
Command: <channel alias> <on|off|who|message|:pose|;pose>
If you select 'on', you will begin listening to messages on the channel
associated with <alias>.
If you select 'off', you will stop listening to messages on the channel
associated with <alias>. However, that alias remains active and useful
for other comsystem commands.
If you select 'who', you will be shown a list of players and objects
currently active on the channel associated with <alias>.
You may send a message over the channel with <alias> <text>, where <text>
is the message to be sent; you can pose on a channel with <alias> :<text>
or <alias> ;<text>
See also: allcom, comlist, addcom, delcom.
& allcom
Command: allcom <on|off|who>
This works like using a single alias, except it does an action for every
alias you have. You can turn every alias on, or off, or see who is on
every channel you subscribe to.
See also: comsys aliases, comtitle, delcom, addcom.
& clearcom
Command: clearcom
Removes all your aliases for channels. You should be extremely careful
about this command, as it will wipe out all of your channel information.
See also: addcom, delcom.
& delcom
Command: delcom <alias>
Deletes <alias> from your list of channel aliases. If <alias> was the only
alias you had for a certain channel, you will leave that channel, and
will need to addcom a new alias for it, if you need to use it in the
future.
See also: addcom, comlist, clearcom.
& @ccreate
Command: @ccreate <channel name>
Creates a channel with default settings. Only Wizards and those with
the Comm_All power can create a channel.
See also: @cdestroy, @clist, @channel.
& @cdestroy
Command: @cdestroy <channel>
Deletes <channel> permanently from the comsystem database. This removes
all aliases that are associated with <channel>.
See also: @clist, @ccreate, @channel.
& @clist
Command: @clist[/<switch>] [<channel name>]
When given an argument, if you are a Wizard, have the Comm_All power,
or the owner of the channel, this will display the flag information,
locks, and description of the channel.
Without any switches or arguments, this command will display the list of
channels, together with the names of their owners, and their descriptions.
With the /header switch, this command will display the list of
channels, together with the names of their owners, and their headers.
With the /full switch, this command will display the list of channels,
together with some more detailed information about them. The channels
displayed are limited to Public ones, unless you are a Wizard or have
the Comm_All power.
See also: @ccreate, @cdestroy, @channel.
& @cwho
Command: @cwho[/all] <channel>
If you are a Wizard, have the Comm_All power, or own <channel>, this
command displays a list of all objects and connected players on the
channel. If the /all switch is specified, all objects and players
are displayed. Note that the connect status of hidden players is
protected.
See also: @clist.
& @channel
@channel/header <channel>=<header>
@channel/desc <channel=<description>
@channel/owner <channel>=<new owner>
@channel/charge <channel>=<charge>
@channel/set <channel>=[!]<channel flag>
@channel/lock/<join | transmit | receive> <channel>=<lock>
This command allows a Wizard, someone with the Comm_All power, or
the owner of the channel, to manipulate the channel settings.
The channel header is the prefix that is prepended to channel messages.
It defaults to '[<name of channel>]'. <header> can be any string of
text of reasonable length, and it can contain ANSI characters.
Similarly, <description> is any string of text; if none is specified,
the channel's description is cleared.
Continued in 'help @channel2'.
& @channel2
Changing the channel owner is straightforward; <new owner> is specified
as a dbref or player name.
Changing the cost of sending a message on the channel is also
straightforward; <charge> is the cost in MUSH money. Every time
someone sends a message on the channel, that person pays <charge>
to the channel owner.
Continued in 'help @channel3'.
& @channel3
The channel flags available are:
public -- All players see this on a @clist.
loud -- People on the channel see when someone on the channel
connects or disconnects.
spoof -- Comtitles replace names, rather than prepending them.
p_join -- Any player can join this channel.
p_transmit -- Any player can transmit on this channel.
p_receive -- Any player can receive on this channel.
o_join -- Any object can join this channel.
o_transmit -- Any object can transmit on this channel.
o_receive -- Any object can receive on this channel.
The available channel locks are join, transmit, and receive. They
are specified like regular object locks. To unlock, simply specify
a blank string for <lock>. Channel locks are evaluated with respect
to the channel's owner.
Channel flags always override channel locks. In other words, if a
channel has a p_join flag, the join lock is never checked for players.
& @cemit
Command: @cemit[/noheader] <channel>=<message>
This command allows a Wizard, someone with the Comm_All power, or
the owner of <channel>, to send <message> to everything listening
to <channel>. If the /noheader switch is specified, then the channel
name is not prepended to the message.
& COMSYS FUNCTIONS
Topic: Comsys Functions
cemit() comalias() comdesc() comheader()
cominfo() comlist() comowner() comtitle()
cwho() cwhoall()
These functions are only enabled if the comsys module is enabled.
Information about a channel is generally only available to those with
the Comm_All power, Wizards, or the owner of the channel. Channel names
must be typed in full, and are case-sensitive.
Information about a player's comsys options is generally only available
if you control the player, or have the Comm_All power. For comsys
functions, players should be referred to by name (or *name) or
by dbref. The partial name of a connected player can be matched.
& @malias
Command: @malias
This allows you to generate and maintain mailing lists with the mail
system. All mail aliases start with '*', and are case-sensitive. (*dir is
different than *Dir). There are two kinds of mail aliases, Personnal
and Global. Global mailing lists are owned and maintained by the god (#1)
char and are available for anyone to use. Generally there will be
*Wizards, *Admin, *Roleplay, and things of that nature. Personal mailing
aliases are mailing lists that you have defined with the @malias commad.
Currently there is no limit to the number of people you can have on a
mailing alias.
To begin sending mail to a mailing list, use @mail *<alias>=subject.
Usage:
@malias Displays a list of all mail aliases.
@malias *<alias> Displays a list of people on that alias.
@malias *<alias>=<list> Creates that mailing list, using <list>.
Continued in 'help @malias2'.
& @malias2
You can add, remove, rename, chown, redescribe, and delete mailing lists
with a switch.
@malias/remove *<alias>=<player> Removes <player> from *<alias>.
@malias/desc *<alias>=<description> Changes the description for *<alias>.
@malias/add *<alias>=<player> Adds <player> to *<alias>.
@malias/rename *<alias>=<name> Renames that alias. Names must always
begin with '*'.
@malias/delete *<alias> Deletes <alias>.
@malias/chown *<alias>=<player> Changes the owner of <alias> to
<player>.
Wizards can use all of the malias commands on any mail alias. Instead of
trying to figure out different mailing lists with the same name, wizards
may use #<MALIAS NUMBER> instead of *alias in regards to the command.
Remember that the alias commands will only recognize aliases owned by #1,
owned by you, or by number.
@malias/list When invoked by a wizard, it will
list all mailing aliases currently
defined by their number.
& @mail
@mail[/<switches>] <player-list> = <subject>
@mail[/<switches>] [<msg-list> [= <target>]]
@mail invokes the built-in MUSH mailer, which allows players to send
and receive mail. Pronoun/function substitution is performed on
any messages you may try to send.
See 'help mail-players' for an explanation of what constitutes a
valid player list.
See 'help mail-messages' for an explanation of what constitutes a
valid message list.
See the following topics for more details:
mail-sending mail-reading mail-folders mail-other
mail-admin @malias mail-reviewing mail-examples
& mail-players
Topic: Mail Player Lists
A <player-list> is a space-separated list of recipients, which may be:
Player names (names with spaces in them should be put in double
quotes, ex: "Foo Bar")
Player dbref #'s
Message numbers to be replied to.
A mix of the above, and mail aliases (see @malias)
& mail-messages
Topic: Mail Message Lists
A <msg-list> is one of the following:
A single msg # (ex: 3)
A message range (ex: 2-5, -7, 3-)
A sender (ex: *lauren)
An age of mail in days (ex: ~3 (exactly 3), <2, >1)
"days" here means 24-hour periods from the current time.
One of the following: "read", "unread", "cleared", "tagged", "urgent"
For certain commands, "all".
& mail-reviewing
@mail/review [<player> | all]
Reviews the messages you have sent to <player>. With no
argument, or "all", lists all messages you have sent.
@mail/review [<player> | all]=<msglist>
Reads the messages you have sent to <player>. With no
player name, or "all", reads selected messages from among
all you have sent.
@mail/retract <player>=<msglist>
Retracts (deletes) unread messages you have sent to <player>.
& mail-reading
@mail <msg #>
@mail/read <msg-list>
This displays messages which match the msg# or msg-list from
your current folder.
@mail
@mail <msg-list, but not a single msg #>
This gives a brief list of all mail in the current folder,
with sender name, a list of receiving players, subject, and
message status.
@mail/list [<msg-list>]
This gives the same list, but with time sent instead of subject.
The status field is a set of characters (ex: NC-UF+) which mean:
N = New (unread) message
C = Cleared message
U = Urgent message
F = Forwarded message
+ = Tagged message
The opposites of these (read messages, etc.) are indicated with a
'-' in the status field in that position.
& mail-sending
@mail/quick <player-list>/<subject> = <message>
Sends <message> to the list of players.
@mail[/switch] <player-list> = <subject>
This begins a message to all players in <player-list>.
-<text> adds text to the message in progress, for example
-This is a test
would add the text 'This is a test' to the end of your @mail
message, likewise, ~<text> prepends the text.
@mail/send
This sends the message that is currently in progress.
-- is the equivalent of @mail/send. @mail/urgent sends
the message as urgent, and should not be used often.
@mail/abort
This aborts the message currently in progress, allowing you
to start a new one.
Continued in 'help mail-sending2'.
& mail-sending2
@mail/to <player-list>
@mail/cc [<player-list>]
@mail/bcc [<player-list>]
@mail now supports three separate address lists for a mail, the
standard To list for recipients, a Cc list for carbon-copying,
and a Bcc list for blind carbon-copying. These commands set each
of the three address lists; they operate by replacing the list,
and do _not_ add onto the existing lists. @mail/cc and @mail/bcc
with no argument will empty the corresponding list.
@mail/proof
This shows you the message that is currently in progress, as
it would be read by whomever received it.
@mail/edit <old text> = <new text>
Like @edit, but edits the message in process.
Continued in 'help mail-sending3'.
& mail-sending3
@mail/fwd <msg> = <player-list>
This sends a copy of <msg> to all the players in <player-list>.
The copy will appear to have been sent by you (not the original
sender), and its status will be "Forwarded". Note that this places
the message to be forwarded into your mail buffer, where you can
edit it with @mail/edit, add text with '-', or prepend text with
'~'. You have to use '--' or @mail/send to send the message.
@mail/reply[/quote] <msg>
This sends a reply to the person who sent you <msg>. The
subject line will be 'Re: <original subject line>'. If you
specify the /quote switch, the original message will be quoted
back at the beginning of your mail message.
@mail/replyall[/quote] <msg>
This sends a reply to the person who sent you <msg>, as well
as all other recipients of <msg>. The subject line will be
'Re: <original subject line>'. If you specify the /quote switch,
the original message will be quoted back at the beginning of
your mail message.
& mail-other
@mail/clear [<msg-list | all>]
@mail/unclear [<msg-list> | all>]
These commands mark mail in the current folder as cleared or uncleared.
Mail marked for clearing is deleted when you disconnect, or
if you use @mail/purge. If no msg-list is specified, all
mail in your current folder is cleared. If "all" is given instead
of a msg-list, all mail in *all* folders is cleared/uncleared.
@mail/purge
Actually deletes all messages marked for clearing with @mail/clear.
This is done automatically when you log out.
@mail/tag [<msg-list | all>]
@mail/untag [<msg-list> | all>]
These commands tag or untag mail in the current folder.
Tagged mail can be later acted on en masse by using "tagged" as
the msg-list for other commands (which does *not* untag them
afterward). If no msg-list is specified, all messages in the
current folder are tagged/untagged. If "all" is given as the
msg-list, all mail in *all* folders is tagged/untagged.
(Ex: To clear all mail from Lauren and Crusade, @mail/tag *lauren,
@mail/tag *crusade, @mail/clear tagged, @mail/untag all).
{ 'help mail-other2' for more }
& mail-other2
@mail/safe [<msg-list> | all>]
This command marks a message as being safe from mail expiration. It
should be used sparingly and only for very imporatant messages.
& mail-folders
The MUSH mail system allows each player 16 folders, numbered from
0 to 15. Mail can only be in 1 folder at a time. Folder 0 is
the "inbox" where new mail is received. Most @mail commands
operate on only the current folder.
@mail/folder
This commands lists all folders which contain mail, telling
how many messages are in each, and what the current folder is.
@mail/folder <folder#|foldername>
This command sets your current folder to <folder#>.
@mail/folder <folder#> = <foldername>
This command gives <folder#> a name.
@mail/file <msg-list>=<folder#>
This command moves all messages in msg-list from the current
folder to a new folder, <folder#>.
& mail-admin
The @mail command can also take the following switches:
@mail/stats [<player>] -- Basic mail statistics.
@mail/dstats [<player>] -- Also provides read/unread count.
@mail/fstats [<player>] -- Does all that, plus gives space usage.
@mail/debug <action>[=<player>]
@mail/nuke
Only wizards may stats players other than themselves. The mail statistics
commands are computationally expensive, and thus are subject to "daytime"
restrictions. They also cost the same as a @find (100 credits).
The /debug switch does sanity checking on the mail database, and may only
be used by a wizard. "@mail/debug sanity" just does the check; the command
"@mail/debug clear=<player name or dbref number>" wipes mail for an object.
"@mail/debug fix" attempts to repair problems noted in the sanity check.
The /nuke switch destroys the post office, erasing all @mail everywhere.
It may only be used by a wizard.
Also, admin may set the @amail attrib on their char. When somebody sends
you mail, it will trigger that attrib if it exists.
& mail-examples
Here is an example of mailing a player, where is the player will be "bob",
and sending the mail.
> @mail bob = The MUSH - This is the Subject line.
Sending mail to player 'Bob'
> -Hi bob. - This is where you will enter the body
of the message.
Text Added.
> @send - Basically, sends the @mail.
MAIL: You sent your message to 'Bob'.
& @amail
Command: @amail <player> = <command-list>
Attribute: Amail
Sets the actions to be taken after a player receives @mail. This should
*never* @mail another player, as this could cause an infinite loop.
Example: @amail me=@mail/file [mail()]=2
This would place all incoming messages in folder #2.
See also: @mailsucc, @signature, @mail.
& @mailsucc
Command: @mailsucc <player> = <message>
Attribute: Mailsucc
Sets a message to be displayed to the sender whenever <player> receives
mail.
Example: @mailsucc me=Thanks for the mail.
See also: @amail, @signature, @mail.
& @signature
Command: @signature <player> = <message>
Attribute: Signature
Sets a message to be appended to ever @mail message you send. It is
appended directly at the end of the message, so if you wish to start the
signature on a new line you should begin it with a %r.
Example: @signature me=%rThis is a mail signature. (Note: You might want
to include the %r at the front of the signature, other wise it will be
combined with the @mail message.)
See also: @mailsucc, @amail, @mail.
& MAIL()
mail(<mail message #>)
mail(<player name>)
mail(<player>, <mail message #>)
mail()
The first form returns a message corresponding to that mail message
number in your MUSH mailbox. This function can be used to forward
mail, or as a way to simply transfer mail messages to attributes
on an object.
The second form returns three numbers, corresponding to the number of
read, unread, and cleared messages <player> has.
The third form returns <player>'s <mail message #>. It works like
the first form except it applies to another player.
The last form returns the number of messages the evaluating player has.
Only wizards can use the second and third forms of the function
on other players.
& MAILFROM()
Function: mailfrom(<msg #>)
Returns the dbref # of the player who sent you <msg #>. Wizards may
specify mailfrom(<player>,<msg #>).
& STRUCTURE()
Function: structure(<struct>,<names>,<types>[,<defaults>[,<sep>[,<delim>]]])
This function creates a structure definition called <structure>. <names>
is a space-separated list of component names. <types> is a space-separated
list of data types. <defaults> is a <sep>-separated list of the default
values for each of the components. <delim> is the default delimiter
used by load() and unload().
The valid data types are 'a' ("any", untyped), 'c' (single character),
'd' (dbref), 'i' (integer), 'f' (floating-point number), and 's' (string
without any whitespace in it).
The function returns 0 on failure and 1 on success. You cannot re-define
an already-defined structure; you must unstructure() it first. Typically,
you will want to put your structure definitions in a @startup, rather than
declaring them each time they are needed within a code block.
Example: 'structure(grid,xcoord ycoord,i i,0 0)' defines a structure named
"grid" with two integer components, xcoord and ycoord, which both have a
default value of 0.
& UNSTRUCTURE()
Function: unstructure(<struct>)
This function removes the structure definition <struct>, and returns
1 on success and 0 on failure. There cannot be any instances of
<struct> currently in existence.
See also: STRUCTURE FUNCTIONS
& CONSTRUCT()
Function: construct(<instance>,<struct>[,<names>,<values>[,<delim>]])
This function creates an instance of <struct> named <instance>. If
<names> and <values> are specified, they are used instead of the
default values for the named components; any components not specified
in <names> are initialized to their default values. <names> is a
space-separated list. <values> is a <delim>-separated list (or
space-separated, if <delim> is not specified).
The function returns 1 on success and 0 on failure. You cannot re-create
an instance that already exists; you must destruct() it first. Make sure
to always destruct() instances as soon as they're not needed!
Example:
> @eval [structure(grid,xcoord ycoord zcoord,i i i,0 0 0)]
> @eval [construct(blank,grid)]
> say [unload(blank)]
You say, "0 0 0"
> @eval [construct(space,grid,xcoord ycoord,2|5,|)]
> say [unload(space)]
You say, "2 5 0"
& DESTRUCT()
Function: destruct(<instance>)
Removes the named <instance> of a structure. You should always clean up
unneeded instances in this way, as soon as they are no longer needed
(i.e., after the code block that uses them).
This function returns 1 on success and 0 on failure.
See also: STRUCTURE FUNCTIONS
& LOAD()
Function: load(<instance>,<struct>,<raw text>[,<delim>])
This function creates a new instance of <struct> named <instance>.
It loads <raw text> into the components of the structure, where
<raw text> is a <delim>-separated list; if <delim> is not specified,
the default delimiter for that structure will be used. The function
returns 1 on success and 0 on failure. As with construct(), you cannot
re-create an instance that already exists; you must destruct() it first.
Example:
> @eval [structure(grid,xcoord ycoord zcoord,i i i,0 0 0)]
> @eval [load(space,grid,3 4 5)]
> say [z(space,ycoord)]
You say, "4"
See also: STRUCTURE FUNCTIONS
& UNLOAD()
Function: unload(<instance>[,<delim>])
This function prints the values of the components in <instance>; the
list will be <delim>-separated if <delim> is specified, or separated
by the default delimiter for that structure. If <instance> does not
exist, an empty string will be returned.
Example:
> @eval [structure(grid,xcoord ycoord zcoord,i i i,0 0 0)]
> @eval [load(space,grid,3 4 5)]
> say [unload(space,|)]
You say, "3|4|5"
See also: STRUCTURE FUNCTIONS
& READ()
Function: read(<obj>/<attr>,<instance>,<struct>)
Similar to load(), this function creates a new instance of <struct>
named <instance>. However, this function loads text from <obj>/<attr>
(assuming that the player has permissions to read it), and assumes that
the fields within that attribute's data are separated by the invisible
structure delimiter, as would be true if the attribute had been written
via the write() function. The function returns 1 on success and
0 on failure. As with construct(), you cannot re-create an instance
that already exists; you must destruct it first().
See also: STRUCTURE FUNCTIONS
& WRITE()
Function: write(<obj>/<attr>,<instance>)
This function writes the value of the data held within <instance>
to <obj>/<attr> (assuming the player can set that attribute),
with the fields delimited by the invisible structure delimiter.
If it is successful, an empty string will be returned; otherwise,
some form of error message beginning with #-1 will be returned.
This function is very useful if the data within a structure contains
arbitrary characters that might otherwise be used for delimiters,
such as the '|' symbol. The data can be read back in via the read()
function, or retrieved in some other form via the delimit() function.
Attributes containing this kind of data are marked with the 'structure'
flag; when examined, the data fields are normally delimited by a
linefeed (but this can be changed via the conf parameter
'structure_delimiter_string'). These attributes are not readable
via other means.
See also: STRUCTURE FUNCTIONS
& DELIMIT()
Function: delimit(<obj>/<attr>,<separator string>[,<input delim>])
This function is intended to be used to take structure data written
to an attribute with an invisible delimiter, and output that data
with the fields delimited by an arbitrary <separator string>.
However, it can also be used to take an arbitrary <input delim>-delimited
list from an attribute, and print out that list delimited by the
<separator string>.
Example:
> @va me=apple|banana|orange
> say [delimit(me/va,---,|)]
You say, "apple---banana---orange"
> @eval [structure(grid,xcoord ycoord zcoord,i i i,0 0 0)]
> @eval [load(space,grid,3 4 5)]
> @eval [write(me/coords,space)]
> say [delimit(me/coords,_)]
You say, "3_4_5"
See also: STRUCTURE FUNCTIONS
& Z()
Function: z(<instance>,<component>)
This function retrieves the value of <component> in <instance>. If
<instance> or <component> do not exist, this function returns nothing.
Example:
> @eval [structure(grid,xcoord ycoord,i i,2 3)]
> @eval [construct(space,grid)]
> say [z(space,ycoord)]
You say, "3"
See also: STRUCTURE FUNCTIONS
& MODIFY()
Function: modify(<instance>,<components>,<new values>[,<delim>])
This function changes the value of each component in the list of
<components> in <instance> to the corresponding element of the
list of <new values>. <components> is a space-delimited list.
<new values> is a <delim>-delimited list (space, by default).
Type-checking is performed on each component/value pair; if the
type-check fails, the value is unchanged. The function returns
the number of components successfully modified.
Example:
> @eval [structure(grid,xcoord ycoord,i i,0 0)]
> @eval [construct(space,grid)]
> @eval [modify(space,xcoord,5)]
> say [z(space,xcoord)]
You say, "5"
> @eval [modify(space,ycoord xcoord,3 8)]
> say X:[z(space,xcoord)] Y:[z(space,ycoord)]
You say, "X:8 Y:3"
See also: STRUCTURE FUNCTIONS
& LSTRUCTURES()
Function: lstructures()
Returns a space-separated list of all structure names associated with
the calling object. This is potentially computationally expensive and
should be avoided if possible.
See also: STRUCTURE FUNCTIONS
& LINSTANCES()
Function: linstances()
Returns a space-separated list of all defined structure instances
associated with the calling object. This is potentially computationally
expensive and should be avoided if possible.
See also: STRUCTURE FUNCTIONS
& mSQL
Topic: mSQL
This is a very brief reference to the mSQL 2.0 query language. Please
consult the mSQL home page at http://www.hughes.com.au/ for details.
CREATE DELETE DROP INSERT
SELECT UPDATE Operators Variables
See 'help mSQL <topic>' for details.
& mSQL Operators
The valid basic mSQL operators are: =, <, >, <=, >=, <> ("not equal"))
mSQL also supports the LIKE operator, the CLIKE operator (identical to
LIKE, but ignores case), and the RLIKE operator (does a more Unix-style
regular expression match).
The regular expressions supported by LIKE and CLIKE are SQL regexps;
'_' is used to match a single character, '`' is used to match zero
or more characters, and all other characters match themselves.
RLIKE's regular expressions use '.' to match a single character,
'*' to match zero or more characters, '^' to anchor a pattern at the
beginning, '$' to anchor a pattern at the end, and characters enclosed
in brackets to match a range.
& mSQL CREATE
Syntax:
CREATE TABLE table_name ( col_name col_type [ not null ]
[, col_name col_type [ not null ] ] )
CREATE [UNIQUE] INDEX index_name ON table_name ( field_name [, field_name ] )
CREATE SEQUENCE ON table_name [ STEP step_val ] [ VALUE initial_val ]
Valid column types are: char(len), text(len), int, real
Examples:
CREATE TABLE nametab ( name char(16) not null, dbnum int )
CREATE UNIQUE INDEX num_index on nametab (dbnum)
CREATE SEQUENCE ON nametab STEP 2 VALUE 4
& mSQL DELETE
Syntax:
DELETE FROM table_name WHERE column OPER value [ AND | OR column OPER value ]
OPER can be any standard mSQL operator.
Example:
DELETE FROM nametab WHERE name='Wizard' AND dbnum=3
& mSQL DROP
Syntax:
DROP TABLE table_name
DROP INDEX index_name FROM table_name
DROP SEQUENCE FROM table_name
Examples:
DROP TABLE nametab
DROP INDEX num_index FROM nametab
DROP SEQUENCE FROM nametab
& mSQL INSERT
Syntax:
INSERT INTO table_name [ ( column [, column ] ) ] VALUES (value [, value] )
Examples:
INSERT INTO nametab (name, dbnum) VALUES ('Wizard', '3')
INSERT INTO nametab VALUES('Wizard', '3')
& mSQL SELECT
Syntax:
SELECT [DISTINCT] [table.]column [ , [table.]column ]
FROM table [ = alias] [ , table [ = alias] ]
[ WHERE [table.] column OPERATOR VALUE
[ AND | OR [table.]column OPERATOR VALUE] ]
[ ORDER BY [table.]column [DESC] [, [table.]column [DESC] ]
Examples:
SELECT dbnum FROM nametab WHERE name='Wizard'
SELECT DISTINCT name, dbnum FROM nametab WHERE dbnum > 10 ORDER BY name DESC
SELECT nametab.dbnum infotab.history FROM nametab, infotab
WHERE nametab.name='Wizard' AND nametab.dbnum=infotab.dbnum
& mSQL UPDATE
Syntax:
UPDATE table_name SET column=value [ , column=value ]
WHERE column OPERATOR value
[ AND | OR column OPERATOR value ]
Examples:
UPDATE nametab SET dbnum=10 WHERE dbnum=3
UPDATE nametab SET name='Number_One' WHERE dbnum=1
& mSQL Variables
_rowid: This is the unique identifier for a row in a table.
_seq: This is the current sequence value of a table.
_sysdate: Current time and date.
_timestamp: Last modified time and date (in epoch time seconds) for a row.
& TCL
Topic: TCL
Tcl (pronounced "tickle") -- the Tool Command Language -- is a
simple, easily extensible, scripting language. It is a popular
language for embedding in applications, and commonly used in
World-Wide Web development. It is included as part of TinyMUSH
in an effort to provide an alternative to making direct server
modifications for sophisticated tasks.
A complete discussion of the Tcl language is beyond the scope
of these help files. Interested readers are directed to the
Tcl/Tk website at http://sunscript.sun.com/ for details.
Basic Tcl syntax and functions are given in "help Tcl Primer".
Tcl is called through the use of MUSH functions, and is accessible
only by privileged users. This is "Safe TCL", which means that
file operations and other dangerous primitves are disabled.
See "help Tcl Functions" for details.
WARNING: This has not been implemented in TinyMUSH 3, yet.
& Tcl Functions
Topic: Tcl Functions
Not all MUSHes will support the use of Tcl. To use these functions,
the object must have the TICKLER flag.
MUSH functions:
TclClear() TclEval() TclParams() TclRegs()
Tcl built-ins:
Tcl pemit Tcl mushfunc Tcl getattrib Tcl setattrib
See the help for each individual function for details.
& TclClear()
Function: TclClear()
Each object can be considered to have its own private version
of the Tcl interpreter. The interpreter is persistent for the
duration of the MUSH's uptime, unless specifically cleared
for that object.
This function creates a "fresh" interpreter for the executing
object. The previous interpreter instance, if any, is flushed;
all variables, procedures, etc. associated with it will be
removed.
& TclRegs()
Function: TclRegs()
This function "imports" the current value of the local registers (%q0
through %q9) into the current instance of the executing object's Tcl
interpreter, as the array 'mushregs'.
For example, if you use: '[setq(0,foo)] [TclRegs()]' then
'$mushregs(0)' will be the string 'foo'.
& TclParams()
Function: TclParams(<arg 0>[, <arg2>, ..., <arg 9>])
This function "imports" its arguments into the current instance of the
executing object's Tcl interpreter, as the array 'mushparams'.
For example '[TclParams(foo, bar, baz)]' would set $mushparams(0) to
'foo', $mushparams(1) to 'bar', and $mushparams(2) to 'baz'.
This function is thus very useful for passing arbitrary useful
data to the Tcl interpreter; for example, this is a good way to
pass arguments to commands and the like.
& TclEval()
Function: TclEval(<object>/<attribute>[,<arg 0>,...,<arg 9>])
This function executes the Tcl script contained in <attribute> on
<object>.
The variable $me is automatically set to the object number of the
calling object (equivalent to '%!' with the leading '#' sign stripped),
and the variable $enactor is automatically set to the object number
of the enactor (equivalent to '%#' with the leading '#' sign stripped).
Any additional arguments are passed as the array $in(0) through $in(9).
Please note that invocations of the interpreter are dangerous. There
are no time limits placed upon the execution of a given command; if
you set up an infinite loop, the MUSH will hang.
& Tcl pemit
Tcl Command: pemit <dbref> <text>
This command can be used from within a Tcl script to send a message
back to a MUSH object. Note that the target is a dbref, not a number,
and therefore needs a leading '#' sign. <text> can be any string.
The Tcl command 'pemit #$enactor "This is a test."' is equivalent to
the MUSH command '@pemit %# = This is a test.'
& Tcl getattrib
Tcl Command: getattrib <dbref> <attribute>
This command can be used from within a Tcl script to retrieve the
value of an attribute on a MUSH object. Note that the object is
specified as a dbref (with a leading '#'), not as a number.
The Tcl command 'getattrib #$enactor TEST' is equivalent to the MUSH
function invocation '[get(%#/TEST)]'.
& Tcl setattrib
Tcl Command: setattrib <dbref> <attribute> <text>
This command can be used from within a Tcl script to set the value of
an attribute on an object. Note that the object is specified as a dbref
(with a leading '#'), not as a number. <attribute> is any value attribute
name. <text> is any arbitrary string.
The Tcl command 'setattrib #$me TEST "This is a test string."' is
equivalent to the MUSH command '&TEST %! = This is a test string.'
or '&TEST me = This is a test string.'
& Tcl mushfunc
Tcl Command: mushfunc <MUSH function name> <param 1> <param 2> <etc.>
This command can be used from within a Tcl script to execute a MUSH
function (except for MUSH Tcl functions). <function name> is the name
of the MUSH function, and the parameters are remaining arguments to
the Tcl command.
For example, the Tcl command 'mushfunc lnum 2 6' is equivalent to
the MUSH function 'lnum(2,6)' and produces '2 3 4 5 6' as a result.
& Tcl Primer
The following topics contain a very brief summary of the Tcl language.
Arrays Control Structures Errors Expressions
Info Lists Procedures Strings
Tracing Variables
See "help Tcl <topic name>" for details.
& Tcl Variables
Topic: Tcl Variables
Everything in Tcl is treated as a string. Anything placed with double
quotes is grouped; expressions within double quotes are
evaluated. Anything placed within curly braces is grouped, but
expressions within the curly braces are not grouped. Statements are
separated with semi-colons. Comments begin with a # and extend to the
end of the line.
Variables are set with: set VariableName "String"
Variables are unset with: unset VariableName
Variables are accessed with $VariableName
To use a literal dollar sign in an expression, escape it: \$
All commands return values. To evaluate a command and use its
return value inside an argument to another command, enclose the
command in square brackets.
Continued in 'help Tcl Variables2'.
& Tcl Variables2
Topic: Tcl Variables (continued)
There is also a special command, 'incr', which adds a number to the
value of a variable, and then sets the variable. For example,
"incr x 1" increases the value of x by 1; "incr x -1" decreases the
value of x by 1. "incr" with only one argument increments the
variable by 1.
Examples of valid syntax (commands executed in order):
set name "Joe Smith"; ==> returns Joe Smith
set a 1; ==> returns 1
set b 2; ==> returns 2
set sum "[expr $a + $b]"; ==> returns 3
set x $sum ==> returns 3
incr a ==> returns 2
incr b -1 ==> returns 1
incr x "[expr $a + $b]"; ==> returns 6
& Tcl Expressions
Topic: Tcl Expressions
Mathematical expressions are essentially strings that have values.
The usual mathematical operators (+ - * / %) are available, as
are mathematical functions such as sin(), cos(), floor(), ceil(),
and so forth.
For comparison purposes, || (or), && (and), and ! (not) are available,
as are == (equal to), != (not equal to), <= (less than or equal to),
and >= (greater than or equal to).
Mathematical expressions are not commands, however. They must be
evaluated, through the use of the 'expr' command. For example:
set sum "Sum: 1 + 2" ==> Returns "Sum: 1 + 2"
set sum "Sum: [ 1 + 2 ]" ==> Returns an error
set sum "Sum: [ expr 1 + 2]" ==> Returns "Sum: 3"
set x "[ expr (1 + 2) * 3 ]" ==> Returns "9"
To force a string to evaluate as a command, use: eval String
& Tcl Control Structures
Topic: Tcl Control Structures
There are a number of loop and other control structures in Tcl.
They are treated like standard Tcl commands.
IF/THEN/ELSE
if { Expression } { if { $x < 0 } {
# Commands set out "Less than zero";
} elseif { Expression } { } elseif { $x == 0 } {
# Commands set out "Equal to zero";
} else { } else {
# Commands set out "Greater than zero";
} }
Continued in 'help Tcl Control2'.
& Tcl Control2
Topic: Tcl Control Structures (continued)
SWITCH
switch Option VariableName \ switch -exact $sum \
String1 { 1 { set out "One" }
# Action 1 2 { set out "Two" }
} String2 { 3 { set out "Three" }
# Action 2 default { set out "Error" };
} default {
# Default action
}
The option for the switch command must be -exact (match exactly),
-glob (match wildcards), or -regexp (match regular expressions).
Continued in 'help Tcl Control3'.
& Tcl Control3
Topic: Tcl Control Structures (continued)
WHILE LOOP
while { Expression } { while { $i < $total } {
# Commands incr x 5;
} incr i;
}
FOR LOOP
for { Start Command } { Test Expression } { Next Command } {
# Commands
}
for { set i 0 } { $i < 5 } { incr i } {
set sum "[expr $sum * $i]";
}
Continued in 'help Tcl Control4'.
& Tcl Control4
Topic: Tcl Control Structures (continued)
It is possible to prematurely exit a loop with the 'break' and
'continue' commands. The 'break' command causes the loop to
immediately exit; the 'continue' command causes control to
return to the top of the loop, for the next iteration to
execute.
Example of 'break' (and equivalent 'for' loop):
set x 0; for { set x 0 } { $x <= 5 } { incr x } {
while { 1 } { incr y 2;
incr x; }
incr y 2;
if ($x > 5) break;
}
Continued in 'help Tcl Control5'.
& Tcl Control5
Topic: Tcl Control Structures (continued)
Example of 'continue' (only adds odd numbers):
for { set x 0 } { $x < 100 } { incr x } {
if { $x % 2 == 0 } continue;
incr y 1;
incr sum x;
}
& Tcl Procedures
Topic: Tcl Procedures
It is possible to define procedures, which act just like built-in
commands; every procedure returns a value. Procedures are defined by
the 'proc' command, with the following syntax:
proc ProcedureName { Arg1 Arg2 ... ArgN } {
# Commands
return Value;
}
If the 'return' statement is ommitted, the return value is that of
the last statement in the procedure.
Variables in procedures are passed by value, and variables used within
a procedure are local to that procedure unless specificied otherwise
with the 'global' command.
Continued in 'help Tcl Proc2'.
& Tcl Proc2
Topic: Tcl Procedures (continued)
The 'global' command specifies that the value of a variable inside the
procedure is the same as its value outside that procedure. It can take
multiple arguments; for example, "global x y z;" is a valid statement.
For example, the following would compute the area of two circles:
set pi 3.14159;
proc circle_area { radius } {
global pi;
expr $pi * $radius * $radius;
}
set little_circle "[ circle_area 4 ]";
set big_circle "[ circle_area 10 ]";
Continued in 'help Tcl Proc3'.
& Tcl Proc3
Topic: Tcl Procedures (continued)
It is possible to make a variable visible outside of its normal scope
with the "upvar" command, thus making it possible to implement
pass-by-reference in procedures. The command takes the following syntax:
upvar Referred-To Referred-Through
For example, "upvar old new" means that if "new" is changed, "old"
will also be changed: "set new 1" will set "new" to 1 inside the
procedure, and "old" to 1 in the caller of the procedure.
It is also possible to use the command "uplevel Command" to
evaluate a command in the scope of the calling procedure.
& Tcl Lists
Topic: Tcl Lists
Like MUSH, Tcl has a concept of a "list", a space-separated set of
words. For example, "a b c d e" is a list of five elements. Unlike
MUSH, however, Tcl numbers its list elements starting from zero,
not one.
It is possible to have lists of lists, usually written by enclosing
each set of elements within curly braces, as in the following example:
set biglist { a b {c d { e f g }} {h i j} k}
A variety of commands exist for list manipulation, as well as a
special loop construct, which takes the following syntax:
foreach VariableName List { foreach elem "1 2 3 4 5" {
# Commands incr sum $elem;
} }
Continued in 'help Tcl Lists2'.
& Tcl Lists2
Topic: Tcl Lists (continued)
list Element1 Element2 ... ElementN
Takes the arguments and makes them into a list, i.e.,
'list a b c d' returns "a b c d". This will preserve
lists-within-lists.
concat "List1" "List2" ... "ListN"
Takes the arguments and turns them into a single list.
lappend Variable Arg1 Arg2 ... ArgN
Appends the arguments to the end of an existing list stored
in the variable, i.e., 'set x "a b c"; lappend x d e' returns
'a b c d e'.
split String Separators
Splits a string into a list, using the characters specified as
separators to delimit the original string, i.e., 'split a:b:c:d :'
returns the list 'a b c d'.
join "List" Separator
Joins elements of a list together, with Separator as the delimiter,
i.e., 'join "a b c" :' returns 'a:b:c'.
Continued in 'help Tcl Lists3'.
& Tcl Lists3
Topic: Tcl Lists (continued)
llength "List"
Returns the length of a list, i.e, 'llength "a b c"' is 3.
Equivalent to MUSH 'words(a b c)'.
lsort SortTypes "List"
Returns the list in sorted order. Sort type switches may optionally
be specified: -ascii (lexicographical order), -integer (as integers).
-real (as floating-points), -command (using a comparison command),
-increasing (increasing order), and -decreasing (decreasing order).
The default is ascii and increasing.
lindex "List" Number
Returns the element in that position of the list, i.e.,
'lindex "a b c" 1' returns 'b'.
lrange "List" Begin End
Returns the elements in that range of positions in the list, i.e.,
'lrange "a b c d e" 1 3' returns 'b c d'.
Continued in 'help Tcl Lists4'.
& Tcl Lists4
Topic: Tcl Lists (continued)
lsearch "List" Element
Returns the index of the first element in the list which matches
Element, i.e., 'lsearch "a b c d e" c' returns '2'.
linsert "List" Number Arg1 Arg2 ... ArgN
Inserts the arguments before the Number'd element in the original list,
i.e., 'linsert "a b f g" 2 c d e' returns 'a b c d e f g'.
lreplace "List" Begin End Arg1 Arg2 ... ArgN
Deletes the arguments from element positions Begin to End, inserting
the arguments in their place, i.e., 'lreplace "a b x y z f g" 2 4 c d e'
returns 'a b c d e f g'.
& Tcl Strings
Topic: Tcl Strings
Tcl has a number of build-in commands for string manipulation.
String positions are numbered starting from zero.
append Variable String1 String2 ... StringN
Takes the string in Variable, and appends the other strings to it, i.e.,
'set str "xyz"; append str "abc" "def"' returns 'xyzabcdef'.
format FormatString Arg1 Arg2 ... ArgN
Takes a format string and prints the arguments appropriately. Equivalent
to C's sprintf() function, i.e., 'format "X: %3d" x' where x is 12,
returns 'X: 12'.
scan String FormatString Var1 Var2 ... VarN
Takes a string, and breaks it down according to the format given,
placing the results in the named variables. Equivalent to C's
sscanf() function, i.e., 'scan "abc 15 xy" "%s %d %s" str1 num str2'
returns str1 as 'abc', str2 as 'xy', and num as '15'.
Continued in 'help Tcl Strings2'.
& Tcl Strings2
Topic: Tcl Strings (continued)
string compare String1 String2
Returns -1, 0, or 1, depending on which string is lexicographically
greater; 0 indicates identical strings. Equivalent to MUSH comp().
string match Pattern String
Returns 1 if the string matches the wildcard pattern, 0 if not.
This is like MUSH strmatch(), but with the argument order reversed.
string index String Position
Returns the character at that position in the string, i.e.,
'string index abcde 2' returns '2'.
string range String Begin End
Returns the characters between those positions in the string, i.e.,
'string range abcde 1 3' returns 'bcd'.
Continued in 'help Tcl Strings3'.
& Tcl Strings3
Topic: Tcl Strings (continued)
string first Substring String
Returns the first position in the string, that substring occurs at.
If the substring is not in the string, -1 is returned. For example,
'string first man superman' returns '5'.
string last Substring String
Returns the last position in the string, that substring occurs at,
i.e. 'string last abc abc123abc456' returns '6'.
string trim String Characters
Removes, from the beginning and end of the string, any of the
specified characters. For example, 'string trim -*-POW-*- *-'
returns 'POW'.
string trimleft String Characters
Like string trim, but only removes from the beginning of the string.
string trimright String Characters
Like string trim, but only removes from the end of the string.
Continued in 'help Tcl Strings4'.
& Tcl Strings4
Topic: Tcl Strings (continued)
string tolower String
Returns the string with all letters lowercased, like MUSH lcstr().
string toupper String
Returns the string with all letters uppercased, like MUSH ucstr().
& Tcl Arrays
Topic: Tcl Arrays
Tcl has arrays, indexed by arbitrary strings. An array element
is a variable of the format VariableName(Index); for example,
players(0), players(1), players(2), players(Zod) are all valid
variable names for elements of an array.
Because array indexes are arbitrary strings, they can contain
whitespace, and it is possible to simulate multi-dimensional
arrays by placing a comma within the index: for example,
players(5,12) is valid.
Array variables are set and retrieved just like ordinary
variables, i.e.:
set objects(0) "Limbo" if { $objects(limbo) != 0 } {
set objects(1) "Wizard" set errstr "Error!";
set objects(2) "Master Room" }
set objects(limbo) 0
Continued in 'help Tcl Arrays2'.
& Tcl Arrays2
Topic: Tcl Arrays (continued)
Unsetting an array variable name unsets the entire array; i.e., the
command 'unset objects' removes objects(0), objects(1), etc.
There are also two special commands which provide information about
arrays:
array size ArrayName
Returns the number of elements in the array.
array names ArrayName
Returns a list of element names in the array.
& Tcl Info
Topic: Tcl Info
The 'info' set of commands provides various bits of information
on the current state of the interpreter.
info exists VariableName
Returns 1 if a variable exists, 0 if it does not.
info vars Pattern
Returns a list of all local and global variables. If a wildcard
pattern is specified, it will only return those variables whose
names match the pattern.
info locals Pattern
Like info vars, but returns only local variables.
info globals Pattern
Like info vars, but returns only global variables.
info level Number
With no arguments, this returns the stack depth. With an argument of 0,
it returns the command and arguments of the current procedure; an
argument of -1 gives this info for the calling procedure, -2 the
info for the procedure beyond that, and so forth.
& Tcl Errors
Topic: Tcl Errors
Tcl has a variety of exception-handling mechanisms for dealing with errors.
catch { Procedure Arg1 Arg2 ... ArgN } Variable
If the procedure succeeds, 'catch' returns 0. If a variable name is
specified, the return result of the procedure is set in that variable.
error String
If this command is given, the string will be stored in the optional
variable name specified to 'catch', and 'catch' will return 1.
The gloable variable errorInfo can be used to give a more detailed
description of the error, for debugging purposes; it lists the
commands and procedures on the stack leading to the error.
& Tcl Tracing
Topic: Tcl Tracing
trace variable VariableName Type Procedure
Invokes a procedure whenever the named variable is "r"ead,
"w"ritten to, or "u"nset/goes out of scope. One of these options
must be specified as the type of trace).
The procedure must be declared as: proc Procedure { Variable Element Type }
where the first parameter is the variable to trace, the second the
element of the array (if the variable is an array), and the third the
type, specified as r, w, or u.
Note that due to the scope of the procedure being executed, it will
usually be necessary to do an 'upvar' to get the variable being
traced from the caller's scope.
& About TinyMUSH
TinyMUSH 3 is the result of converging the development paths of
TinyMUSH 2.2 and TinyMUX. It was designed to be a stable, efficient,
highly-configurable, feature-rich code version, offering users a full
array of 2.2 and MUX features, as well as substantial enhancements to
functionality and performance.
TinyMUSH 3 is under active development, and is the standard supported
version of TinyMUSH for the forseeable future. The primary developers are
Lydia Leong ("Amberyl"), David Passmore ("Lauren"), Robby Griffin
("Alierak", as of 3.0 beta 18), and Scott Dorr ("Myrddin", as of
3.0 beta 23).
See 'help Patchlevel' for notes on TinyMUSH 3 changes.
See 'help Writing News' for an explanation of how to write news files.
See 'help Support' for URLs to TinyMUSH 3 announcements and resources.
See 'help Mailing Lists' for a list of TinyMUSH-related mailing lists.
& Mailing Lists
Support for TinyMUSH 3 is done via 'tinymush-support@lists.sourceforge.net',
a mailing list. The list's home page, subscription tool, and archives
are at http://lists.sourceforge.net/mailman/listinfo/tinymush-support
Announcements of new server versions, new games, and other information
of interest to the general MUSH community, is available through
tinymush-announce@lists.sourceforge.net, a moderated mailing list with
low traffic. We highly encourage all users to subscribe to it through
http://lists.sourceforge.net/mailman/listinfo/tinymush-announce
Archives are also available through that page.
There is an unofficial MUSH programmer's list, 'softcode@legendary.org'.
Go to http://www.legendary.org/mailman/listinfo.cgi/softcode to subscribe.
There is a mailing list for MUSH administrators, 'gods@godlike.com'.
Go to http://www.godlike.com/mailman/listinfo.cgi/gods to subscribe
or to peruse the archives.
An informal meeting grounds for MUSH administrators, called The
Godlike Edge, is located at edge.godlike.com 6250.
& Support
TinyMUSH 3 announcements and related support information can be found
at the official TinyMUSH 3 home, http://tinymush.sourceforge.net/
The MUSH Manual can be found at http://www.godlike.com/mushman/
It might also be accessible by typing 'man' within this MUSH.
General information about MUDs and a MUSH list can be found on the
MUD Resource Collection, at http://www.godlike.com/muds/
The MUD Connector is an excellent general MUD list. It can be found
at http://www.mudconnect.com/
Users may also be interested in the TinyFugue client, available from
http://www.muq.org/~hawkeye/tf/
Also useful is the LogEdit program, a tool for quickly editing logs,
available from ftp.pennmush.org, in /pub/PennMUSH/Accessories.
& Writing News
The format of a news entry file is simple. A news entry begins with
"& <topic name>", where <topic name> is whatever you want that news
entry to be called. Topics with similar names should be placed in
alphabetical order; i.e., "Magic" should come before "Magic Weapons".
Topic names are not case-sensitive.
News entries are displayed "as is". No special formatting is done.
Blank lines are normally "eaten"; to get a blank line into a news
file, enter a line with a single space on it. You may want to avoid
"tab" characters in news files, since some terminal types are confused
by them. You will probably want to make individual news topics no more
than 23 lines long, in order to accomodate screen sizes.
Percent-substitutions are evaluated inside files added with the
'helpfile' config directive, so you can use ANSI color codes in
them. Be aware that this means you will need to escape certain special
characters, such as the backslash and percent.
You must use the 'mkindx' program to re-index the news file when it
is changed. If you change any text files while the game is running,
a Wizard must do a @readcache from within the game.
& Patchlevel
The user-visible changes to TinyMUSH 3.1 (from TinyMUSH 3.0) can be
found in the following help entries:
'help 3.1 base' New/enhanced base server and configuration directives.
'help 3.1 attrs' New/enhanced attributes and attribute flags.
'help 3.1 flags' New/enhanced flags and powers.
'help 3.1 commands' New/enhanced commands.
'help 3.1 functions' New/enhanced functions.
See 'help Patchlevel 3.0' for the TinyMUSH 3.0 new/enhanced features
and differences from TinyMUSH 2.2 and TinyMUX 1.6.
& Patchlevel 3.0
TinyMUSH 3.0 began with the fusion of the TinyMUSH 2.2.5 and TinyMUX 1.6
code bases.
The user-visible changes to TinyMUSH 3 can be found in the following
help entries:
'help 3.0 base' New/enhanced base server and configuration directives.
'help 3.0 flags' New/enhanced flags and powers.
'help 3.0 commands' New/enhanced commands.
'help 3.0 functions' New/enhanced functions.
'help upgrade mush' What's different from TinyMUSH 2.2.
'help upgrade mux' What's different from TinyMUX 1.6.
& 3.0 base
- GNU dbm 1.8.0 is required. Database code has been rewritten to take
advantage of its features. Dumps are now automatically optimized (though
you can turn this off using the new conf parameter opt_frequency), and
you may safely back up the MUSH while it is running, either internally
(through @dump/flatfile) or externally (through the Backup script).
- An interface to an external SQL database is now supported, through
the SQL() function and supporting administrative commands. Currently,
modules for mSQL and MySQL are available.
- There is now a generic indexed-textfile facility, allowing 'news'-like
commands and their associated files to be specified via the 'helpfile'
and 'raw_helpfile' parameters in the conf file.
- The readability of a configuration parameter can be set via the
config_read_access param, and can be listed with @list config_read_perms.
A config() function allows players to obtain the value of a configuration
parameter that they have permission to read.
Continued in 'help 3.0 base2'.
& 3.0 base2
- The new game_log and divert_log parameters allow the logs for different
types of events to be sent to different files. The new @logrotate
command allows these logfiles to be rotated while the game is running.
Logfiles are also rotated when a @restart is done. Old log are marked
with a timestamp in seconds. The new Logclean script simplifies
cleanup of old logfiles.
- Command-table additions (@addcommand and family) are supported (a
cleaned-up version of the MUX implementation). Three new conf parameters:
- addcommands_match_blindly (defaults to 'yes', controls whether or not
a 'Huh?' is produced when a match on an @addcommand'd command doesn't
actually match a $command)
- addcommands_obey_stop (defaults to 'no') controls whether or not an
object with the Stop flag actually enforces a stop of match attempts
when a match is found on an @addcomand for that object.
- addcommands_obey_uselocks (defaults to 'no') controls whether or not
the uselock is checked when an added command is matched.
(The defaults are MUX behavior; we suggest that the reverse of the
defaults is more desirable, though.)
Continued in 'help 3.0 base3'.
& 3.0 base3
- There are now command "hooks", implemented via the @hook command. Hooks
are functions which execute before and/or after a built-in command;
using side-effect functions, it is thus possible to customize a
command without needing to write a full-blown @addcommand for it,
or to execute things before/after every move through an exit.
- The term "zone" is now used for two things: MUX-style control-oriented
zones, and 2.2-style local-master-rooms. Both types of zones default
to on (local_master_rooms and have_zones conf parameters). MUX-style
zones now use ControlLock rather than EnterLock, and only objects
set CONTROL_OK may be controlled by a ZMO; this provides slightly
better security. A new config parameter, 'autozone', controls
whether or not objects are automatically zoned to their creator's
ZMO at the time of their creation.
- The comsystem has been rewritten, resulting in a variety of minor
syntax changes and alterations and enhancements to functionality.
Default channel aliases can now be set with the public_calias and
guests_calias config parameters.
Continued in 'help 3.0 base4'.
& 3.0 base4
- Variable destination exits are implemented, via the "variable" keyword
and the ExitTo attribute; the destination of the exit is determined when
it is used. The link_variable power has been added in support of this.
(This works in a way similar to PennMUSH's variable destination exits,
but ExitTo was used instead of Destination, to reduce likelihood of
previous attribute conflicts.)
- Optional uselock checking for global aconnects has been implemented.
(2.2 had this by default; MUX did not have this.)
- The disconnect reason is passed for master-room disconnects, too.
- When the new conf parameter dark_actions is enabled, objects set Dark
still trigger @a-actions when moving, unless the /quiet switch is
specified.
Continued in 'help 3.0 base5'.
& 3.0 base5
- When the new conf parameter exit_calls_move is enabled, trying to go
through an exit by just typing its name is equivalent to typing
'move <exit name>', allowing this to be intercepted by a move
@addcommand.
- When the new conf parameter move_match_more is enabled, the move
command matches exits like the main command parser does, i.e., it
also checks global and zone exits, and in the case of multiple
matches, picks a random match.
- When the new conf parameter no_ambiguous_match is enabled, ambiguous
matches always result in a random selection amongst the matches (i.e.,
you will never get a "I don't know which one you mean!" message).
- The new conf parameter guest_starting_room allows Guest characters to
start in a different default room than other characters.
- The MUSH manual is included in the distribution in helpfile format.
(Thanks to Alierak and sTiLe.) It should be accessible on most MUSHes
with the 'man' command.
& 3.0 flags
- There are now ten user-defined flags, MARKER0 through MARKER9. The flag
names can be set through the flag_name option. Commands, functions, and
other things with configurable permissions can also be tied to these
flags (for instance, 'function_access lwho marker0').
- The access permissions of flags, including user-defined flags, can be
set via the flag_access config directive. In addition to permissions
for wizards, wizards/royalty, and god, there is a restrict_player
option (only settable by Wizards on players, but settable by mortals
on other types of things), and a privileged option (only settable by
God on players, but settable by non-robot players on other types of
things, if they themselves have the flag).
- The access permissions of powers can be set via the power_access config
directive. The permission types available are the same as for flags.
- Command permissions can also be linked to the STAFF and HEAD flags.
The "robot" permission has been removed, since nobody was using it.
(The "no_robot" permission still exists, though.)
Continued in 'help 3.0 flags2'.
& 3.0 flags2
- A new flag, BLIND, suppresses has arrived / has left messages.
- A new flag, CONSTANT, prevents attributes from being set or altered
on an object by anyone other than God.
- The FLOATING flag, if set on a player, now suppresses floating-room
messages sent to that player.
- There is now a link_to_anything power, and an open_anywhere power, doing
the obvious; these are handy for building-staff players.
- The see_hidden power now works. DARK is really two concepts, not showing
up in the WHO list and not showing up in the contents list / moving
silently. see_hidden allows seeing the former but does not affect the
latter. These two concepts are now handled in a consistent manner
within the server.
& 3.0 commands
- New /info switch to @attribute shows global attribute flags for a single
attribute (similar to what '@list user_attributes' produces for all
user-defined attributes).
- @chown now checks a ChownLock on CHOWN_OK objects.
- @chown, @chownall, @chzone, and @clone now strip flags in a consistent
manner, as defined by the conf option stripped_flags. The /nostrip
switch negates this stripping. For consistency, @clone/inherit no
longer preserves IMMORTAL (but it still preserves INHERIT).
- @clone/preserve can be used by anyone, but you must control the original
object's owner.
- A @cron facility allows tasks to be scheduled at specific times,
in much the same way that Unix cron does.
Continued in 'help 3.0 commands2'.
& 3.0 commands2
- New /instant switch to @destroy causes objects to be instantly destroyed
(rather than being queued for destruction at the next purge). Also, a
new conf option, instant_recycle, controls whether or not Destroy_OK
objects are instantly recycled (rather than being queued for destruction).
- New /pretty switch to examine and @decompile "pretty-prints" (with
indentation) attributes. Based on Andrew Molitor's +pex-equivalent code.
- New /pairs switch to examine matches parentheses, brackets, and braces(),
displaying them in ANSI colors. Based on Robby Griffin's ChaoticMUX code.
- New @freelist command moves an object to the head of the freelist,
until the next dbck.
- New /noeval switch to @function defines a user-defined function whose
arguments are not pre-evaluated.
- When you try to 'give' someone money, their ReceiveLock, rather than
their UseLock, is checked.
Continued in 'help 3.0 commands3'.
& 3.0 commands3
- New @hashresize command dynamically resizes the hash tables. This is
also automatically done at startup time.
- The @list options command has been reformatted and reorganized. A
new command, @list params, lists additional configuration parameters.
- New /reply and /replyall switches to @mail allow replying to a mail
message, including quoting it via the additional /quote switch.
- An object can @program another object if the first object or its owner
has the Program power, or the first object controls the second. (This
fuses the 2.2 and MUX models.)
- @program now reads attributes on the object's parent chain as well,
not just the object itself (thus behaving like @trigger and friends).
- @ps now shows the attribute being waited upon, for non-Semaphore
semaphore waits.
- @stats() and stats() now count the number of Going objects, as well
as the number of objects of unknown (corrupted) type.
& 3.0 functions
- Functions for generic named variables, preserved in a manner similar to
the stack (i.e., associated with a specific object, persistent until a
restart is done), have been added. setx() sets a named variable,
xvars() parses a list of strings into a list of variables, regparse()
parses a regular expression into a list of variables, x() accesses
a named variable (as does %_<var>), lvars() lists named variables,
clearvars() mass-unsets named variables, and let() does a Scheme-style
code block (with localized variables).
- Functions for generic named data structures (data types), preserved in
a manner similar to the stack, in a LISP-like style. structure()
defines a structure, unstructure() undefines one, construct() and
load() create instances of structures, destruct() removes an instance
of a structure, unload() dumps the components of an instance, z()
gets the component of an instance, modify() modifies a component
of an instance, and lstructures() and linstances() list the names
of structures and instances, respectively.
- The equivalent of v(ATTRIBUTE) can now be accessed as '%=<ATTRIBUTE>',
where the angle-brackets are literal.
Continued in 'help 3.0 functions2'.
& 3.0 functions2
- Functions that take output delimiters can take null output delimiters
(symbolized by the token '@@') and newline ('%r') output delimiters.
- Booleans, as represented by functions such as t(), andbool(), and
ifelse(), are now handled in a more sensible manner. All dbrefs
(#0 and higher) are now considered true; #-1 and below are considered
false. The string '#-1 <string>' (such as '#-1 NO MATCH') is considered
false. All other strings beginning with '#' are treated like arbitrary
strings, so, for instance, lists of dbrefs ('#0 #3 #5') are considered
true. The old behavior can be obtained by enabling the booleans_oldstyle
config parameter.
- The ansi() function compacts multiple ANSI attributes into a single
ANSI code.
- String-manipulation functions, such as edit() and mid(), no longer
strip ANSI characters, and @edit is better able to handle ANSI
characters.
- An ANSI underline code, %xu, has been added.
Continued in 'help 3.0 functions3'.
& 3.0 functions3
- Added chomp() function -- akin to perl chomp(), it chomps off a
trailing carriage-return newline from a string, if there is one.
(Useful for dealing with pipe output.)
- Added command() function, which allows the execution of a variety of
built-in commands in function form, such as @parent and @name.
- Added doing() function, to get @doing text.
- Added force(), trigger(), and wait() functions. Evil, but useful.
- iter() and list() can now be nested, and the nesting level can be
obtained with '#!'. This changes the way parsing is done on both
functions, and may affect the manner in which arguments to these
functions should be escaped. For backwards compatibility, parse()
works like the old iter() (unchanged behavior), and the new loop()
function works like list() used to.
Continued in 'help 3.0 functions4'.
& 3.0 functions4
- The ladd(), lmin(), lmax(), lor(), land(), lorbool() and landbool()
functions operate on lists, eliminating the necessity to fold() elements
through their non-list counterparts.
- Conf parameter lattr_default_oldstyle controls what lattr() returns when
it fails to match: if 'yes', this is empty (2.0.10p5 and before, 2.2.1
and later), if 'no', this is #-1 NO MATCH (2.0.10p6, 2.2.0, MUX).
Defaults to 'no'.
- Added localize() function, keeping changes to r-registers within the
"local" scope of that evaluation.
- Added lrand() function, generating a delimiter-separated list of
N random numbers between X and Y.
- The log() function can now taken an optional second argument, the base.
- The mix() function can now take an unequal number of elements in each
list. (The lists are considered to be padded out with nulls.)
Continued in 'help 3.0 functions5'.
& 3.0 functions5
- If the new conf parameter, objeval_requires_control, is enabled (it
is disabled by default), the objeval() function requires that you
control the evaluator, not just have the same owner as it.
- Added ncomp() function for comparing numbers comp() style (very
useful for sortby() afficianados).
- Added null() function, which just eats output. (Useful for doing things
like iter() with side-effect functions, and getting rid of the resulting
garbage spaces.)
- The nonzero() function outputs the result of an if/else condition on a
non-zero result. (This provides MUX-style ifelse() behavior. ifelse()
follows the TinyMUSH 2.2 behavior of conditioning on a boolean.)
- The objmem(<thing>) function does a MUX-style object-structure count;
objmem(<thing>/<wild>) does a 2.2-style attribute-text count. (Fuses
the two models.)
Continued in 'help 3.0 functions6'.
& 3.0 functions6
- The pfind() function returns a dbref, or looks up a player. (This
provides MUX-style pmatch() behavior. pmatch() now behaves like the
MUX documentation said it should, which is identical to its PennMUSH
predecessor.)
- step() does the equivalent of map() over multiple elements of a single
list, with N elements at a time passed as %0, %1, etc.
- streq() does a case-insensitive comparison of two strings, returning 0 or 1.
- switchall() returns the string results from all cases that match.
- switch() and switchall() can nest the '#$' token, and the nesting
level is available with '#!'.
- Vector functions no longer have a maximum dimension.
- vunit() can take an output delimiter.
- Added while() function. Evaluates elements of a list, until a
termination condition is reached or the end of the list is reached.
& 3.0 upgrade mush
The following are important changes in behavior between TinyMUSH 2.2 and 3.0:
- objmem() behaves differently, taking into account the object structure
as well as attribute text. To get the equivalent behavior to 2.2's
objmem(<obj>), use objmem(<obj>/*)
- hasattr() no longer checks for the presence of the attribute on the
object's parent chain. To get the equivalent of the 2.2 behavior,
use hasattrp() instead. Databases upgraded from 2.2 to 3.0 should
have automatically been modified to use hasattrp().
- Two additional categories have been added to the stats() function. If
you have softcode that extracts the number of garbage objects in the
database from stats(), it will be fine if you used last(stats()) to
get the data; if you used extract() or another function that depended
upon list position, you will need to modify your code.
Continued in 'help 3.0 upgrade mush2'.
& 3.0 upgrade mush2
The following is a list of features/functions that were in TinyMUX 1.6,
but were not in TinyMUSH 2.2.5, and which have become part of 3.0.
- The TinyMUX powers system has been added.
- Added the MUX mailer. (Config option, on by default.)
- Added the MUX com system. (Config option, on by default.)
- The Guest system has been replaced by the MUX Guest system.
- DNS lookups are now done by a slave process (automatically started at
startup, or through @startslave); the server will no longer block for
them.
- Support for identd.
- Max login record kept and displayed in WHO.
Continued in 'help 3.0 upgrade mush3'.
& 3.0 upgrade mush3
- Added indent_desc config parameter.
- Buffer size is now 8000 characters (doubled).
- Output block size is now a compile-time parameter.
- Auto-restart on crash controlled by signal_action conf parameter.
- Attribute caching has been eliminated.
- Memory-based databases supported.
- Wizards can connect dark via the 'cd' command.
- Added '@cpattr' command.
- @daily implemented; enabled by 'eventchecking' global parameter, time
set by events_daily_hour.
Continued in 'help 3.0 upgrade mush4'.
& 3.0 upgrade mush4
- Added @dbclean command, which removes stale attribute names from the
database.
- Destruction of all objects is delayed until a dbck is done, as was
previously true just for rooms. (Exception: DESTROY_OK objects.)
- @edit hilites the changed text.
- examine/brief now shows everything but the attributes on the object.
To get the old behavior (just showing the owner), use examine/owner.
- '@function/preserve' preserves registers across user-defined functions.
- '@list process' shows the number of descriptors available.
- Multi-page and last-paged are now supported.
- @search supports a GARBAGE class.
Continued in 'help 3.0 upgrade mush5'.
& 3.0 upgrade mush5
- Added 'think' command.
- Semaphore @wait can now block on a user-specified attribute.
- Added @tofail/@otofail/@atofail (messages for failing to teleport out).
- Added the ROYALTY flag.
- Added SpeechLock/AUDITORIUM support.
- Added FIXED flag (prevents teleporting or going home), with conf
parameters fixed_home_message and fixed_tel_message.
- The GAGGED flag is back.
- Added marker flags: HEAD, STAFF, UNINSPECTED.
- TRANSPARENT flag on room shows exits in "long" style.
Continued in 'help 3.0 upgrade mush6'.
& 3.0 upgrade mush6
- Added VACATION flag, which auto-resets when a player connects.
- Added WATCHER flag, and Watch_Logins power, which is equivalent to the
connection monitoring functionality of MUX's MONITOR flag.
- hasattr() no longer finds attributes on parents; use the new hasattrp()
function for the old hasattr() behavior.
- Added alphamax(), alphamin() functions.
- Added art() function.
- Added beep() function.
- Added case() function.
- Added children(), lparent() functions.
- Added columns() function.
Continued in 'help 3.0 upgrade mush7'.
& 3.0 upgrade mush7
- Added encrypt(), decrypt() functions.
- Added grep(), grepi() functions.
- Added hastype() function.
- Added playmem() function.
- Added pmatch() function.
- Added strcat() function.
- Added strtrunc() function.
- Note that side-effect functions that fail now generally return #-1
NOT a null string (MUX behavior). If you want to guarantee a null
return, wrap the call in a null().
& 3.0 upgrade mux
The following are important changes in behavior between TinyMUX 1.6
and TinyMUSH 3.0:
- MUX used '%c' for ANSI color. 3.0 uses '%x' for ANSI color ('%c' is
the last-command substitution, as it is in PennMUSH and TinyMUSH 2.2.)
Databases imported from MUX have had this conversion done automatically.
- MUX ifelse() conditioned on a non-zero result. 3.0 ifelse() conditions
on a boolean-true result. To get the old behavior, use nonzero().
Databases imported from MUX have had this conversion done automatically.
- pmatch() now works as documented (i.e., identical to its PennMUSH
predecessor). To get the old behavior, use pfind().
Databases imported from MUX have had this conversion done automatically.
- Objects are now checked for commands if they are set COMMANDS (instead
of not being checked for commands if they are set NO_COMMAND).
Databases imported from MUX have had this conversion done automatically.
Continued in 'help 3.0 upgrade mux2'.
& 3.0 upgrade mux2
- ZMOs are now controlled by their ControlLock, not their EnterLock.
Only objects that are set CONTROL_OK may be controlled according to
their zone's ControlLock.
Databases imported from MUX have had this conversion done automatically.
- The COMPRESS flag has been eliminated. It was unused in MUX, though
you could manually set it on objects.
Databases imported from MUX have had this conversion done automatically.
- The WATCHER flag is now used to watch logins, rather than MONITOR.
The power to do this is now called Watch_Logsin, and it allows
you to set WATCHER on objects that you own (rather than on objects
that you control).
Databases imported from MUX have had this conversion done automatically.
- There is no longer a /dbref switch for @decompile; just use
'@decompile <object>=<dbref of object>' to get the same effect.
Continued in 'help 3.0 upgrade mux3'.
& 3.0 upgrade mux3
- The channel administration commands have been consolidated to a
single command, @channel, which takes a variety of switches. Channel
objects are no longer necessary.
Comsys databases imported from MUX have had channel object data
imported into the main comsystem configuration done automatically.
- Multiple aliases for a single channel work in a much saner manner.
Each alias can be associated with a different comtitle.
- Two additional categories have been added to the stats() function. If
you have softcode that extracts the number of garbage objects in the
database from stats(), it will be fine if you used last(stats()) to
get the data; if you used extract() or another function that depended
upon list position, you will need to modify your code.
- Though MUX's help files documented the behavior of teleport locks, the
implementation didn't reflect the help. The implementation now works
the way help says it does.
Continued in 'help 3.0 upgrade mux4'.
& 3.0 upgrade mux4
The following is a list of features/functions that were in TinyMUSH 2.2.5,
but were not in TinyMUX 1.6, and which have become part of 3.0.
- Quotas by object type supported.
- Added building_limit conf parameter.
- Added player_parent, room_parent, exit_parent, thing_parent conf
parameters for default parent objects.
- Added log options keyboard_commands and suspect_commands.
- Decent password choices are enforced via safer_passwords.
- Guest can be locked out from sites via the guest_site parameter.
- SIGUSR1 is logged, and the game restarts as GOD, not #1.
- Note is written to log after @startup queue is run.
Continued in 'help 3.0 upgrade mux5'.
& 3.0 upgrade mux5
- Disconnect log includes command count, bytes input, and bytes output.
- New COMMANDS flag, the reverse of the NO_COMMAND flag, which has been
eliminated.
- New STOP flag, halts matching if a command is matched on a STOP object.
(Wizard-only.)
- NOSPOOF is only wiz-visible.
- The color substitution is now '%x' rather than '%c'.
- The '%c' substitution returns the last command.
- Added "lag checking".
- Added timechecking.
- @daily is now implemented using the @cron facility.
Continued in 'help 3.0 upgrade mux6'.
& 3.0 upgrade mux7
- @dump/optimize no longer exists, since the database is optimized after
every dump.
- @doing truncates the minimum possible (i.e., don't truncate for the ANSI
character unless necessary).
- Added @dolist/notify.
- @enable/@disable now appear in the logfile, like config updates do.
- Added @eval command.
- examine/brief now shows everything but the attributes on the object.
- INFO command implemented.
- Added '@list cache'.
- Hash statistics listing shows stats for @function hash table.
Continued in 'help 3.0 upgrade mux8'.
& 3.0 upgrade mux8
- @mvattr no longer clears the original attribute unless it was able
to copy it at least once.
- @pemit/noeval permits unparsed output.
- @pemit/list now obeys the /contents switch.
- There is a space after the @program prompt (2.2 behavior).
- Added object count to @search.
- @stats shows the next dbref to be created.
- The #$ @switch/switch() token has been added.
- Added @conformat and @exitformat contents and exits formatting.
- Command matches can be done unparsed through no_eval attribute flag.
Continued in 'help 3.0 upgrade mux9'.
& 3.0 upgrade mux9
- New BOUNCE flag acts like equivalent of @listen of '*' without @ahear.
- Added bor(), band(), bnand() functions.
- die() checks its arguments 2.2-style (so 0-100 is valid).
- Added filterbool() function.
- ifelse() now conditions on a boolean, rather than on a non-zero number.
- Added nonzero() function, which behaves like ifelse() used to.
- lastcreate() and the NewObjs attribute keep track of last-created
objects for a given thing.
- Added lpos() function.
- matchall() returns a null string, not 0, on no match.
Continued in 'help 3.0 upgrade mux10'.
& 3.0 upgrade mux10
- mix() can take up to ten arguments total.
- objeval() now preserves the cause (enactor) in the evaluation, and
allows the calling object to succeed if its owner is the same as
the evaluator's owner, instead of needing to _be_ the evaluator's
owner (2.2 behavior).
- Added programmer() function.
- Added remit() function, like pemit() but does contents.
- restarts() and restarttime() added.
- Added sees() function.
- shl(), shr(), inc(), dec() no longer require inputs to be numbers
(2.2 behavior).
- Added t() function.
Continued in 'help 3.0 upgrade mux11'.
& 3.0 upgrade mux11
- Added toss() function.
- Vector functions replaced by 2.2 ones, including addition of vdot().
This means that vector multiplication now works, but it breaks the
old MUX behavior of vmul().
- Added wipe() function.
- Added xcon() function.
- elements(), filter(), map(), munge(), setunion(), setinter(), setdiff(),
shuffle(), sort(), sortby(), splice() take output delimiters.
& 3.1 base
- '@list memory' gives a breakdown of the MUSH's memory usage.
'@list cache' shows an object-based summary of cache information.
'@list cache_attrs' shows the attributes in the cache.
- A new conf parameter, attr_type, allows attributes whose names match
certain wildcard patterns to be given certain default flags. Attribute
names can now start with '_'.
- New conf parameters exit_proto, room_proto, etc. allow one object of
each type to be defined as the "prototype" for new objects of that
type. When an object of that type is created, it copies the flags,
parent, zone (if 'autozone' is off), and attributes of the prototype;
the effect is similar to cloning.
Continued in 'help 3.1 base2'.
& 3.1 base2
- New conf parameters exit_attr_defaults, room_attr_defaults, etc.
allow one object of each type to be defined as the repository for
"attribute defaults" for many built-in attributes, such as
attr/oattr pairs (@desc, @odesc, @succ, @osucc, etc.), @conformat,
and @exitformat, as well as user attributes that have a global attribute
flag of 'default'. These defaults override the attributes set on
objects of that type (the local value of the attribute is passed
to it as %0, for evaluation). This allows the global definition
of formats for those attributes, without requiring a global
parenting scheme or an unusual attribute naming scheme. Objects
with the FREE flag ignore attribute defaults.
- The new conf parameter, c_is_command, controls whether %c is last
command (default) or ANSI substitution.
- The new conf parameter forwardlist_limit allows you to set a limit
for the number of objects that can be listed in a single @forwardlist.
Continued in 'help 3.1 base3'.
& 3.1 base3
- The new conf parameter function_cpu_limit allows you to set a limit
for the number of seconds of CPU time that can be taken up by
function evaluations associated with a command.
- The new conf parameters guest_basename, guest_prefixes, guest_suffixes,
and guest_password allow flexible naming of guests. See the FAQ for
details. (The guest_prefix parameter is now obsolete, and has been
removed.)
- The new conf parameter huh_message lets you change the Huh? message
that is displayed when a command cannot be matched.
- The new conf parameter power_alias allows you to set aliases for powers.
- The new conf parameter visible_wizards (disabled by default) results
in DARK wizards being hidden from WHO (and related things), but not
being invisible and silent. This prevents accidental or deliberate
spying by DARK wizards.
Continued in 'help 3.1 base4'.
& 3.1 base4
- Garbage is trimmed from the top of the database, if possible, reducing
bloat due to tail-end garbage.
- When an object name is ambiguously matched (i.e., potentially matches
several objects), the match is now truly chosen randomly; in the past,
the last match was heavily favored.
& 3.1 attrs
- @aconnect and @adisconnect attributes are triggered consistently on all
connections and disconnections, with a reason in %0 and the player's
resulting number of open connections in %1.
- Players can now specify multiple aliases for themselves (up to
the conf parameter player_aliases_limit), via @alias, separating
aliases with ';'. Players no longer inherit @alias from their
parent (this never made sense, or worked properly, anyway).
- @conformat and @exitformat get their visible contents/exits lists
passed as %0.
- A new attribute, LastIP, tracks the last IP address of a player.
When Lastsite is set, the identd user and hostname are no longer
truncated.
- The new attribute @nameformat controls the display of location's name
when someone looks at the location.
Continued in 'help 3.1 attrs2'.
& 3.1 attrs2
- The format and text of a say and pose can be arbitrarily altered, via the
@speechformat attribute and SPEECHMOD flag on the speaker, or the
speaker's location.
- General visibility of an attribute is now consistently controlled by the
'visual' attribute flag (previously it was controlled by 'private' on the
global attribute definition, and 'visual' on the specific attribute).
Attributes default to not visual; if you were previously defining global
attributes with '!private' (via @attribute/access, user_attr_access, etc.)
you should now define them as 'visual'.
- Visibility restrictions on attributes have been sanitized, so they are
consistent across commands and functions.
- Attribute flags that have no meaning on a global basis can no longer
be set globally via @attribute and the like, thus reducing confusion.
- The global flags for attributes are now shown in parentheses, when
an object is examined.
Continued in 'help 3.1 attrs3'.
& 3.1 attrs3
- A new attribute flag, 'case', controls whether regular expression matching
is case-sensitive, for $-commands, ^-listens, @filter, @infilter, and
@listen.
- A new attribute flag, no_name, controls whether or not the actor's
name is prepended when an attribute is used as an @o-attr, such as
an @osucc or with @verb.
- @filter, @infilter, and @listen do regular expression matches if
set 'regexp'. They do not evaluate themselves before matching,
if set 'no_parse'.
- A new attribute flag, 'rmatch', assigns the results of a $-command's
wildcard-match, to named local registers, as well as to the stack.
& 3.1 flags
- If a wizard connects while DARK, they are reminded that they are
currently set DARK. Also, wizards are notified when they are set
DARK due to idle-wizards-being-set-dark. A player must have the
Hide power or equivalent in order to auto-dark.
- There is a new type of lock, the DarkLock, which controls whether or
not a player sees an object as DARK. Based loosely on a patch by
Malcolm Campbell (Calum).
- There is a new power, Cloak, which is God-settable. It enables an
object which can listen (such a player or puppet) to be dark in the
room contents and movement messages; previously, this was only true
for listening objects both Dark and Wizard. Note that since wizard
Dark is now affected by the visible_wizards config parameter, if that
parameter is enabled, wizards will need this power in order to
become invisible.
Continued in 'help 3.1 flags2'.
& 3.1 flags2
- The new ORPHAN flag, when set on an object, prevents the object from
inheriting $-commands from its parents (just like objects in the master
room do not inherit $-commands from their parents). This allows you to
@parent a command object to a data object, without worrying about the
overhead of scanning the data object for $-commands.
- The new PRESENCE flag, in conjunction with six new locks (HeardLock,
HearsLock, KnownLock, KnowsLock, MovedLock, MovesLock) supports "altered
reality" realm states such as invisibility.
- An object with the new attr_read power is able to see attributes
with the 'hidden' attribute flag, just like Wizards and Royalty can.
- An object with the new attr_write power is able to set attributes
with the 'wizard' attribute flag, just like Wizards can.
- An object with the new link_any_home power can set the home of any
object (@link an object anywhere), just like Wizards can.
& 3.1 commands
- Some commands that would normally be queued can now be executed
immediately, using the /now switch: @dolist/now (@iter), @force/now,
@switch/now (@branch), @trigger/now (@call), @verb/now
force() and trigger() now behave like @force/now and @trigger/now.
The new conf parameters command_invocation_limit and
command_recursion_limit are used to limit this behavior.
- A user-defined $-command is executed immediately if the attribute has
the new Now attribute flag.
- Commands added via @addcommand are now run immediately. Also, these
commands now respect an escaped-out ':', as well as the regexp and
case attribute flags.
- A new switch, @addcommand/preserve, causes the text of an added
command to be executed by the player, not by the specified object,
unless the player is God (for security reasons).
Continued in 'help 3.1 commands2'.
& 3.1 commands2
- Custom comsys headers can now be specified for channels, via
@channel/header. These headers can be listed via @clist/header.
Also, the @channel command now interprets its arguments, and channel
descriptions are passed through a sanity check.
- The new Spoof comsys flag, when set on a channel, replaces player names
with their comtitles, instead of prepending the comtitle to the player
name.
- @cpattr can copy multiple attributes at a time.
- Exits can now @destroy themselves.
- @doing (including @doing/header) now takes a /quiet switch.
- A new command, @floaters, shows floating rooms. Floating rooms are no
longer reported by @dbck, and thus the FLOATING flag has been eliminated
(since it's no longer needed to suppress @dbck spam).
- The new /permit switch to @hook allows the permissions for a built-in
command to be defined via a user-defined function.
Continued in 'help 3.1 commands3'.
& 3.1 commands3
- Functions defined via @function can be listed via @function/list.
- Function permissions can be listed via '@list func_permissions'.
- Lock syntax is now always sanity-checked. Unbalanced parentheses within
a lock are no longer permitted.
- The new @log command can be used to log arbitrary messages to the
logfile(s).
- When you log in, you are warned if you are currently in the midst
of writing a @mail message.
- A @mail recipient now receives only a single copy of a @mail message,
even if he appears multiple times in the list of players the message
is to.
- @mail now has real carbon-copy and blind-carbon-copy. Patch from Simon Bland.
Continued in 'help 3.1 commands4'.
& 3.1 commands4
- @pemit/list now obeys the same permission checks as @pemit, including
obeying pemit_any as well as restricting use of the /contents switch.
- The @emit, @oemit, @femit, @fpose, @fsay, page, pose, and say commands
now take a /noeval switch. (Analogous to the /noeval switch for @pemit.)
- The @pemit and @oemit commands now take a /speech switch, which makes
the message subject to Presence checks.
- The new @redirect command can be used to redirect Trace, Puppet, and
Verbose output from an object, to a player other than the object's
owner. The REDIR_OK flag allows an object's output to be redirected
by someone who does not control it, thus allowing non-Wizards to
participate in mutual debugging sessions. Based on an idea from
AlloyMUSH.
- The new @reference command creates named references ("nrefs"), which
behave like aliases for dbrefs, in the form of '#_<name>'.
Continued in 'help 3.1 commands5'.
& 3.1 commands5
- The new conf parameter say_uses_comma, if enabled, will insert the
grammatically-correct comma into say and @fsay.
- The new conf parameter say_uses_you, if enabled, will always show the
speaker '<name> says' rather than 'You say'.
- A @dbck is automatically done before a @restart or normal @shutdown,
so recycling cleanup is done first, thus avoiding inconsistencies
upon startup.
- The @teleport command can now be used on exits. Players with the
Open_Anywhere power can now drop or @teleport exits to any location.
- Specifying an object to @trigger is now optional; if no object is
specified, the object defaults to 'me'.
- @verb now takes a no_name switch, which prevents the actor's name from
being prepended to the default o-message.
- Attributes containing a $command or ^monitor can now be @trigger'd
directly, as well as used as @a-actions; everything before the first
un-escaped ':' is ignored. Based on an idea from PennMUSH.
& 3.1 functions
- Multi-character input and output delimiters are now supported for
most functions.
- There are additional global registers, %qa-%qz (based on an idea from
PennMUSH). Furthermore, arbitrarily-named global registers can be defined
on the fly (up to the conf parameter register_limit, per action list).
setq() can now take multiple name-value pairs.
- The caller of a function can now be tracked via %@; it's normally equal
to the enactor, except where u()-type functions, including objeval()
and @functions, are called. This provides better security-checking
capabilities. Based on an idea from PennMUSH.
- The %m substitution can now be used for last command (MUX2 compatibility;
%c is the usual substitution).
- Brackets are no longer required around eval-locks, hooks, or @exitto code.
- The *<player> syntax is supported in many more places.
Continued in 'help 3.1 functions2'.
& 3.1 functions2
- There is a more informative error message when a function is given the
wrong number of arguments. Idea from Philip Mak.
- Extended regular expression syntax from Perl 5 is now supported.
This is based on the PCRE library, as modified by the PennMUSH team.
- New regular expression functions: regedit(), regediti(), regeditall(),
regeditalli(), regrab(), regrabi(), regraball(), regraballi(),
regrep(), regrepi(), regmatchi(), regparsei().
- Added a variety of comsys-related functions: cemit(), comalias(),
comdesc(), comheader(), cominfo(), comlist(), comowner(), comtitle(),
cwhoall().
- Added fcount(), fdepth(), ccount(), cdepth(), for getting function and
command invocation and recursion counters. Based on a concept from
Shadowrun Denver MUSH.
Continued in 'help 3.1 functions3'.
& 3.1 functions3
- The filter(), filterbool(), map(), and while() functions pass the
position of the element in the list as %1. fold() passes the position
of the element in the list as %2. foreach() passes the position of
the character in the string (starting from position 0). Based on
an idea from PennMUSH.
- The idle(), conn(), and doing() functions can now take a port number.
- The escape(), secure(), capstr(), lcstr(), and ucstr() functions now
handle ANSI properly.
- Added border(), rborder(), and cborder(). These are word-wrap functions
which can left/right/center-justify text within the field, and add
left and right-margin borders.
- Added cand(), cor(), candbool(), and corbool(), similar to and() etc.,
except these functions stop evaluating their arguments once a terminating
conclusion is reached. Based on an idea from PennMUSH.
Continued in 'help 3.1 functions4'.
& 3.1 functions4
- chomp() can now handle a lone CR or LF.
- choose() picks an element from a list on a weighted-random-choice basis.
- Added connrecord(), connected player record (as in WHO).
- Added entrances() function, similar to @entrances command. Based on an
idea from PennMUSH.
- Added elockstr(), to check if an object would pass the lock defined by
a string. Idea from Joel Ricketts.
- You can now get attribute flags with flags(<obj>/<attr>). Based on an
idea from PennMUSH.
- Added graball(), which is to grab() what matchall() is to match().
- Added group(), for splitting/sorting a list into groups.
- hasflag() can now detect object types.
Continued in 'help 3.1 functions5'.
& 3.1 functions5
- Added hasflags(), which can operate on multiple lists of flags and
types, returning true if all elements in any of the lists are true.
- Added hears(), moves(), and knows() functions for checking Presence
permissions.
- helptext() retrieves an entry from an indexed textfile (help, news, etc.).
- The third argument to ifelse() -- the 'false' result -- is now optional.
- Added istrue() and isfalse() -- iter()-style filterbool() and its reverse.
- Added ilev(), itext(), and inum() functions, for retrieving data
from multiple levels of nested iter()-type functions. Based on
an idea from PennMUSH.
- Added itemize() function, which formats a list of items. Typically used
to turn a list of words into something like "a, b, and c". Based on an
idea from PennMUSH.
Continued in 'help 3.1 functions6'.
& 3.1 functions6
- Last-accessed and last-modified timestamps are now tracked for all
objects. The timestamps are visible on an 'examine', and the seconds-value
can be retrieved via the new functions lastaccess() and lastmod().
- Added ledit() function, a mass find-and-replace on a list which can
replace many instances of nested edit() calls.
- lpos() can now check multiple characters at one time. Based on a
suggestion from Joel Ricketts.
- lpos(), lattr(), lexits(), lcon(), xcon(), children(), lparent(), and
the grep() family now take an output delimiter.
- The ljust(), rjust(), and center() functions can take multi-character
fills.
- The lunion(), linter(), and ldiff() functions are similar to setunion(),
etc., but an attempt is made to autodetect the list type and sort
accordingly, or you can specify a sort type, as you can with sort().
Continued in 'help 3.1 functions7'.
& 3.1 functions7
- The modify() function now takes lists, enabling multiple variables
to be modified at once.
- The behavior of remainders in division with negative numbers is
now consistent (rather than being compiler-dependent), including
new modulo(), remainder(), and floordiv() functions. The mod()
function is now an alias for remainder(), which is closest to
the old mod() on most platforms; if you want it to be an alias
for modulo() instead, change it in alias.conf
- munge() now passes its input delimiter to the u-function, as %1.
Idea from PennMUSH.
- Added objcall(), which evalutes the text of an attribute from another
object's perspective, like a combination of u() and objeval(). Idea
from Joel Ricketts.
- Added oemit(), which is the function equivalent of @oemit.
- Added nattr(), which counts the number of attributes on an object.
- rloc() now returns the destination of an exit.
Continued in 'help 3.1 functions8'.
& 3.1 functions8
- New search classes -- ueval, uthing, uplayer, uroom, uexit -- have
been added, allowing a u-function to be called for evaluation. This
makes it unnecessary to deal with brackets-escaping issues.
- sees() can now evaluate the visibility of exits as well as things.
Also, a small bug has been fixed: the see_owned_dark calculation in
sees() now uses the object doing the looking, not the player invoking
the function.
- Added session(), which returns command count, bytes of input, and
bytes of output associated with a port.
- Added speak(), which formats, parses, and transforms speech strings.
- Added store(), which is basically to setx() what setr() is to setq().
Continued in 'help 3.1 functions9'.
& 3.1 functions9
- The new structure functions read() and write() allow the use of an
"invisible" delimiter, which permits data to be stored in delimited
lists without worrying about user-provided data containing the
delimiter character. The delimit() function processes a stored
list, substituting a separator string for a delimiter.
- Added table(), tables(), rtables(), and ctables() functions. table()
is based on an idea from PennMUSH, formatting text within a table of
equally wide columns. The other three functions format text within
a table of variably-wide columns (left/right/center-justified), with
left and right-margin borders.
- Added timefmt() function. This is essentially an interface to the C
library function strftime(), allowing the time to be formatted in
psuedo-arbitrary ways. Based on an idea from PennMUSH.
- translate() now handles tabs.
- trim() now handles multi-character trim strings.
Continued in 'help 3.1 functions10'.
& 3.1 functions10
- Added sind(), cosd(), tand(), asind(), acosd(), atand() degree-based
trigonometry functions.
- Added until() function, which is similar to while(), except it operates
on multiple lists and terminates on a regular expression condition.
- valid() can now detect valid attribute names and player names, for
PennMUSH compatibility.
- Added whentrue() and whenfalse() functions, which go through a list
iter()-style until a terminating boolean condition is reached.
- Added wildgrep(), wildmatch(), and wildparse(), which are similar to
regrep(), regmatch() and regparse(), but work against wildcard patterns
rather than regexps.
- Added writable() function, which returns 1 if object X can set an
attribute A on object Y.
Continued in 'help 3.1 functions11'.
& 3.1 functions11
- Added @@() function, which is like null(), but does not evaluate
its argument.
- elock(), hasflag(), haspower(), and type() now all return #-1 NO MATCH
when they can't find the object they're checking. Previously they
returned #-1 NOT FOUND; for consistency's sake, they now behave like
everything else.