TinyMUCK 2.2 fb 5.30 MUF Manual

PRIMITIVES
LOOPS
DIRECTIVES
LIBRARIES
LEVELS
MULTITASKING
FLAGS
MISCELLANEOUS
CREDITS

LOOPS

The BEGIN statement marks the beginning of a loop.
Either the UNTIL or the REPEAT statement marks the end of the loop.
REPEAT will do an unconditional jump to the statement after the BEGIN statement.
UNTIL checks to see if the value on the stack is false. If it is, it jumps execution to the statement after the BEGIN statement, otherwise, it falls through on execution to the statement after the UNTIL.

Within a loop, even within IF-ELSE-THEN structures within the loop structure, you can place WHILE, CONTINUE, or BREAK statements. There is no limit as to how many, or in what combinations these instructions are used.

A WHILE statement checks to see if the value on the stack is false. If it is, execution jumps to the first statement after the end of the loop. If the value was true, execution falls through to the statement after the WHILE.
The CONTINUE statement forces execution to jump to the beginning of the loop, after the BEGIN.
The BREAK statement forces execution to jump to the end of the loop, at the statement after the REPEAT or UNTIL, effectively exiting the loop.

Note: You can nest loops complexly, but WHILE, BREAK, and CONTINUE statements only refer to the innermost loop structure.

Example of a complex loop structure:

 
 101 begin (BEGIN the outer loop)
 dup while 1 - (This WHILE, ...)
 dup not if break then (this BREAK, and..)
 dup 2 % not if continue then (this CONTINUE refers to the outer loop)
 dup 10 % not if
 15 begin (BEGIN inner loop)
	dup while 1 - (This WHILE, and.. )
	dup 5 % not if break then (... this BREAK, refers to inner loop)
 repeat (This REPEAT statement ends inner loop.)
 then
 dup 7 % not if continue then (This CONTINUE, and...)
 dup 3 % not if dup 9 % while then (this WHILE refers to the outer loop)
 dup intostr me @ swap notify
 dup 1 = until pop (This UNTIL ends the outer loop)

FLAGS

Flags that have importance to MUF:

If a program is set DARK (DEBUG), then when it is run, it will print out a stack trace for each instruction executed, to the player running the program. This is useful for debugging programs.
On dbload, if a program is set ABODE (AUTOSTART), *AND* it is owned by a wizard, then it will be placed in the timequeue with a delay of 0 and a string parm of "Startup". Autostart programs run with the location NOTHING (#-1) rather than the location of the owner of the program.
If a program has the HAVEN flag set on it (HARDUID) then it runs with the uid and permissions of the owner of the trigger of the program. If the program is a timequeue event with trigger of #-1, then it will run with the permissions and uid of the program owner as in SETUID.
If a program is set both SETUID and HARDUID, and it is owned by a wizard, then it inherits the uid and mucker level of the program that called it. If it was not called by a program, then it runs SETUID. This is useful for writing libraries.
Programs set BUILDER (BOUND) run in preempt mode, regardless of the mode of the program. ie: a foreground program, while running in a program set BOUND, will run pre-empt, with the multitasking effectively shut off.
A program that is set WIZARD ignores almost all permissions checking.

The Mucker Level of the program also has a great deal of influence on what a program can and cannot do. See also MUCKER LEVELS for more information.

MISCELLANEOUS

When a message is notify_except'ed or notify_exclud'ed to a room, and LISTENERS and LISTENERS_ENV are defined, then it will run ALL the programs referred to in all the _listen properties down the environment tree, And in all of the objects in the room with LISTENERS_OBJ defined. Also, the muf NOTIFY primitive was changed to run the _listen program on an object or player if a message is sent to them that way.

There is a COMMAND variable, similar to ME, LOC, and TRIGGER, except that it contains a string. The string contains the command the user typed that triggered the the program, without the command line arguments. ie: if there was an exit named "abracadabra;foo bar;frozzboz" that was linked to the program, and the user typed in "foo bar baz", then the program would run with "baz" on the stack, and "foo bar" in the global COMMAND variable.

Programs are now compiled when they are run or called instead of when the databate is loaded. They are compiled with the uid of the owner of the program.

A room or player may have a "_connect" property set that contains the dbref of a program to run when a player connects. The program must be either link_ok or must be owned by the player connecting. When the program is run, the string on the stack will be "Connect", the "loc @" will be the location of the connecting player, the "me @" will be the connecting player, and the "trigger @" (and "trig") will be the object that had the _connect property on it. All programs referred to by _connect properties on the player, and on rooms down the environment tree from the player, will be QUEUEd up to run. When a player desconnects, programs referred to by _disconnect properties will be run in a similar manner. (connect and disconnect _actions_ are also implemented.)

Programs refered to by props in _depart/_arrive/_connect/_disconnect propdirs will all be queued up, eliminating the need for a dispatcher program. An example would be _connect/announce:1234 That would queue up program #1234 when a player connects. The name ("announce") is not important, and can be anything you want, but they are queued up in alphabetic order.

DIRECTIVES

Compiler directives for MUF:

$define defname definition $enddef

Basically the same as C's #define defname definition

$def defname definition

This is the same as $define, except that the definition stops at the end of the program line, without using an ending $enddef.

$undef defname

About the same as C's #undef defname

$echo string

Echos the given string to the screen of the person compiling the program. Runs at compile-time.

__version

A pre$defined macro that contains the current server version. Contains the same string that the VERSION primitive returns.

$ifdef condition compile this if true $else compile if false $endif or

$ifndef condition compile this if true $else compile if false $endif

where condition is either a $defined name, or a test that consists of a $defined name, a comparator (=, <, or >) and a test value, all in one word without space. The $else clause is optional. Compiler directives are nestable also.

Some examples:

    $ifndef __version>Muck2.2fb3.5 $define envprop .envprop $enddef $endif
    $define ploc $ifdef proplocs .proploc $else $endif $enddef

$include dbref|progreg

Sets a bunch of $defines from the properties in the /_defs/ propdir.

For example, if object #345 had the following properties:

 
    /_defs/desc: "_/de" getpropstr
    /_defs/setpropstr: dup if 0 addprop else pop remove_prop then
    /_defs/setpropval: dup if "" swap addprop else pop remove_prop then
    /_defs/setprop: dup int? if setpropval else setpropstr then

then if a program contained '$include #345' in it, then all subsequent references to 'desc', 'setpropstr', 'setpropval', and 'setprop' would be expanded to the string values of their respective programs. ie: 'desc' would be replaced throughout the program with '"_/de" getpropstr'

You can now escape a token in MUF so that it will be interpreted literally. ie: \.pmatch will try to compile '.pmatch' without expanding it as a macro. This lets you make special things with $defines such as: $define addprop over over or if \addprop else pop pop remove_prop $enddef so that all the 'addprop's in the program will be expanded to the definition, but the 'addprop' in the definition will not try to expand recursively. It will call the actual addprop.

LIBRARIES

How to use a library:

Use "@register lib" to list what libraries exist.
Use "@view $lib/libraryname" to list the docs on that library.
When you've found the library and the function you want, then all you have to do in your program is, at the beginning of it, $include $lib/libraryname
Now just use the function name to invoke it later in your program and it will run as if it were a function in your program.

How to make a library:

create a program with several useful generic subroutines.
DOCUMENT those subroutines in a commented out header in the prog.
@set program=_docs:command to list those DOCS you made
make sure that all the functions are declared PUBLIC.
Make sure the program is set LINK_OK.
Globally register the program with the @register command with a prefix of "lib/". ie: @reg lib-strings=lib/strings
Set up the interface for each function on the program. To do this, you will need to set properties on the program in the form _defs/callname:"$libname" match "funcname" call where callname is the name that you want to have people use to invoke it in their programs, libname is the registered name you gave it (ie: lib/strings), and funcname is the actual name of the function in the program. Example: @set lib-strings=_defs/.split:"$lib/strings" match "split" call
You're done!

Currently standard libraries:

$lib/strings - Functions for manipulating strings.
$lib/props - Routines for searching for properties, or setting them.
$lib/lmgr - Standard list manager routines.
$lib/stackrng - Routines to handle variable sized ranges on the stack.
$lib/edit - String range editing and manipulation routines.
$lib/editor - Standard user text editor.
$lib/mesg - Standard message manager routines.
$lib/mesgbox - Routines for handling lists of messages.
$lib/match - Object or string matching routines.
$lib/reflist - Dbref-list management routines.
$lib/index - Hashed linked list manager with partial key matching.

MUCKER LEVELS

There are now four levels of MUCKERs in fb4.0. Level zero is a non-mucker. They cannot use the editor, and MUF programs owned by them cannot be run.

Level one MUCKER's are apprentices. Their powers are restricted as they cannot get information about any object that is not in the same room they are. ie: OWNER, NAME, LOCATION, etc all fail if the object isn't in the same room as the player. Level one MUCKER programs always run as if they are set SETUID. NOTIFY, NOTIFY_EXCEPT, and NOTIFY_EXCLUDE will refuse to send messages to rooms the user is not in. Level one programs cannot use ADDPENNIES. Level one programs don't list DARK objects or rooms in the contents of a room, unless they are controlled by the program owner. Additionally, level one programs have an absolute instruction limit that is the same size as the PREEMPT instruction limit. This is usually around 20,000 instructions.

Level two MUCKERs are also called Journeymen. Their permissions are equivalent to the permissions for a normal MUCKER under older versions of the server. Level two programs can run as many as four times the number of instructions that a preempt program could. This is usually around 80,000 instructions.

Level three MUCKERs are referred to as Masters. They can use the con- nection info primitives (ie: CONDBREF, ONLINE, etc.), read the EXITS list of any room, use NEXTPROP on objects, can use NEWROOM, NEWOBJECT, NEWEXIT, and COPYOBJ without limitations, can use QUEUE and KILL, and can override the permissions restrictions of MOVETO. You only give a player MUCKER level 3 if they are very trusted. There is no absolute instruction count limit for level three or above, except for programs running in PREEMPT mode.

A player who is wizbitted is effectively Mucker Level 4. MUCKER level four is required for the RECYCLE primitive, the CONHOST primitive, the FORCE primitive, and the SETOWN primitive. ML4 also allows overriding of permissions of the SET* primitives, and property permissions. Props not listed by NEXTPROP with ML3 are listed with ML4. Programs running ML4 do not even have instruction limits on PREEMPT mode programs.

The MUCKER level permissions that a program runs at is the lesser of it's own MUCKER level and the MUCKER level of it's owner. If it is owned by a player who is MUCKER level 2, and it is MUCKER level 3, then it runs at Muckr level 2. The one exception to this is programs owned by a Wizard player. They run at Mucker level 2 if the program itself is not wizbit, and at Mucker level 4 if the program IS set wizbit.

Mucker level is referred to in flags lists by M# where the # is the Mucker level. Level zero objects don't show a flag for it.

    Example: Revar(#37PM3)

In verbose flags lists, Mucker levels greater than zero are shown by MUCKER# where # is the mucker level.

To set a level on a player or program, use the level number as the flag name. MUCKER is the same as 2, and !MUCKER is the same as 0.

    Example: @set Revar=2

A player may set the MUCKER level on a program they own to any level lower than or equal to their own level, and a wizard may set a program or player to any MUCKER level.

When a program is created, it is automatically set to the same MUCKER level as the creating player. When a program is loaded from an old db, if it is Mucker Level 0, it is upgraded to Mucker Level 2.

MULTITASKING

There are now 3 modes that a program can be in when running: foreground, background, and preempt. A program running in the foreground lets other users and programs have timeslices (ie multitasking), but blocks input from the program user. Background mode allows the user to also go on and do other things and issue other commands, but will not allow the program to do READs. Preempt mode means that the program runs to completion without multitasking, taking full control of the interpreter and not letting other users or progs have timeslices, but imposes an instruction count limit unless the program is a wizard program.

Programs run by @locks, @descs, @succs, @fails, and @drops default to the preempt mode when they run. Programs run by actions linked to them default to running in foreground mode. QUEUEd program events, such as those set up by _listen, _connect, _disconnect, etc, and those QUEUEd by other programs default to running in background mode. (NOTE: these programs cannot be changed out of background mode)

See also FOREGROUND, BACKGROUND, PREEMPT, FORK, QUEUE, KILL, and SLEEP.

MUF PRIMITIVES

a - function address.
d - dbref. (#-1, #-2, #-3 are okay)
D - valid, non-garbage dbref. (#-1, #-2 NOT allowed. #-3 is okay)
e - exit dbref. (#-1, #-2 allowed)
E - exit dbref. (#-1, #-2 NOT allowed)
f - program dbref. (#-1, #-2 allowed)
F - program dbref. (#-1, #-2 NOT allowed)
i - integer.
l - lock boolean expression.
p - player dbref. (#-1, #-2 allowed)
P - player dbref. (#-1, #-2 NOT allowed)
r - room dbref. (#-1, #-2 allowed) (#-3 is a room)
R - room dbref. (#-1, #-2 NOT allowed) (#-3 is a room)
s - string.
S - non-null string.
t - thing dbref. (#-1, #-2 allowed)
T - thing dbref. (#-1, #-2 NOT allowed)
v - local or global variable.
? - any stack item type.

Tests can be repeated multiple times by following the test with a number. ie: '"i12" checkargs' would test the stack for 12 integers.

The last test in the string expression will be done on the top stack item. Tests are done from the top of the stack down, in order, so the last test that fails in a string expression will be the one that the Program Error will be given for. ie: '"sdSi" checkargs' will test that the top stack item is an integer, then it tests that the next item down is a non-null string, then it tests the third item from the top to see if it is a dbref, and lastly it tests to make sure that the 4th item from the top is a string.

Spaces are ignored, so "s d i" is the same as "sdi". However, multipliers are ignored if they follow a space, so "s 4d i" is also the same as "sdi". This is because you are basically telling it to repeat the space 4 times, and since spaces are ignored, it has no effect.

If you have a function that takes a stack item of any type, you can use the "?" test. "?" will match a string, integer, dbref, or any other type.

Since sometimes arguments are passed in ranges, such as the way that the explode primitive returns multiple strings with an integer count on top, there is a way to group arguments, to show that you expect to recieve a range of that type. ie: '"{s}" checkargs' would test the stack for a set of strings like '"first" "second" "third" "fourth" 4' where the top stack item tells how many strings to expect within the range.

Sometimes a function takes a range of paired arguments, such as: '"one" 1 "two" 2 "three" 3 "four" 4 4' where the count on the top of the range refers to the number of pairs. To test for the range given above, you would use '"{si}" checkargs' to tell it that you want to check for a range of paired strings and integers. You can group as many argument tests together in a range as you would like. ie: you could use "{sida}" as an expression to test for a range of related strings, integers, dbrefs, and function addresses.

Since the argument multipliers refer to the previous test OR range, you can test for two string ranges with the test '"{s}2" checkargs'. ie: It would succeed on a stack of: '"one" "two" "three" 3 "four" "five" 2'. '"{s2}" checkargs', however, would test for one range of paired strings. ie: It would succeed with a stack of: '"one" "1" "two" "2" "three" "3" 3'.

If, for some reason, you need to pass a range of ranges to a function, you can test for it by nesting the braces. ie: '"{{s}}" checkargs'

Now, as one last example, the primitive notify_exclude, if we were to test the arguments passed to it manually, would use the test '"R{p}s" checkargs' to test for a valid room dbref, a range of player dbrefs or #-1s, and a string.

conboot (i -- )

Takes a connection number and disconnects that connection from the server. Basically @boot for a specific connection.

(wizbit only)

concount ( -- i)

Returns how many connections to the server there are.

(Requires Mucker Level 3)

condbref (i -- d)

Returns the dbref of the player connected to this connection.

(Requires Mucker Level 3)

condescr ( i -- i )

Takes a connection number and returns the descriptor number associated with it.

(Requires Mucker Level 3)

conhost (i -- s)

Returns the hostname of the connection.

(wizbit only)

conidle (i -- i)

Returns how many seconds the connection has been idle.

(Requires Mucker Level 3)

connotify (i s -- )

Sends a string to a specific connection to the server.

(Requires Mucker Level 3)

contents ( d -- d' )

Pushes the dbref of the first thing contained by d. This dbref can then be referenced by 'next' to cycle through all of the contents of d. d may be a room or a player.

contime (i -- i)

Returns how many seconds the given connection has been connected to the server.

(Requires Mucker Level 3)

continue ( -- )

Jumps execution to the beginning of the current loop.

See also, LOOPS.

copyobj ( d -- d' )

Creates a new object (returning d' on top of the stack), that is a copy of object d. Each program is allowed to create only one new object per run.

date ( -- i i i)

Returns the monthday, month, and year. ie: if it were February 6, 1992, date would return 6 2 1992 as three integers on the stack.

dbcmp ( d1 d2 -- i )

Performs comparison of database objects d1 and d2. If they are the same object, then i is 1, otherwise i is 0.

dbref ( i -- d )

Converts integer i to object reference d.

dbref? ( x -- i )

Returns true if x is a dbref.

dbtop ( -- d)

Returns the dbref of the first object beyond the top object of the database. 'dbtop ok?' would return a false value.

depth ( -- i )

Returns the number of items on the stack.

desc ( d -- s )

Takes object d and returns its description (@desc) string field.

descrcon (i -- i)

Takes a descriptor and returns the associated connection number, or 0 if no match was found.

descriptors (d -- ix...i1 i)

Takes a player dbref, or #-1, and returns the range of descriptor numbers associated with that dbref (or all for #-1) with their count on top. Descriptors are numbers that always stay the same for a connection, while a connection# is the relative position in the WHO list of a connection.

drop ( d -- s )

Takes object d and returns its drop (@drop) string field.

dup ( x -- x x )

Duplicates the item at the top of the stack.

envpropstr (d s -- d s )

Takes a starting object dbref and a property name and searches down the environment tree from that object for a property with the given name. If the property isn't found, it returns #-1 and a null string. If the property is found, it will return the dbref of the object it was found on, and the string value it contained.

execute ( a -- ?? )

Executes the function pointed to by the address a on the stack.

exit ( -- )

Exits from the word currently being executed, returning control to the calling word, at the statement immediately after the invokation of the call (exiting the program if applicable).

exit? ( d -- i )

Returns 1 if object d is an exit object, 0 if otherwise.

exits ( d -- d' )

Returns the first exit in the linked exit list of room/player/object d. This list can be transversed with 'next'.

explode ( s1 s2 -- ... i )

s2 is the delimiter string, and s1 is the target string, which will be fragmented, with i pushed on top of the stack as the number of strings s1 was broken into. For instance:

"Hello world" " " explode

will result in

"world" "Hello" 2

on the stack. (Note that if you read these items off in order, they will come out "Hello" first, then "world".) For TinyMUCK 2.2, s2 may be any length. But "" (null string) is not an acceptable string for parameter s2.

fail ( d -- s )

Takes object d and returns its fail (@fail) string field.

flag? ( d s -- i )

Reads the flag of object d, specified by s, and returns its state: 1 = on; 0 = off. Different flags may be supported in different installations. flag? returns 0 for unsupported or unrecognized flags. You can check the "interactive" flag to see if a player is currently in a program's READ, or if they are in the MUF editor.

force (d s -- )

Forces player d to do action s as if they were @forced. (wizbit only)

foreground ( -- )

To turn on multitasking, you can issue a foreground command. While a program is in foreground mode, the server will be multitasking and handling multiple programs at once, and input from other users, but it will be blocking any input from the user of the program until the program finishes. You cannot foreground a program once it is running in the background. A program will stay in foreground mode until it finishes running or until you change the mode.

fork ( -- i)

This primitive forks off a BACKGROUND (muf) process from the currently running program. It returns the pid of the child process to the parent process, and returns a 0 to the child. If the timequeue was full, then it returns a -1 to the parent process, and there is no child process.

(Requires Mucker Level 3)

getlink ( d -- d' )

Returns what object d is linked to, or #-1 if d is unlinked. The interpretation of link depends on the type of d: for an exit, returns the room, player, program, action, or thing that the exit is linked to. For a player, program, or thing, it returns its 'home', and for rooms returns the drop-to.

getlockstr ( d -- s )

Returns the lock expression for the given object in the form of a string. Returns "*UNLOCKED*" if the object doesn't have a lock set.

getprop (d s -- ?)

Gets the value of a given property, and puts it on the stack. This can return a lock, a string, a dbref, or an integer, depending on the type of the property. Permissions are the same as those for GETPROPSTR. This primitive returns 0 if no such property exists, of if it is a valueless propdir.

getpropstr ( d s -- s )

s must be a string. Retrieves string associated with property s in object d. If the property is cleared, "" (null string) is returned.

getpropval ( d s -- i )

s must be a string. Retrieves the integer value i associated with property s in object d. If the property is cleared, 0 is returned.

gmtoffset ( -- i)

Returns the machine's offset from Greenwich Mean Time in seconds.

if ... [ else ... ] then ( x -- )

Examines boolean value x. If x is TRUE, the sequence of statements after the 'if' up until the 'then' (or until the 'else' if it is present) performed. If it is FALSE, then these statements are skipped, and if an 'else' is present, the statements between the 'else' and the 'then' are performed. Control continues as usual at the statement after the 'then'. Note that checking the top of the stack actually pops it, so if you want to re-use it, you should dup (see also DUP) it before the if. For every IF in a word, there MUST be a THEN, and vice-versa. ELSE is optional.

instr ( s s1 -- i )

Returns the first occurrence of string s1 in string s, or 0 if s1 is not found.

instring ( s s1 -- i )

Returns the first occurrence of string s1 in string s, or 0 if s1 is not found. Non-case sensitive. This is an inserver define to 'tolower swap tolower swap instr'.

int ( x -- i )

Converts variable or object x to integer i.

int? ( x -- i )

Returns true if x is a int.

intostr ( x -- s )

x must be an integer or a dbref. Converts x into string s.

ispid? (i -- i)

Takes a process id and checks to see if an event with that pid is in the timequeue. It returns 1 if it is, and 0 if it is not. ispid? will also return 1 if the given process id is that of the currently running program.

This primitive requires at least mucker level 3.

jmp ( a -- )

The JMP Muf primitive takes an address like those supplied by 'funcname and moves execution to that point. It's one early way that was used to do tail-recursion loops without as much overhead, and without failing due to system stack overflows. It's mostly obsolete now, except that it's one of the three or four internal primitives used to implement if-else-then and begin-while-repeat loops and such.

Example of JMP as a tail-recursion optimization:

: countforever ( i -- )

1 +

dup intostr .tell

'countforever jmp

;

How MUF uses JMP internally to implement if-else-then. The following line of MUF:

random 2 % if "a" else "b" then me @ swap notify

Is implemented internally like:

1: Primitive: RANDOM

2: Integer: 2

3: Primitive: %

4: Address: Step 9 (address of instruction after ELSE)

5: Primitive: IF (basically a branch-if-zero command)

6: String: "a"

7: Address: Step 10 (address of instruction after THEN)

8: Primitive: JMP (Unconditional branch to implement ELSE)

9: String: "b"

10: Variable: 0 (me global variable)

11: Primitive: @

12: Primitive: SWAP

13: Primitive: NOTIFY

kill (i -- i)

Attempts to kill the process referred to by the given process ID. Returns 1 if the process existed, and 0 if it didn't.

(Requires Mucker Level 3)

localvar (i -- l)

Takes an integer and returns the respective local variable. Similar to the variable primitive.

location ( d -- d' )

Returns location of object d as object d'.

lock? (? -- i)

Returns true if the top stack item is a lock.

locked? (d d -- i)

Takes, in order, the dbref of the player to test the lock against, and the dbref of object the lock is on. It tests the lock, running programs as necessary, and returns a integer of 0 if it is not locked against them, or 1 if it is.

LVAR varname

This declares a variable as a local variable, that is local to a specific program. If another program calls this program, the values of the local variables will not be changed in the calling program, even if the called program changes them.

match ( s -- d )

Takes string s, first checks all objects in the user's inventory, then checks all objects in the current room, as well as all exits that the player may use, and returns object d which contains string s. If nothing is found, d = #-1. If ambiguous, d = #-2. If HOME, d = #-3.

mlevel (d -- i)

returns the mucker (or priority) level of the given object.

Also see MUCKER LEVELS.

mode ( -- i)

Returns an integer denoting the current multitasking mode. This ignores BOUND bits on programs. The integer this returns will be the same as one of those defined by the standard $defines bg_mode, fg_mode, and pr_mode, being background, foreground, and preempt mode, respectively.

moveto ( d1 d2 -- )

Moves object d1 to object d2.

MOVETO is affected by the following rules:

If the object being moved is !JUMP_OK and is it being moved by someone other than the object's owner, then the moveto fails.
If the object being moved is a person and either the source or destination rooms (if not owned by the person being moved) are !JUMP_OK, the moveto fails.
If the object being moved is not a player, is owned by the owner of either the source or destination rooms, and either room where the ownership matches is !JUMP_OK, the moveto fails.

The moveto succeeds under any other circumstances. MOVETO rules follow the permissions of the current effective userid. MOVETO will run programs in the @desc and @succ/@fail of a room when moving a player.

name ( d -- s )

Takes object d and returns its name (@name) string field.

newexit (d s -- d)

Takes location and name and returns new exit's dbref. Owner is the person running the program.

(program must have a wizbit)

newobject (d s -- d)

Takes location and name and returns new thing's dbref. Owner is the person running the program.

(program must have a wizbit)

newroom (d s -- d)

Takes the dbref of the parent and the name of the room. It returns the dbref of the created room. Owner is the person running the program.

(program must have a wizbit)

next ( d -- d' )

Takes object d and returns the next thing in the linked contents/exits list of d's location.

nextdescr (i -- i)

Takes a descriptor number, and returns the next connected descriptor number. To get the first descriptor number, use '1 condescr'. Between these, you can step through the descriptors list. If you try to use nextdescr on an invalid descriptor, it will return 0. If you have reached the end of the descriptor list, it returns 0.

(Requires Mucker Level 3)

nextprop (d s -- s)

This takes a dbref and a string that is the full propdir pathname of a property and returns the full pathname of the next property in the given object's given propdir, or returns a null string if that was the last property in the propdir. To *start* the search, give it a propdir name ending in a '/', or a blank string.

For example, '#10 "/" NEXTPROP'

returns the name of the first property in the root propdir of object #10, and '#28 "/letters/" NEXTPROP' would return the name of the first property in the 'letters/' propdir on object #28. A blank string is the same as "/". If you try to do a Nextprop on a non-existant property, you will have a null string returned to you. Nextprop will skip properties if they would not be readable by the program with the given permissions and effective user id.

(Requires Mucker Level 3)

not ( x -- i )

Performs the boolean 'not' operation on x, returning i as 1 if x is FALSE, and returning i as 0 otherwise.

notify ( d s -- )

d must be a player object. s must be a string. Tells player d message s. If s is null it will print nothing. This primitive will trigger the _listen'er property on the object the message is sent to, unless the program that would be run is the same as one one currently running.

notify_except ( d1 d2 s -- )

d1 must be a room object, s must be a string. Tells everyone at location d1 except object d2 message s. If object d2 is not a player or NOTHING (#-1) all players are notified. If s is null it prints nothing. NOTE: notify_except is now only an inserver $define. It is translated to '1 swap notify_exclude'. Please see the man sections on NOTIFY_EXCLUDE and DIRECTIVES for more information.

notify_exclude (d dn ... d1 n s -- )

Displays the message s to all the players (or _listening objects), excluding the n given players, in the given room. For example:

#0 #1 #23 #7 3 "Hi!" notify_exclude

would send "Hi!" to everyone in room #0 except for players (or objects) #1, #7, and #23. _listener's will not be triggered by a notify_exclude if the program they would run is the same as the current program running.

number? ( s -- i )

Returns 1 if string on top of the stack contains a number. Otherwise returns 0.

odrop ( d -- s )

Takes object d and returns its odrop (@odrop) string field.

ofail ( d -- s )

Takes object d and returns its ofail (@ofail) string field.

ok? ( x -- i )

Takes x and returns 1 if x is a type dbref, as well as 0 or above, below the top of the database, and is not an object of type garbage.

online ( -- d ... i )

Returns a dbref for every connection to the game, and lastly the number of connections.

or ( x y -- i )

Performs the boolean 'or' operation on x and y. Returns i as 1 if either x or y is TRUE, returns i as 0 otherwise.

osucc ( d -- s )

Takes object d and returns its osuccess (@osucc) string field.

over ( x y -- x y x )

Duplicates the second-to-top thing on the stack. This is the same as 2 pick.

owner ( d -- d' )

d is any database object. Returns d', the player object that owns d. If d is a player, d' will be the same as d.

parselock (s -- l)

Parses a lock string into a lock. If the parsing failed, then the lock returned will be a TRUE_BOOLEXP, which is logically false to an 'if' test.

parseprop (d s s i -- s)

Returns the string output of the MPI Parser, given an object, a property name to parse, an input string for the {&how} variable, and an integer that should either be 1, for when you want {delay} messages to be sent to the player only, or 0, when you want the rest of the players in the room to get the omessages. NOTE: for security reasons, you cannot use PARSEPROP with a mucker level of less than 3.

part_pmatch (s -- d)

Takes a player name, or the first part of the name, and matches it against the names of the players who are currently online. If the given string is a prefix of the name of a player who is online, then their dbref is returned. If two players could be matched by the given string, it returns a #-2. If None of the players online match, then it returns a #-1.

pennies ( d -- i )

Gets the amount of pennies player object d has, or the penny value of thing d.

pick ( ni ... n1 i -- ni ... n1 ni )

Takes the i'th thing from the top of the stack and pushes it on the top. 1 pick is equivalent to dup, and 2 pick is equivalent to over.

pid ( -- i)

Returns the process ID of the program that is currently running.

player? ( d -- i )

Returns 1 if object d is a player object, otherwise returns 0. If the dbref is that of an invalid object, it will return 0.

See also program?, room?, thing?, exit?, and ok?.

pop ( x -- )

Pops the top of the stack into oblivion.

preempt ( -- )

Prevents a program from being swapped out to do multitasking. Needed in some cases to protect crutial data from being changed while it is being worked on. A program will remain in preempt mode until it's execution is completed. Basically what this command does is to turn off multitasking, but then you have a limit on how many instructions you can run without needing either to pause with a SLEEP, or have a wizbit on the program.

prettylock (l -- s)

Unparses a lock into a string fit for players to see. See also LOCK?, PARSELOCK, UNPARSELOCK, TESTLOCK, GETLOCKSTR, SETLOCKSTR, and LOCKED?.

prog ( -- d)

Returns the dbref of the currently running program.

program? ( d -- i )

Returns 1 if object d is a program, otherwise returns 0. If the dbref is that of an invalid object, it will return 0.

See also player?, room?, thing?, exit?, and ok?.

pronoun_sub ( d s -- s' )

Takes database object d and substitutes string s according to o-message rules. For example:

me @ "%N has lost %p marbles." pronoun_sub

would return:

"Igor has lost his marbles."

if the player's name was Igor and his sex were male.

d does not have to be a player for the substitutions to work. The substitutions are

%a/%A for absolute possessive (his/hers/its, His/Hers/Its)
%s/%S for subjective pronouns (he/she/it, He/She/It)
%o/%O for objective pronouns (him/her/it, Him/Her/It)
%p/%P for possessive pronouns (his/her/its, His/Her/Its)
%r/%R for reflexive pronouns (himself/herself/itself,Himself/Herself/Itself)
%n/%N for the player's name.

if it comes across a %X substitution, where X is any character not listed in the above substitutions table, it will search down the environment tree from d to try to find the appropriate %X property for use in substitution.

propdir? (d s -- i)

Takes a dbref and a property name, and returns a boolean integer that tells if that property is a propdir that contains other props.

(Requires Mucker Level 3)

PUBLIC functionname

Declares a previously defined function to be public for execution by other programs. This is a compile-time directive, not a run-time primitive. To call a public function, put the dbref of the program on the stack, then put a string, containing the function name, on the stack, then use CALL.

For example:

#888 "functionname" CALL

put ( nx...n1 ni i -- nx...ni...n1 )

Replaces the i'th thing from the top of the stack with the value of ni. 1 put is equivalent to swap pop

Example:

"a" "b" "c" "d" "e" 3 put

would return on the stack:

"a", "e", "c", "d"

queue (i d s -- i)

Takes a time in seconds, a program's dbref, and a parameter string. It will execute the given program with the given string as the only string on the stack, after a delay of the given number of second. Returns the pid of the queued process, or 0 if the timequeue was full.

(Requires Mucker Level 3)

random ( -- i )

Returns a random integer from 0 to the MAXINT of the system running the MUCK. In general this number is (2^31)-1 or 2,147,483,647 (2.1 billion).

read ( -- s )

Reads a string s from the user. This command should not be used in a program that is locked (as opposed to linked) to an object, as the lock will always fail and print the fail messages at read time. It cannot be used in a program associated with a room object.

recycle (d -- )

Recycles the given object d. Will not recycle players, the global environment, the player starting room, or any currently running program.

(Can recycle objects owned by uid if running with Mucker Level 3 permissions. Can recycle other people's items with wizbit)

remove_prop ( d s -- )

Removes property s from object d. If the property begins with an underscore, '_' or a dot '.', and the effective user does not have permission on that object, the call fails.

repeat ( -- )

Jumps execution to the instruction after the BEGIN in a BEGIN-REPEAT loop. Marks the end of the current loop.

See also, LOOPS.

rinstr ( s s1 -- i )

Returns the last occurrence of string s1 in string s, or 0 if s1 is not found. '"abcbcba" "bc" rinstr' returns 4. See also instr.

rinstring ( s s1 -- i )

Returns the last occurrence of string s1 in string s, or -1 if s1 is not found. Non-case sensitive. This is an inserver define to 'tolower swap tolower swap rinstr'.

rmatch ( d s -- d' )

Takes string s, checks all objects and actions associated with object d, and returns object d' which matches that string. For example, matches actions and inventory objects for a player object, actions on a thing object, etc. If nothing is found, d' = #-1. if ambiguous, d' = #-2. If HOME, d' = #-3.

room? ( d -- i )

Returns 1 if object d is a room, otherwise returns 0. If the dbref is that of an invalid object, it will return 0. A dbref of #-3 (HOME) returns 1.

rot ( x y z -- y z x )

Rotates the top three things on the stack. This is equivalent to 3 rotate.

rotate ( ni ... n1 i -- n(i-1) ... n1 ni )

Rotates the top i things on the stack. '"a" "b" "c" "d" 4 rotate' would leave "b" "c" "d" "a" on the stack. Using a negative rotational value rotates backwards. ie: '"a" "b" "c" "d" -4 rotate' would leave "d" "a" "b" "c" on the stack.

set ( d s -- )

Sets flag s to object d. Currently settable things are: abode, chown, dark, haven, jump, link, sticky. Boolean operations (e.g. '!abode') work as expected.

setdesc (d s -- )
setsucc (d s -- )
setfail (d s -- )
setdrop (d s -- )
setosucc (d s -- )
setofail (d s -- )
setodrop (d s -- )

Takes object d, and sets the string field specified to s. A program may only set string fields of objects that are owned by the effective user of the program, or any object if the program is Wizard. These are all actually $defines to addprop with the apprpriate property name.

They are effectively defined as:

$define setdesc "_/de" swap 0 addprop $enddef
$define setsucc "_/sc" swap 0 addprop $enddef
$define setfail "_/fl" swap 0 addprop $enddef
$define setdrop "_/dr" swap 0 addprop $enddef
$define setosucc "_/osc" swap 0 addprop $enddef
$define setofail "_/ofl" swap 0 addprop $enddef
$define setodrop "_/odr" swap 0 addprop $enddef

See also set, setname, addprop, getpropstr, remove_prop, desc, succ, fail, drop, osucc, ofail, and odrop.

setlink ( d1 d2 -- )

Takes an exit dbref d1, and sets its destination to d2. You must have control of the exit, and if the exit is already linked, it must be unlinked first by doing setlink with #-1 as the destination.

setlockstr (d s -- i)

Tries to set the lock on the given object to the lock expression given in the string. If it was a success, then it will return a 1, otherwise, if the lock expression was bad, it returns a 0. To unlock an object, set its lock to a null string.

setmode (i -- )

Sets the current multitasking mode to the given mode. The integer this uses will be the same as one of those defined by the standard $defines bg_mode, fg_mode, and pr_mode, being background, foreground, and preempt mode, respectively. Programs set BOUND will run PREEMPT, ignoring this mode.

See also PR_MODE. pr_mode ( -- i) fg_mode ( -- i) bg_mode ( -- i)

These are all standard built in defines. They are used with MODE and SETMODE to show what mode the program is running in, or to set what mode it will run in. For example, MODE returns an integer on the stack, that you can compare against pr_mode, fg_mode, or bg_mode, to determine what mode the program is in. pr_mode is defined as 0, fg_mode is defined as 1, and bg_mode is defined as 2.

setname ( d s -- )

Takes object d, and sets the name to s. A program may only set the names of objects that are owned by the effective user of the program, or any object if the program is Wizard. The name of a player can never be set, since that would normally require a password.

setown (d d -- )

Sets the ownership of the first object to the player given in the second dbref.

(wizbit only)

setprop (d s ? -- )

Stores a lock, dbref, integer, or string into the named property on the given object. Permissions are the same as for ADDPROP.

sleep (i -- )

Makes the program pause here for 'i' seconds. the value of i cannot be negative. If the sleep is for more than 0 seconds, then the program may not thereafter use the READ primitive.

smatch ( s s2 -- i )

Takes a string s, and a string pattern, s2, to check against. Returns true if the string fits the pattern. This is case insensitive. In the pattern string, the following special characters will do as follows:

A '?' matches any single character.
A '*' matches any number of any characters.
'{word1|word2|etc}' will match a single word, if it is one of those given, seperated by | characters, between the {}s. A word ends with a space or at the end of the string. The given example would match either the words "word1", "word2", or "etc".
- {} word patterns will only match complete words: "{foo}*" and "{foo}p" do not match "foop" and "*{foo}" and "p{foo}" do not match "pfoo".
- {} word patterns can be easily meaningless; they will match nothing if they:
  1. contains spaces,
  2. do not follow a wildcard, space or beginning of string,
  3. are not followed by a wildcard, space or end of string.
If the first char of a {} word set is a '^', then it will match a single word if it is NOT one of those contained within the {}s. Example: '{^Foxen|Fiera}' will match any single word EXCEPT for Foxen or Fiera.
'[aeiou]' will match a single character as long as it is one of those contained between the []s. In this case, it matches any vowel.
If the first char of a [] char set is a '^', then it will match a single character if it is NOT one of those contained within the []s. Example:
'[^aeiou]' will match any single character EXCEPT for a vowel.
If a [] char set contains two characters seperated by a '-', then it will match any single character that is between those two given characters. Example: '[a-z0-9_]' would match any single character between 'a' and 'z', inclusive, any character between '0' and '9', inclusive, or a '_'.
The '\' character will disable the special meaning of the character that follows it, matching it literally.

Example patterns:

"d*g" matches "dg", "dog", "doog", "dorfg", etc.
"d?g" matches "dog", "dig" and "dug" but not "dg" or "drug".
"M[rs]." matches "Mr." and "Ms."
"M[a-z]" matches "Ma", "Mb", etc.
"[^a-z]" matches anything but an alphabetical character.
"{Moira|Chupchup}*" matches "Moira snores" and "Chupchup arghs."
"{Moira|Chupchup}*" does NOT match "Moira' snores".
"{Foxen|Lynx|Fier[ao]} *t[iy]ckle*\?" Will match any string starting with 'Foxen', 'Lynx', 'Fiera', or 'Fiero', that contains either 'tickle' or 'tyckle' and ends with a '?'.

stats ( d -- total rooms exits things programs players garbage )

Returns the number of objects owned by 'd', or the total objects in the system if d == #-1. This is broken up into a total, rooms, exits, things, programs, players, and garbage. This functions much as the @STAT command.

(Needs Mucker Level 3)

strcat ( s1 s2 -- s )

Concatenates two strings s1 and s2 and pushes the result s = s1s2 onto the stack.

strcmp ( s1 s2 -- i )

Compares strings s1 and s2. Returns i as 0 if they are equal, otherwise returns i as the difference between the first non-matching character in the strings. For example, "a" "z" strcmp returns 25. The reason it returns a 0 for a match, and the difference on a non-match, is to allow for nice things like string sorting functions. This primitive is case sensitive, unlike stringcmp.

strcut ( s i -- s1 s2 )

Cuts string s after its i'th character. For example,

"Foobar" 3 strcut

returns

"Foo" "bar"

If i is zero or greater than the length of s, returns a null string in the first or second position, respectively.

string? ( x -- i )

Returns true if x is a string.

stringcmp ( s1 s2 -- i )

stringpfx (s s2 -- i)

Returns 1 if string s2 is a prefix of string s. If s2 is NOT a prefix of s, then it returns 0. Case insensitive.

strip (s -- s)

This is a built in $define. It is interpreted as "striplead striptail" It strips the spaces from both ends of a string.

striplead (s -- s)

Strips leading spaces from the given string.

striptail (s -- s)

Strips trailing spaces from the given string.

strlen ( s -- i )

Returns the length of string s.

strncmp ( s1 s2 i -- i' )

Compares the first i characters in strings s1 and s2. Return value is like strcmp.

subst ( s1 s2 s3 -- s )

s1 is the string to operate on, s2 is the string to change all occurences of s3 into, and s is resultant string. For example:

"HEY_YOU_THIS_IS" " " "_" subst

results in

"HEY YOU THIS IS"

s2 and s3 may be of any length.

succ ( d -- s )

Takes object d and returns its success (@succ) string field s.

swap ( x y -- y x )

Takes objects x and y on the stack and reverses their order.

systime ( -- i )

Returns the number of seconds from Jan 1, 1970. This is compatible with the system timestamps and may be broken down into useful values through 'timesplit'.

testlock (l d -- i)

Tests the player against the given lock. If the test was successful, then this returns a 1. If the test failed, then this returns a 0.

thing? ( d -- i )

Returns i as 1 if object d is a thing, otherwise returns i as 0.

See also player?, program?, room?, exit?, and ok?.

time ( -- s m h )

Returns the time of day as integers on the stack, seconds, then minutes, then hours.

timefmt (s i -- s)

Takes a format string and a SYSTIME integer and returns a string formatted with the time. The format string is ascii text with formatting commands:

%% -- "%"
%a -- abbreviated weekday name.
%A -- full weekday name.
%b -- abbreviated month name.
%B -- full month name.
%C -- "%A %B %e, %Y"
%c -- "%x %X"
%D -- "%m/%d/%y"
%d -- month day, "01" - "31"
%e -- month day, " 1" - "31"
%h -- "%b"
%H -- hour, "00" - "23"
%I -- hour, "01" - "12"
%j -- year day, "001" - "366"
%k -- hour, " 0" - "23"
%l -- hour, " 1" - "12"
%M -- minute, "00" - "59"
%m -- month, "01" - "12"
%p -- "AM" or "PM"
%R -- "%H:%M"
%r -- "%I:%M:%S %p"
%S -- seconds, "00" - "59"
%T -- "%H:%M:%S"
%U -- week number of the year. "00" - "52"
%w -- week day number, "0" - "6"
%W -- week# of year, starting on a monday, "00" - "52"
%X -- "%H:%M:%S"
%x -- "%m/%d/%y"
%y -- year, "00" - "99"
%Y -- year, "1900" - "2155"
%Z -- Time zone. "GMT", "EDT", "PST", etc.

timesplit ( i -- is im ih id im iy iw iyd )

Splits a systime value into 8 values in the following order: seconds, minutes, hours, monthday, month, year, weekday, yearday. Weekday starts with sunday as 1, and yearday is the day of the year (1-366).

timestamps ( d -- i i2 i3 i4 )

Returns the following for a program, the time created (i), the time last modified (i2), the time last used (i3), and the number of uses(i4) for any object.

tolower (s -- s)

Takes a string and returns it with all the letters in lowercase.

toupper (s -- s)

Takes a string and returns it with all the letters in uppercase.

trig ( -- d)

Returns the dbref of the original trigger.

unparselock (l -- s)

Unparses a lock into a string fit for program editing.

unparseobj ( d -- s )

Returns the name-and-flag string for an object. It always has the dbref and flag string after the name, even if the player doesn't control the object.

For example: "One(#1PW)"

until (i -- )

If the value on top of the stack is false, then it jumps execution back to the instruction after the matching BEGIN statement. (BEGIN-UNTIL, BEGIN-REPEAT, and IF-ELSE-THEN's can all be nested as much as you want.) If the value is true, it exits the loop, and executes the next instruction, following the UNTIL. Marks the end of the current loop.

See also, LOOPS.

var name

Var is not a 'true' primitive in that it must always be used outside words and does not alter the stack in any way. When the compiler sees a 'var' statement, it allows the use of name as a variable in all words sequentially defined after the var declaration.

variable ( i -- v )

Converts integer i to variable reference v. Of the pre-defined variables, 'me' corresponds to integer 0, 'loc' to 1, and 'trigger' to 2. Thus:

me @

and

0 variable @

will do the same thing (returning the user's dbref). User-defined variables are numbered sequentially starting at 3 by the compiler. Note that these variable numbers can be used even if variables have not been formally declared, making implementation of such things as arrays conveniently easy.

version ( -- s)

Returns the version of this code in a string. "Muck2.2fb5.55", currently.

while (i -- )

If the value on top of the stack is false, then this causes execution to jump to the instruction after the UNTIL or REPEAT for the current loop. If the value is true, however, execution falls through to the instruction after the WHILE.

See also, LOOPS.

CREDITS

Credits:

The people responsible (at fault?) for this manual are: Foxen (foxen@netcom.netcom.com), who wrote the original terrible docs, and WhiteFire (kinomon@glia.biostr.washington.edu), who cleaned them up a lot.

Thanks WF!

Most recently this file was re-edited by Ioldanach (jmorton@druid.ddns.org) to alphabetical order for ease of indexing as a printed document, and later as an html document.

maintained by Jeff Morton / jmorton@druid.ddns.org