MUCK Manual Version 1.0
Written for TinyMuck version 2.2 fb5.64 and fb6.0
by Jessy @ FurryMUCK
INTRODUCTION
ABOUT THIS MANUAL
1.0 BASIC COMMANDS AND SETTING UP A CHARACTER
1.1 Some Definitions and Abbreviations
1.2 Connecting to the MUCK
1.3 Getting a Character
1.4 Basic Commands
1.4.1 Looking
1.4.2 Moving
1.4.3 Talking
1.4.4 Seeing Who's Around
1.4.5 Carrying Things
1.5 Setting Up Your Character
1.5.1 Describing Yourself
1.5.2 Setting Your Sex and Species
1.5.3 Locking Yourself
1.5.4 Getting a Home
1.6 Getting Help
2.0 COMMANDS
2.1 Overview: Dbrefs, Names, Flags and Properties
2.1.1 Protected, Restricted, and Wizard Properties
2.1.2 Messages and Message Properties
2.1.3 Data Types and Setting Properties
2.1.4 Triggering from Properties
2.1.5 Registered Names
2.1.6 Pattern Matching, Regular Expressions, and Output Types
2.1.7 Pronoun and Name Substitutions
2.2 Overview: Rooms, Things, and the Environment Tree
2.2.1 Droptos
2.2.2 Looktraps
2.3 Overview: Exits and Locks
2.3.1 Bogus Exits
2.3.2 Unsecured Exits
2.3.3 Exit Priorities
2.3.4 Multiple Links
2.4 User-Created Commands
2.5 Flag Reference
2.6 Server Command Reference
2.7 User-Created Command Reference
3.0 PROGRAMMING
3.1 Overview: MPI
3.1.1 MPI Macros
3.1.2 MPI Examples
3.1.3 MPI Reference
3.2 Overview: MUF
3.2.1 Mucker Levels
3.2.2 MUF Libraries
3.2.3 MUF Macros
3.2.4 MUF Examples
3.2.5 MUF Reference
3.2.6 MUF Library Reference
4.0 TUTORIALS
4.1 Using the List Editor
4.2 Making a Multi-Action
4.3 Making Puppets
4.4 Making Vehicles
4.5 Building Rooms and Areas
4.6 Archiving Your Belongings
5.0 ADMINISTERING A MUCK
5.1 Technical Issues
5.1.1 Selecting a Site
5.1.2 Compiling the Server
5.1.3 Setting Up the Database
5.1.4 Security Concerns
5.2 Non-technical Issues
5.2.1 Conceptualizing the World
5.2.2 Recruiting a Staff
5.2.3 Sharing Responsibility
5.2.4 Privacy Issues
5.2.5 Acceptable Use
5.2.6 Toading
5.2.7 Record Keeping
Appendix A: Getting a Client Program
Appendix B: UNIX Crash Course
Appendix C: Sample Acceptable Use Policy and Programming Policy
*****************************************************************************
INTRODUCTION
A MUCK is a computer-driven, text-based `world'. Users, or `players',
log on to the MUCK computer via the Internet, and may then interact with
other players. The program running the MUCK and the computer it's on are
both called the `server'. Each player controls a `character', a virtual
person or creature inhabiting the world of the MUCK. Your character
might be very much like you, the player, or she might be very different.
MUCK is one member of a group related servers, including MUSH, MUX, MOO,
MUSE, and MUD; collectively, these servers are often referred to as M*'s
or M***'s.
Everything is in text; there are no graphics. You will `see' things from
the perspective of your character: whatever place you're in will be
described, in words; people and things around you will also be
described, and you can look at them. Succinct commands let you say and
do things, interacting with other people on the MUCK (on a small MUCK,
this might be six other people; on a large one, it might be 300). Some
people view the text-only aspect of MUCKs as a limitation, others as a
very positive feature. While a screen full of text lacks the instant
impact of well done graphics, the world that comes alive in your
imagination can be more vivid and colorful than anything computer
graphics can produce. Just as the words on the page `disappear' when one
is immersed in a novel -- and one instead imaginatively experiences the
world described in the book -- the words on your computer screen can
`disappear', and you imaginatively experience the world of the MUCK.
Here, though, you are an active participant rather than a passive
observer.
MUCKs can be constructed to model any sort of world imaginable, on any
scale: a droplet populated by microbes, a one-room bar, an undersea
kingdom, or a far-flung stellar empire. By (recent) historical accident,
many MUCKs are worlds populated by furries. A furry is an
anthropomorphic animal, an animal with human characteristics. You might
meet an accountant or a college student on a MUCK, but you're more
likely to meet a suave wolf who likes to quote poetry, or a tiger with a
weakness for chocolate truffles. So, yes, furries are inherently silly.
But they are also inherently noble: protean and indestructible, they
embody who we might be in a world where anything is possible.
*****************************************************************************
ABOUT THIS MANUAL
The MUCK Manual comprises five sections. Section 1 is an introduction
for new players, covering basic commands and setting up your character.
Section 2 deals with server commands and the commands included in the
standard start-up database. Section 3 covers programming. Tutorials are
presented in Section 4. Section 5 discusses technical and nontechnical
issues of administering a MUCK. New players should read Section 1;
others may safely begin with later sections.
The Overview sections provide relatively thorough discussion of relevant
concepts, but are not comprehensive. The Reference sections are
comprehensive (or at least attempt to be), but are written in a terse
style that assumes the reader has some familiarity with the topic or has
read the Overview. The remaining sections discuss aspects of the section
topic meriting special attention.
====================================
Examples in the manual are set off by half-lines of equal signs, like this.
====================================
Text enclosed in [square brackets] is optional. Text enclosed in
<angle brackets> should be edited as appropriate for you and your
character. For example, where the manual says `type <your name>',
type your name, rather than typing this literally. Within examples,
lines beginning with a > sign indicate material you should enter at
your keyboard; the remaining lines are sample output from the MUCK. (In
some longer programming entries, the > sign has been omitted so that
you may cut and paste text from this file to a MUCK.)
The MUCK Manual attempts to provide a single, relatively comprehensive
reference for MUCK, as Lydia Leong's MUSH Manual does for MUSH. The
organization of the MUCK Manual is in part based on her manual, and any
indebtedness is gratefully acknowledged.
The MUCK Manual was written with help from Winged(***@***), author of
the online documentation for MUCK, version 6.0. Authors and editors of
reference materials quoted include Foxen (foxen@belfry.com), Fre'ta
(stevenl@netcom.netcom.com), Ioldanach (mortoj@rpi.edu).
This version of the manual was written for MUCK version 2.2 fb6.0.
Copyright of The MUCK Manual is held by Jessy Dupres. The Manual may be
freely copied, distributed, and archived.
-- Jessy (scampergal@hotmail.com)
*****************************************************************************
1.0 BASIC COMMANDS AND SETTING UP A CHARACTER
1.1 Some Definitions and Abbreviations
Frequently used terms:
Player: The person reading this manual; the entity who types things on
behalf of a character.
Character: The virtual person or creature inhabiting the MUCK,
controlled by a player. Players have characters; characters have
players. The terms `player' and `character' are often used
interchangebly.
Puppet: A player-like object controlled by a character. A `virtual
character', as it were. A puppet can move and act independently of the
character; everything the puppet sees and hears is relayed to the
character and player.
Zombie: Same thing as a puppet.
Robot (or `bot): An object programmed to act like a character, or a
character under the control of a program that causes her to perform
certain actions automatically. `Bots are sometimes called AI's (from
`artificial intelligence').
Flag: A setting on an object that influences or restricts its behavior.
Flags are also called `bits'. Flags are discussed in Section 2.1.
Object Type: An object may be a PLAYER, THING, ROOM, EXIT, or PROGRAM.
A `player' is something that can be connected to via a name and
password, can own things, and can act independently. Because this object
type is called `player' rather than `character', many help documents
(including this manual) will often use this term, though what's meant is
the character object, not the living person who controls it. A `thing'
is a mobile object that may be picked up, dropped, handed, and otherwise
manipulated. A `room' is a place in the world of the MUCK, though it
need not be described as an interior room: rooms can also be described
to simulate an outdoor area, or described in an abstract way so that
moving through the room shows characters useful text (for example, a
tutorial on building might be set up as a series of rooms, with the
description of each room serving as a `page' in a maunal). An `exit' is
a link between two objects on the MUCK. Exits may be created such that
they serve as virtual doors between rooms, or they may serve as
user-created commands. (`Exits' are also called `actions'.) A `program'
is a special instance of class `thing' which contains the code of an
executable program. The type of an object is determined when it is
created, and indicated by a flag. An object with a P flag is a player;
an object with an R flag is a room; an object with an E flag is an exit;
an object with an F flag is a program. If an object has none of these
flags, it is a thing. The collective term for all of these is is
`object': players, rooms, etc. are all objects.
Dbref: Every object in the database has a unique identifying number: its
`database reference number', or `dbref' for short. (Many objects may
have the same name.) A dbref is usually preceeded by an # octothorpe,
e.g. #123.
Client: A program that replaces Telnet as a means to connect to the MUCK
server. Clients have numerous special features specifically applicable
to M*'s, such as automated logon, the capacity to switch between several
worlds, hiliting certain kinds of text, line-wrapping, separating text
being typed from text being displayed by the MUCK, paging, and
scrollback. Different platforms require different clients. TinyFugue is
a popular UNIX client. MUDDweller is a widely used Macintosh client.
SimpleMU, Pueblo, Phoca, and ZMud are common Windows clients. A single
client can connect to different servers... that is, you don't need a
separate client for MUSH, MUCK, and MUD. Virtually all client programs
are distributed as freeware or shareware, and are widely available over
the Internet (see Appendix A).
Penny: The unit of currency on a MUCK. Money is usually a non-issue on
MUCKs, though some commands require an expenditure of pennies. The
administrators of a MUCK may set the name of the currency: it might be
pennies, or it might be pop-tarts, fleas, or lurid fantasies. You will
often find money simply by moving through the MUCK, and will see a
message such as `You find a penny!' or `You find a reason for living!'
Many MUCKs also have banks or other places where you can get more
pennies.
Save: A period in which the server backs up the database to disk. At
scheduled intervals, the server automatically executes relatively brief
saves in which only those objects changed or created since the last save
are backed up (`delta saves'), as well as longer saves in which the
entire database is backed up (`full saves' or `database saves'). In
addition to automated saves, wizards may initiate a save via the @dump
command. (`Saves' are also called `dumps'.) During a save, activity on
the MUCK is frozen: commands you enter during a save will be queued and
executed after the save completes. On a very large MUCK, a full save can
take ten or more minutes.
Lag: (noun) A perceptible delay between the time you enter a command and
the time it is executed. Lag may be caused by an overloaded server (too
many people logged on or too many programs running), by an overly large
database (the database is larger than available RAM, necessitating
frequent swaps to disk), or by problems on the Internet. (verb) To
experience lag or a `locked-up' screen.
Spam: (noun) Text scrolling by too fast to be read comfortably. (verb)
To act or use programs in such a way that those around you are subjected
to an excessive amount of frivolous or repetitive text.
Idle: To be logged onto the MUCK but not doing anything.
Mav: To say aloud something meant to be whispered. By extention, to say
aloud something meant to be paged, or to whisper or page to the wrong
person. Maving is a potential source of embarrassment or awkwardness.
The name derives from a character in the early days of M*s who was
chronically prone to this particular faux pas.
God: The MUCK's overall controller or administrator, and the player
object with dbref #1. God has access to a few commands unavailable to
all other players, and may not be @forced. The term `God' is used less
frequently on MUCKs than on MUSHes and MUDs. In fact, leadership by a
single wizard player is relatively rare. More often, a core group of
wizards share responsibility for administering the MUCK, with each
having access to the God character's password.
Wizard: An administrator of the MUCK, and a player with the W flag.
Wizards have control over all objects in the database, and may use
restricted commands available only to them. (`Wizard' is often shortened
to `wiz'.)
Realm Wizard or Realms Wizard: An administrator of a certain area within
a MUCK. Realms wizards have partial command over objects and players
within their area, but cannot use wiz commands. Use of the realms wizard
system is somewhat uncommon.
Mortal: A non-wizard character. This term too is used less frequently on
MUCKs than on MUSHes and MUDs. While wizards are technically players,
people usually refer simply to `wizzes' on the one hand and `players' on
the other. (Where the distinction is important, this manual will use the
term `mortal'.)
Staff: A MUCK administrator, who may or may not be a wizard, and may or
may not have access to restricted commands. A common staff position is
`helpstaff': someone who agrees to help new players and answer
questions, but seldom has access to restricted commands. Most wizards
are staff, but occassionally a player will be given a wizbit without
staff responsibilities and privileges. In other words, `staff' is an
administrative rather than technical term.
MPI: An online programming language with a LISP-like syntax. MPI is
available to all players. Because it is universally available, MPI
includes a number of security features that restrict its power. MPI is
covered in Section 3.
MUF: An online programming language with a FORTH-like syntax. MUF
security is handled through a system of privileges. In order to program
in MUF, one must have a `Mucker bit' (an M flag). Mucker bits range from
M1 (highly restricted) to M3 (almost as powerful as a Wizard flag). On
well established MUCKS, only highly trusted players with demonstrated
programming skill are given M3 bits. The power and efficiency of MUF
make MUCK readily user-extensible. MUF is covered in Section 3.
User-Created Command or User-Created Program: This term is not commonly
used on MUCKs, but is often used in this manual, and so is mentioned
here. Many of the commands people are accustomed to using on MUCKs are
not part of the MUCK server, but rather separate programs created by
players and wizards. Soft-coded commands, in other words. Some (such as
the `say', `page', and `whisper' commands used on most MUCKs) are
enhancements of server commands. Others (such as `ride', `lsedit', and
`lookat') are basic utilities that do something the server itself
cannot. A large MUCK will also have a great many other user-created
commands and programs: some invaluable, some highly specialized, and
some frivolous.
Control: This term too is used quite frequently in the manual. In almost
all cases, your permission to change an object is determined by whether
or not you control it. For mortals, control is essentially synonymous
with ownership: you control everything you own; you don't control things
you don't own, with one exception: anyone can control an unlinked exit.
Wizards and realms wizards have extended control: Realms wizards control
anything in their realm, including players; wizards control everything.
*****
Frequently used abbreviations:
VR: Virtual Reality. The MUCK world or worlds. Characters live there.
RL: Real Life. The world outside the MUCK. Most players live there.
M* or M***: A generic abbreviation for all flavors of text-based,
Internet-accessible, interactive programs, including MUD, MUSH, MUX,
MOO, MUSE, and MUCK.
IC: In Character. Acting or speaking as your character, rather than as
you, the player.
OOC: Out of Character. Acting or speaking as you, the player, rather
than the character. Medieval warriors arguing about Mac vs. Windows are
OOC. In some situations, on some MUCKs, being OOC without signalling
that you are doing so (by putting something like `(OOC)' or `notes OOC'
before your poses and comments) is considered a breach of etiquette.
IMHO: In My Humble (or Holy) Opinion, & IMO, In My Opinion
LOL: Laughs Out Loud.
ROTFL: Rolls on the Floor Laughing.
AFK: Away From Keyboard
BRB: Be Right Back
BBL: Be Back Later
TS: TinySex. To make love or have sex on the MUCK, via the gestures and
comments of your character. `TS' is both a verb and noun.
TP: TinyPlot. A role-played, jointly-authored, predominantly improvised
storyline acted out by a group of players. TPs are usually consensual:
players agree ahead of time to participate in the TP, though other
players may be drawn into the TP by the storyline's development. Usually
players will plan the main conflict, premise, or events ahead of time --
at least provisionally -- and improvise their characters' individual
contributions and reactions. (The terms `TinySex' and `TinyPlot' derive
from `TinyMUD', an early server from which MUCK grew out of.)
RP: Role Playing. Acting IC in a way that is consistent with either the
overall theme of the MUCK, a TinyPlot in which one is participating, or
both. Some MUCKs are predominantly places to RP; some are mostly places
to socialize, where RP is sporadic.
Sidebar: `MUCK' itelf is not an abbreviation or acronym. The names of
other M* servers are: MUD stands for Multi-User Dungeon or Multi-User
Domain; MUSH for Multi-User Shared Hallucination; MOO for MUD, Object
Oriented. `MUCK' is simply a name with a sound and connotations rather
like those of `MUD' and `MUSH'. Purportedly, the name derives from the
fact that MUF gives players the ability to `muck around with' the
database.
1.2 Connecting to the MUCK
To play on a MUCK, you need to be logged onto a character. The most
basic way to do this is with Telnet. A client program (see Appendix A)
is vastly preferable to Telnet, but not essential. For now, examples
will assume you are using Telnet from a UNIX account. If you don't have
a character on the MUCK, you will need to log on as a Guest. You will
also need to find the addresses and port numbers of some open MUCKs.
Lists of such address are frequently posted on the newsgroup
rec.games.mud.announce, and are easily found via web searches for
keywords such as `muck' or `mud'. The example below use the current
address for FurryMUCK (as of Summer, 1997).
Logging on involves two steps: connecting to the MUCK, and logging onto
a specific character.
To connect to the MUCK via Telnet on a UNIX account, type `telnet',
followed by a numeric or domain name IP address, followed by a port
number. Press enter.
====================================
> telnet furry.org 8888
====================================
If the connection is successful (i.e., if you typed everything
correctly, the Net is not having a Bad Day, and the MUCK itself is
running) a login screen will scroll onto your terminal. If you
experience a delay, and then a messages such as `connection incomplete:
timed out', wait a few minutes and try again: it's possible that the
MUCK was undergoing a save while you were trying to connect, or that
there were transient connection problems on the Internet.
The login screen should show informational text, illustrations composed
of ASCII characters, or a combination of these. It is possible to
successfully connect to the MUCK, yet see a rather garbled looking login
screen. Usually this is due to improper terminal settings. If this
happens, continue with the login step. The problem may disappear once
you've logged on, and if doesn't, people online may be able to help with
terminal settings. (This problem is relatively rare.)
Once you've connected to the MUCK, you need to log onto a specific
character. If you don't have a character on the MUCK, you can (usually)
connect to a Guest character.
====================================
> connect guest guest
====================================
If you have a character, type `connect' followed by the character name
and password.
====================================
> connect cashmere flipFlap
====================================
On large MUCKs (including our example, FurryMUCK) it is common to
require Guests to page a wizard and ask to be let out of the Guest Room.
This is a security measure: it is not unheard of for players who have
been banned from the MUCK for causing problems to attempt to log on as a
Guest and continue their improper behavior; a wizard can check the site
from which a Guest is connecting, and refuse to free someone from a site
known to be the home of problem-causers. If this step is required (the
text you see after logging on as a Guest will say so), type `wizzes' to
get a list of any wizards online, and page one asking him to let you out
(paging is discussed below, 1.4.4). If no wizards are online, you'll
have to try again later. On most MUCKs, this step is unnecessary. You
can get out of the Guest Room simply by typing `out'.
1.3 Getting a Character
The MUCK server has a provision for automatic character generation, but
usually this is disabled. Instead, you'll need to send email requesting
a character. The contents of the email you send will vary from MUCK to
MUCK: some simply ask for the character name you want, others require
your real name, your age, and your state or country of residence. Help
files on the MUCK or people online should give you more specific
information. Typing `news registration' or `news join' for a helpfile or
`staff' for a list of people responsible for answering such questions
are good first steps for finding this information.
Once your character is approved and created, you will be sent email
containing the character's name (usually the name you asked for) and
your password. Sometimes you request a password; sometimes it is
randomly assigned. Random passwords may be changed to something
memorable once you connect. Passwords are case-sensitive: `flipFlap' and
`flipflap' are two different passwords.
Character creation by this method usually takes a day or two.
On MUCKs that allow automatic character creation, use the `create'
command at the log on screen:
====================================
> create Cashmere flipFlap
====================================
1.4 Basic Commands
1.4.1 Looking
The `look' command (abbreviated `l') shows you your surroundings.
Typing `look' by itself shows you the room you are in. You automatically
see the description of a room upon entering it; typing `look' shows the
same description again (it may have scrolled off your screen). Typing
`look <object>' or `l <object>' shows you the description of
<object>. The `lookat' command does a possessive look, showing
something that is held by someone else. The syntax is `lookat
<object>'s <thing>', e.g. `lookat Jessy's ring'.
1.4.2 Moving
The `go' or `goto' command causes your character to move in a certain
direction or use a specific exit. For example, typing `goto north' would
cause your character to move one room to the north (assuming there is a
room to the north -- or, more accurately, there is an exit named `north'
in your current location, leading to another room). The `goto' command
is not really necessary, and is almost never used: typing the exit name
by itself will also cause you to `go' in that direction, and directions
are usually abbreviated to their first letter. Thus, typing `north' or
`n' should produce the same result as `goto north'. If you can't go in a
particular direction (because there is no exit in that direction, or the
exit is locked against you), you will see a fail message such as `You
can't go that way.'. A commonly used exit name is `out' or `o': typing
either of these in an interior room will often move you outside the room
or building.
Frequently, the builder of a room makes use of a program that appends
the names of `Obvious Exits' to the description of a room (An `obvious'
exit is one that is not hidden by being set Dark). The names of these
exits will then appear in a list below the room's description. The
absence of such a list does not mean that there is no way out of the
room. Read the room's description carefully to see if it indicates
directions you can go. If you are still unable to determine valid
directions, try common-sense directions such as `west', `n', or `out'.
If all else fails, you can get out of room by typing `home' or `gohome',
which will return you to your home location.
1.4.3 Talking
The `say' command (abbreveated as a " quotation mark) causes your
character to say something hearable by all other characters in the same
room. Thus, if Cara's player types `say Hi there!' or `"Hi there!',
people in the same room will see `Cara says, "Hi there!"'
Characters can communicate via gestures or `poses' as well as speech.
The `pose' command (abbreated as a : colon) causes your character to do
something seeable by all other characters in the same room. So, if
Cara's player types `pose waves.'. or `:waves.', people in the same room
will see `Cara waves.' The pose command handles punctuation
intelligently, omitting the space between the character's name and the
pose when the text begins with punctuation. Thus, if Cara's player typed
`:'s going to go see a friend', characters around her would see `Cara's
going to go see a friend.', rather than `Cara `s going to go see a
friend.' You can communicate with a specific player, or a group of
players, rather than the whole room, via the `whisper' command
(abbreviated as `w' or `wh'). The syntax is `w <name or names> =
<message>' For example, if Clearsong's player typed `w cashmere =
What say we blow this joint?', Cashmere would see `Clearsong whispers,
"What say we blow this joint?" (to you)'. If Clearsong's player had
typed `w cashmere cara = I thought that was illegal.', both Cashmere and
Cara would receive the whisper. To format a whisper as a pose, put a
colon before the whispered message. For example, Cashmere could answer
Clearsong by typing `w clearsong = :nods.' Whisper will search the room
for partial name matches. Thus, if there is no one else named
Clear<something> present, typing `w clear = :nods' would send the
whisper to Clearsong. The whisper command `remembers' the last person
you whispered to, so to continue a whispered conversation, the name may
be omitted: `w = <message>'. You can communicate with people in
other rooms via the `page' command (abbreviated as `p'). The syntax for
pages, page poses, and pages to multiple players is the same as that of
whisper: `p <name or names> = <message>' (for a page) and `p
<name or names> = : <pose>' (for a page pose). Like whisper,
the page `remembers' the last person you paged to and the name may be
omitted.
(Note: Spaces have been placed around the = equal sign in the above
examples for clarity. The spaces are not necessary, but can be
included.)
1.4.4 Seeing Who's Around
Space on the MUCK is divided into `rooms', which may or not be described
to resemble an actual interior room. There may be numereous people
online, but not in the same room as you.
The names of characters in the same room as you will be appended to the
room's description in a list of the room's `Contents'. Some things in
the list may not be connected characters, however: some may be things.
some may be puppets, and some may be characters who are not online
(they're `asleep'). To get a list of online characters in the same room,
type `who' in lower case. In rooms set Dark, the `Contents' list will
not appear: there may or may not be other players present. Guest Rooms
and New Player Start rooms are often set Dark.
To see who's online on the MUCK as a whole, type `WHO', all upper case.
1.4.5 Carrying Things
The commands for handling things are quite straightforward: `get
<object>' causes you to pick up something; `drop <object>'
causes you to drop it. When you go somewhere, objects you are carrying
will go with you.
In order to get something, you must be in the same room, and it must not
be locked against you.
You can hand things to other players, syntax `hand <object> to
<player>'. Being able to hand or be handed to isn't automatic:
type `hand #ok' to enable handing.
The `inventory' command, abbreviated `i' or `inv', shows a list of
everything you are carrying, and a line showing how many pennies you
have.
1.5 Setting Up Your Character
A new character is essentially a blank slate, having only a name, a
dbref, a password, a flag or two, and some pennies. In order to become a
fully functioning part of the MUCK world, you will need to do a few
things to get your character set up. The following section describes a
very basic set up. Most of the things you'll do in this section involve
setting `properties'. A property is a named location on a MUCK object
where information is stored. Properties are discussed fully in Section
2; you don't need to understand exactly how MUCK handles properties in
order to set up your character. Any commands you issue at this stage are
reversible, so don't worry about making mistakes. Simply re-enter the
command correctly.
1.5.1 Describing Yourself
Until you describe yourself, people who look at you will see `You see
nothing special'. You can (and should) set what people see when looking
you by entering a description, or `desc' as it's usually called. The
syntax is `@desc me = <description>'.
A `straight desc' such as this is rather limited: the text remains the
same at all times, you won't know when someone looks at you, you'll be
limited to about twelve lines of text, and you can't divide the text
into paragraphs.
Later, you can use MPI and the list editor (a program that lets you work
with a `list', a series of props which together act like a document) to
create highly flexible descs that change in response to the time of day,
who's looking at you, what you're wearing or what mood you're in, and so
forth.
Many MUCKs have a user-created command that allows you to `morph', or
change descriptions with a succinct command. You may wish to type `morph
#help' to see if such a program is available on your MUCK.
Most MUCKs also have an MPI macro that notifies you whenever someone
looks at you, called `look-notify'. To use it, put `{look-notify}' --
curly braces included -- anywhere in your description. For example,
`@desc me = A nymph with green hair.{look-notify}'
1.5.2 Setting your Sex and Species
Your sex does not have to be male or female, but it's recommended. From
time to time you'll encounter programs or commands that format their
output based on the user's sex (pronoun substitution is the most common
instance). No harm will be done if your sex is something other than male
or female, but the program output may look a bit strange.
To set your sex, type `@set me = sex : <value>'.
Your species can be anything appropriate to the MUCK. On MUCKs where
everyone is human, the species prop is often used to indicate a
profession or social position.
To set your species, type `@set me = species : <value>'.
Many MUCKs have a user-created command that shows the sex and species of
everyone in the room. The most common is `WhoSpecies', or `ws'. Type
`ws' to see if it's available on your MUCK.
1.5.3 Locking Yourself
On some M* servers, locking yourself is a very worthwhile precaution,
preventing other players from taking things from you or picking you up.
On MUCKs, locking yourself really isn't crucial. The server won't let
you pick up players, and it won't let you take things being held by
other players. If you are not locked, people *can* `rob' you, which
means that they take one of your pennies. Most players have several
thousand more pennies than they need.
Nonetheless, you can lock yourself by typing `@lock me = me'. (Locks are
discussed in Section 2.)
A more practical issue is that of `handing' and `throwing'. You may or
may not wish to allow people to hand and throw things to you. Both are
convenient, but it is possible to abuse the hand and throw commands.
Abuses range from throwing objects to someone who does not wish to be
disturbed (a minor annoyance) to handing someone an innocuous looking
object that can eavesdrop on their conversations (an offense that merits
being banned from the MUCK). Most players do allow handing and
throwing.
To allow handing, type `hand #ok'. To allow throwing, type `throw #ok'
and `@set me = J'. To disallow them, type `hand #!ok' and/or `throw
#!ok'. Both are disallowed by default. (`hand' and `throw' are
user-created commands, but most MUCKs have them.)
1.5.4 Getting a Home
(Note: It is not necessary to get a home immediately, and sometimes the
simplest approach is the best one: page a staff member and ask her to
set you up with a home or tell you how to do so.)
'Home' has both a technical and non-technical meaning on MUCKs. In the
technical sense, all players and things have a `home', a place to which
they are `linked', and to which they will return if the MUCK doesn't
know where to put them or if they are sent home by a command or program.
A player's home must be a room. A thing's home may be a room or player.
In the non-technical sense, your `home' is, naturally enough, where you
live. Your `non-technical home' (the place where you hang out, keep
your belongings, sleep, etc.) does not necessarily have to be your
`technical home', but it is more convenient for both to be the same.
Getting a home on the MUCK involves both technical and non-technical
issues. Read this section completely before typing any of the commands.
On the non-technical side, you will need to find a place where you can
put a home. There may be places where the builder has installed a
command that lets you put in a home: read `news' and any materials in
the place where you start off, or ask people online for information
about such places.
If you don't find such a place, or if you find a public place where you
would like a home but such a command is not available, you will need to
contact the owner of the room and work with her to set up a home. Type
`ex here' to find out the name of the room's owner, then contact her by
page or page #mail. On most MUCKs, wizards or staff members work with
new players to help set up a home. It's worthwhile asking people online
how this matter is usually handled on your MUCK.
On the technical side, getting home involves three steps:
1. Creating a home.
2. Linking yourself to the home.
3. Linking the home to the rest of the MUCK.
If you are using a program that automates the process, creating a home
is simply a matter of following instructions provided on a sign or
directory. Usually you just type something like `claim <# or
direction>'.
To create your own home, make a room with the `@dig' command, syntax
`@dig <room name>'. (You must have a `builder bit' -- the B flag
-- in order to use @dig. On most MUCKs, all players have a builder bit.)
====================================
> @dig Cashmere's Den
Cashmere's Den created with Room #1234.
Parent set to Outdoor Environment Room(#101RJA).
====================================
Note the dbref of the newly created room (#1234 in this example). You
will need it in order to go there or link the room to the rest of the
MUCK. If you forget the room's dbref, you can determine it with the
`@find' command.
====================================
> @find cashmere's den
Cashmere's Den(#1234RJ)
End of list
(1 object found)
====================================
(If you see the room's name, but not its dbref, you are set Silent. Type
`@set me=!S' to clear the Silent flag set on your character.)
A newly created room is said to be `floating': it exists, but is not
linked to anything else on the MUCK. In other words, there are no
`doors' in and out of the room. If your MUCK has convenient `global
exits' (commands that take you to a centralized location from anywhere
on the MUCK) it may be feasible to leave the room floating indefinitely.
If your MUCK has a convenient global exit, and you would like to set up
a home without having to wait for help from someone else, @dig a room as
described above, then use the `@link' command (syntax `@link
<object> = <home>') to set your home and the `home' command
to go there.
====================================
> @link me = #1234
Home set.
> home
You wake up at home, without your possessions...
Cashmere's Den(#1234RJ)
====================================
As the example suggests, you can loose things when using the home
command: when you type `home', both you and anything you are carrying go
home. If you are carrying things that do not belong to you, or that are
linked to somewhere else on the MUCK, they will return to their homes
when you use the home command (in other words, the `home' command is
recursive). There are two ways to avoid this problem. Teleporting may or
may not be allowed on your MUCK (usually players can teleport to rooms
they own). If you are able to, teleport to the new room first, then link
yourself there.
====================================
> @tel me = #1234
You feel a wrenching sensation....
Cashmere's Den(#1234RJ)
> @link me = here
Home set.
====================================
The second alternative is to use `gohome' rather than `home'. The `gohome'
command takes you to your home without causing the things you're carrying to
also go home. However, `gohome' is a user-created command: though it's widely
available, there is a possibility that your MUCK does not provide it.
====================================
> @link me = #1234
Home set.
> gohome
You head home, arriving safely.
Cashmere's Den(#1234RJ)
====================================
If you plan to leave your room set floating for a while, and your MUCK has a
gohome command, you can just use it whenever you want to go home. If there is
no gohome command, it will be worthwhile to create an action that takes you
there without causing you to loose things you are carrying. Use the @action
command (abbreviated @act, syntax `@act <action name> = <origin or
attachment point of acction>'), and the @link command (syntax @link
<action> = <destination>) to create the action
====================================
> @act myplace = me
Action created with number #1236 and attached.
> @link myplace = #1234
Linked to Cashmere's Den(#1234).
====================================
*****
Linking to the Rest of the Muck: Worst-Case Scenario
If you want to link your home to the rest of the MUCK, and no programs or
staff members are able to do this for you, you will need to work in concert
with another player (the owner of the room where you want your home to be).
The two of you will create two exits: one leading from your home to the other
person's room, and one leading from the other person's room to your home. By
working together, you will be able to work within a basic security
restriction: a player may not attach an exit in a room owned by someone else.
There are a number of ways to accomplish this, and a number of different
orders in which the steps could be performed. The method and order in the
following example will work fine. Cashmere has dug his den, and he has found a
place where he'd like to put his home: The Deep Dark Woods, owned by Fin.
Cashmere and Fin go to the Deep Dark Woods together and begin. Both players
will set their rooms Link_OK, so that others may make exits that lead to them.
Fin will make an exit in the Woods (she owns the Woods, so she can make an
exit there, and the Den is set Link_OK, so she can link the exit to the Den).
Cashmere will use the new exit to go to his Den. From there, he will make an
exit leading out to the Woods (he owns the Den, so he can make an exit there,
and the Woods are set Link_OK, so he can link the exit to the Woods)
====================================
C> @set #1234 = L (Cash sets Den Link_OK)
Flag set.
F> @set here = L (Fin sets Woods Link_OK)
Flag set.
F> @open Cashmere's Den;cd (Fin makes new exit)
Exit created with number #5222
F> "What's the dbref of your room?
Fin says, "What's the dbref of your room?"
C> "#1234
Cashmere says, "#1234"
F> @link cd = #1234 (Fin links exit to Den)
Linked to Cashmere's Den(#1234RJL).
F> "OK, done. `Cashmere's Den', alias `cd'"
Fin says, "OK, done. `Cashmere's Den', alias `cd'"
C> "What's the dbref here?
Cashmere says, "What's the dbref here?"
F> "#3209
Fin says, "#3209"
C> :nods... "Thanks. BRB."
Cashmere nods... "Thanks. BRB."
C> cd (Cash uses new exit to go to Den)
Cashmere's Den(#1234RJL)
C> @open Out;ou;o (Cash makes a new exit)
Exit created with number #5223
C> @link out = #3209 (Cash links exit to Woods)
Linked to The Deep Dark Woods(#3209RJL)
C> @set here = !L (Cash sets Den not-Link_OK)
C> out (Cash uses new exit to go to Woods)
The Deep Dark Woods
.
.
.
F> @set here = !L (Fin sets the woods not-Link_OK)
====================================
Finally, note that it is quite feasible to simply move in with someone
else. All that is necessary is that the other player's home be set 'A'
or 'Abode'. This flag lets other players set it as their homes. To do
so, simply go there and type `link me = here'.
1.6 Getting Help
There are a number of online resources for getting help with questions
or problems. The server command `help' (syntax `help <topic>')
provides online documentation of many (but not all) server commands and
features. Many (but not all) user-created commands follow the convention
of including a #help function (syntax `<command> #help'). For
example, you can get information on using the page program by typing
`page #help'. MUF and MPI both have online documentation: for MUF, type
`man <topic>'; for MPI, type `mpi <topic>'. Additional
information can be found in the `news' and `info' files. Typing either
of these commands should show a list of topics. The news and info files
are written and updated by a wizard; their content and quality will vary
widely. The staff should also be able to provide help and information:
type `staff' or `helpstaff' to get a list of available staff members.
Smaller MUCKS may not have a separate helpstaff; in this case type
`wizzes'. And, there's always The MUCK Manual.
*****************************************************************************
2.0 COMMANDS
Section 2 documents server commands and the user-created commands
provided in the standard start-up database.
2.1 Overview: Dbrefs, Names, Flags, Properties and Lists
All objects on a MUCK, of whatever type -- Player, Thing, Room, Exit, or
Program -- have a unique identifying number, a `database reference
number', or `dbref' for short. Multiple items may have the same name.
The type and behavior of all database objects are determined by flags
and properties. Both are ways of storing information about the object.
Of the two, flags control more basic or fundamental aspects of the
object. It might be helpful to think of flags as something that
determine *what an object is* and properties as something that determine
what *features* or *attributes* and object has (a property is in many
ways comparable to an `attribute' on MUSH). Multiple properties can be
combined to form a `list'... a collection of props that together act
much like a file or document.
Dbrefs and Names:
A dbref is assigned to each object when it is created. In most cases,
when specifying an object by its dbref, the number should be preceded by
an # octothorpe. (Some user-created programs require that the octothorpe
be omitted when the dbref is stored in a property.) The server assigns
either the next available number or that of the most recently recycled
object. For example, if the database holds 1,000 objects and all are
valid (have not been recycled), the next object created will be given
dbref #1001. If someone then recycles an object, say #123, the next
object created would be given dbref #123. So, dbrefs are not a reliable
guide to an object's age. Dbrefs cannot be changed. Unused dbrefs of
recycled objects are `garbage'.
Multiple objects can have the same name, except for players: there can
be several hundred exits named `out' on a MUCK, but only one player
named `Ruffin'... and there could (conceivably) be many things, exits,
and programs named `Ruffin'. All names can be changed with the `@name'
command, syntax `@name <object> = <new name>'. To rename a
player, the password must be supplied as well: `@name <'me' or old
name> = <new name> <password>'. A player must have
control of an object to rename it; programs can rename objects if the
object and the program have the same controller, or if the program is
set W. (Programs can only name players indirectly: if the player's
password is available, a wizbitted program can force the player or a
wizard to rename a player.).
Player names, unfortunately, cannot include spaces. `Madame_Bovary' is
an acceptable player name, but `Madame Bovary' is not. The names of
other types of objects can include spaces.
When handling or modifying an object in the same vacinity as you, you
can specify it by its name or part of its name. Partial names will work,
provided that you specify enough characters to distinguish the object
from others in the vacinity: `@desc super = <description>' will
describe `Superball', provided that `Superman' or something else with a
name beginning with `Super-' is not in the same vacinity.
When handling or modifying an object that has the same name as something
else in the vacinity, or an object not in the same vacinity as your
character, the object will need to be specified by dbref. You can
determine the dbref of an object controlled by you and in the same
vacinity by examining it (ex <object>). You can determine the
dbref of objects that you control but are not in the same vacinity with
the @find command, syntax `@find <object's name>'.
Two substitution strings can be used in place of either a name or dbref:
`me' and `here'. `Me' matches your character's dbref; `here' matches the
dbref of the room you are in.
====================================
> @name here = Waterloo Station
Name set.
> @name pen = Bic Four-Color Ballpoint
I don't see that here. (You left the pen at home.)
> @find pen
Nyest Penal Colony, Massage Room(#855RJ) (Includes string `pen'. Ignore.)
pen(#1237)
End of list
2 objects found.
> @name #1237 = Bic Four-Color Ballpoint
Name set.
> @name me = Ruffin flipFlap
You can't give a player that name. (Already a player named Ruffin.)
> @name me = Nebuchudnezer flipFlap
Name set. (But Nebuchudnezer works.)
====================================
Flags:
Flags -- also called `bits' -- provide an economical way to store
important information about all objects in the database.
Usually you can see both the dbref and flags of any objects you control
when they appear in a Contents or Inventory list, or in the case of
rooms, simply by doing a look. Whether or not you can see this
information is determined by the S flag set on your character: type
`@set me =!S' to see dbrefs and flags, or `@set me = S' to hide them (in
this context, the S flag means `Silent'). Whether you are set Silent or
not, you can see the flags set on an object you control by examining it.
The first flag listed after an object's dbref is its `type flag'. The
type flag functions differently than any remaining flags. It determines
the type of the object; it is set at the time of the object's creation;
it cannot be changed; and it determines the meaning or function of
remaining flags. If an object is created with the @dig command, it will
be a room and will have an R flag in the first position. If it is
created with the @action or @open command, it will be an exit and will
have an E flag. If it's created with the @program command, it will be a
program and will have an F flag. If it's created with the @pcreate
command, it will be a player and have a P flag. If it's created with the
@create command, it will be a thing, and will have none of these flags.
All flags are either `set' or `not set' at all times.
The meaning or function of the remaining flags depends on their
context... that is, on what type flag the object has. For example, if a
program (something with an F flag in the first position) is set D, the D
flag means `Debug', and debugging information is shown whenever the
program runs. If a room (something with an R flag in the first position)
is set D, the D flag means `Dark': the `Contents' list won't appear for
a player who doesn't control the room, and no notices are emitted when
players connect and disconnect in the room. In short, the same flag
won't always mean the same thing. While the context-dependent meanings
of flags can be confusing for new users, it provides an elegantly
economical way to store important information. The meanings of each
flag in relation to the type flags are listed in Section 2.5.
The type flag is set at the time of an object's creation. The remaining
flags can be toggled with the @set command and the `not operator' (an !
exclamation point). The syntax for setting a flag is `@set
<object> = <flag>'. For removing a flag, it's `@set
<object> = !<flag>'. Flags are not case sensitive: `@set
here = D' and `@set here = d' produce the same result.
====================================
> @set here = D
Flag set.
> @set here = !D
Flag reset.
====================================
Mortals' use of flags is restricted in a few ways. Most importantly,
they can only set flags on things they control. Players cannot change
the state of the Zombie (Z) or (D) flags on themselves. They cannot set
themselves or anything they own Builder (B) or Wizard (W). They must
have a Mucker bit (flags M1, M2, or M3) in order to change the Mucker
bit of a program. Players can set the Mucker bit of a program they own
to a level lower than or equal to their own, but not higher. Wizard's
control all objects and may change the state of any flag on any object,
with two exceptions: (1) type flags can never be changed; (2) if the
MUCK is compiled with the god_priv option (which it usually is), wizards
cannot set players W or !W.
*****
Properties:
A property is a named location on a database object that holds
information. Both the server and user-created programs reference
properties to obtain the data they need in order to carry out specific
operations. For example, when someone looks at you, the server
references your description property ( _/de), retrieves the information
stored there (your desc), and displays it to the person who's looking at
you. Properties are often called just `props'.
Props are organized into property directories (often called `propdirs').
The structure and syntax of property directories are very much like
those of file directories in the UNIX or DOS operating systems, with
props being analogous to files and propdirs being analogous to
directories. A directory can contain props or additional directories;
names of props and directories are separated by a slash; props and
directories are organized in a hiearchical `tree' structure such that
each prop has a unique path name. So, the desc prop mentioned above,
`_/de', is actually the `de' property in the _ underscore directory.
You can view the props on any object you control by examining it, syntax
`ex <object> = <path>'. Typing `ex me = /' would show the
`first level' or `root directory' of props and directories stored on
your character. Typing `ex me = sex' would show your sex property.
Typing `ex me = _page/' would show properties stored in the propdir
created and modified when you use the page command. Directories will be
prefaced by `dir' and will end with a slash. Properties will be prefaced
by something different (usually `str' for `string'), and will end with
the value stored in the prop.
Like flags, properties are set and removed with the @set command, though
the syntax is slightly different. The syntax for setting a prop is `@set
<object> = <[path/]property>: <value>'. For removing a
prop, it's `@set <object> = <[path/]property>: ` (that is, a
property name followed by just a colon). To clear a directory, it's
`@set <object> = <propdir>/:' You can remove all the
properties you have set on an object by typing `@set <object> =
:clear'.
====================================
> @set me = obstreperous:yes
Property set.
> @set me = obstreperous:
Property removed.
> @set me = personality_traits/obstreperous:yes
Property set.
> @set me = personality_traits/lascivious:yes
Property set
> @set me = personality_traits/:
Property removed.
> @set me = :clear
All user owned properties removed. ( oops )
====================================
It is common practice to separate words in a property name with
underscores (@set me = my_favorite_color:blue), but spaces can be used
in property names (@set me = my favorite color:blue). However, spaces at
the beginning and end of property names are removed when the prop is
set. (Spaces at the beginning or end of a property *value* are not
stripped: you can store a string beginning or ending with spaces, or
even a string consisting of only spaces.)
The number, names, and content of properties are not pre-defined as they
are in the case of flags. You can't `make up' a new kind of flag and set
it on your character (@set me = G or @set me = 9, say), but you can
create and set any property you like and store any information there, as
long as the syntax is correct and the amount of information stored
doesn't exceed certain limits . If you wanted to do `@set me =
number_of_pickles_in_my_jar:32', you could, though the information might
not be especially useful. (There are some restrictions on what
properties you can set, discussed in Section 2.1.1)
While you can set virtually any property, the server and user-created
commands will expect specific information to be stored in specific,
predefined properties. The server will always reference the `_/de' prop
when obtaining a desc; the `hand' command will always check your
`_hand_ok' prop. So, using a program or configuring an object is often a
matter of determining what props are referenced (by reading #help or
program documentation, or by asking players or staff) and setting them
appropriately. Important and frequently used properties are stored in
the correct location by server commands: @desc, @success, @osuccess,
@drop, @odrop, @fail, @ofail, and various @lock commands all store
information in the _/ directory. (Properties in the _/ directory and
their values are often called `messages' and `locks'. See Sections 2.1.2
and 2.3.)
====================================
> @create Feep
Feep created with number #1237
> @desc feep = A cute little feep.
Description set.
> @succ feep = You pick up the feep. It warbles contentedly.
Message set.
> @osucc feep = picks up the feep. It warbles contentedly.
Message set.
> @fail feep = You try to pick up the feep, but it scuttles away whimpering!
Message set.
> @ofail feep = tries to pick up the feep, but it scuttles away whimpering!
Message set.
> @drop feep = You set the feep down gently. It nuzzles your ankle.
Message set.
> @odrop feep = sets the feep down gently. It nuzzles %p ankle.
> @lock feep = me
Locked.
> @chlock feep = me
Chown lock set.
> ex feep = _/
lok /_/chlk:Mistral(#100PWX)
str /_/de:A cute little feep.
str /_/dr:You set the feep down gently. It nuzzles your ankle.
str /_/fl:You try to pick up the feep, but it scuttles away whimpering!
lok /_/lok:Mistral(#100PWX)
str /_/odr:sets the feep down gently. It nuzzles %p ankle.
str /_/ofl:tries to pick up the feep, but it scuttles away whimpering!
str /_/osc:picks up the feep. It warbles contentedly.
str /_/sc:You pick up the feep. It warbles contentedly.
====================================
The properties in the _/ directory trigger events or messages when the
object is used in a certain way. For example, the @success message is
displayed to a player who Successfully uses the object. If the object is
a thing, `successful use' means picking it up. For a room, `success'
means looking at the room. For an exit, it means passing through the
exit or using the exit as a command. The @osuccess message uses the same
definitions of `success', but in this case the message is shown to Other
players present, rather than the triggering player.
@Fail works similarly to @success, but in this case the message is shown
when a player *fails* to use the object successfully, usually because it
is locked against him (locks are discussed in Section 2.3), and @ofail
has a similar relationship to @osuccess.
On a thing, a @drop message is shown to a player who drops the object;
the @odrop message is shown to other players present when the object is
dropped. When a @drop message is set on an exit, the message is shown
to the player when he arrives in the destination room. The @odrop
message is shown to other players in the destination room.
Lists:
In addition to directories, props can also be organized in `lists'. A
list is a group of properties which are handled together in such a way
that they emulate a document or computer file. Lists can be created and
edited with the list editor, command `lsedit', syntax `lsedit
<object> = <list name>'. This is useful for descriptions
that need formatting such as paragraph breaks, indentations, and so
forth. Complex MPI strings can be stored in a list rather than a
property as well, in which case indentation and other whitespace can be
used to make the code more readable than it would be as one long
uninterrupted string. There are other uses.
====================================
> lsedit here = maindesc
< Welcome to the list editor. You can get help by entering `.h' >
< `.end' will exit and save the list. `.abort' will abort any changes. >
< To save changes to the list, and continue editing, use `.save' >
< Insert at line 1 >
<you type type type some text text text>
> .end
< Editor exited. >
< list saved. >
====================================
Lists are stored as a set of properties sharing the same path name, and
ending with `#/<line number>'.
====================================
> ex here = maindesc#/
str /maindesc#/1: (a line of text you entered... )
str /maindesc#/2: (another line... )
str /maindesc#/3: (another line... )
(etc)
====================================
The list name can be a path name that includes propdirs. For example,
you could store multiple descs in propdir `_descs'.
====================================
> lsedit me = _descs/snazzy
<enter your `snazzy' desc>
> .end
> lsedit me = _descs/grungy
<enter your `grungy' desc>
> .end
====================================
(The server, recall, always references the `_/de' property for a
description. If you write a description with lsedit, you will need to
put an MPI string in this property that tells the server where to find
the description and how to display it.
====================================
> lsedit me = _descs/snazzy
<enter `snazzy' desc... >
> look me
You see nothing special.
> @desc me = {list:_descs/snazzy}
Description set.
> look me
Ooo la la! Today Mistral is modeling the latest from the Spiegal
Catalogue: a fetching two-piece... (etc etc)
====================================
The MPI string stored in `_/de' can be made considerably more elaborate
and flexible than the one shown here. (See Section 3 for a more complete
discussion of MPI.)
The syntax for removing a list is `@set <object> = <[path/]list
name>#/:'
====================================
> @set me = descs/snazzy#/:
Property removed.
====================================
2.1.1 Protected, Restricted, and Wizard Props
Property handling is governed by a system of privileges, though in most
cases this will be transparent to the user: you will usually be able to
set the properties you want without even being aware that the server is
checking to see if you're allowed to do so. Besides `normal' props,
there are three classes of priviledged properties: protected,
restricted, and wizard. The class of a property or propdir is determined
by the first character in its name. A prop or propdir beginning with an
_ underscore, % percent sign, or . period is `protected'. A prop or
propdir beginning with a ~ tilde is `restricted'. A prop or propdir
beginning with an @ at-mark is `wizard'. If the prop or propdir begins
with any other character, it is `normal' or `unprotected'. (Note: the
`first character' restriction applies to any property or propdir. So,
`@email', `@/email', and `data/personal/@email' are all wizard props:
each includes a prop or propdir that begins with an @ at-mark.)
Properties beginning with a an _ underscore can only be written to by
the owner of the object on which the property is stored, or by programs
owned by the owner, or by programs running at M3 or W.
Properties beginning with a . period can only be written to *or read* by
the owner of the object on which the property is stored, or by programs
owned by the owner, or by programs running at M3 or W.
Properties beginning with a % percent mark, like _ underscore
properties, can only be written to by the owner or by programs owned by
the owner. The % percent mark properties have the additional function of
over-riding pronoun and name substitutions. For example, if Jessy does
@set me = %n:the Scamper Gal, the prop will be protected, and will serve
the additional function of causing `the Scamper Gal' instead of `Jessy'
to be substituted in messages that use the `%n' substitution string.
(See Section 2.1.6 for additional information on substitution strings.)
A restricted property ( ~ ) may be read like an unprotected prop,
however it may only be modified by a wizard or a wizbitted program. A
common use of restricted props is appointing non-wiz staff members.
Staff commands, exits to administrative areas, and so forth, can be
locked so that they may only be used by characters with specific
restricted prop, such as `~staff'.
A wizard property ( @ ) may only be read or modified by a wizard or a
wizbitted program. The server records connection data in players'
propdir @/. On some MUCKs, wizard props and propdirs are used to record
administrative information such as players' email addresses. Some
wizbitted programs record potentially sensitive data such as mail in a
wizard propdir stored on players.
Locks can read any property -- including restricted and wizard
properties -- but may only check for matches with a specific value. (See
section 2.3.)
2.1.2 Messages and Message Properties
As indicated earlier, a set of properties in the _/ directory is given
special handling by the server. They can be set with a group of server
commands such as @succ, @ofail, etc., and they cause strings to be
parsed and displayed automatically whenever certain events happen.
Collectively, this group of commands, properties, and their values are
called `messages'.
Command/Message Type Property
@desc _/de
@succ _/sc
@osucc _/osc
@fail _/fl
@ofail _/ofl
@drop _/dr
@odrop _/odr
@pecho _/pecho
@oecho _/oecho
(There does not seem to be a definitive pronunciation for messages: when
speaking in RL, some people would say `at-fail' for @fail, and others
would say simply `fail'.)
The @desc message is evaluated and displayed to any user who looks at an
object of any type.
====================================
> @desc me = A nymph with green hair.{look-notify}
Message set.
> l me
[ Kiri looked at you. ]
A nymph with green hair.
====================================
The @succ message is evaluated and displayed to any user who
successfully uses an object. The meaning of `success' varies depending
on the object type. To successfully use a thing or a program means to
pick it up. To successfully use a room means to look at it. To
successfully use an exit means to pass through it or use it as a command
that triggers a program. To successfully use a player means to steal one
of her pennies with the `rob' command.
====================================
> @succ out = You step out back.
Message set.
> out
You step out back.
====================================
The @osucc message is evaluated and displayed to all players in a room
where a player successfully uses the object, *other than* the player in
question. The @osucc message (that is, the string stored in the object's
_/osc property) is prefaced with the user's name when it is displayed.
====================================
> @osucc out = steps out back.
Message set.
(Kiri types `out'... others see...)
Kiri steps out back.
====================================
The @fail is evaluated and displayed to a user who fails to successfully
use an object. The normal reason for failure is that the object is
locked against the player. The terms for success or failure are those
indicated above, for @succ.
====================================
> @fail vault = Ahem. Only authorized bank employees may open the
vault. Various alarms begin to sound.
Message set.
> @lock vault = ~banker:yes
Locked.
> vault
Ahem. Only authorized bank employees may open the vault.
====================================
The @ofail message is evaluated and displayed to all players in a room
where a player fails to successfully use the object, *except* the player
in question. The @ofail message is prefaced with the user's name when it
is displayed.
====================================
> @ofail vault = tried to open the vault! Shrill alarms begin ringing!
Message set.
(Kiri types `vault'... others see...)
Kiri tried to open the vault! Shrill alarms begin ringing!
====================================
The @drop message is evaluated and displayed to a player who triggers a
drop. For a thing or program, a drop is triggered when the object is
dropped. For a room, a drop is triggered whenever an object is dropped
in the room. For an exit, a drop is triggered when a player (or other
object type) passes through the exit (using an exit/action linked to a
program does not trigger a drop). For a player, a drop is triggered
when he or she is killed.
====================================
> @drop grenade = BANG!
Message set.
> drop grenade
BANG!
====================================
The @odrop message is is evaluated and displayed to all players in a
room where a player drops an object, except for the triggering player,
or all other players in the room a player arrives in when she passes
through an exit. The @odrop message is prefaced with the user's name
when it is displayed.
====================================
> @odrop out = comes out of the house.
Message set.
(Kiri types `drop out'... the players in the outside room see...)
Kiri comes out of the house.
Kiri has arrived.
> @odrop grenade = drops a grenade! Run! {null:{delay:3,{lit:
{null:{tell:BANG!}}}}}
Message set.
(Kiri types `drop grenade'... others see...)
Kiri drops a grenade! Run!
BANG!
====================================
@Pecho and @oecho are somewhat different than the preceding messages,
having to do with the format of messages transmitted (or `broadcast') by
puppets and vehicles.
By default, output broadcast from a puppet is prefaced by the puppet's
name and a > greater than sign. Typing `@pecho <puppet name> =
<new preface string> sets the puppet objects _/pecho property,
which will become the new preface string. (See Section 4.3 for more
information on creating puppets.)
====================================
> z look
Squiggy> Amberside Inn, Tavern
Squiggy> At first glance the tavern seems little changed from days when
Squiggy> pirate sloops sought haven in the protected coves of Amberside's
Squiggy> cliffs: the beams are still low and smoke-stained...
> @pecho squiggly = *
Message set.
> ex squig = _/
str /_/pecho:*
1 property listed.
> z look
* Amberside Inn, Tavern
* At first glance the tavern seems little changed from days when pirate
* sloops sought haven in the protected coves of Amberside's cliffs: the
* beams are still low and smoke-stained...
====================================
By default, messages broadcast from the exterior of a vehicle object to
its interior will be prefaced by the string `Outside> `. Typing
`@oecho <vehicle object> = <new preface string>' will set
the vehicle's _/oecho property, which will become the new preface
string. (See Section 4.5 for more information on creating vehicles.)
====================================
> @create 1967 Corvette Sting Ray
1967 Corvette Sting Ray created with number #558.
> @set 1967 = V
Flag set.
> @act getin = 1967
Action created with number #559 and attached.
> @link getin = 1967
Linked to 1967 Corvette Sting Ray(#558V)
> drop 1967
Dropped.
> getin
1967 Corvette Sting Ray(#558V)
> z :raps sharply on the window... "Can you hear me in there, mistress?"
Outside> Squiqqy raps sharply on the window... "Can you hear me in
there, mistress?"
> @oecho here = >>>
Message set.
> z :raps again. "What about now?"
>>> Squiggy raps again. "What about now?"
====================================
2.1.3 Data Types and Setting Properties
In the vast majority of cases, props can be correctly set by players and
wizards with the @set command, as described above. However, in rare
cases the `data type' of a property needs special handling, and a
different command is needed: @propset.
Data handled by the MUCK server is `typed', as it is in many computer
languages, including C (the language the server program is written in)
and MUF (one of the two programming languages available on MUCKs). The
server handles different types of data, and most operations require a
specific type of data. In this context, the relevant types are `string',
`dbref', `integer', and `float'. (There is also a fifth data type:
`lock', which is discussed in secton 2.3. Type `float' is only available
on MUCK versions 6.0 or higher.)
A string is a series of zero or more characters (a zero-length string is
called a `null string'). A dbref is a database reference number. An
integer is a whole number. A float is a floating point decimal number.
These values can *look* the same but have different *types*. The type of
a datum is determined when it is stored. The string of numeral
characters "123", the #dbref 123, and the integer 123, and the float
123.0 are *four different values*.
The @set command stores property data as a string. The following three
commands store information in three different properties, but it's the
same value in each case: a string composed of the characters `1', `2',
and `3'.
====================================
> @set me = my_favorite_dbref:123
Propery set.
> @set me = my_favorite_integer:123
Property set.
> @set me = my_favorite_string:123
Property set.
====================================
If you typed these commands, and then did `ex me = /', you would see the
three properties, each prefaced by `str', meaning `this data is stored
as a string'.
====================================
> ex me = /
str /my_favorite_dbref:123
str /my_favorite_integer:123
str /my_favorite_string:123
====================================
(Note: on some versions of MUCK, the format of this output will be
somewhat different, such as `my_favorite_string: (String) 123')
Programs and commands often store data as dbrefs or integers rather than
strings; occasionally, players will want or need to do so as well. The
command for doing this is `@propset', syntax `@propset <object> =
<data type> : <[path/]property> : <value>'. The
following three commands store information in three different
properties, and although they look similar, it's a different value in
each case: a dbref, an integer, and a string respectively.
====================================
> @propset me = dbref:my_favorite_dbref:#123
Property set.
> @propset me = int:my_favorite_integer:123
Property set.
> @propset me = str:my_favorite_string:123
Property set.
====================================
(Type `float' has been omitted from this example: at the time of this
writing, @propset does not handle floating point numbers.)
If you typed these commands, and then did `ex me = /', you would see the
three properties, prefaced by `ref', `int', and `str' respectively, with
each preface showing the type of the data stored in the string.
====================================
> ex me = /
ref /my_favorite_dbref:Hortense(#123PBJ)
int /my_favorite_integer:123
str /my_favorite_string:123
====================================
There is also a server shortcut for setting properties with values of
type integer: put a ^ carot before the number.
====================================
> @set me = lucky_number:^5
Property set.
> ex me = lucky_number
int /lucky_number:5
====================================
2.1.4 Triggering From Properties
In most cases, programs and server operations are triggered (i.e. caused
to run or execute) by typing a command. However, they can also be
triggered from a number of protected properties: all message props
(_/de, _/sc, etc.), plus _connect, _oconnect, _disconnect, _odisconnect,
_arrive, _oarrive, _depart, _odepart, and _listen.
Performing any of the actions implied by these property names sends
information to the server and (if the property is set correctly) causes
messages to be displayed, an MPI string to be parsed, or a program to
run. For example, if you set a _connect prop on your character to
trigger a certain program, the program will run each time you connect;
if you put an MPI string in your _/de prop, it will be parsed each time
someone looks at you. The server searches up the environment tree (see
Section 2.2) for triggering props. For example, if _connect prop that
triggers a program is set on your character, the program will run each
time you connect. If it's set on a room, the program will run each time
someone connects in that room. If it's set on the global parent room
(#0), the program will run each time someone connects anywhere on the
MUCK.
The manner in which the props are set differs depending on which prop it
is (the _/ directory is handled differently than the others, such a
_connect or _listen) and on what the intended result is (messages are
handled differently than MPI, which is handled differently than program
calls).
To cause a message to be displayed by a _/ prop (_/de, _/sc, etc),
simply set the message as a string, with @set or the specific server
command. `@o- ` messages such as @osucc, @ofail, and @odrop are
prepended with the name of the triggering player (or other object type).
====================================
> @desc out=A simple wooden door.
Message set.
> look out
A simple wooden door.
> @succ out=You decide to go outside for a bit....
Message set.
> out
You decide to go outsides for a bit...
> @set out=_/sc:You head outside.
Property set.
> out
You head outside.
====================================
MPI strings in _/ props will be parsed automatically.
====================================
> @desc watch=You glance at your watch. The time is {time}.
look watch
You glance at your watch. The time is 01:44:31.
====================================
To trigger a MUF program from a _/ prop, preceed the dbref of the
program with an @ at-mark. For example, let's assume the dbref of the
`Obvious Exits' program is #123:
====================================
> @succ here=@#123
Message set.
> look here
Messy Room(#545RJ)
Boy, this place is a mess!
Obvious Exits:
Out <O>
====================================
The other triggering props (_arrive, _oconnect, etc) are handled
slightly differently. Simple strings cause no result, MPI must be
preceeded with an & ampersand in order to be parsed, and MUF programs
can be called with just a string indicating the dbref.
====================================
> @set me=_connect:555
Property set.
> @set me=_arrive:&{null:{otell:waltzes in.}}
Property set.
====================================
These triggers can be set up as a propdir rather than a single prop, in
order to trigger multiple results from the same action. For example, the
following settings would trigger both programs #581 and #555 each time
someone connects in the room. The propdirs are evaluated in alphabetical
order, so #581 would execute first. (Other than determining alphabetical
order, the prop names following the first / slash mark have no effect:
they can be whatever you like.)
====================================
> @set here=_connect/desc-check:#581
Property set.
> @set here=_connect/my-wwf:#555
Property set.
====================================
The _listen is triggered by *any* activity. As such, it is both very
useful and very easily abused. Permissions safeguards are coded into the
server for _listen: the only result that can be triggered is execution
of a program; the program must be set Link_OK and have a Mucker level
equal to or higher than a level set by the MUCK administrators. Usually
this parameter is set to 3 or 4 (M4 is `wizard'). `Bot programs and
automatic `noise' or `event' programs are common examples. The prop is
set simply by putting the dbref of the program to run in the property
value.
====================================
> @find noises
noises.muf(#812FLM3)
***End of List***
1 objects found.
> @set here=_listen/noise:812
Property set.
====================================
2.1.5 Registered Names
Objects can be specified by `registered names' as well as by names and
dbrefs. A registered name is an alias that can (like a dbref) be used
regardless of the object's location, but (like a name) consisting of a
memorable string. The primary use is to provide a convenient, memorable
way of specifying an item, regardless of its location and ownership. For
example, a player on a large MUCK might have a puppet with a long,
difficult to remember dbref, such as #128629. If the player frequently
wanted to teleport the puppet to her from somewhere else, she would need
to either memorize the dbref or repeatedly retrieve it with the @find
command. As an alternative, she could give the puppet an
easy-to-remember registered name such as `pup'. From that point on, the
puppet could be specified with the name `pup' preceeded by a $ dollar
sign, rather than by dbref.
Players can create registered names -- usuable only by the player --
with the @register command, syntax `@reg #me <object> =
<registered name>'. (The information is stored in the player's
`_reg/' directory.)
====================================
> @find Squiggy
Squiggy(#128629XZ)
***End of List***
1 objects found.
> @reg #me #128629 = pup
Now registered as _reg/pup: Squiggy(#128629XZ) on Jessy(#2PWQX)
> @tel $pup = me
Teleported.
> i
You are carrying:
Squiggy(#128629XZ)
You have 5086 pennies.
===================================
Individual registered names may also be set when an object is created.
The standard creation commands -- @create, @dig, @action, and @open --
each take two optional argument fields, separated by = equals signs. The
first of these fields is specific to each command; the second field for
all four may be used to specify a registered name.
@create <name> = <cost in pennies> = <reg name>
@dig <name> = <parent room> = <reg name>
@action <name> = <source> = <reg name>
@open <name> = <link> = <reg name>
====================================
> @create Mary Poppins Umbrella == umbi
Mary Poppins Umbrella created with number 226.
Registered as $umbi
> ex $umbi
Mary Poppins Umbrella(#226) Owner: Mistral
Type: THING
Created: Fri May 09 14:33:47 1997
Modified: Fri May 09 14:33:47 1997
Last used: Fri May 09 14:33:47 1997
Usecount: 0
> ex me=_reg/
ref /_reg/umbi:Mary Poppins Umbrella(#226)
> @dig OOCafe = #143 = cafe
OOCafe created with room number 225.
Trying to set parent...
Parent set to OOC Environment(#143RL).
Room registered as $cafe
> @open Enter Garden = $garden = gogard
Exit opened with number 224.
Trying to link...
Linked to Secret Garden(#455R).
Registered as $gogard
====================================
Wizards can set global registered names -- usuable by all players --
syntax `@reg <object> = <registered name>. A frequent and
convenient use of global registered names is to provide an alias for
publicly available programs such as `do-nothing' and `obvious-exits'.
Without global registered names, players would need to find the dbrefs
of these programs each time they needed them for building purposes.
Since the players do not control these programs, finding the dbrefs can
be difficult.
====================================
> @find obv
gen-Obvexits(#2002FLM3)
***End of List***
1 objects found.
> @reg #2002 = exits
Now registered as _reg/exits: gen-Obvexits(#2002) on The Void(#0R)
> @succ here = @$exits
Message set.
====================================
Global registered names are stored on room #0, in propdir `_reg/'.
2.1.6 Pattern Matching and Output Types
As indicated, the @find command can be used to locate items with a given
name. For more flexible searches, you can use pattern matching (a
limited version of regular expressions) to find objects whose name
matches a certain pattern, rather than matching the name string
literally. A pattern consists of logical and grouping operators,
wildcard characters, and/or literal characters. @Find -- and the related
search commands @owned, @contents, and @entrances -- can be used with a
subset of standard regular expression conventions, and additional
parameters that specify `output types' (parameters for values such as
memory used, time since used or modified, etc.)
Suppose that you have created a Coral Reef area, with interesting
scenery and games: players try to avoid sharks, wrestle octopi, and find
sunken treasure before they run out of breath and are forced to return
to the surface. To use the rooms and games, a player must have a
snorkle. You have set up a `make snorkle' action linked to an M2 program
that changes an object into a snorkle (it sets all the properties used
by your games). And, you have a Snorkle Rental Booth: a room where can
people rent snorkles or read `The Complete Book of Snorkles' and `Field
Guide to the Lesser Coral Reef' (help on how to use the area). The reef
rooms have names like `Coral Reef, Sandy Wash' and `Coral Reef, Moray's
Lair'. Occassionally, you need to find these objects... to recall and
update your snorkles or track down your wandering shark-bot, for
example.
You can use literal matches to find objects whose name includes the
string you are trying to match. Matching is not case-sensitive.
====================================
> @find complete book
The Complete Book of Snorkles(#811SJ)
1 objects found.
> @find coral reef
Field Guide to the Lesser Coral Reef(#810SJ)
Coral Reef, Sandy Wash(#802RJ)
Coral Reef, Moray's Lair(#805RJ)
Coral Reef, Near the Surface(#809RJ)
Coral Reef, Weed-Shrouded Cave(#812RJ)
Coral Reef, Sunken Hull(#815RJ)
Coral Reef, Dark Cave(#817RJ)
<etc.>
<etc.>
***End of List***
16 objects found.
====================================
The * and ? wildcard characters allow you to search for names that match
a pattern, rather than a literal string. The * asterix wildcard
(sometimes called a `glob') matches any zero or more characters; the ?
question mark matches any single character.
You could find your two cave rooms in the coral reef area (and leave out
other cave rooms you might have) by beginning putting a glob between
`Coral' and `Cave'.
====================================
> @find coral*cave
Coral Reef, Weed-Shrouded Cave(#812RJ)
Coral Reef, Dark Cave(#817RJ)
***End of List***
2 objects found.
====================================
You could find all the reef rooms, leaving out the book `Field Guide to
the Lesser Coral Reef', by searching for `reef' followed by a ? question
mark, which would require that there be at least one character after the
string `reef'.
====================================
> @find reef?
Coral Reef, Sandy Wash(#802RJ)
Coral Reef, Moray's Lair(#805RJ)
Coral Reef, Near the Surface(#809RJ)
<etc.>
<etc.>
***End of List***
15 objects found.
====================================
The {curly braces} grouping operators delimit word patterns. To find all
your snorkle objects and the `make snorkle' action, but omit `The
Complete Book of Snorkles', you could delimit `snorkle' as a word, and
not simply a string.
====================================
> @find {snorkle}
Snorkle Rental Booth(#856RJ)
make snorkle(#857ED)
Snorkle 1(#854)
Snorkle 2(#859)
Snorkle 3(#881)
Snorkle 4(#882)
Snorkle 5(#883)
Snorkle 6(#884)
Snorkle 7(#885)
Snorkle 8(#886)
Snorkle 9(#887)
Snorkle 10(#888)
Snorkle 11(#889)
Snorkle 12(#890)
***End of List***
13 objects found.
====================================
One can search for objects whose names include words from a group of
valid words by separating the words with the `or' operator, a | vertical
bar. For example, you could find all objects that include the words
`sunken' or `surface'.
====================================
> @find {sunken|surface}
Coral Reef, Near the Surface(#809RJ)
Coral Reef, Sunken Hull(#815RJ)
***End of List***
2 objects found.
====================================
The [square brackets] grouping operators delimit character groups or
ranges or characters.
A group of characters in square brackets are treated as valid single
characters. A find for `coral reef, [wdn]' would find the coral reef
rooms with either `w', `d', or `n' following the string `coral reef, `.
====================================
> @find coral reef, [wdn]
Coral Reef, Near the Surface(#809RJ)
Coral Reef, Weed-Shrouded Cave(#812RJ)
Coral Reef, Dark Cave(#817RJ)
***End of List***
3 objects found.
====================================
Instead of typing each valid character, you can also designate a range
of valid characters, such as [0-9], [a-z], or [A-Z]. You could find all
your snorkle objects, which all have a numeric character following the
string `Snorkle `, by using [0-9] as the range of characters.
====================================
> @find snorkle [0-9]
Snorkle 1(#854)
Snorkle 2(#859)
Snorkle 3(#881)
Snorkle 4(#882)
Snorkle 5(#883)
Snorkle 6(#884)
Snorkle 7(#885)
Snorkle 8(#886)
Snorkle 9(#887)
Snorkle 10(#888)
Snorkle 11(#889)
Snorkle 12(#890)
***End of List***
12 objects found.
====================================
Note that the [square brackets] delimit *character ranges*, not *numeric
ranges*. A find for `snorkles [1-12]' won't work... or won't work as one
might intend. It finds all objects with either characters in the range
of `1 to 1' or the character `2' following the string `snorkles `.
====================================
> @find snorkle [1-12]
Snorkle 1(#8454)
Snorkle 2(#8459)
snorkle 10(#8488)
snorkle 11(#8489)
snorkle 12(#8490)
***End of List***
5 objects found.
====================================
Output Types:
Searches with @find and the related commands (@owned, @contents, and
@entrances) may also be narrowed by object type and several other
values, and may return additional information such as the objects'
owners and locations. The extended syntax is:
@find <name or regex pattern> = <search parameter> = <output type>
One or several search parameters may be used. Valid search parameters may be a type flag, a Mucker level, or the following special values:
U = Show only unlinked objects
@ = Show only old and unused objects
~<size> = Show only objects with current memory used greater than <size>
^<size> = Show only objects with total memory used greater than <size>
(wizard only)
An output type parameter must be typed in full; only one output type may be used per search. Valid types include:
owners = List owners along with objects
links = List links along with objects
size = Show memory size
count = Don't list objects: just show total found
location = Show objects' locations
====================================
This search would list any unlinked exits you control...
> @find = EU
South;sout;sou;so;s(#528E)
North;nort;nor;no;n(#533E)
***End of List***
2 objects found.
====================================
====================================
This search would list any old and unused objects you control,
along with their locations...
> @find = @ = location
Faded rose(#761) Mistral(#100)
***End of List***
1 objects found.
====================================
Objects become `old and unused' if none of their `created', `modified', or `last used' timestamps is more recent than the `aging_time' system parameter.
====================================
This search will find all your M1 programs...
> @find = 1
HelloWorld.muf(#976FM1)
TrainingWheels.muf(#978FDM1)
WhatsMyName.muf(#979FM1)
CountMyBellyButton.muf(#980FM1)
***End of List***
4 objects found.
====================================
====================================
This search will find any objects you control which use more than
2000 bytes of memory, along with the current memory size...
> @find = ~2000 = size
Manhattan Phonebook(#1301) 1932373346 bytes.
***End of List***
1 objects found.
====================================
For additional information on output types and regular expressions, see
the entry for @find in the Server Command Reference (Section 2.6) and
the entry for SMATCH in the MUF Reference (Section 3.2.5).
2.1.7 Pronoun and Name Substitution
Messages returned by fields such as @success, @drop, etc., and also the
formatting of a number of commands and programs such as page, may be
dynamically formatted for a player's name and gender: substitution
strings (a % percent mark followed by a key character) are replaced by
the appropriate name or pronoun. Standard substitution strings are:
%a (absolute) = Name's, his, hers, its.
%s (subjective) = Name, he, she, it.
%o (objective) = Name, him, her, it.
%p (possessive) = Name's, his, her, its.
%r (reflexive) = Name, himself, herself, itself.
%n (player's name) = Name.
Capitalizing the substitution string -- such as %S or %R -- causes the
substitute value to be capitalized as well.
The server examines the `sex' property of the triggering player (or
other object type) and substitutes as needed. Supported values for the
sex property are `male', `female', and `neuter'. If the property is not
set, the player's name is used instead.
====================================
> @set $pup = sex:male
Property set.
> @osucc bonk = bonks %r on the head. %S exclaims, "I could have
had a V8!"
Message set.
> pp bonk
Squiggy bonks himself on the head. He exclaims, "I could have
had a V8!"
> @set $pup = sex:neuter
Property set.
> pp bonk
Squiggy bonks itself on the head. It exclaims, "I could have
had a V8!"
====================================
The values for these substitutions may be over-ridden by setting a
property with the same name as the substitution string.
====================================
These settings give Squiggy a nickname and some way PC pronouns...
> @set $pup = %n:The Squigmeister
Property set.
> @set $pup = %a:hes
Property set.
> @set $pup = %s:s/he
Property set.
> @set $pup = %o:hem
Property set.
> @set $pup = %p:hes
Property set.
> @set $pup = %r:hemself
Property set.
> pp bonk
Squiggy bonks hemself on the head. S/he exclaims, "I could have
had a V8!"
====================================
2.2 Overview: Rooms, Things, and the Environment Tree.
Rooms are objects created with the @dig command and having the type flag
R. Things are objects created with the @create command and having no
type flag. Both rooms and things can contain other objects.
Rooms:
The syntax for the @dig command is
@dig <room> [=<parent> [=<regname>]]
The position of rooms -- and the resulting `geography' of the MUCK -- is
determined in two ways. In addition to named exits creating the illusion
of spatial relationships (e.g. having a room called `The Village Green'
that can be reached by travelling West from `The Cove'), rooms exist in
a hierarchical tree structure known as the `environment tree'. One can
lead a rich VR life without ever needing to know about the MUCK's
environment tree, but builders and administrators will profit from an
understanding of how it works.
As an analogy, one might think of the rooms on a MUCK as numerous nested
boxes. Room #0, the `global parent', would in our analogy be a large box
containing all the other boxes... all the other rooms. Rooms inside #0
can also contain rooms: the boxes can contain other boxes, in an
unending series. The boxes (rooms) can contain items (players, things,
etc) as well as other boxes. A room that contains another room is said
to be a `parent room'; a room contained in another room is said to be a
`daughter room'. A given room can be contained in another and at the
same time contain other rooms: in this case, the room is both a parent
and daughter room. Intermediate rooms of this type are often called
`environment rooms'. (Or, another analogy: rooms are like directories in
a computer file system: the root directory is analogous to Room #0;
environment rooms and rooms are analogous to directories and
subdirectories within the root directory; players and objects in rooms
are analogous to files in these directories.) Environment rooms are used
to define areas of a MUCK and to provide commands or features that
should only be available in certain areas (more on this below).
You can view the series of rooms containing the room you are located in by typing `@trace here'.
====================================
> @trace here
Sinshe Village, by the Pier(#687RJ)
Sinshe Parent Room(#635RA)
Environment: Lowlands(#285RA)
Rainforest Parent Room(#121RWA)
Rainforest: Main Prarent(#118RA)
Master Environment(#101RA)
**Missing**
====================================
In this example, the administrators of the MUCK have carefully laid out
a consistent, hierarchical environment tree. In addition to the
`geographical position' of Sinshe Village, each room on the MUCK has a
specific and meaningful place in the environment tree. The village pier
is nested inside -- or `parented to' -- the Sinshe Parent Room (#635),
which presumably contains all the rooms that make up the village of
Sinshe. This room is in turn parented to Environment: Lowlands (#285),
which would contain the parent rooms for all areas in the lowlands. The
series continues up through rooms #121, #118, #101, and finally, room
#0, which appears on this list as `**Missing**' (to mortals, rooms not
set Abode and not controlled by them appear as **Missing** on a @trace;
for security reasons, the global parent of a MUCK is usually not set A,
and as a result the last item on the list will be **Missing**).
In fact, not only rooms but all objects on a MUCK have a position in the
environment tree. Exits are considered to be located in or on the object
to which they are attached. Players and things are always located in a
specific room or thing... but, unlike rooms and exits, they move around.
The @trace command works on any object. If a player were holding an
object called `paper sack', `@trace paper sack' would show the sack's
current position in the environment tree.
====================================
> @trace paper sack
paper sack(#5474)
Jessy(#2WQJ)
Sinshe Village, by the Pier(#687RJ)
Sinshe Parent Room(#635RA)
Environment: Lowlands(#285RA)
Rainforest Parent Room(#121RWA)
Rainforest: Main Prarent(#118RA)
Master Environment(#101RA)
**Missing**
====================================
A newly created room is parented to the first room above it that is set
Abode, or the first room controlled by the player issuing the @dig
command. If no rooms in the environment path meet one of these criteria,
it is parented to Room #0. Keeping parent rooms set Abode will insure
that new rooms are correctly parented: if Jessy stood on the pier and
typed `@dig Under the Pier', the new room would be correctly parented to
Sinshe Parent Room(#635RA), the same parent as that of the pier proper.
The position of a room within the environment tree can be changed (that
is, it can be `re-parented') with the @teleport command: teleport the
daughter room to its new parent room. For example, if another player
wanted to begin a new area -- an African village say -- she could start
off from the pier in Sinshe, and use the @teleport command to position
the new rooms correctly.
====================================
> @dig Environment: Afurica
Environment: Afurica created with room number #5266.
Parent set to Sinshe Parent Room(#635RA).
> @tel #5266 = #101
Parent set.
> @dig Kapiti Plain Environment Room
Kapiti Plain Environment Room created with room number #5435.
Parent set to Sinshe Parent Room(#635RA).
> @tel #5435 = #5266
Parent set.
> @dig Kapiti Plain -- By the Watering Hole
Kapiti Plain -- By the Watering Hole created with room number #5433.
Parent set to Sinshe Parent Room(#635RA).
> @tel #5433 = #5435
Parent set.
> @act kap = me
Action created with number #5435 and attached.
> @link kap = #5433
> kap
Kapiti Plain -- By the Watering Hole(#5433R)
> @trace here
Kapiti Plain -- By the Watering Hole(#5433R)
Kapiti Plain Environment Room(#5435R)
Environment: Afurica(#5266R)
Master Environment(#101RA)
**Missing**
***End of List***
====================================
The new environment rooms do not have an Abode flag. In order to make
#5435 and #5266 appear for other players in a @trace, and in order for
player-created rooms to be correctly parented, they will need to be set
A. Once Kenya has moved to Kapiti Plain -- By the Watering Hole(#5433),
any new rooms she digs from there will be correctly parented to Kapiti
Plain Environment Room(#5435).
Alternately, the parent room can be declared at the time the room is created.
====================================
> @dig Environment: Afurica = #101
Environment: Afurica created with room number #5266.
Trying to set parent...
Parent set to Master Environment(#101RA).
====================================
Registered names also can be declared when the room is created.
====================================
> @dig Kapiti Plain -- By the Watering Hole = #5435 = kap
Kapiti Plain -- By the Watering Hole created with room number #5433.
Trying to set parent...
Parent set to Sinshe Parent Room(#635RA).
Room registered as $kap
or...
> @dig Kapiti Plain -- By the Watering Hole == kap
Kapiti Plain -- By the Watering Hole created with room number #5433.
Parent set to Sinshe Parent Room(#635RA).
Room registered as $kap
====================================
Environment rooms have numerous uses, most deriving from the fact that
the MUCK server uses something very much like the UNIX and DOS operating
systems' `search path' when locating executable commands. When a player
issues a command, the server looks for a command of that name on rooms
up the environment path as well, and will execute the first match it
finds, or the command with the highest priority. (The search order and
rules for determining exit priority are somewhat involved. See Section
2.3.3., Exit Priorities.)
One result is that commands can be made available for a whole area (and
only that area) by placing them in the appropriate parent room. In our
above example, Kenya could make a command called `map' that shows an
ASCII map of Kapiti Plain, and attach it to the Kapiti Plain Environment
Room. Then, when any player in the Kapiti area types `map', he would see
the map. Because each room has a unique path within the environment
tree, there is no danger that a map for some other area will be shown,
even if other builders make similar commands with the same name.
Environment rooms can also be used to *disable* commands within a
certain area. If, for some reason, Kenya decided that spoofing should
not be allowed in Kapiti, she could create a command with the same name
as that of the global spoof command, attach it to Kapiti Plain
Environment Room, and link it to $nothing. The server's search path
starts with one's present location and moves toward the global parent.
As a result, the newly created do-nothing spoof will be found and
executed before the server reaches the global spoof command in #0:
spoofs in Kapiti will be intercepted at the area parent room, and
produce no result.
Programs can search for properties as well as command names in the same
way, a fact that has numerous applications for builders and programmers.
Keeping all one's rooms and belongings within a parent room also
facilitates archiving. If a player parents all her rooms to a personal
parent room, she could then archive all her belongings by going to the
parent room and typing `@archive here'. Everything controlled by the
player and contained in the parent -- daughter rooms, the contents of
daughter rooms, and the player herself -- would be archived. (For more
information on archiving, see Section 4.5.)
The parent room and everything contained by it and controlled by the
player -- daughter rooms, the contents of the daughter rooms, and the
player herself -- will be archived.
The Realms Wizard system also makes use of the the environment tree. A
Realms Wizard is a player who owns a room set W, on a MUCK where realms
control is enabled. Such a player has wizard-like powers in that room
and any rooms below it in the environment tree. This explains a
seemingly unnecessary duplication in the environment path from the
previous example, which contains `Rainforest Parent Room(#121RWA)' and
`Rainforest: Main Parent(#118RA)'. There seem to be two `main' parent
rooms for the Rainforest: an additional environment room has been
slotted into the path, giving the owner of room #121 (which is set W)
realms-wiz control over the Rainforest. This player can attach exits,
examine objects, and so forth anywhere in the Rainforest, but not in
other areas of MUCK.
====================================
> @trace here
Sinshe Village, by the Pier(#687RJ)
Sinshe Parent Room(#635RA)
Environment: Lowlands(#285RA)
Rainforest Parent Room(#121RWA) <-- Owner of this room
Rainforest: Main Parent(#118RA) is a realms wizard
Master Environment(#101RA)
**Missing**
====================================
The same result could be achieved by @chown'ing #118 to the player, and
setting it W. Often, though, there are reasons to slot in an extra room
in this way. In this example, the realms wiz owning #121 would have
control over the Rainforest, but not over Rainforest-specific commands
attached to #118.
The organizing logic of a MUCK's environment tree does not necessarily
have to be spatial or geographical. Another workable system is to create
environment rooms that each serve as the parent for rooms of a given
type. For example, the administrators of a MUCK might create a series of
environment rooms such as `Outdoors Environment Room', `Indoors
Environment Room', and `Vehicle Environment Room'. Additional more
specific environment rooms might be created as well: the Outdoors
Environment Room could contain rooms `Mountain Environment Room', `Swamp
Environment Room', `Plains Environment Room', and so forth. The
advantage of this system is that commands and default messages can be
set up in a consistent, realistic, and economical way. The disadvantage
is that -- since newly created rooms have the same parent as the room
from which one digs -- players often end up with incorrectly parented
rooms: if a player owns an indoors room called `The Den', and then digs
an adjacent outdoors room called `The Backyard', the backyard will be
located in the Indoors Environment Room unless the player moves it. Many
players won't.
Things:
Things are created with the @create command:
@create <object> [=<cost> [=<regname>]]
The standard start-up database includes the user-created commands `put'
and `fetch'. `Put' allows you to put an item you are carrying inside
another item (syntax `put <object> in <object>'). `Fetch'
allows you to retrieve an item from inside another (syntax `fetch
<object> from <object>'). Partial names may be used for
<object>.
====================================
> put kitty snacks in backpack
Putting Kitty Snacks in Backpack.
> fetch kitty from back
Fetching Kitty Snacks from Backpack.
====================================
Things can also be set up as vehicles, by setting their V flag and
creating an exit that is both attached and linked to the thing. For
vehicles, and occassionally for other objects, you would want to
describe the interior of the thing. The interior of a thing can be given
a description with the @idescribe command, syntax `@idesc <object>
= <interior description>'.
====================================
> @create tRanSMogriFIER
tRanSMogriFIER created with number 5489.
> @desc trans = A large cardboard box with tRanSMogriFIER
written on the side in marker, and an arrow that says ----> IN
Description set.
> @idesc tRanSMogriFIER = An enthusiastic artist has made lots of
buttons and monsters with a marker on the sides.
Description set.
> l trans
A large cardboard box with tRanSMogriFIER written on the side in
marker, and an arrow that says ----> IN
> @act get in;in;enter = trans
Action created with number #2543 and attached to tRanSMogriFIER(#5489)
> @link get in = trans
Linked to gen-nothing.muf(#363FLM2)
> get in
tRanSMogriFIER(#5489)
An enthusiastic artist has made lots of buttons and monsters with
a marker on the sides.
====================================
See Section 4.4 for more information on making vehicles.
2.2.1 Droptos
If a room is linked to another room or to a thing, the object linked to
will serve as the room's `dropto'. A dropto is a location to which
dropped objects will be moved.
====================================
> @dig Lost and Found = #102 = lnf
Lost and Found created with room number 198.
Trying to set parent...
Parent set to OOC Environment(#102RA).
Room registered as $lnf
> @link here = #102
Dropto set.
> Drop bic
Dropped.
> @contents #198
Bic Four-Color Ballpoint(#1237)
***End of List***
1 objects found.
====================================
If a room's Sticky flag is set, the drop-to is delayed until all players
have left the room. To remove a dropto, @unlink the room. To remove a
Sticky bit, type `@set here = !S'.
2.2.2 Looktraps
'Looktraps' are details or `fake objects' in a room. For example, rather
than creating a `Sign' object with instructions on how to use some local
commands and placing it in a room, you could mention the sign in the
room's desc and create it as a looktrap. There will be no separated
dbref'd object named `Sign', but players will still be able to do `look
sign' and see it. The primary value of looktraps is efficiency: because
no separate object is created, overall database size is somewhat
smaller, and commands that must search the database have one fewer
objects to examine.
Looktraps are stored as properties in the _details/ directory. Names of
looktraps follow the aliasing conventions of exits: strings delimited by
; semicolons serve as alias names.
====================================
> @set here = _details/sign;plaque;notice:To see who lives here,
type `look mailboxes'. To get a home here, type `claim #',
using an unclaimed home number for `#'.
Property set.
> l plaque
To see who lives here, type `look mailboxes'. To get a home here,
type `claim #', using an unclaimed home number for `#'.
====================================
Looktraps are automatically parsed for MPI.
====================================
This looktrap puts the sign text in a list, allowing better control
over formatting...
> @set here = _details/sign;plaque;notice:{list:signtext}
Property set.
> lsedit here = signtext
< Welcome to the list editor. You can get help by entering `.h' >
< `.end' will exit and save the list. `.abort' will abort any changes. >
< To save changes to the list, and continue editing, use `.save' >
< Insert at line 1 >
> ... text text text ...
> ... blah blah blah ...
> ... etc etc etc ...
< Editor exited. >
< list saved. >
====================================
====================================
This looktrap creates a `delayed effect'. Players get a little message
nine seconds after they look at the portrait.
> @set here=_details/painting;picture;portrait:A somber portrait in oils,
depicting Baron Von Hoofenstaffen, former owner of this mansion.{null:
{delay:9,{lit:{null:{tell:You're not quite sure: it seems, perhaps, that
the eyes of the portrait are following your moves.}}}}}
====================================
Note: Many MUCKs have soft-coded `look' commands that handle setting and
removing looktraps, with syntaxes such as `look #add <detail> =
<desc>'. Type `look #help' to determine if such a system is
available on your MUCK.
2.3 Overview: Exits and Locks
An `exit' is a link between two objects on a MUCK. When the two objects
are rooms, the exit creates a virtual `door' between them. When the
destination is a program, the exit serves as a user-created command.
Other combinations are possible. Exits are also called `actions'. Use of
exits (as well as objects of other types) is controlled by `locks': an
expression that evaluates as either `true' (in which case the
exit/object can be used) or `false' (in which case it cannot). An exit
is characterized by having a starting point (an object to which it is
`attached') and a destination point (an object to which it is `linked').
*****
Exits are created with either the @open or @action command. Both create
an exit (an object with type flag E), but the syntax and defaults are
slightly different.
The basic syntax of the @open command is `@open <exit name>'. An
exit created in this way will be attached to (i.e., start from) the room
in which one issues the command, and it will not be linked to anything
(it won't lead anywhere). The exit can be linked to another object on
the MUCK with the @link command, syntax `@link <exit name> =
<destination>'. Since the destination will usually be somewhere
else on the MUCK, it will need to be specified by dbref rather than
name.
====================================
Hooking up an exit in two steps...
> @open out
Exit opened with number #1766.
> @find hallway
Ansley Inn, Hallway(#198R)
1 objects found.
***End of List***
> @link out = #98
Linked to Ansley Inn, Hallway(#98R)
Hooking up an exit in one step...
> @open out = #98
Exit opened with #1766.
Linked to Ansley Inn, Hallway(#198R)
====================================
An exit does not have to be attached to a room, however: an exit can be
attached to anything except a program or another exit. The `@action'
command (abbreviated as `@act') creates an action/exit attached to an
object specified at the time of creation:
====================================
> @act myplace = me
Action created with number #1236 and attached.
> @link myplace = #1234
Linked to Cashmere's Den(#1234).
Many MUCKs have a soft-coded @action command, that allows you to specify
both the source and destination at the time of the exit's creation:
> @act myplace = me,#1234
Action created with number #1236 and attached.
Trying to link...
Linked ot Cashmere's Den(#1234)
====================================
The attachments and links of exits can be changed. To relink an exit,
issue the @unlink command and then @link the exit to the new
destination.
====================================
> @unlink myplace
Unlinked.
> @link myplace = #1768
Linked to Cashmere's Bachelor Pad(#5784R).
====================================
To change an exit's point of attachment, use the @attach command, syntax
`@attach <exit> = <new attachment point>.
====================================
> @attach refrigerator = here
Action re-attached.
====================================
(Obvious-exit programs generally list exits in the order of
first-attached to last-attached, or the reverse. Therefore, the order in
which exits appear on the list can be changed by using @attach to
re-attach exits to the room: the exit will then become the last-attached
exit, and move to either the first or last position in the list.)
To reiterate, exits have a source (the object to which they are
attached) and a destination (the object to which they are linked). This
means that they are *one way*. This point often causes confusion for new
builders: in order to create a `door' between two rooms, one needs to
create two exits, one leading in each direction. The following example
illustrates this: Cashmere's Bachelor Pad has dbref #5784. From the
Bachelor Pad, he will create a Bedroom, and then create two exits that
make a door between the Pad and the Bedroom.
====================================
> @dig Cashmere's Bedroom
Cashmere's Bedroom created with #5792.
Parent set to BD's Environment Room(#4989RA).
> @open Bedroom = #5792
Exit opened with number #5793.
> bedroom
Cashmere's Bedroom(#5792)
> @open Out = #5784
Exit opened with number #5784.
Linked to Cashmere's Bachelor Pad(#5784R).
====================================
Exits linked to things move the the thing to the point of attachment
when used (rather than moving the user to the thing).
====================================
> @act getpup = me
Action created with number #4684 and attached.
> @link getpup = $pup
Linked to Squiggy(#128629XZ).
> getpup
done
> i
You are carrying:
Squiggy(#128629XZ)
You have 10664 wet cats.
====================================
Exits' names can include `aliases', other names that can be used as the
exit name. An existing exit can be renamed to include aliases with the
@name command, or the aliases can be specified at the time of the exit's
creation.
====================================
Renaming an existing exit...
> @name bedroom = Bedroom <B>;bedroom;bed;b
Name set.
Creating an exit with aliases...
> @open Out <O>;out;ou;o
Exit opened with number #5785.
====================================
Each string separated by a ; semi-colon is an alias for the exit. In the
`out' example above, typing either `out <o>', `out', `ou', or `o'
would cause the player to use the out exit. Only the first name or alias
is shown a list of obvious exits. The above examples follow the common
and useful convention of supplying a `full' exit name along with a
simple abbreviation in the first alias.
====================================
> look
Cashmere's Bachelor Pad(#5784R)
Obvious Exits:
Bedroom <B> Out <O>
====================================
*****
Locks:
Locks are expressions used to control the use of objects. The most
common applications are to lock exits so that only some people can use
them, and to `lock down' things that you need to leave lying about in
rooms (a sign or bulletin board, for example). Just what constitutes
`use' depends on the object type. To `use' a thing means to pick it up.
To `use' an exit means to pass through it to another room, or to use it
as a command. To `use' a room means to look at it.
If an object is locked it may be used if and only if the lock expression
is `true' for the player (or other object type) attempting to use the
object. `True' in this context and in rather nontechnical terms means
`if the triggering player/object "is" or "has" or "is owned by" a result
of the lock expression'.
A simple example...
====================================
> @lock closet = me
Locked.
> ex out = _/
lok /_/lok:Kenya(#75PBJM1)
====================================
A lock expression is stored as data type `lock' (see also section
2.1.2), as indicated indicated by the prefix `lok', and meaning that the
server will evaluate the expression for `truth' in reference to the
triggering player (or other triggering object type). The lock in this
example evaluates to `database object #75'. If the player or other
object trying to use the exit `is' #75 (that is, if it is Kenya), then
the lock `passes': Kenya will be able to use the exit. Further, if the
the triggering player/object `has' Kenya, the lock would pass: if Kenya
were inside a vehicle object, the vehicle would be able to use the exit.
And, if the triggering object `is owned by' Kenya, the lock would
pass... for example, a puppet owned by Kenya would be able to use the
exit.
Property values as well as dbrefs can serve as lock expressions. The
syntax for locking an object to a property value is `@lock
<object> = <property> : <value>.
====================================
> @lock Powder Room = sex:female
Locked.
> ex out = _/
lok /_/lok:sex:female
====================================
If the triggering player/object `has' the property value `female' in her
`sex' property, the lock passes: in other words, only females can use
this exit. (When the system parameter `lock_envcheck' is tuned to `yes',
the server searches rooms in the environment tree path for property
matches on locks, as well as the triggering player/object. In this case,
if room #0 were set sex:female, the lock in the above example would
always pass.)
Wildcard characters (see Section 2.1.5) may be used in locks for
property values:
====================================
This exit may be used by males and females, but not fluffs... lyve wyth yt.
> @lock Normal Folks Bar and Grill = sex:*ale
Locked.
====================================
Lock expressions may contain or evaluate to multiple elements. The
elements must be separated by an `or' operator (a | vertical bar) or by
an `and' operator (an & ampersand), and may optionally be preceded by a
`not' operator (an ! exclamation point). Player names may be used,
provided that they are preceded by an * asterix pointer.
====================================
This exit may be used by either of two players, Passiflora or Kenya...
> @lock Den of Iniquity = *passiflora|*kenya
Locked.
This exit may only be used by female staff members...
> @lock Wizards' GunPowder Room = ~staff:yes&sex:female
This exit may be used by anyone (or anything) who is *not* Stinker...
> @lock Jessy's House = !*stinker
This exit may only be used by someone who *is* Jessy and who *is not*
Jessy. In other words, this lock alway fails...
> @lock chair = *jessy&!*jessy
====================================
The operators have the following order of precedence:
1) ! not
2) | or
3) & and
The order of precedence can be over-ridden by enclosing sub-expressions
within (parentheses).
====================================
This exit may be used by all females and all others who are *not* Stinker...
> @lock bar = !*stinker|sex:female
This exit may be used by all who are *not* female and *not* Stinker...
> @lock bar = !(*stinker|sex:female)
====================================
An object can be locked to a MUF program, in which case the program runs
when someone uses or attempts to use the object, and the lock passes if
the program returns a true *MUF* value (that is, MUF's truth conditions
over-ride the truth conditions for locks). In MUF, a "" null string, the
integer 0, the floating point value 0.00000, and the dbref for
`nothing', #-1, are false. If the MUF program returns any of these
values, the lock fails; if it returns any other value, the lock passes.
A lock cannot include MPI (or rather, will invariably fail if set to an
MPI string), but an object can be locked to a property value, and the
property value on a relevant object can be set to an MPI string.
====================================
This exit may only be used on the stroke of midnight (or by someone who has figured out the lock and set his `time' property to `00:00:00')...
> @lock time machine = time:00:00:00
Locked.
> @set time machine = time:{time}
Property set.
====================================
Locks may be removed with the @unlock command, syntax `@unlock
<object>'.
2.3.1 Bogus Exits
It is (or was) a relatively common practice to create lookable details
and realism-enhancing actions in rooms by means of `bogus exits'...
exits that do not lead anywhere. The exits can be given a description,
so that doing `look <exit>' shows some detail of the room, and
realistic messages can be put in the exit's @fail/@ofail or
@succ/@osucc.
====================================
> @open Grandma's Rocker;grandmas rocker;rocker;chair;sit
Exit opened with number #5797.
> @lock chair = me&!me
Locked.
> @desc chair = An old, old rocker that has been in the family
for generations.
Description set.
> @fail chair = You take a seat in the old rocker.
Message set.
> @ofail chair = takes a seat in the old rocker.
Message set.
====================================
The above example creates a `virtual chair'. Though it will not appear
in the room's Contents list, people can look at it, and can sit in it by
typing `sit' (or any of its other aliases).
Bogus exits have their place, but builders should be aware that there
are other ways of accomplishing the same goals without creating a
separate exit for each item (an approach that quickly leads to dbase
bloat). Lookable details can created with `looktraps' (see section
2.2.2) and many events like the `sit' message in the above example can
be handled by a single action (See section 3.1.2, MPI Examples).
2.3.2 Unsecured Exits
An exit that is not linked to anything and not thoroughly locked is
insecure, in that its ownership transfers to anyone who uses the exit
and anyone can link it. This creates a minor security risk: someone
could take control of an exit attached to one of your rooms and make it
do something annoying or harmful. So, always secure exits. An exit can
be secured by locking it to a condition that always fails -- such as
`me&!me' -- or by linking it to something. All established MUCKS provide
a `do-nothing' program, a program that produces no result, and thus
serves as a convenient linking point for exits. Usually such a program
is given the registered name `$nothing' or `$do-nothing'.
====================================
> @link sit = $nothing
Linked to gen-nothing.muf(#363FLM2).
====================================
2.3.3 Exit Priorities
In our discussion of the environment tree, it was noted that the server
searches up the environment tree for commands matching users' input. If
more than one command with the same name is found, the server must
resolve which command to execute. This is determined by the `priority'
of the exits, and the order of the search path. Both are affected by the
system parameter `compatible_priorities'.
Wizards can set Mucker bits on exits as well as on programs and players.
An exit with a higher Mucker bit runs at higher priority than an exit
with a lower Mucker bit, or one with no Mucker bit.
For example, suppose a MUCK has a global exit named `bank' linked to a
program that gives players 100 pennies, and a player has an exit in his
room named `bank' linked to a program that gives players 500 pennies. If
neither exit has a Mucker bit set, both are considered `Priority 0'
(zero). The *first* exit found in the search path would be executed: a
player standing in the room with the `local' exit would receive 500
pennies; elsewhere, the global `bank' command would run, and the player
would receive 100 pennies.
However, if a wizard set the global `bank' exit M1, the global exit
would now have higher priority. Even in the room with the `local' exit,
typing `bank' would execute the global exit, and players would receive
100 pennies.
As indicated, if there are two exits with the same name and the same
priority, the server executes the *first* exit found. But the order of
the search path changes depending on whether the system parameter
`compatible_priorities' is set to `no' or `yes'. (Wizards may set system
parameters with the @tune command.)
If compatible_priorities is set to `no', all non-prioritied exits (i.e.,
exits with no Mucker bit set) are considered `priority 0', and the
server uses the following search order:
1) On the room the player is located in
2) On objects the player's inventory
3) On objects in the room's inventory
4) On the player
5) Environment rooms containing the present room, beginning with the
`closest' room... the room furthest from room #0
6) Room #0
7) The server
If compatible_priorities is set to `yes', all non-prioritied exits are
considered `priority 1', and the server uses the following search order:
1) On the room the player is located in
2) On the player
3) Environment rooms containing the present room, beginning with the
`closest' room... the room furthest from room #0
4) Room #0
5) Objects in the player's inventory
6) Objects in the room's inventory
7) The server
In our example, the wizard had just set the global `bank' exit M1, so it
had a higher priority than the local M0 exit. If the wizard then did
`@tune compatible_priorities = yes', both exits would now be considered
`priority 1': the global is priority 1 because it is set M1, and the
local is considered priority 1 because the system parameter is set to
run all unprioritied exits at priority 1. The search order for players
and inventories has changed, but in both cases the local room is checked
before the global parent #0. So, now the local exit would run when
player's type `bank' in the room with the local exit. If the wizard then
set the global exit M2, it would again have higher priority than the
local exit, and would run regardless of where a player is standing when
typing `bank'.
If you have difficulty getting a local or personal exit to run in
preference to a global of the same name, contact a wizard and discuss
modifying priorities, either by raising your exit's priority, or by
changing the system parameter.
2.4 User-Created Commands
We have used the term `user-created commands' throughout the manual to
indicate soft-coded commands created by the wizards or players of a
MUCK. Most other issues affecting such commands -- the command search
path, exit priorities, locks, etc. -- have been discussed at various
points above.
Because efficient soft-coded commands can easily be added to a MUCK, the
platform is highly customizable. In general, this is a Really Good
Thing: MUCKs can be continually improved and tailored to their
population's needs, without hacking the server code, which often results
in bugs and invariably results in innumerable versions and patch levels
of the program.
On the downside, you can't assume that something you've learned on one
MUCK will work exactly the same way on a different MUCK. And, the MUCK
Manual cannot provide a complete reference for any given MUCK.
Most MUCKs do share a core set of standard programs, libraries, and
commands, distrubuted as the `standard database'. Discussion of the
standard commands is provided in Section 2.7, User-Created Command
Reference. The programming libaries are discussed in Section 3.2.4, MUF
Library Reference.
2.5 Flag Reference
A (Abode, Abate, Autostart)
- On a Room: Anyone can set their home or the home of objects to the
room.
- On an Exit: The exit is lower priority than an exit without the ABATE
flag. If compatible_priorties is tuned to `no', an abated exit's priority
is `less than 0'; If compatible_priorites is tuned to `yes', an abated
exit's priority is `less than 1'.
- On a Program: The program will automatically be loaded into memory
and executed when the MUCK starts or restarts.
B (Builder, Bound or Block)
- On a Player: Player can create and modify objects with the @create,
@dig, @link, and @open. On most MUCKs, players start off with a B flag.
A B flag on players is also called a `builder bit'.
- On a Room: Personal exits (exits attached to a player) cannot be used
in the room.
- On a Program: Any functions within the program run in pre-empt mode.
If the program set B is called by another program, multi-tasking
status returns to that of the calling program when execution exits
from the called program.
(Only wizards can set and remove B flags.)
C (Chown_OK, Color)
- On any object except Players: Anyone can take control of the object
with the @chown command (`change ownership').
- On a Player: MUCK output will be formatted with ASCII color, provided
that the player's client handles color and that the text has been
formatted with color (version 6.0+ only)
D (Dark, Debug)
- On a Room: Wizards and the owner of the room see all objects normally,
but other players see only objects they own. If no objects would be
seen, a `Contents' list is not appended to the description of the room.
- On a Thing: The object does not appear in the room's `Contents' list.
- On a Player: The player does not appear in the `Contents' list of rooms
or in the WHO list. Only wizards may set players dark.
- On a Program: A stack trace of internal program operations is printed
out to anyone who uses the program.
E (Exit)
Type Flag: The object is an Exit/Action.
F (MUCK Forth Program)
Type Flag: The object is a program.
H (Haven, HardUID)
- On a Room: The `kill' command may not be used in that room.
- On a Player: The player cannot be paged.
- On a Program: The program runs with the permissions of the owner of
the trigger, rather than with the permissions of the user of the
program. When this is set in conjunction with the STICKY (SETUID,
below) flag on a program, and the program is owned by a wizard, then
it will run with the effective mucker level and permissions of the
calling program. If the caller was not a program, or the current
program is NOT owned by a wizard, then it runs with SETUID.
J (Jump_OK)
- On a Room: Players can teleport to and from the room (assuming other
conditions for teleporting are met). If the MUCK is configured with
SECURE_TELEPORTING, J indicates that exits attached to players and
objects can be used to leave to leave the room, and !J indicates that
they cannot.
- On a Thing: The object can be moved by a program running at any Mucker
level.
- On a Player: The player can teleport to and from rooms (assuming other
conditions for teleporting are met).
K (Kill_OK)
- On a Player: The player can be killed with the `kill' command. A player
who is `killed' is simply sent home.
L (Link_OK)
- On a Room: Anyone can link exits to the room.
- On a Program: The program can be called by any program, and can be
triggered by actions and propqueues not owned by the owner of the
program.
M1 (Mucker Level 1) (See also section 3.2.1)
- On a Player: The player is an `apprentice' Mucker. He can use the
MUF editor and create M1 programs.
- On an Exit: The exit runs at priority 1.
- On a Program: The program runs with Mucker level 1 permissions. The
program cannot get information about or send information to any object
that is not in the same room. Some MUF primitives cannot be used.
Program output to anyone except the triggering player is prepended with
the triggering player's name. Instruction count is limited to about
20,000 instructions. The program follows permissions for protected
props (see section 2.1.1).
M2 (Mucker Level 2) (See also section 3.2.1)
- On a Player: The player is a `journeyman' Mucker. She can use the
MUF editor and create M2 programs. She can set the Mucker level of
any program she controls to M1 or M2.
- On an Exit: The exit runs at priority 2.
- On a Program: The program runs with Mucker level 2 permissions. Some
MUF primitives cannot be used. Instruction count is limited to about
80,000 instructions. The program follows permissions for protected
props (see section 2.1.1).
M3 (Mucker Level 3) (See also section 3.2.1)
- On a Player: The player is a `master' Mucker. He can use the MUF
editor and create M3 programs. He can set the Mucker level of any
program he controls to M1, M2, or M3.
- On an Exit: The exit runs at priority 3.
- On a Program: The program runs with Mucker level 3 permissions. Almost
all MUF primitives can be used. There is no absolute limit to instruction
count, unless the program is running in PREEMPT mode. The program may
over-ride the permissions for protected props.
P (Player)
Type Flag: The object is a Player.
Q (Quell)
- On a Player or Room: The Quell flag cancels the effects of a wizard
flag. A wizard player set Q is effectively a normal player. A Q flag on
a wizbitted room will cancel the realms-wiz powers of the room's owner.
R (Room)
Type Flag: The object is a Room.
S (Silent, Sticky, SetUID)
- On a Thing: The object will return to its home when dropped.
- On a Room: The room's drop-to is delayed until all players have left
the room.
- On an Exit: If the exit is attached to a thing and linked to another
thing <<<check>>>
- On a Player: The player will not see dbrefs on things she owns, and
will not see objects in a Dark room. Control is unchanged however.
- On a Program: The program runs with the permissions of the owner of
the program, and not those of the user.
W(izard)
- On a Room: The room's owner has Realms Wiz powers in that room and
any rooms parented to it, provided that the MUCK's realms_control
parameter is set to `yes'.
- On an Exit: The exit runs at priority 4.
- On a Player: The player is a wizard. Wizards have control over all
objects in the database (although with some restrictions in their
control over God and other wizards). Wizards can use restricted,
wiz-only commands, and can set programs, rooms, and things W and B.
Some wizard powers are enabled or disabled by the system parameter
`god_priv'.
- On a Program: The program is effectively Mucker level 4. All MUF
primitives may be used, and do not have a maximum instruction count
unless the program is running in pre-empt mode.
X(forcicble)
- On a Player or Thing: The player or thing may be forced by a player
(or other object type) to which it is force_locked.
V(ehicle)
- On a Thing: The object is a vehicle.
- On a Room: Vehicles may not enter the room.
- On an Exit: Vehicles may not use the exit.
Z(ombie)
- On a Thing: The object is a Zombie: all output the Zombie sees or hears
will be related to the controlling player.
- On a Room: Zombies may not enter the room or be forced in the room.
- On an Exit: Zombies may not use the exit.
2.6 Server Command Reference
@ACTION | @ACT
@action <name>=<source> [=<regname>]
Creates a new action and attaches it to the thing, room, or player
specified. If a <regname> is specified, then the
_reg/<regname> property on the player is set to the dbref of the
new object. This lets players refer to the object as $<regname>
(ie: $mybutton) in @locks, @sets, etc. You may only attach actions you
control to things you control. Creating an action costs 1 penny. The
action can then be linked with the command @LINK.
~
@ARMEGEDDON
@armedeggon
Shuts down the MUCK without first doing a save. The primary purpose is
to avoid over-writing the saved database if it becomes aware the current
database is corrupt. (Wizard only)
~
@ATTACH | @ATT
@attach <action> = <new source>
Removes the action from where it was and attaches it to the new source.
You must control the action in question.
~
@BOOT
@boot <player>
Disconnects a player from the game. If a player is connected more than
once it affects the most recent connection. (Wizard only)
~
@CHOWN
@chown <object> [=<player>]
Changes the ownership of <object> to <player>, or if no
player is given, to yourself. If the MUCK is compiled with PLAYER_CHOWN,
all players are allowed to take possession of objects, rooms, and
actions, provided the CHOWN_OK flag is set, with the following
exception: mortals may @chown an exit if they own the object it is
attached to, or an object it is linked to. Mortals cannot take ownership
of a room unless they are standing in it, and may not take ownership of
an object unless they are holding it. Wizards have absolute power over
all ownership.
~
@CHOWN_LOCK | @CHLOCK
@chown_lock <object> = <lock expression>
Locks <object> such that it may only be chowned by players for
whom <lock expression> is true. The object's CHOWN_OK flag must be
set as well. Wizards may chown any item, regardless of its chown_lock.
~
@CONLOCK
@conlock <object> = <lock expression>
Locks <object> such that only those for whom <lock
expression> is true may place things in or remove things from
<object>.
~
@CONTENTS
@contents [<object>] [= <flags/types> = [<output type>]]
Searches the given object for items & exits that match the given flag
string.
For an explanation of the flags/types modifiers and the output types,
see the help entry for @FIND.
Example: `@contents here = DE = owner' will list all Dark Exits attached
to your current location, giving the owner of each one. See also @FIND,
@OWNED, @ENTRANCES
~
@CREATE
@create <object> [=<cost> [=<regname>]]
Creates a new object and places it in your inventory. This costs at
least ten pennies. If <cost> is specified, you are charged that
many pennies, and in return, the object is endowed with a value
according to the formula: ((cost / 5) - 1). Usually the maximum value of
an object is 100 pennies, which would cost 505 pennies to create. If a
<regname> is specified, then the _reg/<regname> property on
the player is set to the dbref of the new object. This lets players
refer to the object as $<regname> (ie: $mybutton) in @locks,
@sets, etc. Only a builder may use this command.
~
@CREDITS
@credits
Displays a screen listing the names of people and places who have
contributed to TinyMUCK's development.
~
@DESCRIBE | @DESC
@describe <object> [=<text>]
Sets the description field of <object> to <text>. If
<text> is not specified, the description field is cleared. This is
the same as `@set <object> = _/de:[text]'. A description is what
is seen when a player looks at something.
~
@DIG
@dig <room> [=<parent> [=<regname>]]
Creates a new room, sets its parent, and gives it a personal registered
name. If no parent is given, it defaults to the first ABODE room down
the environment tree from the current room. If it fails to find one, it
sets the parent to the global environment, which is typically room #0.
If no regname is given, then it doesn't register the object. If one is
given, then the object's dbref is recorded in the player's
_reg/<regname> property, so that they can refer to the object
later as $<regname>. Digging a room costs 10 pennies, and you must
be able to link to the parent room if specified. Only a builder may use
this command.
~
DROP
drop <object>
Drops the <object> if you are holding it. It moves the object to
the room you are in, unless its STICKY flag is set (in which case the
object will go to its home), or the room has a drop-to (in which case
the object will go to the room's drop-to). Programs are much like
objects but are not affected by room droptos or STICKY flags. A `drop'
message can be set, which will be shown to the player dropping the
object, and an `odrop', which will be shown to the other players in the
room. See @drop, @odrop.
~
@DROP
@drop <object> [=<text>]
Sets the drop field of <object> to <text>. If <text>
is not specified, the drop field is cleared. The drop message on an
object is displayed when you drop it. On an exit, it is displayed upon
entering the destination room. On a player it is displayed to whoever
kills them. On a room, it is displayed when an object is dropped there.
This is the same as `@set <object> = _/dr:[text]'
~
@DUMP
@dump [filename]
Saves the database from memory to disk. Automatically occurs every three
hours, and when @shutdown is used. It does slow down the server, so only
use if you fear a server crash is iminent. If a filename is given, it
will save the db to that file, and save any subsequent dumps to it as
well. (Wizard only)
~
@EDIT
@edit <program>
Searches for a program and if a match is found, puts the player into
edit mode. Programs must be created with @PROGRAM.
~
@ENTRANCES | @ENT
@entrances [<object>] [= <flags/types> = [<output type>]]
Searches through the database for items that you control linked to
<object>.
For an explanation of the flags/types modifiers and the output types,
see the help entry for @FIND.
Example: `@entrances here = ED = location' will list all Dark Exits
that are linked to your current location, giving the location of each
one. See also @FIND, @OWNED, @CONTENTS.
~
EXAMINE | EX
examine <object> [=propdir]
If you control <object>, examine will give you a complete
breakdown of all fields, flags, etc., that are associated with the
object. If the optional propdir field is supplied, then it instead lists
out all the properties directly under that propdir. To list the base
propdir of an object, use `ex <object>=/'. Program-executing
fields are displayed as their true text, rather than executing the
program in question. If you do not control <object>, however, it
prints the owner of the object in question, and, again, displays the
true text of the description.
~
@EXAMINE <<< check >>>
~
@FAIL
@fail <object> [=<message>]
<Object> can be a thing, player, exit, or room, specified as
<name> or #<number> or `me' or `here'. Sets the fail message
for <object>. The message is displayed when a player fails to use
<object>. Without a message argument, it clears the message. This
is the same as: `@set <object>=_/fl:[text]' See also @OFAIL, and
@DESC.
~
@FIND
@find [<name>] [= <flags/types> = [<output type>]]
Searches through the database for items that you control matching
<name>. Players control only objects they own; wizards control all
objects, so @find searches the entire database when they use it.
Flags or types can be specified, to specify that you only want to list
objects that have that flag set, or that are of that type. You can also
specify to list objects that are NOT of that specific type, or that do
NOT have that flag. (A ! not operator before the modifier indicates that
it is to be inverted.)
The flags that you can specify are: (use the initial capitalized letter
only) Abode, Builder/Block, Chown_ok, Dark/Debug, Haven, Interactive,
Jump_ok, Kill_ok, Link_ok, Mucker, Quell, Sticky/Silent, Vehicle,
Wizard, Xforcible, and Zombie.
You can also specify Mucker Levels by the level number: 1, 2, 3, or 4.
The types that you can specify are: (use the capitalized letter only)
Exit, muF program, Garbage, Player, Room, and Thing.
There are a few other modifiers you can specify: (use only initial character)
Unlinked will specify that you want to list only unlinked objects.
@ specifies to list objects longer than about 90 days old.
~size will match all objs whose current memory usage is greater than
or equal to size bytes. This must be the last modifier in the
list of modifiers.
^size will match all objs whose total memory usage, when fully loaded,
is greater than size bytes. To do this, it loads the entire
object into memory from disk. This modifier is only available
to wizards. For regular players, this acts like ~size. This
must be the last modifier in the list of modifiers.
The output types that can be given are owners, links, size, count, &
location.
(You use the whole name for output type, and you can use only one at a time.)
owners lists who owns each object.
links shows what each object is linked to, or *UNLINKED*, or, for exits
linked to multiple things, *METALINK*
size displays how much memory is currently being used by an object. If
this option is used with the ^ modifier, (see above) then this
will display the true full size of the object, and not just how
much is currently being used.
count causes nothing to be shown but how many objects the @find/etc would
match. ie: it doesn't display any of the matched objects.
location shows where the object is located at.
The matching on names is as follows:
Individual words can be matched as {word1|word2|...}
Individual characters can be matched as [abc...]
A ? matches any character.
A * matches any number of characters, including none.
Any of these special charcters can be matched by putting a \ before it.
Examples of use:
"@find north = EU = location" will find all of your unlinked exits named
"north" and print them along with their locations.
"@find {big|little} = R!L" finds all your rooms whose names contain "big"
or "little" and are not LINK_OK.
"@find w[ei]ll" will find everything you control whose name contains "will"
or "well."
"@find =E=links" will list all exits that you control, and display where
they are linked to.
"@find button==locations" will list all objects you control with `button'
in the name, and it will display where thay are located at.
"@find =~2000=size" will list all your objects whose current memory usage
is 2000 bytes or more, and it will display their size.
"@find =^2000=size" will, for a wizard, find all objects in the db that are
2000 or more bytes in total size, when fully loaded, and it will show
their sizes. Note that this will load all of each object into memory
to make the size determination. On some systems this can take a while,
and on all systems this is an abuse to the diskbasing cache. Only
Wizards may use this search feature.
See also @OWNED, @ENTRANCES, @CONTENTS
~
@FORCE
@force <player>=<command>
Causes the game to process <command> as if typed by
<player>. With the compile option GOD_PRIV, God cannot be forced
by his/her sub-wizards.
~
@FORCE_LOCK
@force_lock <object> = <lock expression>
Locks <object> such that it may only be @forced by players or
other object types for whom <lock expression> is true, provided
that the XFORCIBLE flag is set. Wizards may force any object, except
God.
~
GET
get <object>
Attempts to pick up <object>. The lock on <object> is
checked for a success (true), and the normal path of success/fail is
then taken. On success the object is placed in your inventory.
Another variation on this is `get <container>=<object>',
which attempts to get <object> from the given container. The _/clk
lock property on <container> is tested, and if it is true, when it
checks to see if the standard _/lok lock property on <object>
tests true. If both locks pass, then <object> is moved into the
player's inventory. If there is no _/clk property on <container>
it defaults to failing. The _/lok property, on <object>, on the
other hand, defaults to passing. @succ/@fail messages are not displayed,
when fetching something from a container.
~
GOTO, GO
go[to] <direction>; go[to] home
Goes in the specified direction. `go home' returns you to your starting
location. The word `goto' or `go' may be (and usually is) omitted.
`Move' is the same as `go'.
~
GIVE
give <player> = <# pennies>
Gives <# pennies> to <player>. For mortals, <#
pennies> must be a positive number less than or equal to the number
of pennies they have. <# pennies> is subtracted from the giving
player's inventory. Wizards may give any amount from positive
MAX_INTEGER to negative MAX_INTEGER. Giving does not affect the wizard's
own inventory of pennies.
~
GRIPE
gripe <message>
Sends <message> to the system maintainer. Gripes are logged for
later reference; also, if the system maintainer is connected he will
receive the gripe real-time when the gripe is made.
~
HELP
help <topic>
Shows an online help document for <topic>. `Help' with no argument
shows a brief list of basic commands. `Help help' shows a list of index
topics.
~
HOME
home
Sends you home, no matter where you are. You retain your pennies, but
any objects you are carrying leave your inventory and return to their
own homes.
~
@IDESCRIBE
@idescribe <object> [=<text>]
Sets the idescription field of <object> to <text>. If
<text> is not specified, the description field is cleared. This is
the same as `@set <object>=_/ide:[text]' An idescription is what
is seen on the inside of a vehicle, when a player inside it looks
around.
~
INFORMATION
information <topic>
Shows an online document about <topic>. If no topic is supplied, a
list of available topics will be shown.
~
INVENTORY | INV | I
inventory
Lists what you are carrying. This can be abbreviated to inv or i.
~
KILL
kill <player> [=<cost>]
A successful kill sends the player home, sends all objects in the
player's inventory to their respective homes. The probability of killing
the player is <cost> percent. Spending 100 pennies always works
except against Wizards who cannot be killed. Players cannot be killed in
rooms which have the HAVEN flag set. On systems where the KILL_OK flag
is used, you cannot kill someone unless both you and they are set
Kill_OK.
~
@KILL
@kill <processid|playername|programdbref|"all">
If passed a processid (a number without a `#' preceeding it), it will
kill the given process, if the player controls it. If passed a player
name, it will kill all the processes controlled by that player. If
passed a program dbref, it will kill all processes that that program is
running in. If the argument passed is "all", and the player is a wizard,
it will kill all processes on the timequeue.
~
LEAVE
leave
Leave the vehicle you are currently inside.
~
@LINK
@link <object1>=<object2> [; <object3>; ... <objectn> ].
Links <object1> to <object2>, provided you control
<object1>, and <object2> is either controlled by you or
linkable. Actions may be linked to more than one thing, specified in a
list separated by semi-colons.
~
@LIST
@list <program> [=[line1] [-] [line2]].
Lists lines in a program, provided you control it or it is LINK_OK.
Zero, one, or two line numbers may be specified, denoting the range of
lines to list. If no lines are given, the entire program is listed.
~
@LOCK
@lock <object> = <key>
Locks <object> to a specific key(s). <Object> can be
specified as <name> or #<number>, or as `me' or `here'.
Boolean expressions are allowed, using `&' (and), `|' (or), `!' (not),
and parentheses (`(` and `)') for grouping. To lock to a player, prefix
their name with `*' (ex. `*Igor'). A key may be a player, an object, or
`property:value'.
~
LOOK
look <object>
Looks around at the current room, or at <object> if specified. For
players, displays their description and inventory, for things, their
description, and for rooms, their name, description, succ/fail message,
and contents. Also triggers osucc/ofail messages on rooms. Programs are
triggered accordingly on desc/succ/fail fields.
~
MAN
man [<subject>]
Displays the programmer's manual or a quick reference for MUF.
~
MOVE See GOTO.
~
MPI [<subject>]
Displays the programmer's manual or a quick reference for MPI.
~
@NAME
@name <object>=<name> [<password>]
Sets the name field of <object> to <name>. <Name>
cannot be empty; a null name is illegal. <Password> must be
supplied to rename a player. Wizards can rename any player but still
must include the password.
~
@NEWPASSWORD
@newpassword <player> [=<password>]
Only wizards may use this command. Changes <player>'s password,
informing <player> that you changed it. Must be typed in full. If
GOD_PRIV was defined, nobody can change God's password.
~
NEWS
news [<topic>]
Displays the current news file for the game. Must be typed in full. If a
topic is given, then it displays the information on that specific topic.
~
@ODROP
@odrop <object> [=<text>]
Sets the odrop field of <object> to <text>. If <text>
is not specified, the odrop field is cleared. Odrop on an object is
displayed prefixed by the player's name when s/he drops that object. On
an exit, it is displayed upon a player's arrival to the destination room
(or the location of the destination player). On a player, it is
displayed after the `name killed victim!' message. On a room, it is
displayed when an object is dropped there, prefixed by the object's
name. This is the same as: `@set <object>=_/odr:[text]' See also
@DROP.
~
@OECHO
@oecho <vehicle object> = <echo prepend string>
Sets a string to prepend to messages relayed to the interior of a
vehicle in the vehicle's _/oecho property. By default, the name of the
vehicle object, followed by a > greater than character is used to
prepend such messages.
~
@OFAIL
@ofail <object> [=<message>]
The @ofail message, prefixed by the player's name, is shown to others
when the player fails to use <object>. Without a message argument,
it clears the message. <object> can be specified as <name>
or #<number>, or as `me' or `here'. This is the same as: `@set
<object>=_/ofl:[text]'. See also @FAIL.
~
@OPEN
@open <exit> [=<object> [; <object2>; ... <objectn> ] [=<regname>]]
Opens an exit in the current room, optionally attempting to link it
simultaneously. If a <regname> is specified, then the
_reg/<regname> property on the player is set to the dbref of the
new object. This lets players refer to the object as $<regname>
(ie: $mybutton) in @locks, @sets, etc. Opening an exit costs a penny,
and an extra penny to link it, and you must control the room where it is
being opened.
~
OUTPUTPREFIX
OUTPUTPREFIX [string]
Must be in all capitals, and typed in full. Prints the given line before
the output of every command, setting them apart from other messages.
~
OUTPUTSUFFIX
OUTPUTSUFFIX [string]
Must be in all capitals, and typed in full. Prints the given line after
the output of every command, setting them apart from other messages.
~
@OSUCCESS
@osuccess <object> [=<message>]
The @osuccess message, prefixed by the player's name, is shown to others
when the player successfully uses <object>. Without a message
argument, it clears the @osuccess message. It can be abbreviated @osucc.
<Object> can be specified as <name> or #<number>, or
as `me' or `here'. This is the same as `@set
<object>=_/osc:[text]' See also @SUCCESS.
~
@OWNED
@owned <name> [= <flags/types> = [<output type>]]
Searches through the database for items that <name> controls.
For an explanation of the flags/types modifiers and the output types,
see the entry for @FIND.
Example: `@owned Revar=F!L3=location' will list all Mucker Level 3 (3)
programs (F) owned by Revar, that are NOT set Link_OK (!L), and it will
show the location of each one.
Note that only wizards can do an @owned on other people. See also
@ENTRANCES, @FIND, @CONTENTS.
~
PAGE
page <player> [= <message>]
This tells a player that you are looking for them. They will get a
message in the form of `You sense <pager> is looking for you in
<location>.' A <message> is optional, and is delivered in
the form of `<pager> pages: <message>.' Your location is not
revealed in message pages. If a player is set HAVEN, you cannot page
them, and they will not be notified that you tried. You will instead be
told, `That player does not wish to be disturbed.' (Note: Most systems
use a user-created program with a global `page' action, which takes the
place of the built-in `page' command, and has more features.)
~
@PASSWORD
@password <old password> = <new password>
This changes your password.
~
@PCREATE
@pcreate <player> = <password>
Only wizards can use this command. This command creates a new player. It
may only be used if REGISTRATION is enabled.
~
@PECHO
@pecho <puppet object> = <echo prepend string>
Sets a string to prepend to messages relayed from a puppet in the
puppet's _/pecho property. By default, the name of the puppet object,
followed by a > greater than character is used to prepend such
messages.
~
POSE
pose <message> or :<message>
Causes <message> to be displayed to the room, prepended by your
name.
~
@PROGRAM
@program <program>
Create a new program, or enter edit mode on an existing one. See also
@EDIT.
~
@PROPSET
@propset <object> = <data type> : <property> : <value>
Sets <object's> <property> to <value>, with
<value> stored as data type <data type>. You must control
<object>.
~
@PS
@ps
Lists the status of the currently running MUF program processes. This
lists all processes for a Wizard. Non-Wizards only see the muf processes
that they can @kill. See @KILL.
~
PUT
server: put <object>
user-created: put <object> in <container>
The server version of `put' is an alias of `drop'. The standard start-up
database supplies a user created command that moves <object> into
<container>, provided that you are holding both <object> and
<container> and that <container> is not @conlocked against
you.
~
QUIT
QUIT
Must be in all capitals, and typed in full. Logs out of your character
and leaves the game. Your character remains at the location you are in
when you log out, although it might be moved elsewhere while you are
`asleep.'
~
READ
read [<object>]
An alias for `look'. The standard start-up dbase supplies a bulletin
board program for which `read' is a command to read bulletins.
~
@RECYCLE
@recycle <object>
Destroy an object and remove all references to it within the database.
The object is then added to a free list, and newly created objects are
assigned from the pool of recycled objects first. You *must* own the
object being recycled, even wizards must use the @chown command to
recycle someone else's belongings.
~
@RESTRICT
@restrict <on|off>
Turning restriction on allows only wizards to log onto the MUCK. Turning
it off returns to unrestricted access.
~
ROB
rob <player>
Attempts to steal one penny from <player>. The only thing you can
steal are pennies.
~
@sanchange <<< check >>>
~
@sanity <<< check >>>
~
@sanfix <<< check >>>
~
SAY
say <message> or "<message>
Says <message> out loud. See also POSE, PAGE, and WHISPER.
~
SCORE
score
Displays how many pennies you are carrying.
~
@SET
@set <object> = [!] <flag> -or-
@set <object> = <property> : [ <string> ] -or-
@set <object> = :
@set does one of three things on TinyMUCK, it can modify flags, add
properties to an object, or remove properties from an object.
Using the first format, you may set flags, which are: WIZARD, LINK_OK,
DARK [DEBUG], FILTER, STICKY [SETUID], JUMP_OK, BUILDER [BOUND], QUELL,
CHOWN_OK, HAVEN [HARDUID], ABODE [AUTOSTART], VEHICLE, ZOMBIE, or
Mucker. You can also set the Mucker (or Priority) Level of an object by
using 0, 1, 2, or 3 as the flag name. An optional flag which may or may
not be on a given site is KILL_OK.
The second format sets <property> on <object> to
<string>, or if <string> is not given, removes
<property>.
The third format removes all properties from an object.
~
@SHUTDOWN
@shutdown
Only wizards may use this command. Shuts down the game. Must be typed in
full.
~
@STATS
@stats [<player>]
For mortal players, returns the highest number in the database, which
includes garbage that has been generated with @recycle. For Wizards,
gives this number as well as a breakdown of each type of object: rooms,
exits, things, programs, players, and garbage. Wizards may also specify
<player> which returns a similar display limited to the
possessions of <player>.
~
@SUCCESS
@success <object> [=<message>]
Sets the success message for <object>. The message is displayed
when a player successfully uses <object>. Without a message
argument, it clears the message. It can be abbreviated @succ.
<object> can be specified as <name> or #<number>, or
as `me' or `here'. This is the same as `@set <object>=_/dr:[text]'
See also @OSUCCESS.
~
@SWEEP
@sweep [<object>]
Returns a list of objects that are listening to <object>.
<Object> defaults to `here'.
TAKE See GET.
~
@TELEPORT
@teleport <arg1> [=<destination>]
Moves <arg1> to <destination>, if <destination> is not
given, moves you to <arg1>. Wizards may teleport anything to
anywhere, provided it makes sense, and mortals are allowed to do two
things: teleport rooms to change their parent fields, and the may
teleport things to a room they can link to, provided they control either
the thing or its location.
~
THROW
server: put <object>
user-created: throw <object> to <player>
The server version of `throw' is an alias of `drop'. Most MUCKs have a
user-created program that moves <object> to <player>,
announcing the move, provided that you are holding <object> and
that you, <object>, and <player> are each configured in such
a way as to allow the throw.
~
@TOAD
@toad <player1> = <player2>
Only wizards may use this command. Turns <player1> into a slimy
toad, destroying their character. All possessions of <player1> are
@chowned to <player2>. Must be typed in full.
~
@TRACE
@trace <object> [=<depth>]
Starts with <object> and traces all location fields, until the
global-environment room is reached or the optional <depth> is
specified. This is generally useful for finding which rooms are parents
in your heirarchy. If you cannot link to a particular location its name
is replaced by stars ***.
~
@UNCOMPILE
@uncompile <program>
Uncompiles all programs in the database. (Wizard only)
<<<more>>>
~
@UNLINK
@unlink <exit>; @unlink here
Removes the link on the exit in the specified direction, or removes the
drop-to on the room. Unlinked exits may be picked up and dropped
elsewhere. Be careful, anyone can relink an unlinked exit, becoming its
new owner (but you will be reimbursed your 1 penny). See @LINK.
~
@UNLOCK
@unlock <object>
Removes the lock on <object>. See @LOCK.
~
@USAGE
@usage
A Wizard only command that gives system resource usage stats for the
muck server process.
~
@WALL
@wall <message>
Only wizards may use this command. Shouts something to every player
connected. Must be typed in full.
~
WHISPER
whisper <player>=<message>
Whispers the message to the named person, if they are in the same room
as you. No one else can see the message. Wizards can whisper
*<player>=<message> to whisper to players in other rooms.
(Note: Some systems use a user-created program in place of the built in
whisper command. These programs generally provide many more useful
features.)
~
WHO
WHO [<player>]
Must be in all capitals, and typed in full. Lists the name of every
player currently logged in, and how long they have been inactive. If
given a player name, it displays only the matching names and idle times.
Wizards also get a display of the host the player is connected from.
2.7 User-Created Command Reference
This section provides a quick reference for user-created commands
supplied in the standard start-up database (std-db.db). On many MUCKS,
several or many of these programs will have been modified or replaced
with versions that are either more recent or more specifically attuned
to the needs of the MUCK. So syntax may very slightly, but you can
reasonably expect to find a command that offers similar functionality.
An established MUCK will have many other user-created commands besides
these.
Most user-created commands follow the convention of a #help argument:
typing the command name followed by `#help' will display a help screen.
~
3WHO
3who
Displays the names, online times, and idle times of all players online,
formatted to three columns. A less spammy alternative to WHO.
~
@ARCHIVE | @ARC
@archive <object>
The archive command essentially `decompiles' an object, outputting all
commands and settings that would be necessary to recreate the object.
The output is simply printed to your screen: it is not saved in some
archive on the MUCK. In order to use an @archive dump, you will need to
capture the output, by cutting and pasting, logging with a client, or
some other means, and save it to a file on your own computer.
The archived object can then be recreated by quoting or pasting the file
into a MUCK window. The most common uses of archive dumps are porting
objects between MUCKs or keeping a back-up copy offline to safeguard
against loss or corruption of the MUCK's dbase.
The @archive command is recursive: <object> and anything contained
by <object> will be archived. Thus, for example, an entire area
can be dumped to an archive file by archiving the parent room: all
rooms, exits, things, and programs in the area that are owned by the
archiving player will become part of the dump.
For non-wizzes, @ wiz props will not be part of the dump. Restricted
props (props that begin with a ~ tilde) will be included in the dump,
but will not be recreated when the archive is quoted, unless the player
is a wizard at that time. Also, exits leading to and from archived rooms
or areas cannot be linked when the archive is quoted (though exits
within an archived area can). It is normal to see various `Huh?' and
`Permission denied' messages when recreating an object from an archive
dump.
MPI and MUF that contains hard-coded dbrefs create another portability
concern. A dbref, naturally, refers to a specific object on a specific
MUCK. The corresponding object on a different MUCK will have a different
dbref. To some extent, this problem can be reduced by using pointers and
registered names when building, describing, coding, etc. For example, if
you (player #123) used a personal version of {look-notify} ...
{null:{tell:[ {name,me} looked at you. ],#123}}
... the code would result in a `Permission denied' error if you
recreated yourself on another MUCK via an archive dump. This could be
avoided with either of the following versions:
{null:{tell:[ {name,me} looked at you. ],this}}
{null:{tell:[ {name,me} looked at you. ],*Jessy}}
Recreating objects from archive dumps usually sets temporary registered
name values on your character, in propdir _reg/tmp. It is not necessary
to do anything with this directory, but to conserve dbase space, you
might want to remove it after doing a large dump: @set me = _reg/tmp:
~
@BANSITE
@bansite sitename Prevents logins from the given site.
@bansite !sitename Re-allows logins from the given site.
@bansite #list Lists all the sites that are banned.
This command prevents anyone from logging onto the MUCK from a banned
site. Along with @toad, it is used to prevent problematic players from
connecting to the MUCK. For example, a player might be toaded for
violations of the MUCK's acceptable use policy, but continue to log on
via guest and alternate characters. @Bansite prevents this by locking
out connections from a given site regardless of the character.
Sites may be specified by host name or numeric address. Wildcards may be
used in the site name and address. Wildcards are frequently necessary,
since many ISP's use dynamic host names for customer's connected via
SLIP or PPP connections. For example, an examination of a problematic
player's @/ directory might show that the last host used was:
user12.vnn.luser.com
Doing `@bansite user12,vnn.luser.com' would be ineffective: in all
likelihood, the first one or two sections of the hostname would
different the next time the player logged on. In lieu of
@bansite user12.vnn.luser.com
... one should do
@bansite *vnn.luser.com or,
@bansite *luser.com
@Bansite has two disadvantages: it locks out other players who connect
from the same site, and it offers no protection against players who you
want to ban but can log on from alternate sites. (Wizard only)
~
BOOTALL
bootall
Boots all but your lowest numbered connection. This program does not
work well. Cmd-@bootme, which is widely available, is a better choice.
~
CHANGE
change <object>=<propname>:/<old>/<new> or
change <object>=<mesgtype>;/<old>/<new>
Edits a property or message, replacing string <old> with string
<new>. The syntax varies slightly -- that is, it uses either a :
colon or ; semi-colon delimiter -- for `messages' and properties.
`Messages' are `name', `desc', `succ', `osucc', `fail', `ofail', `drop',
and `odrop'. Examples:
change here=_arrive/check:/444/445
change me=desc;/top hat/beret
~
@CHECK
@check
Checks all objects in your location for completeness, with the
definition of `complete' being adjusted as appropriate for the object
type. For example, exits are checked for links, descs, succs, osuccs,
and odrops. Locked exits are checked for fails and ofails. The command
prints a list of objects that need further work.
~
@DOING
@doing <msg>
Sets your `sticky do' string... that is, the message shown with your
name and times with commands `WHO' and `whodo'. The original purpose of
doing strings was to provide a way for people to let others know what
they are doing at the moment. Rather than frequently updating their
doing string, most players set it to some (presumably) witty or
interesting `bumpersticker' type remark, and leave it.
~
EDIT
edit <object> = <prop> or,
edit <object> = @<mesgtype>
This unusual and useful command is works only with the TinyFugue UNIX
client. Entering the command and parameters pulls the value of
<prop> or <mesgtype> into your client window, with the
cursor positioned for editing. You can then use arrow keys, backspace,
etc., to edit the property value. Pressing `enter' stores the new
property value. <Mesgtype> can be `name', `desc', `succ', `osucc',
`fail', `ofail', `drop', or `odrop'.
Before using `edit', you must define the following TinyFugue macro:
/def -fg -p100 -t"##edit> *" = /grab %-1
Like most TinyFugue settings, this setting is `volatile'... It is not
retained between TinyFugue sessions. To avoid having to redefine it each
time, put the definition line in TinyFugue's resource file, .tfrc, so
that it will be defined each time you start the client.
~
FETCH | RETRIEVE | GRAB
fetch <object 1> from <object 2>
Removes <object 1> from <object 2>. You must be carrying
<object 2> and it must not be locked or container_locked against
you. The object names do not have to be typed completely: partial
strings sufficient to distinguish the object from others you are
carrying will work. See also `put', below.
~
LOOKAT
lookat <player's> <object>
Does a `possessive look', showing you the description of an object being
carried by another player. Example: `lookat tarka's linux club pin'
~
LSEDIT | LSE
lsedit <object> = <list name>
Puts you in an interactive list editor. See sections 2.1 and 4.1 for
more information.
~
LSPROP | LSP
lsprop <object> [= <path>]
Lists all properties on object and their values. If a path is specified,
it will list only properties on that path. Examples:
lsp me ............ Lists all properties on your character
lsp me = _descs ... Lists all properties in your _descs/ directory
~
PROPCP | CP
cp <object 1>=<prop 1>,<object 2>=<prop 2>
Copies <prop 1> and its value from <object 1> to <prop
2> on <object 2>. Example:
cp out=_/sc,#1344=_/sc (Copies the @succ of exit `out' to another exit)
Propcp handles partial input well. If <object 1> is omitted, it
assumes <prop 1> is on the user. If <object 2> is omitted,
it assumes the destination object is the same as <object 1>...
i.e., that you are copying from one prop to another on the same object.
If <prop 2> is omitted, is assumes that it is the same as <prop
1>... i.e., that you are copying a property on one object to the same
property on a different object. If more information is omitted, the
program will ask for it. Rather than providing all -- or even any -- of
the information on the command line, one can simply to `cp', and respond
to prompts. You must control both objects. See also `propmv', below.
~
PROPMV | MV
mv <object 1>=<prop 1>,<object 2>=<prop 2>
Moves <prop 1> and its value from <object 1> to <prop
2> on <object 2>, erasing <prop 1>. Example:
mv out=_/fl,out=_/ofl (Moves the fail message on `out' to the ofail)
Propmv handles partial input well. If <object 1> is omitted, it
assumes <prop 1> is on the user. If <object 2> is omitted,
it assumes the destination object is the same as <object 1>...
i.e., that you are moving a value from one prop to another on the same
object. If <prop 2> is omitted, is assumes that it is the same as
<prop 1>... i.e., that you are moving a property on one object to
the same property on a different object. If more information is omitted,
the program will ask for it. Rather than providing all -- or even any --
of the information on the command line, one can simply to `mv', and
respond to prompts. You must control both objects. See also `propcp',
above.
~
@PURGE
@purge <player> = yes
Recycles all of <player's> belongings. Most often, this will be
used before @toad. It is a good idea to do `@owned <player>'
first, and make suitable arrangements. Exits leading to rooms owned by
the player will become unlinked, and should either be relinked or
recycled. Public building -- or rooms that are jointly used by the
player and others -- should be chowned to someone else. Mortals my purge
only themselves; wizards may purge any player.
~
PUT | REPLACE | STUFF
put <object 1> in <object 2>
Moves <object 1> from your inventory into the contents of
<object 2>. You must be holding both objects, and <object 2>
must not be locked or container_locked against you. Partial names for
both objects will work. See also `fetch', above.
~
READ | WRITE | EDIT | ERASE | PROTECT
read Show the headers of all posted messages.
read new Show headers of all mesgs less than 2 days old.
read recent Show headers of all mesgs after last read mesg.
read KEYWORD Show headers of all mesgs with matching KEYWORD.
read -DAYS Show headers of all mesgs fewer than DAYS old.
read MESGNUM Read the mesg referred to by the given mesg number.
read - Read the next mesg, after the last one you read.
read -recent Read all mesgs after last read mesg, in one long dump.
write Post a message. Prompts for subject and keywords.
write SUBJECT Post a mesg with given SUBJECT. Prompts for keywords.
write SUBJECT=KEYWRDS Post a message with given SUBJECT and KEYWRDS.
erase MESGNUM Lets message owner erase a previously written mesg.
editmesg MESGNUM Lets message owner edit a previously written mesg.
protect MESGNUM Lets a wizard protect a mesg from auto-expiration.
These commands operate bulletin boards that run from the standard
bulletin board program, gen-mesgboard. `Read' is also an in-server alias
for `look'. So, in a room that contains a bulletin board, `read' is a
bulletin board command; elsewhere, it does a look.
@REGISTER | @REG
@reg <object> = <registered name>
@reg #me <object> = <registered name>
@reg #prop <target object>:<propdir> <object> = <registered name>
Sets a registered name for <object>. (See section 2.1.4 for more
information on registered names).
The default format, @reg <object> = <registered name>,
creates a global registered name by setting property _reg/<reg
name> on room #0 with the value of <object's> dbref. Because a
property is being set on room #0, this will result in a `Permission
denied' error for a mortal player (unless she happens to own room #0).
The following example, which would be typed by a wizard, gives the
gen-nothing program the registered name of `nothing'; players would then
be able to link actions to it by typing `@link <action> =
$nothing'
@reg gen-nothing = nothing
Registered names can be set on your character rather than on room #0, in
which case they will be be meaningful only for you, by using the #me
argument. The following example, which could be typed by a mortal, or by
a wizard who wants to create a personal registered name, gives a puppet
object the registered name `pup'. It could then be specified by `$pup',
rather than its dbref, as in `@tel $pup = me'.
@reg #me squiggy = pup
You can over-ride the target propdir, from _reg/ to anything else, by
using the #prop argument. If the target propdir does not begin with
_reg/ , the setting will not be usable as a registered name; this would
simply be a way to set a property with data type dbref rather than
string (which could also be accomplished with @propset). The following
example sets property _disconnect/cleanup in the current room with the
dbref of program gen-sweeproom.
@register #prop here:_disconnect gen-sweeproom=cleanup
The same thing could be accomplished by typing:
@propset here=dbref:_disconnect/cleanup:<#dbref of gen-sweeproom>
This example makes a setting in sub-propdir _reg/lib, giving the
lib-strings library program the registered name $lib/strings.
@register #prop #0:_reg/lib lib-strings = strings
The same thing could be accomplished by typing:
@register lib-strings = lib/strings or,
@propset #0 = dbref:_reg/lib/strings:<#dbref of lib-strings>
@RESTART
@SIZE
SWEEP
UPTIME
@VIEW
@WHEN
who
*****************************************************************************
3.0 PROGRAMMING
MUCK supports two online programming languages, MPI and Muck FORTH, or
MUF. MPI is an interpretted language (you don't need to compile it; the
server reads the code directly) available to all players. MUF is a
compiled, stack-based language, available to players who have a Mucker
bit (an M flag). In general, MPI is better for one-off programming tasks
and customizing messages (descriptions, exit @osucc's, etc.). MUF is
better for public utilities and tasks that involve modifying the
database.
3.1 Overview: MPI
MPI is an interpretted language with a LISP-like syntax available to all
players. Because it is universally available, MPI includes security
features that restrict its power. In general, MPI can only read props on
the triggering object and on objects controlled by the controller of the
object on which the MPI string is stored, and can only set props on the
latter... on objects controlled by the owner of the MPI object. Other
than setting props as mentioned, MPI cannot modify the database to any
significant extent, but is ideally suited for message-handling. And
because it is interpretted, it is well-suited for one-off programming
tasks: no separate compiling and linking operations are needed, nor is a
separate program object for holding the code.
MPI's syntax consists of nested functions enlcosed in curly braces that
are evaluated left-to-right and `from the inside out'. For example...
{if:{eq:{ref:me},#1},Hey it's God!,Hello world!}
The MPI parser will first evaluate the innermost function, {ref:me}. The
{ref} function returns the dbref of its single argument -- which in this
case is `me' -- so {ref:me} returns the user's dbref. The returned
expression `replaces', as it were, the function. So, if the user's dbref
were #123, the MPI string would in effect and at this moment be...
{if:{eq:#123,#1},Hey it's God!,Hello world!.}
Then the next-innermost expression, effectively {eq:#123,#1}, would be
evaluated. The {equals} function returns true if the two arguments
supplied are the same; otherwise it returns false. In this case, the two
arguments are not the same, so {equals} will return false. At this
point, the MPI value for false -- the string "0" -- will replace the
function. (A "" null string is also false in MPI. Any value other than
"" or "0" is considered true.) So, at this point the string would in
effect be...
{if:"0",Hey it's God!,Hello world!}
Finally, this, the outermost function will be evaluated. The {if}
function takes three arguments. If the first argument is true, it
returns the second argument. If the first argument is false, it returns
the third argument. In this example, the first argument is false, so the
the third argument will be returned: MPI will return the string "Hello
world!" to player #123. If God had triggered the string, the {if} test
would have been true, and the string "Hey it's God!" would have been
returned instead.
The {debug} function displays the progress of the parser. Enclosing the
whole of our example in a {debug} function will show the process
described above.
====================================
> @succ testmpi = {debug:{if:{eq:{ref:me},#1},Hey it's God!,Hello world!}}
Message set.
> testmpi
(@Succ) {IF:"{eq:{ref:me},#1}", "Hey it's God!", "Hello world!"}
(@Succ) {EQ:"{ref:me}", "#1"}
(@Succ) {REF:"me"}
(@Succ) "me"
(@Succ) {REF:"me"} = "#123"
(@Succ) "#1"
(@Succ) {EQ:"#123", "#1"} = "0"
(@Succ) "Hello world!"
(@Succ) {IF:"{eq:{ref:me},#1}", "Hey it's God!", "Hello world!"} = "Hello world!"
Hello world!
====================================
In the lines from the first half of the debugging output -- where
indentation is moving to the right -- the parser is essentially finding
the innermost, left-most function to be evaluated. The remaining
portion, with lines ending in `= <value>' and indentation moving
back to the left, depicts the series of returned expressions described
above.
*
The keywords `me' and `here' can be used as normal. In addition, MPI
supports the keyword `this', which will be replaced by the dbref of the
object on which the MPI is stored.
*
The variable functions {&cmd}, {&arg}, and {&how} may be used to retrive
information about how MPI was triggered. {&cmd} stores the command name
typed to trigger the MPI. {&arg} stores any arguments typed along with
the command. {&how} stores the method by which MPI was triggered, and
will have values such as "(@desc)", "(@succ)", "(@osucc)", "(@lock)",
etc.
*
Functions can be nested up to 26 levels deep. Loops may iterate a
maximum of 256 times, at which point the automatically exit. Lists may
have a maximum of 256 lines, or 4096 characters, whichever is less.
*
An MPI string that appears in a _/ prop (a @succ message, a @desc, and
so forth) will be parsed automatically. For other triggering props, the
parser must be called by an & ambersand at the beginning of the prop
string.
====================================
> @set me=_oarrive/aaa:&{null:{otell:pads in quietly.}}
Property set.
====================================
*
The arguments of functions are separated by commas. Commas appearing in
argument strings will confuse the parser: functions will seem -- to it
-- to have too many arguments. So, commas in argument strings must be
`escaped'... i.e., preceded with a \ backslash escape character, which
tells the parser to treat the next character literally, rather than as
an MPI instruction. For example, if we wanted our first example to say
"Hey, it's God!" or "Hello, world!", the commas would need to be escaped
with a backslash character.
{if:{eq:{ref:me},#1},Hey\, it's God!,Hello\, world!}
*
Complex or very long MPI instructions are often better stored in a list,
where whitespace can be used to make the code more readable, rather than
in a single prop where all will run together in an opaque mass of
characters. A simple pointing string using the {lexec} (`execute list')
function can then be placed in the triggering prop.
====================================
> lsedit harley = bikecode
< Welcome to the list editor. You can get help by entering `.h' >
< `.end' will exit and save the list. `.abort' will abort any changes. >
< To save changes to the list, and continue editing, use `.save' >
> {null:
> {if:
> {
> (lots of complicated really cool
motorcycle code goes here)
}
> }
> }
> .end
< Editor exited. >
< list saved. >
> @succ ride harley;ride motorcycle;ride cycle = {lexec:bikecode}
Message set.
> ride harley
(The Harley does something amazing.)
====================================
The {lexec} function executes MPI in a list. The {exec} function
executes MPI in a property, and thus provides another way to break code
up into managable pieces. MUSH coders especially might find this method
more intuitive.
3.1.1 MPI Macros
3.1.2 MPI Examples
3.1.3 MPI Reference
DB Functions:
ref name fullname owner location
flags controls nearby money type
istype contents exits links force
dbequals locked testlock holds contains
Connection Functions:
online awake ontime idle
List-Handling Functions:
count mklist sublist lrand lunique
lunion lcommon lremove lmember lsort
commas
Loop Functions:
for while foreach filter parse
fold
Logical Functions:
if equals notequals gt ge
lt le not or and
xor
Property Handling:
prop prop! exec exec! index
index! store delprop list concat
lexec rand select timesub propdir
listprops
Math Functions:
increment decrement addition subtraction multiply
divide modulo dice minimum maximum
absolute sign distance
Miscellaneous Functions:
isnum isdbref version muckname muf
debug debugif macros func delay
kill fox
String Functions:
nl subst strlen smatch strip
tolower toupper right left center
instr midstr literal eval null
pronouns tell otell
Time Functions:
time timesub lastused usecount modified
created convsecs convtime date delay
ftime ltimestr stimestr timestr secs
tzoffset
Variable-Handling Functions:
variable &how &cmd &arg set
with
Definitions:
A trigger object is the object that the MPI script is evaluated from.
A list is a string containing several individual substring items,
seperated by carriage return characters.
A property based list is a set of consecutively numbered properties that
each contain one string in a list of strings. Property based lists are
often numbered like: listname1, listname2, listname3, listname4, etc.
Another popular format is listname#/1, listname#/2, listname#/3, etc.
MPI can read in either of those formats, and several more, for that
matter.
For logical constructs, a string value of "0", or a null string ("") are
both considered false. Any other value is considered true.
ABS|ABSOLUTE
{abs:expr}
Returns the absolute value of expr.
ADD|ADDITION
{add:expr1,expr2}
{add:expr1,expr2,expr3...}
Returns the sum of the values of expr1 and expr2. If more than two args
are given, then this will add all the args together and return the
result.
AND|&&
{and:expr1,expr2...}
Returns true if expr1 and expr2 evaluate as true. Otherwise, this
returns false. If expr1 was false, this doesn't bother to evaluate
expr2, as it does C-style shortcutting. If there are more than two
arguments, then this will evaluate all of them until either one returns
false, in which case this function returns false, or until it has
evaluated all of the arguments. This function returns true only if all
the arguments evaluate as true.
ARG|&ARG
{&arg}
The {&arg} variable contains a string with the value of the command line
arguments the user entered. This is so that you can have stuff like MPI
in the fail of an exit, and when the user triggers the exit, and has
some extra text on the line they entered, other than the exitname, the
MPI can take that extra stuff as arguments for use. Note that you need
to set an action HAVEN to get it to accept command line arguments.
AWAKE
{awake:player}
Returns how many times player is connected. This means that it will
returns 0 if the player is not connected. If the given object is NOT a
player, it will return 0. In all other cases, it will return a positive
number, being how many times the given player is connected to the
server.
CENTER
{center:string}
{center:string,fieldwidth}
{center:string,fieldwidth,padstring}
Takes a string and pads it to fit the given fieldwidth, with the string
center justified. If no padstring is given, it assumes that it will pad
the string with spaces. If no fieldwidth is given, it assumes that the
field width is 78 characters. Example: {center:Hello,10,1234567890}
would return the string "123Hello12"
COMMAS
{commas:list}
{commas:list,lastsep}
{commas:list,lastsep,var,expr}
Takes a list and returns a plain english comma delimited string with the
items in it. For example, {commas:{mklist:Tom,Dick,Harry}} will return
"Tom, Dick and Harry". If you specify the lastsep argument, you can
replace the "and" with something else, such as "or" to get a result like
"a, b or c". Note: You need to be careful to include spaces around the
"or" or else you might get a result like "a, borc". Example:
{commas:{mklist:a,b,c}, or } If the var and expr arguments are passed,
then for every item in the list, it will set the value of the given
variable name (which it will declare) to the item, then evaluate expr,
and use the result in the string it outputs. Example:
{commas:{contents:here},\, or ,v,{name:{&v}}} will return the name of
every object in the room in a comma separated list, using ", or " as the
final conjunction. ie: "Tom, Can of SPAM, Dick, or Harry."
CMD|&CMD
{&cmd}
The {&cmd} variable contains the command name the user used, that caused
the MPI to run. This is generally the exit name that the player
triggered. For example, if the player typed `east', and triggered the
exit named `east;e;out', which ran some MPI commands, the {&cmd}
variable would have a value of "east".
CONCAT
{concat:listname}
{concat:listname,obj}
Returns a string, containing the concatenated lines of a property based
list. It concatenates the list semi-intelligently, putting a single
space between lines normally, and two spaces between lines when the
previous one ended with a period, exclamation mark, or question mark. A
property based list is a series of properties that are consecutively
numbered. The server understands several different formats, and can also
read in property lists in either the propnameX format, or the
propname#/X format. It does NOT evaluate the contents of the list for
embedded MPI commands. If no obj argument is supplied, then it looks for
the list somewhere down the environment from the trigger object.
Otherwise, it looks for the list down the environment from the given
object.
CONTAINS
{contains:obj1}
{contains:obj1,obj2}
Returns true if obj1 is within obj2, or within anything it contains, or
within anything they contain. If obj2 is not given, then it checks to
see is obj1 is held by the player, or by anything they hold, etc.
Basically, this just sees if obj1 is within the locational environment
of obj2.
CONTENTS
{contents:obj}
{contents:obj,type}
Returns a list of the contents of the given object. If a second argument
is passed to it, it restricts the listing to only those objects that are
of the given type. Either the object must be nearby the trigger object,
or else the owner of the trigger object must control the object.
Otherwise this will error out with a Permission Denied error. The valid
object type values are Room, Thing, Exit, Player, Program, and Bad.
HINT: If you need to get a list of two types of objects from the room,
just concatenate the lists from two calls to this function, with each
object type you want. ie:
{mklist:{contents:here,player},{contents:here,thing}} or
{contents:here,player}{nl}{contents:here,thing}
CONTROLS
{controls:obj}
{controls:obj,player}
If one argument is given, then this returns true ("1") if the trigger
object's owner controls the given object. If two arguments are given,
then it returns true if the given player controls the given object.
Otherwise, this returns false. ("0") Wizards control everything.
CONVSECS
{convsecs}
Converts systime seconds into a readable time string.
CONVTIME
{convtime:string}
Converts "HH:MM:SS Mo/Dy/Yr" format time string to systime seconds.
COUNT
{count:list}
{count:list,sep}
This counts the number of \r delimited items that are in the given list.
This is effectively a list item count. If the sep argument if given,
then it counts the number of sep delimited substrings in list. ie: The
default sep is \r. (A carriage return.)
CREATED
{created:obj}
Returns the systime when obj was created.
DATE
{date}
{date:timezone}
Returns a date string in the form mm/dd/yy. If the timezone argument is
given, then it offsets the date returned by that number of hours.
DBEQ|DBEQUALS
{dbeq:obj1,obj2}
Returns true if obj1 and obj2 refer to the same object. This does name
matching, so {dbeq:*Wizard,#1} will return true if #1 is named Wizard.
DEBUG
{debug:expr}
This will show MPI debugging information for all the commands within the
given expression. This is useful for seeing why something isn't working.
This returns the result of the evaluation of expr.
DEBUGIF
{debugif:condition,statement}
If condition evals true, use debug mode is used when evaluating
statement. Otherwise the statement is evaluated in regular mode.
DEC|DECREMENT
{dec:var}
{dec:var,val}
Decrements the value of the given variable by one, returning the result.
If a value argument is given, then it will subtract that from the
variable, instead of the value 1.
DELAY
{delay:secs,expr}
Evaluates the given expression, then puts the result of that on the
timequeue, to execute after the given number of seconds. At that time,
the string is evaluated again, and displayed to the user, or to the
room, depending on whether it was run from a regular message such as
@succ, or from an omessage such as @osucc. Since the expression is
evaluated both before and after being delayed, you need to put MPI code
that is to run after the delay within a {lit:expr} command. If a {delay}
evaluation is a null string, then the notify or notify_except will not
be done. {Delay} will return the process ID of the event it puts on the
timequeue.
DELPROP
{delprop:propname}
{delprop:propname,object}
This function will remove a property and all of its subsidiary
properties in the case that it is a propdir. This will delete the
property on the trigger object, unless an object argument is specified.
If one is, then it will delete the property on that given object. This
function returns a null string. If you specify a propname that is
protected, you will get an error of Permission Denied. You are only
allowed to delete properties from objects that are owned by the owner of
the trigger object.
DICE
{dice:X}
{dice:X,Y}
{dice:X,Y,Z}
Given one parameter, picks a random number between 1 and X. (1dX) Given
two parameters, it randomly generates Y numbers between 1 and X, and
adds them together. (YdX) A third parameter, if given, is just added to
this sum as a modifier. (YdX+Z)
DIST|DISTANCE
{dist:x,y} Returns distance from 0,0 that x,y is.
{dist:x,y,z} Returns distance from 0,0,0 that x,y,z is.
{dist:x,y,x2,y2} Returns distance between x,y and x2,y2.
{dist:x,y,z,x2,y2,z2} Returns distance between x,y,z and x2,y2,z2.
Given two arguments, this calculates the distance of a 2D point from the
origin. Given three arguments, this calculates the distance of a 3D
point from the origin. Given four arguments, this calculates the
distance between a pair of 2D points. Given six arguments, this
calculates the distance between a pair of 3D points.
DIV|DIVIDE
{div:expr1,expr2}
{div:expr1,expr2,expr3...}
Returns the value of expr1 divided by expr2. Division by zero will
return zero. If more than two arguments are given, then the first
argument is divided by the second, and the result is divided by the
third, etc, for all of the arguments. For example: {div:180,6,3,5}
would be read like 180 / 6 / 3 / 5, and a result of 2 would be returned.
EQ|EQUALS|==
{eq:expr1,expr2}
If expr1 and expr2 evaluate out to the same value, then this returns
true. Otherwise, this returns false. If both expressions evaluate out to
numbers, then this compares them numerically.
EVAL
{eval:string}
Sort of the exact opposite of {lit:}. This takes a string, and evaluates
it for MPI commands embedded within it. This can be used on the output
of {list:}, for example.
EXEC
{exec:propname}
{exec:propname,obj}
Returns the string value of the given property, after having evaluated
any embedded MPI commands that it contained. If no object parameter is
passed to it, it looks for the property somewhere down the environment
from the trigger object. Otherwise, it looks down the environment from
the object specified. If the property is not found, this returns an
empty string. If the property that it tries to access is read restricted
and the owner of the trigger object does not own the object that the
property is found on, then the MPI script stops with a Permission denied
error.
EXEC!
{exec!:propname}
{exec!:propname,obj}
Returns the string value of the given property, after having evaluated
any embedded MPI commands that it contained. If no object parameter is
passed to it, it looks for the property on the trigger.
Otherwise, it looks for the property on the object specified. If the
property is not found, this returns an empty string. If the property
that it tries to access is read restricted and the owner of the trigger
object does not own the object that the property is found on, then the
MPI script stops with a Permission denied error.
EXITS
{exits:obj}
Returns a list of all the exits on the given object. The owner of the
trigger object has to control obj, or else this errors out with
Permission Denied. Programs and exits never have exits attached to them.
FILTER
{filter:var,list,expr}
{filter:var,list,exp,sep}
{filter:var,lst,exp,sep,s2}
This evaluates expr for each and every item in the given list. On each
evaluation, the temporary variable var will contain the value of the
item under scrutiny. This function returns a list containing all of the
items from the input list, for which expr evaluated true. Var will only
be defined for the duration of expr, and will be undefined after the
{filter} construct finishes. If sep is given, then it uses that string
as the item seperator in the input list, instead of the usual carriage
return character. If s2 is defined, then it will use that string to
seperate the items in the list it returns, instead of the normal
carriage return. Sep and s2 can be multiple characters long.
FLAGS
{flags:obj}
Returns a flaglist string from obj. ie: PM2J. The object must either be
in the vicinity, or it must be controlled by the owner of the trigger
object.
FOLD
{fold:var1,var2,list,expr}
{fold:var1,var2,lst,expr,sep}
This takes a list and stores the first two items in var1 and var2, then
evaluates expr. The value returned by expr is then put in var1, and the
next list item is put in var2. Expr keeps being evaluated in this way
until there are no more list items left. This returns the last value
returned by expr. If a sep argument is given, the input list is assumed
to have its individual items delimited by that string, otherwise it
assumes a carriage return.
FOR
{for:varname,start,end,increment,command}
Acts as a counting loop, like BASIC's for loops. The varname is the name
of the variable that it will create and use to store the count value.
The start value will be the initial value of the variable, and the end
value will be the value that the variable is working towards. The
increment is how much the variable will be incremented by in each loop.
The command will be evaluated for each value of the variable between the
beginning and ending values. For example:
{null:{for:i,10,1,-1,{tell:{&i}}}} will echo a countdown from ten to
one, inclusive, to the user.
FORCE
{force:object,command}
Forces the given player or thing to do the given command. The thing
forced must be @flock'ed to the trigger object, or the trigger object's
owner, and it must be set XFORCIBLE, or else this function will get a
Permission Denied error. This function returns a null string. {Force}
cannot force a thing-object to do something, if it is set Dark, is in a
room set Zombie, if it has the same name as a player, or is owned by a
player set Zombie.
FOREACH
{foreach:var,list,expr}
{foreach:var,list,expr,sep}
This evaluates expr for each and every item in the given list. On each
evaluation, the temporary variable var will contain the value of the
item under scrutiny. var will only be defined for the duration of expr,
and will be undefined after the {foreach} construct finishes. If sep is
given, then it uses that string as the item seperator in list, instead
of the usual carriage return character. sep can be multiple characters
long. This structure returns the result of the last evaluation of expr.
Example: {foreach:thing,{contents:here},{store:1,_seen}}
FOX
{fox}
Returns the string YARF!
FTIME
{ftime:format}
{ftime:format,tz}
{ftime:format,tz,secs}
Returns a time string in the format you specify. See `man timefmt' for
the %subs that you can use in the format string. If specified, tz is the
number of hours offset from GMT. If specified, secs is the systime to
use, instead of the current time. {ftime:%x %X %Y,8,0} will return the
date and time for systime 0, for the Pacific time zone.
FULLNAME
{fullname:obj}
Returns the name of the given object. In the case where the object is an
exit, then the full name of the exit is given, including all the ;
aliases. The object must be in the immediate vicinity, or be controlled
by the owner of the trigger object.
GE|>=
{ge:expr1,expr2}
Evals expr1 and expr2, then returns true if expr1 was larger or equal.
GT|GREATERTHAN|>
{gt:expr1,expr2}
Evaluates expr1 and expr2, then returns true if expr1 was larger.
HOLDS
{holds:obj1}
{holds:obj1,obj2}
Returns true if the location of obj1 is obj2. If no obj2 argument is
given, then this will return true if the location of obj1 is the player.
HOW|&HOW
{&how}
The {&how} variable is a short string telling what ran the MPI command.
It can have the values "(@desc)", "(@succ)", "(@osucc)", etc. for when
it is run from an @desc, an @succ, an @osucc, or whatever. It can also
have the value "(@lock)" for when it is run from a lock test.
IDLE
{idle:player}
Returns player idle time in seconds. If the given player is not
connected, or is not a player object at all, then this will return -1.
This returns the idle time for the most recently connected connection,
if there are multiple connects.
IF
{if:check,true}
{if:check,true,false}
This is a simple conditional command. It evaluates the `check' argument
and if it is true, then it evaluates the `true' argument and returns its
result. If `check' does not evaluate as true, then it will evaluate the
`false' argument, if there is one, and returns its result. If there is
no false argument, and `check' evaluated false, then it returns a null
string. Example:
Your computer is {if:{eq:2,3},broken!,All right.}
INC|INCREMENT
{inc:var}
{inc:var,val}
Increments the value of the given variable by one, returning the result.
If a value argument is given, then it will add that value to the
variable, instead of the value 1.
INDEX
{index:propname}
{index:propname,obj}
Returns the string value of the property whose name is stored in the
given property. This sounds confusing, but it's basically just the same
as {prop:{prop:propname}}. If no object parameter is passed to it, it
looks for both the index property and the referenced property somewhere
down the environment from the trigger object. Otherwise, it looks down
the environment from the object specified for both of them. If either
property is not found, this returns an empty string. If the property
that it tries to access is read restricted, and the owner of the trigger
object does not own the object that the properties are found on, then
the MPI script stops with a Permission denied error.
INDEX!
{index!:propname}
{index!:propname,obj}
Returns the string value of the property whose name is stored in the
given property. This sounds confusing, but it's basically just the same
as {prop!:{prop!:propname}}. If no object parameter is passed to it, it
looks for both the index property and the referenced property on the
trigger object. Otherwise, it looks on the specified object for both of
them. If either property is not found, this returns an empty string. If
the property that it tries to access is read restricted, and the owner
of the trigger object does not own the object that the properties are
found on, then the MPI script stops with a Permission denied error.
INSTR
{instr:str1,str2}
Lists the position of the first substring within str1 that matches str2.
If no such substring exists, then this returns a 0.
ISDBREF
{isdbref:dbref}
Returns true if the string passed to it is a valid dbref.
ISNUM
{isnum:number}
Returns true if the string passed to it is a valid number.
ISTYPE
{istype:obj,typ}
Returns true if the given object if of the given type. Valid types are:
Bad, Room, Exit, Thing, Player, and Program.
KILL
{kill:0}
{kill:processID}
Kills a process on the timequeue, that was possibly created by {DELAY}.
If the process ID it is given is 0, then it will kill all processes done by
that trigger object. If the process to be killed was not set off by that
trigger, and was not set off by any object that the owner of the trigger
owns, then this will error out with Permission denied. If no process is
found, this returns 0. If a process was found, and the permissions were
okay, then the process is killed, and {kill} returns the number of processes
killed. Usually one.
LASTUSED
{lastused:obj}
Returns the systime when obj was last used.
LCOMMON
{lcommon:list1,list2}
Creates a list containing every item that appears in BOTH list1 and
list2. Any duplicate items in the resulting list are removed.
LE|<=
{le:expr1,expr2}
Evals expr1 and expr2, then returns true if expr1 was smaller or equal.
LEFT
{left:string}
{left:string,fieldwidth}
{left:string,fieldwidth,padstring}
Takes a string and pads it to fit the given fieldwidth, with the string
left justified. If no padstring is given, it assumes that it will pad
the string with spaces. If no fieldwidth is given, it assumes that the
field width is 78 characters. Example: {left:Hello,10,_.} would return
the string "Hello_._._"
LEXEC
{lexec:listname}
{lexec:listname,obj}
This takes a property based list, and concatenates all its lines
together, stripping spaces from the beginning and end of each one. It
then evaluates the result for MPI commands, and returns the resulting
string. A property based list is a series of properties that are
consecutively numbered. The server understands several different
formats, and can also read in property lists in either the propnameX
format, or the propname#/X format. If no obj argument is supplied, then
it looks for the list somewhere down the environment from the trigger
object. Otherwise, it looks for the list down the environment from the
given object.
LINKS
{links:obj}
Returns the object reference of what the given object if linked to.
Since exits can be meta-links, linked to multiple exits, if there is
more than one link, then this function returns a list of all the
destinations, seperated by carriage return characters. (\r)
LIST
{list:listname}
{list:listname,obj}
Returns a string, containing a carriage-return delimited list of
individual lines from a property based list. A property based list is a
series of properties that are consecutively numbered. The server
understands several different formats, and can also read in property
lists in either the propnameX format, or the propname#/X format. It does
NOT evaluate the contents of the list for embedded MPI commands. If no
obj argument is supplied, then it looks for the list somewhere down the
environment from the trigger object. Otherwise, it looks for the list
down the environment from the given object.
LISTPROPS
{listprops:propdir}
{listprops:propdir,object}
{listprops:propdir,object,pattern}
This function will return a list that contains the full names of all the
sub-properties contained by the given propdir. If not given, object defaults
to the trigger object. If a pattern is given, the sub-properties in the
propdir are each compared against the smatch wildcard pattern, and only those
that match are returned in the list. This comparison is only done on the last
part of the property name after the last /. See also PROPDIR and SMATCH.
LIT|LITERAL
{lit:string}
Returns the literal string given as its parameter. This means you can
have things that look like MPI commands within it, and it will not
evaluate them, but will rather just treat them as a string.
LMEMBER
{lmember:list,item}
{lmember:list,item,delimiter}
Returns 0 if the given item is NOT in the given list, otherwise, it
returns the item's position in the list. The first list item in the list
would return 1, and the third would return 3, for example. If the
delimiter argument is given, then it treats the list as if it were
delimited by that string, instead of by carriage returns. (\r's)
Example: {lmember:{mklist:a,b,c,d,e,f},d} would return 4.
LOC|LOCATION
{loc:obj}
Returns the location of the given object. The object must either be in
the vicinity, or it must be controlled by the owner of the trigger
object.
LOCKED
{locked:player,obj}
Tests the _/lok (@lock) standard lock property on obj against the given
player. Returns true if the lock is locked against the player.
LRAND
{lrand:list}
{lrand:list,seperator}
Returns a randomly picked stringlist item from the given list. If the
seperator argument is given, then it will assume that the stringlist has
its items delimited by the given seperator string, instead of by
carriage returns.
LUNION
{lunion:list1,list2}
Combines the contents of list1 and list2, removing any duplicates.
LUNIQUE
{lunique:list}
Returns list with all duplicate items removed.
LREMOVE
{lremove:list1,list2}
Returns the contents of list1, with any items that match an item in
list2 removed. The resulting list has all duplicate items removed.
LSORT
{lsort:list}
{lsort:list,var1,var2,expr}
Returns the sorted contents of list. If 4 arguments are given, then it
evaluates expr with a pair of values, in var1 and var2. If expr returns
true, then it will swap the positions of the two values in the list. It
runs this comparison on every pair of items in the list, so it will be
evaluated N*N times, where N is the number of items in the list. This
method can also be used to randomize a list. Example:
{lsort:{&list},v1,v2,{gt:{dice:100},50}}
LT|LESSTHAN|<
{lt:expr1,expr2}
Evaluates expr1 and expr2, then returns true if expr1 was smaller.
LTIMESTR
{ltimestr:secs}
Given a time period, in seconds, this will return a string, including a
breakdown of all the time units of that period. For example, given a
number of seconds, it might return "1 week, 2 days, 10 mins, 52 secs".
MAX|MAXIMUM
{max:expr1,expr2}
Returns the greater of the values of expr1 and expr2.
MKLIST
{mklist:value...}
Returns a list with all the given values as list items, seperated by
carriage returns. (`\r's) Example: {mklist:Tom,Dick,Harry} returns
"Tom\rDick\rHarry". Note: A maximum of nine items can be passed to the
{mklist} function. If you need more, you can chain {mklist}s together.
Example: {mklist:{mklist:a,b,c,d,e,f,g,h,i},j,k,l,m,n,o,p}
MIDSTR
{midstr:str,pos}
{midstr:str,pos1,pos2}
Returns the substring that starts at pos1 within str. If no pos2 is
given, then the returned string is only the character at the given pos1
position. if a pos2 position is given, then it returns the substring
beginning at pos1 and ending at pos2, inclusive. If pos1 or pos2 are
negative, then they represent the position that is that absolute number
of characters from the end of the string. The first character in str is
1, and the last one can always be referenced by -1. If a position would
be before the beginning of the string, it is assumed to be at the
beginning of the string. If it would be beyond the end of the string, it
is assumed to be at the last character. If the starting position is
later in the string than the ending position, then the returned string
has the characters in reverse order. If either pos1 or pos2 are 0, then
this returns a null string. ("")
MIN|MINIMUM
{min:expr1,expr2}
Returns the lesser of the values of expr1 and expr2.
MODIFIED
{modified:obj}
Returns the systime when obj was last modified.
MOD|MODULO
{mod:expr1,expr2}
Returns the leftover remainder of expr1 divided by expr2. If more than
two arguments are given, then the first arguments is modded by the
second, then the result of that would be modded by the third, and so on
and so forth. For example: {mod:91,20,3} would be read as 91 % 20 % 3,
and a result of 2 would be returned.
MONEY
{money:obj}
This returns the value of an object of TYPE_THING, or returns how many
pennies a player has.
MUCKNAME
{muckname}
Returns the muck name string. Example: FurryMUCK
MUF
{muf:prog,arg}
Runs the given MUF prog with the string arg on the stack. This returns
the top stack value when the prog exits. If the MPI code was run from a
propqueue like _listen, or _connect, then {muf} cannot run a MUF program
with a Mucker level of less than 3
MULT|MULTIPLY
{mult:expr1,expr2}
{mult:expr1,expr2,expr3...}
Returns the product of the values expr1 and expr2. If more than two args
are given, then they are all multiplied together to get the result.
NAME
{name:obj}
Returns the name of the given object. If the object is an exit, the name
returned is the first exit name it has before the first `;'. The object
must be in the vicinity, or controlled by the owner of the trigger
object.
NE|NOTEQUALS|!=|<>
{ne:expr1,expr2}
If expr1 and expr2 evaluate out to the same value, then this returns
false. Otherwise, this returns true. If both expressions evaluate out to
numbers, then this compares them numerically.
NEARBY
{nearby:obj}
{nearby:obj,obj2}
If one argument is given, then this returns true ("1") if the given
object is nearby to the trigger object. If two arguments are given, then
it returns true if the two objects are nearby one another. Otherwise,
this returns false. ("0") Nearby is defined as: 1) The two objects are
in the same location, or 2) One object contains the other, or 3) the two
objects are in fact the same object.
NL|\r
{nl} or \r
Returns a carriage return character. This can be used to seperate items
in a list, or can split the string at that point, starting a new line.
Example: the string:
This is\ran example{nl}of using newlines.
would print out like:
This is
an example
of using newlines.
NOT|!
{not:expr}
Returns the logical NOT of expr. If expr was true, this returns false.
If expr was false, this returns true.
NULL
{null:expr...}
Returns a null string, no matter what the expressions within it return.
This can take up to nine arguments, though you could pass the output of
several commands as one argument.
ONLINE
{online}
Returns a list of players who are online. This function can only be
executed by wizbitted objects.
ONTIME
{ontime:player}
Returns player online time in seconds. If the given player is not
connected, or is not a player object at all, then this will return -1.
This returns the online time for the most recently connected connection,
if there are multiple connects.
OR
{or:expr1,expr2...}
Returns true if expr1 or expr2 evaluate as true. Otherwise, this returns
false. If expr1 was true, this doesn't bother to exaluate expr2, as it
does C-style shortcutting. If there are more than two arguments, then
this will evaluate them until either one returns true, or until it has
evaluated all the expressions. This returns false only if all of the
expressions return false.
OTELL
{otell:string}
{otell:string,room}
{otell:string,room,player}
This will tell the given string to all the players in the room, except
for the given player. If no room argument is given, it is assumed to be
the room that the triggering player is in. If no player is given, then
it assumes that you want to skip sending the message to the triggering
player. If you pass it a player of #-1, it will send the message to all
the players in the room. This returns the message that was sent. If the
trigger isn't a room, or an exit on a room, and if the message doesn't
already begin with the user's name, then the user's name will be
prepended to the message.
OWNER
{owner:obj}
Returns the owner of the given object. The object must be in the
vicinity, or be controlled by the trigger object's owner.
PARSE
{parse:var,list,expr}
{parse:var,list,expr,sep}
{parse:var,list,expr,sep,s2}
This evaluates expr for each and every item in the given list. On each
evaluation, the temporary variable var will contain the value of the
item under scrutiny. This function returns a list containing the output
of expr for each item within the list. This lets you do direct
translation of a list of dbrefs, for example, into a list of names. var
will only be defined for the duration of expr, and will be undefined
after the {filter} construct finishes. If sep is given, then it uses
that string as the item seperator in the input list, instead of the
usual carriage return character. If s2 is defined, then it will use that
string to seperate the items in the list it returns, instead of the
normal carriage return. sep and s2 can be multiple characters long.
PRONOUNS
{pronouns:string}
{pronouns:string,object}
If passed one argument, evaluates the string and does pronoun
substitution with regards to the using player. If given two args, it
does the pronoun substitution with regards to the given object.
PROP
{prop:propname}
{prop:propname,obj}
Returns the literal string value of the given property. If no object
parameter is passed to it, it looks for the property somewhere down the
environment from the trigger object. Otherwise, it looks down the
environment from the object specified. If the property is not found,
this returns an empty string. If the property that it tries to access
is read restricted and the owner of the trigger object does not own the
object that the property is found on, then the MPI script stops with a
Permission denied error.
PROP!
{prop!:propname}
{prop!:propname,obj}
Returns the literal string value of the given property. If no object
parameter is passed to it, it looks for the property on the trigger.
Otherwise, it looks for the property on the object specified. If the
property is not found, this returns an empty string. If the property
that it tries to access is read restricted and the owner of the trigger
object does not own the object that the property is found on, then the
MPI script stops with a Permission denied error.
PROPDIR
{PROPDIR:propname,obj}
If the given property on the given object is a propdir, containing
sub-properties, then this returns true. Otherwise it returns false.
Object will default to the trigger object, if not given.
RAND
{rand:listname}
{rand:listname,obj}
Returns the value of a randomly picked list item from a property based
list. If no obj parameter is given, then it looks down the environment
from the trigger object for the list. Otherwise, it looks down the
environment from the given object.
REF
{ref:obj}
Returns the dbref of the given object in the form #xxxx. The object must
be in the vicinity, or controlled by the owner of the trigger object.
RIGHT
{right:string}
{right:string,fieldwidth}
{right:string,fieldwidth,padstring}
Takes a string and pads it to fit the given fieldwidth, with the string
right justified. If no padstring is given, it assumes that it will pad
the string with spaces. If no fieldwidth is given, it assumes that the
field width is 78 characters. Example: {right:Hello,10,_.} would return
the string "_._._Hello"
SECS
{secs}
Returns system time: the number of second since midnight 1/1/70 GMT
SELECT
{select:value,listname}
{select:value,listname,object}
Returns the value of a single list item from a sparse property list. The
item chosen is the one who's line number is the largest one that is less
than or equal to the given value. If the list is missing any items, then
{select} will return the item in the list with the highest line number
that is less than or equal to the given value. ie: If the list has the
following entries:
_junk#/1:one
_junk#/5:two
_junk#/16:three
_junk#/20:four
Then {select:9,_junk} will return "two", {select:16,_junk} will return
"three", and {select:25,_junk} will return "four".
SET
{set:var,value}
This sets the value of the given named variable to the given value. If
no variable with that given name is currently defined, then this gives
an error message complaining about that.
SIGN
{sign:expr}
Returns -1 if expr is negative. Returns 1 if expr is positive. If expr
is 0, then it returns 0.
SMATCH
{smatch:str,pattern}
Matches `str' against the wildcard pattern. If there is a match, this
returns true, or "1". If it doesn't match, this returns a value of "0",
or false. In wildcard patterns, the following characters have the
following meanings:
* matches any number of any character.
? matches one character, of any type.
[abcde] matches one char, if it is a, b, c, d, or e.
[a-z] matches one char, if it is between a and z, inclusive.
[^abd-z] matches one char is it is NOT a, b, or between d and z.
{word1|word2} matches one word, if it is word1, or word2.
{^word1|word2} matches one word, if it is NOT word1 or word2.
\ escapes any of the prev chars, making it not special.
STIMESTR
{stimestr:secs}
Given a time period, in seconds, this will return the most significant
time unit of that time period. For example, a number of seconds, that is
equivalent to 9 days, 23 hours, 10 minutes, and 52 seconds, will be have
the value "9d" returned, as the abbreviated most significant time unit.
STORE
{store:val,prop}
{store:val,prop,obj}
Stores a string value in a given property. If no obj parameter is given,
then it stores the property on the trigger object. Otherwise, it will
store it on the given object. If you specify a propname that is
protected, you will get a Permission Denied error. You are only allowed
to store properties on objects controlled by the owner of the trigger
object. The trigger object is the object that triggered the evaluation
of the MPI commands. This function returns the string that is stored as
the prop value. If you store a null value in the property, then it will
remove the property if it is not a propdir. It will clear the value of
the prop if it IS a propdir.
STRIP
{strip:string}
Returns a copy of string with all the spaces stripped from the beginning
and the end.
SUBLIST
{sublist:list,pos1}
{sublist:list,pos1,pos2}
{sublist:list,pos1,pos2,sep}
Takes a list, and returns a subset of the list items within it. The
subset is all the list items between list item pos1, and list item pos2,
inclusive. If the pos2 argument is omitted, it assumes that pos2 is the
same as pos1. If pos2 is less than pos1, then all the list items between
pos2 and pos1 are returned, in reversed order. If pos1 or pos2 are
negative, it counts that many list items back from the end of the list,
so -1 is the last list item, and -5 would be the fifth from last list
item. The input list is assumed to be delimited by carriage returns (\r)
unless the sep argument is given.
SUBST
{subst:str,old,new}
Returns a copy of `str' with all substring instances of `old' replaced
by the text specified by `new'. Basically just substitutes the new text
for the old text in str. example: {subst:Hello World!,l,r} would return
"Herro Worrd!"
SUBT|SUBTRACTION
{subt:expr1,expr2}
{subt:expr1,expr2,expr3...}
Returns the difference of the values expr1 and expr2. If more than two
args are given, all values are subtracted from the first value in
sequence. For example: {subt:10,3,2,4} would be read as 10 - 3 - 2 - 4,
and it would return a result of 1.
TELL
{tell:string}
{tell:string,player}
If passed only a string, tells the user that string. If passed both a
string, and a player dbref, it will tell the given player the message.
This returns the message that was sent. If the trigger isn't a room, or
an exit on a room, and if the message doesn't already begin with the
user's name, then the user's name will be prepended to the message. The
two exceptions to this are that if the messages is being sent to the
owner of the trigger, or to the user, then the user's name will not be
prepended.
TESTLOCK
{testlock:obj,prop}
{testlock:obj,prop,who}
{testlock:obj,prop,who,def}
Tests the lock property `prop', on `obj' against the given player `who'.
If no `who' argument is given, then it checks the lock against the using
player. If a def argument is given, then the lock will default to that
value, if there is no lock property of the given name on the given
object. Returns true if the lock is locked against the player.
TIME
{time}
{time:timezone}
Returns a time string in the 24hr form hh:mm:ss. If the timezone
argument is given, then it offsets the time returned by that number of
hours.
TIMESTR
{timestr:secs}
Given a time period in seconds, this will return a concise abbreviated
string representation of how long that time was. This might return a
value like "9d 12:56" for 9 days, 12 hours, and 56 minutes.
TIMESUB
{timesub:period,offset,listname}
{timesub:period,offset,listname,object}
This is sort of like {list}, except that it will only return one line of
the given named property list. The line it chooses depends on the time.
The period is the length of time, in seconds, that it takes for
{timesub} to cycle through the entire list. The offset is the number of
seconds to offset into the time period, if you actually need to
synchronize the {timesub} with something. The offset usually is just
left at zero. If the object argument is not passed, it looks for the
list on the trigger. What this all means, is that if you have, for
example, a period of 3600 (one hour), an offset of zero, and a property
list that has six items in it, then {timesub} will return the first line
of the property list during the first ten minutes of the hour, the
second line during the next ten minutes, and so on, until it returns the
last line during the last ten minutes of the hour. Then it returns the
first line for the beginning of the next hour. Here's an example:
{timesub:86400,0,_sunmoon}
This example will show different property list lines, depending on the
time of day. The period is 86400 seconds, which is one day. If the
property list has 24 items in it, then a different line will be returned
for each hour of the day.
TOLOWER
{tolower:string}
Returns a copy of string, with all uppercase chars converted to
lowercase.
TOUPPER
{toupper:string}
Returns a copy of string, with all lowercase chars converted to
uppercase.
TYPE
{type:obj}
Returns the type of an object. The possible values are: Bad, Room, Exit,
Thing, Player, and Program.
TZOFFSET
{tzoffset}
Returns local time zone offset from GMT in seconds.
USECOUNT
{usecount:obj}
Returns the usecount of obj.
V|VARIABLE|&
{v:var}
{&var}
These are two ways of trying to do the same thing. They return the value
of the named variable var. If there is no variable with the given name
currently defined, then this gives an error stating as much. Variables
can be defined either with the {with:} function or within a looping
command.
VERSION
{version}
Returns the version string for the server.
WHILE
{while:check,expr}
This is a looping structure. It evaluates the `check' argument, and if
it evaluates true, then it evaluates the expr argument, and repeats the
process. If `check' evaluates false, then the loop is exited. This
returns the result of the last evaluation of expr.
WITH
{with:var,val,expr..}
This defines a new variable with the given name, and sets its value to
the given val. Up to 7 expr's are allowed, but the only value returned
to {with}'s caller, is the value returned by the evaluation of the last
expr. If there is already a variable of the same name, then this command
will override that variable, for the duration of the {with:} command.
The new variable is only valid to use within the confines of the {with:}
command, and it will go away after the command completes. This provides
scoped variables quite effectively. NOTE: There can be no more than 32
variables defined at any one time, total. This includes variables that
are defined within macros, or properties or lists that are executed with
{exec:} or {lexec:}. Here's an example to illustrate the scope of
variables inside of {with:} commands:
{prop:_mydesc} <- {&people} not defined.
{with:people,{contents:here,players}, <- Defining. Not available yet.
{if:{count:{&people}}, <- It's usable now.
The players awake here are
{lit: } <- just puts in a space.
{commas:{&people},{lit: and },
who,{name:{&who}} <- uses {&who} as temp var.
} <- {&who} no longer defined.
}
} <- {&people} no longer defined.
XOR|EXCLUSIVEOR
{xor:expr1,expr2}
Returns true if expr1 or expr2 evaluate as true, but false if both do.
Otherwise, this returns false.
*
MACROS
If the MPI interpreter comes across a function name that it does not
recognize, it will look in the _msgmacs/ propdirs down the environment
from the trigger object, for a property with the name of the function.
If it does find it there, then it takes the value of that property, and
substitutes it in for the function as a macro. The arguments to the
function replace the {:1} through {:9} markers in the macro definition.
For example, if there were a property set on #0, defined as:
_msgmacs/div_rand:{add:{div:{:2},10},{dice:{:1}}}
And you had some MPI code that looked like:
{div_rand:22,160}
Then the macro would expand out to:
{add:{div:160,10},{dice:22}}
After the macro argment substitution is complete, it is then evaluated.
FUNC
{func:name,vars...,def}
This effectively defines a function in MPI, with the given name, that
takes the given named variables. The function is not immediately
evaluated, so it needs to be invoked later, to do anything. Here's an
example:
{func:sqr,val,{mult:{&val},{&val}}}
This defines the function `sqr', that takes a single argument. That
argument is stored in the `val' variable. The function will multiply the
value of the number passed to it, by itself, returning the result. It's
invoked like: {sqr:10}
Effectively, the above {func} declaration is the same as the following
macro, and in fact, it's internally handled the same way:
_msgmacs/sqr:{with:val,{:1},{mult:{&val},{&val}}}
You can define a function that takes more than one argument, but the
maximum number of args you can pass to the function is seven. Example of
multiple arguments:
{func:names,list,numsp,flagsp,
{parse:v,{&list},
{name:{&v}}
{if:{or:{&numsp},{&flagsp}},
{lit:(}
{if:{&numsp},{ref:{&v}}}
{if:{&flagsp},{flags:{&v}}}
{lit:)}
}
}
}
{names:{contents:here},1,1}
*****
3.2 Overview: MUF
MUF -- a dialect of FORTH -- is one of two programming languages
implemented on all MUCKs, the other being MPI. The speed and efficiency
of MUF make MUCKs readily user-extensible: powerful new commands and
programs can be soft-coded into the database. Although the only place
you'll be able to use it is on MUCKs, MUF is a real programming
language: once you've learned it, you can truthfully say you know how to
program computers, and concepts and habits of thought you pick up as a
Mucker will be useful in learning languages with widespread RL
applications.
MUF is an extensible, structured, stack-based, compiled language.
Extensible: If there isn't a command to do what you want, you can make
one.
Structured: A MUF program consists of `functions' or `words'... blocks
of code that are executed as a unit and `call' each other as needed.
It doesn't matter (to the computer) whether you put all your
code on one long line or every word on a new line (it matters a lot
to people who are trying to read your program). White space (any
combination of spaces, tabs, or new lines) separates words, and the
order of the words and their positioning between the symbols that
start and end a function are what matter. The program is composed
of `functions' or `words' that each perform a specific task.
Stack-based: You do everything by manipulating a stack, a set of
`last-in-first-out' values like HP calculators use.
Compiled: You write a program that people can read, with semi-normal
words like `pop' and `rot' and `remove_prop' (this is your source
code) and then a part of the server, the MUF compiler, turns it
into arcane stuff that computers can read (this is your object code).
You won't ever see the object code.
Before You Begin:
In order to program in MUF, you'll need a Mucker bit, a flag that lets
you use the MUF editor. A wiz will need to set this, so page one and
ask. There are three levels of mucker bits, M1 (apprentice), M2
(journeyman), and M3 (master) (wizards are considered M4).
As a new Mucker, you'll get an M1 bit. M1's have access to most of the
functions, but not all; output from an M1 program to anyone other than
the owner of the program is prefaced by the user's name; and the program
won't be able to send messages to or retrieve information from remote
locations. An M1 bit is essentially MUF with training wheels. Once
you've written a couple M1 programs that work, you can show them to a
wiz and ask for an M2 bit. M2's can't use all the functions, but you can
make truly useful programs at the M2 level: bulletin board or book
programs, specialized exits and locks, morphing programs, etc.
M3 bits are dandy to have, but they are hard to come by on large mucks,
and for good reason. An M3 bit gives its owner considerable power over
the data base, approaching that of a wizard: an inept or malintentioned
M3 coder could cause serious problems. To get an M3 bit on a well
established MUCK, you will need to write some very good programs and
have shown yourself to be a trustworthy player over time. In general,
it's easier to get an M3 on newer, smaller MUCKs.
There are two commands that are good to know Before you Begin. One is
`man', the online manual command. Typing `man pop' would tell you about
the MUF primitive `pop'. The other is @q. This makes a foreground
program you have running quit. If you find yourself in a run-away or
locked-up program, type @q to get out of it.
Actually Beginning:
We'll get to MUF code itself soon, but a few words on the mechanics of
making programs and their trigger actions may be in order first.
The command to make a program is `@program <name of program>', or
just `@prog <name of program>'. This does two things. It creates
the program object (although there is no code in it yet), and it puts
you into the MUF editor. The program is essentially a thing. You can
pick it up, hand it to people, and so on, but it has the type flag F and
so is treated as a different kind of object. The editor lets you enter
and manipulate the text of your program, much like lsedit lets you enter
and manipulate the text of a list (though the commands are different).
Type `q' to get out of the editor (if you're in `insert' mode, you will
need to type a . period and then `q'). Once the program is created, you
can edit or add to the code with the @edit command, syntax `@edit
<program>'.
The editor commands are:
<number> i Insert text before line <number>. If you don't
have any code in the program, you can just type
`i' by itself to enter insert mode.
. Exit insert mode. (That's a period, btw)
<number> <number> l List lines <number> to <number>.
<number> <number> d Delete lines <number> to <number>.
a Show macros (abridged version).
s Show macros (long version).
<program#> v List program's public functions.
n Toggle line numbering on and off.
c Compile the program you're editing.
u Uncompile it.
h Get help on the editor.
q Quit editor mode.
The editor is cumbersome. You may find it easier to work on your program
in a text editor on your own computer or in your UNIX account. The
following technique works well. Begin the file with:
@edit <program name or #dbref>
1 9999 d
i
And end it with:
.
c
q
Put the code of your program between those. Then, by pasting the whole
file into your mucking window, or by using your client to upload the
file onto the MUCK, you automatically delete all old code, insert new
code, and recompile. (To upload a file using TinyFugue, type /quote -0
`<filename> . The apostrophe in front of <filename> is
required.)
You will also need to make something that triggers the program. The most
straightforward method is to open an action and link it to the program.
You can also trigger it from a prop (see Section 2.1.3). If a program is
set with the L flag, it is `public': anyone can link to it or list it.
Without the L flag, only you or a wizard can list and link to the
program.
A First Program:
Let's make a "Hello, world!" program, to practice with the mechanics of
making a program, and because it's something of a rite of passage.
Make a program. Let's call it Tinker.muf, because we'll be tinkering
around with it. Type `@prog Tinker.muf'. The program is created and you
go into the editor. At this point, either type `i' to enter `insert'
mode and type the code below, or type `q' to get our of the editor and
quote/paste it into the MUCK from your host computer, then compile the
program and exit the editor (type `c', then `q' while in the editor).
====================================
> @prog Tinker.muf
Program Tinker.muf created with number 1230.
Entering editor.
> i
Entering insert mode.
> (Tinker.muf. A practice program)
>
> : main
> me @ "Hello, world!" notify
> ;
> .
> c
Compiler done.
> q
Editor exited.
====================================
Create an action attached to yourself and linked to the program.
====================================
> @act test = me
Action created with number #1231 and attached.
> @link test = tinker.muf
Linked to Tinker.muf(#1230FM1)
====================================
Check your program by typing `test'.
====================================
> test
Hello, world!
====================================
The Parts of a MUF Program:
1 ( Tinker.muf. A practice program )
2
3 : main
4 me @ "Hello, world!" notify
5 ;
Line 1 is a comment. In MUF, anything in parentheses is a comment. The
compiler ignores it, and it doesn't add to the compiled size of your
program. Comments are used to tell people what the program does, and
they are important. Tinker.muf is a very simple program at this point,
but you should go ahead and get into the habit of including comments.
They explain what's going on to people who are trying to maintain your
code, including you. Code that makes perfect sense to you when you write
it will look like gobbledygook in a couple days, and you'll thank
yourself for including frequent, detailed comments. The comment here is
a header comment. In a full-blown program, we would put notes here about
who wrote the program, when, how to install it, how to use it, and
permissions for porting the program to other MUCKs.
Lines 3-5 compose a function, or `word'... a block of code that is
executed as one piece. Functions are the building blocks of your
program. You make a MUF program by making different functions that do
different things, and calling the appropriate function when needed (more
on this later). This function is called `main', and it's our only
function so far. A function begins with a colon, a space, and the name
of the function (the space between the colon and the name is essential).
It ends with a semi-colon. Unlike C/C++, there's nothing special about
the function name `main' in MUF. We could call the function anything we
want. A MUF program begins with the *last* function in the program, no
matter what it's called (when we add more functions, they'll need to go
above main). In this case, main is the only function, so it's the last
function, so the program begins execution there.
Line 4 is the heart of our program, and it includes four different kinds
of MUF stuff.
'me' is a variable. It defines a space in the computer's memory that
holds some information... holds a value. In this case, it's a predefined
variable (MUF has already staked out this variable name and declared
what it's going to hold). The variable `me' holds the dbref of whoever's
using the program. When you trigger Tinker.muf by typing `test', `me'
holds your dbref. If someone else typed `test', it would hold his. You
can also add your own variables.
'@' is an operator. Operators do stuff to (operate upon) other things. +
and - are some other operators. They add and subtract, and they only
work on numbers. @ is the `fetch' operator, and it only works on
variables. The @ fetches the value out the variable named right before
it, and puts the information that was in the variable onto the top of
the stack (we'll cover the stack next). Here, the @ is getting a dbref
out of the variable `me'.
"Hello, world!" is a string. A string is a set of characters. Here the
characters are the letters that form the words - Hello, world -. The
quotation marks are important. They tell MUF that this is a string.
Anything inside double quote marks is treated as a string, a set of
characters. The word - me - by itself is a variable, but "me" is a
string. 4 by itself is a number, an integer, but "4" is a string holding
one character, the numeral 4. #123 is a dbref, but "#123" is a string of
the corresponding characters. These differences -- variable vs. string
vs. integer vs. dbref-- are called `data types', and they're important
in MUF (MUF is `strongly typed'). Most operations can only be performed
on one type of data. We have an example of that coming up...
NOTIFY is a primitive, a function that has been defined in MUF. NOTIFY
needs two things to do its job, a dbref and a string. It takes the
string and displays it to the character defined by the dbref (much like
a {tell} in MPI). If it doesn't have a dbref and a string on top of the
stack to work with, the program won't work.
Incidently, the collective term for all these different kinds of MUF
stuff (variables, integers, strings, and dbrefs... operators and
primitives... function names and the symbols that mark their beginning
and end) is `statement'. NOTIFY, @, 123, : , and `main' are all
statements.
The Stack:
Everything in MUF is done by manipulating the stack. The stack is the
area in the computer's memory that holds the data for your program, the
information it uses as it does its job. So try thinking of it as a RAM
disk, a storage device. In this case, the information is stored by
putting pieces of information `on top of each other' instead of in
tracks or sectors. Each time the program is used (each `process'), it
gets its own fresh new stack.
The MUF stack is a LIFO stack: `Last in, first out.' When you add
something to the stack, it goes on top of the stack, and it's the only
thing that's immediately accessible. Previous items are still there, in
the computer's memory, but they're `underneath' whatever you just added,
and you'd need to use some stack handling functions to get them so your
program can use them. A good analogy is a stack of plates. If you put a
red plate on top of a blue plate, and then a white plate on top of the
red one, you'd have a stack:
white plate
red plate
blue plate
All three plates are there, but the only one you can pick up without
rearranging the stack is the white one.
Within a function, MUF reads the code left to right, top to bottom. We
only have one line in our little program, so it reads that line left to
right, coming first to the variable `me'. We haven't yet told MUF to do
anything with the variable; we've just supplied it. So it puts that
variable on the stack. Here it is:
me
Our stack is pretty short right now, just one item. Notice that our one
item right now is the variable `me', as opposed to the information
stored in that variable (a dbref). Then MUF reads along our line of code
and comes to the @ operator. The operator is not data. It's an
instruction to do something with the data that's present, in this case
the variable `me'. So the @ doesn't go on the stack. Instead, it does
its little operation: it fetches the value that's stored inside `me'.
When it does so, it `uses up' the variable `me'. Imagine that the fetch
operator picks up the `me', opens it like a box, pulls out what's
inside, and throws the box away. So, let's say your dbref is #123. Now
the stack looks like this:
#123
Still pretty short. Then, reading along, MUF comes to the string "Hello,
world!". We haven't told MUF what to do with this string, we've just
supplied it. So it goes on top of the stack:
"Hello, world!"
#123
Now we have a stack that actually looks like a stack. The string "Hello,
world!" is stacked on top of the dbref #123. Next MUF comes to the
primitive NOTIFY. Like operators, primitives are instructions to do
things with data, rather than data to be put on the stack. NOTIFY is a
predefined set of instructions that say `Take the string that's on top
of the stack, go find the player with the dbref that's right underneath
that string, and tell her the string. And forget you ever heard of this
string and this dbref'. The program does what it's told, and the player
with dbref #123 suddenly sees Hello, world! on her screen (she won't see
the quotation marks: they're what define the string as a string, and not
part of the string itself). In the process, NOTIFY `uses up' the two
pieces of data that it requires, and the stack is now empty. Since the
program ends at this point, that's fine. But if we did something else
that required data (like tack another NOTIFY on the end of our line),
then we'd get `stack underflow', and the program would crash.
Watching the Stack with the Debug Mode:
You can see exactly what's going on as your program runs by putting it
in debug mode. A D flag set on a program means `turn on debugging.'
====================================
> @set tinker.muf = D
Flag set.
> test
Debug> 1 ("") (main)
Debug> 2 ("") V0
Debug> 2 ("", V0) @
Debug> 2 ("", #123) "Hello, world!"
Debug> 2 ("", #123, "Hello, world!") NOTIFY
Hello, world!
Debug> 3 ("") EXIT
====================================
The first bit of these lines, `Debug>', simply tells you that what
follows is output from the debugger (as opposed to stuff like the line -
Hello, world!' - , which is output from the program). The number
immediately following is the line number of the program that's currently
executing. The items in parentheses, separated by commas, are the stack:
the left end of the line is the `bottom' of the stack; the right end is
the `top'. The last item (after the parentheses) is what MUF is reading
at this exact point in the program's execution.
On the first line, our stack is "", an empty string (this is called a
"null string"). So our discussion above was slightly inaccurate. When a
program is called, the argument to the trigger action (whatever was
typed after the trigger command) is pushed onto the stack. We typed just
`test' by itself, so nothing was pushed onto the stack. In this case,
`nothing' looks like "", a string with nothing in it. Run the program
again, with an argument this time, to see the difference. Type `test
pickle'. The first line of debugging will now look like...
Debug> 1 ("pickle") (main)
That `V0' is our `me'. We call it `me'; MUF calls it `V0'... `V' for
`variable', followed by a zero because it's the first variable it
defined and computers start counting at zero. Study what happens to the
stack as each successive item is read by MUF to get an idea of how the
stack works.
You might try adding another line to Tinker.muf to see the stack at work
a bit more clearly. Change Tinker.muf so that now it reads...
( Tinker.muf. A practice program. )
: main
me @ "Hello, world!" notify
"mink" "otter" "linsang"
pop pop pop
;
====================================
> @edit tinker.muf
> 1 99 d
> i
> ( Tinker.muf. A practice program. )
>
> : main
>
> me @ "Hello, world!" notify
>
> "mink" "otter" "linsang"
>
> pop pop pop
> ;
> .
> c
> q
> test
Debug> 1 ("") (main)
Debug> 2 ("") V0
Debug> 2 ("", V0) @
Debug> 2 ("", #123) "Hello, world!"
Debug> 2 ("", #123, "Hello, world!") NOTIFY
Hello, world!
Debug> 3 ("") "mink"
Debug> 3 ("", "mink") "otter"
Debug> 3 ("", "mink", "otter") "linsang"
Debug> 3 ("", "mink", "otter", "linsang") POP
Debug> 3 ("", "mink", "otter") POP
Debug> 3 ("", "mink") POP
Debug> 4 ("") EXIT
====================================
The POP primitive takes whatever's on top of the stack and gets rid of
it. POP pops it off the top, into oblivion. If we added one more POP,
the null string would be popped off the stack right at the end of the
program, and it would exit with nothing on the stack. If we added yet
another one, it would try to pop something that isn't there, and crash.
Organizing Your Code:
Recall that MUF is a `structured' language: as long as the statements in
a function are in the same order, reading top to bottom and left to
right, and as long as they are separated by whitespace, it doesn't
matter how you place them on the page. `Whitespace' is any combination
of spaces, tabs, or line breaks.
Instead of...
: main
me @ "Hello, world!" notify
"mink" "otter" "linsang"
pop pop pop
;
We could have written...
: main me @ "Hello, world!" notify "mink" "otter" "lingsang" pop pop pop ;
Or even...
: main me
@
"Hello, world!"
notify "mink"
"otter"
"linsang"
pop
pop
pop
;
All three versions would mean the same thing to the compiler, would use
the same amount of memory, and would be executed in exactly the same
way. To most people, however, the first version would be much more
clear. Arrange your code in such a way that its format illustrates or
reinforces logical relationships (that is, combine things that go
together and separate those that don't).
MUF is not case sensitve: `POP', `Pop', and `pop' would all be treated
the same way. Capitalization, therefore, can be used as another way to
format code. For example, you might choose to capitalize all function
names and begin all variable names with lower case to concisely indicate
their difference. Some coders use all capitals for primitives. This does
clearly indicate their difference, but many people find all caps less
readable than upper-lower case. Choose your own style, but remain
consistent within a program.
Now we'll (completely) rewrite Tinker.muf several times, with each
version introducing an important aspect of MUF programming. The >
signs and other formatting information have been omitted from the
remaining examples, so you can cut and paste from this file into the one
you're working on.
Conditional Statements:
A conditional statement causes the program to do something only if a
certain condition is true. The main form of a conditional statement in
MUF is the IF-THEN statement.
IF-THEN works a bit differently in MUF than in some other programming
languages. In BASIC, for example, the meaning is something like `IF A is
true, THEN go do B'. In MUF, the meaning is more like `IF A is true, do
this bit here... B. THEN do all this other stuff, the rest of the
program.'
'True', as far as MUF is concerned, means `any value other than the
integer 0, or a null string ( "" ), or the dbref for "nothing", which is
#-1'.
0 <---- False
"" <---- False
#-1 <---- False
1 <---- True
"Hiya!" <---- True
#123 <---- True
An IF checks (and uses up) the top value on the stack. When this value
is true, any code between the IF and its matching THEN will execute
(every IF must have a matching THEN). When the value is false, the
program skips over everything until it gets to the matching THEN, and
resumes execution at that point. Here's an example...
====================================
: main
random 1000000 > if
me @ "Yes, the number is greater than one million." notify
then
me @ "OK, we're done with the IF-THEN stuff." notify
;
====================================
RANDOM puts a random number between one and the largest integer it can
generate (about 2.1 billion) on the stack. The > greater than
operator tests the two numbers right before it, and returns true (that
is, puts a `1' on the stack) if the first number is greater than the
second. If the first number is less than the second, it returns false
(it puts a `0' on the stack). The two numbers being compared are used up
in the process.
So, when our little program gets to IF in the first line, there will
either be a `1' or a `0' on the stack. If the value on the stack is 1
(which it will be the vast majority of the time), the IF test will be
true, and the next line will execute: the program will notify the user
with `Yes, the number is greater than one million.' Then it will
continue past the THEN and do the next line, notifying the user `OK,
we're done with the IF-THEN stuff.' If the random number were less than
than one million, the IF test would be false, and the program would skip
straight to the last line.
You can also specify what should happen when the IF test is false by
placing an ELSE between the IF and the THEN. The following version will
notify whether the random number is greater or less than one million.
====================================
: main
random 1000000 > if
me @ "Yes, the number is greater than one million." notify
else
me @ "No, the number is less than one million." notify
then
me @ "OK, we're done with the IF-ELSE-THEN stuff." notify
;
====================================
Intenting one level for each condition, as in these examples, is a
common and helpful convention.
Stack Effects and Keeping Your Data:
Recall that when we did `me @ "Hello, world!" notify', the NOTIFY `used
up' the dbref and the string. This is formally expressed in NOTIFY's
`stack effect comment'. Type `man notify' to see the manual entry for
NOTIFY. The entry, like all entries for primitives, includes a stack
effect comment: ( d s -- ).
The stack effect comment provides a `before and after synopsis' of the
primitive's effect on the stack: the items before the dash are what the
primitive requires; the items after are what it leaves. (`d' means
`dbref'; `s' means `string'; `i' means integer; `v' means a variable';
`x' means an item that can have various types.) In this case, NOTIFY
needs a dbref and a string -- in that order -- and leaves nothing in
their place.
Most primitives `use up' their data in this fashion, and this is a Good
Thing. If they did not, programmers would need to put one or several
POPs after each primitive to keep the stack from growing unmanageable,
which would greatly increase the size of programs. However, this also
means that when you are working with data that you will need again later
in the program, you will need to store it, either by putting a copy of
it on the stack or by storing it in a variable.
The DUP primitive makes a copy of the top item on the stack; its stack
effect comment is ( x -- x x ). The following version of our program
uses DUP to make an extra copy of the random number, and after the
IF-ELSE-THEN section it tells the user what the random number is.
====================================
: main
random dup 1000000 > if
me @ "Yes, the number is greater than one million." notify
else
me @ "No, the number is less than one million." notify
then
intostr me @ swap notify
;
====================================
This time, because of the DUP in the first line, there are two copies of
the random number beneath the 1000000 when the greater-than test is
executed. The test will use one of them, but the other will remain on
the stack. The IF-ELSE-THEN part will then execute, leaving this number
unaffected.
The last line tells the user what the random number was. When the
program gets to this line, the only thing on the stack is the random
number, in integer form. The stack effect of NOTIFY is ( d s -- ), so
we need to do a little rearranging: we need to use some `stack handling'
primitives to convert the integer into a string and place the stack
items in the correct order.
INTOSTR converts the random integer into a string. If the random integer
were 23231874, INTOSTR would remove this number from the stack and leave
the string "23231874" in its place. `me @' puts the user's dbref on the
stack. But now the two stack items are in the wrong order. The dbref
needs to be in front of (or `below') the string. SWAP, one of several
stack handling primitives, reverses the order of the top two items on
the stack ( x y -- y x ). So, if our stack were `"23231874" #123', SWAP
would make it `#123 "23231874"', which will work for NOTIFY.
Instead of duplicating a datum on the stack, you can also store it in a
variable. This is especially useful when the datum will be needed much
later in the program, or when the program will need the same datum at
different places. There are two steps to storing data in this way:
declaring the variable, and storing the data.
Declaring the variable is done simply by including the word `var' or
`lvar' followed by the name of the variable in the program. The variable
can be declared anywhere in the program, so long as it's somewhere
*before* the variable is used in the code, and *outside* the definition
of a function. So, it makes good sense to declare all your variables at
the top of the program. `Var' declares a global variable (all programs
can use it); `lvar' declares a local variable (only this program can use
it). *Use local variables.* The data type of a variable does not have to
be declared: once you define a variable, it can hold any type of data.
Once a variable has been declared, you can store data in it with the
`store' operator, an ! exclamation point ( x v -- ). The following
version of our program does the same thing as the previous one, but this
time stores the random number as a variable instead of keeping it on the
stack.
====================================
lvar ourNumber
: main
random ourNumber !
ourNumber @ 1000000 > if
me @ "Yes, the number is greater than one million." notify
else
me @ "No, the number is less than one million." notify
then
me @ ourNumber @ intostr notify
;
====================================
Calling Functions:
So far, all versions of our program have only included one function, but
programs can have as many functions as you want.
Functions (also called `words') are blocks of code executed as a single
unit. They begin with a colon followed by the name of the function, and
end with a semi-colon. The name of a function can be pretty much
anything you want, but should include at least one non-numeric
character. You should also avoid using function names already defined in
MUF (type `man <word>' to see if the function name is already
being used.)
Once they have been defined, functions can be called simply by including
their name in the program's code. The following version of Tinker.muf
does the same thing as the previous two, but this time the `greater' or
`less than' notifications are handled by separate functions:
====================================
lvar ourNumber
: TellTrue
me @ "Yes, the number is greater than one million." notify
;
: TellFalse
me @ "No, the number is less than one million." notify
;
: main
random ourNumber !
ourNumber @ 1000000 > if
TellTrue
else
TellFalse
then
me @ ourNumber @ intostr notify
;
====================================
Loops:
A loop is a section of code that executes repeatedly, until a certain
condition is met. The programmer defines the condition. If no condition
is defined (or if the condition is one that will never be met), the loop
will continue to execute indefinitely. This is called an `infinite
loop'. The code for a loop begins with the primitive BEGIN and ends with
either REPEAT or UNTIL.
A common way to define the exit condition of a loop is to use a variable
to store the number of times the loop is to execute. With each
repetition (or `iteration') of the loop, the variable is increased
(`incremented') or decreased (`decremented') by one. When the value
stored in the variable matches a predefined limit (often `0'), the loop
exits. The following version of Tinker.muf uses a loop controlled in
this manner to do the `random number test' from the previous version
three times.
====================================
lvar ourNumber
: TellTrue
me @ "Yes, the number is greater than one million." notify
;
: TellFalse
me @ "No, the number is less than one million." notify
;
: main
3 counter !
begin
counter @ 0 = if
break
then
random ourNumber !
ourNumber @ 1000000 > if
TellTrue
else
TellFalse
then
me @ ourNumber @ intostr notify
counter @ 1 - counter !
repeat
me @ "OK, we're done with the loop." notify
;
====================================
At the very top of the program, we declared the local variable
`counter'. In the first line in main, we stored the integer 3 in our
variable `counter'. The next line is BEGIN, which starts the loop. The
first thing MUF does with each pass through the loop is check to see if
the value stored in `counter' is 0. If it is, execution BREAKs out of
the loop, and does whatever comes next (which in this case is to tell us
"OK, we're done.")
In the first iteration of the loop, the IF test will be false, because
we just put a 3 in `counter', not a 0. So the loop will continue,
executing our random number test. Then, at the bottom of the loop, we
fetch the number out of `counter', subtract 1 from it, and then store
the new number back in counter. Then the loop REPEATs, jumping back to
the top of the loop. This time, the value in counter is 2... still not
0, so the loop exectutes again. The next time the loop repeats, the
value is 1: the random number test has executed three times. Then
execution will jump back to the top of the loop and begin for a *forth*
iteration. This time, however, the value stored in `counter' has reached
0. The IF test will be true, so the BREAK will be executed. The program
jumps out of the loop and does whatever comes after the REPEAT (tells us
we're done).
Here we are using IF to see if it is time to break out of the loop. MUF
provides another conditional statement that does the same thing in
shortened form. WHILE tests the top value on the stack for truth, just
like IF does. When an IF test is true, code between the IF and its
matching THEN is executed; otherwise, it skips to whatever follows the
THEN. When a WHILE test is true, code between the WHILE and the next
REPEAT or UNTIL is executed; otherwise, it skips to whatever follows the
REPEAT or UNTIL. In other words, the loop continues to execute WHILE the
condition is true.
In the above version of Tinker.muf, we used...
counter @ 0 = if
break
then
to exit the loop. We could accomplish the same thing with...
counter @ while
As long as `counter' is not 0, it will be true, and the rest of the loop
will execute. When it gets to 0, it becomes false, and the WHILE will
cause execution to break out of the loop.
UNTIL also provides a way to exit from a loop. The UNTIL marks the
`bottom' of the loop, like a REPEAT, but also serves as an
exit-condition check like WHILE. If the value on top of the stack is
true when the program gets to UNTIL, execution `falls through' the
bottom of the loop and continues from there. For example, the following
loop repeats until RANDOM generates an integer greater than 1.5 billion.
====================================
begin
random
dup intostr me @ swap notify
1500000000 >
until
====================================
With each iteration, the loop generates a random number, converts it
into a string and notifies the user, then tests to see if it's greater
than 1.5 billion. If so, the top value on the stack at UNTIL will be
true, and the program will exit the loop. Otherwise, execution jumps
back to BEGIN, and the loop repeats.
*****
You make a MUF program do what it is supposed to by defining functions
and directing program flow with conditional statements and loops. There
are a number of fine points, but these are the heart of MUF programming.
Once you have a good grasp of these, you are past the hard part.
Now we will tinker with Tinker.muf until it becomes a useful program,
along the way covering most of the issues you will face in MUF. We will
make Tinker.muf into a program that checks all the exits in a room and
makes sure that they have @succ, @osucc, @odrop, and @desc properties.
First we'll do a rudimentary version with no error checking to
concentrate on new topics, then a final version. Enter the following
code in your program.
====================================
@edit tinker.muf
1 999 d
i
lvar ourExit
: DescTell
dup unparseobj " needs a description." .tell
;
: SuccTell
dup unparseobj " needs a success message." .tell
;
: OsuccTell
dup unparseobj " needs an osuccess message." .tell
;
: OdropTell
dup unparseobj " needs an odrop message." .tell
;
: main
loc @ exits ourExit !
begin
ourExit @ while
ourExit @
dup "_/de" getpropstr not if
DescTell
then
dup "_/sc" getpropstr not if
SuccTell
then
dup "_/osc" getpropstr not if
OsuccTell
then
dup "_/odr" getpropstr not if
OdropTell
then
ourExit @ next ourExit !
repeat
;
.
c
q
====================================
The first line in function `main' uses the predefined `loc' variable to
put the dbref of the user's location on the stack, and then uses the
EXITS primitive to put the first exit in the room onto the stack (the
room's dbref is used up). The exit's dbref is then stored in the local
variable `ourExit'.
This is followed by a loop. The first line in the loop tests the exit
condition: WHILE there is a value in the `ourExit' variable, the loop
will continue to execute.
The next line fetches the value out of ourExit and places it on the
stack. Then, the value is duplicated and tested four times, once for
each message we're interested in.
dup "_/de" getpropstr not if
DescTell
then
DUP puts an extra copy of the exit's dbref on the stack, to be used in
an IF test, leaving the first copy on the stack. Here, GETPROPSTR puts
the value of the exit's "_/de" property on the stack... the exit's desc.
We want to tell the user if the exit *doesn't* have a desc, so we
reverse the truth value of the top item on the stack with NOT. If the
room *does* have a desc, the desc string will be on the stack... and a
string other than "" is true. The NOT will replace this string with 0
zero, and the IF test will be false... execution will jump to the line
following THEN. However, if the exit *doesn't* have a desc, the top item
on the stack will be a "" null string. The NOT will replace this with a
1 one, for `true'. In this case, the IF test will be true, and the code
between IF and its corresponding THEN will execute: the program will
execute the function DescTell.
The same process is then repeated for each of the messages we're
interested in: @succ, @osucc, and @odrop.
Exiting this loop is controlled by the NEXT primitive. NEXT takes the
dbref of an exit or thing, and returns the NEXT exit or thing in the
room's inventory. So, the line...
ourExit @ next ourExit !
fetches the dbref of the current exit, gets the NEXT exit, and stores
that one in the ourExit variable.
Execution then jumps back to the top of the loop: WHILE we still have
exits to check, the loop will continue to execute. But, when we run out
of exits, there will be nothing in the ourExit variable. The WHILE test
will be false, and execution will jump out of the loop.
Refining the program:
There are some weak points to this version of Tinker.muf. If it is an M1
program, and someone tried to use it in a room she doesn't own, the
program would crash with a permission denied error. It is inefficient
and potentially misleading in that NEXT may cause it to report on
objects that aren't exits. Also, there are no comments. And it doesn't
include online documentation such as a #help function. We'll rectify
these weaknesses and add some new capabilities in our final version, and
in the process cover new aspects of MUF programming.
Tinker.muf, final product...
====================================
( Tinker.muf, v1.0, by Jessy @ GenericMUCK 5/96
A builder's utility program that checks the exits in a room to make
sure they have @succ, @osucc, @odrop and @desc messages, and that
none are unlinked.
This program was written to accompany the MUF tutorial in The MUCK
Manual. While it is slightly more convenient than examining all the
exits -- and possibly overlooking some -- its primary purpose is to
introduce different aspects of MUF. Besides, your MUCK probably
already has a @check command which does the same thing better.
Installation:
Port the program and set it Link_OK if it is to be public. Create
an action and link it to the program. If the program is set M2 or
higher, edit the first line of code following the header comment
to read `$def runningM2'. The program requires the standard libarary
lib-match, which should be available on any established MUCK.
Use:
Typing the action name checks all exits in the room. Typing the action
name followed by an exit name checks just that exit.
Clean up:
Your MUCK really doesn't need multiple copies of Tinker.muf lying
around. If you are using this program while learning MUF with the
MUCK Manual, it would be best to recycle it and the action when
finished or -- better yet -- put your own new program in it.
Tinker.muf may be freely ported. Please comment any changes.
)
( define owner's Mucker level. If not M1,
replace `runningM1' with `runningM2' )
$def runningM1
$define Tell me @ swap notify $enddef
( include lib-match for finding exits by name )
$include $lib/match
lvar ourExit ( stores exit dbref )
lvar counter ( store count of exits checked as an integer )
: Help ( -- ) ( show help screen )
"Tinker.muf v1.0" Tell
" " Tell
"A builder's utility that checks to make sure all exits "
"in a room have a @succ, @osucc, @odrop and @desc set."
strcat Tell
" " Tell
"To use, simply type \"" command @ strcat "\"." strcat Tell
" " Tell
"To check a specific exit, type \"" command @ strcat
" <exit name>\"." strcat Tell
;
: Plural? ( s -- s i ) ( return true if s is not "1" )
( leave test string on stack )
dup "1" smatch if
0
else
1
then
;
: CheckExits ( -- ) ( report on exits )
0 counter ! ( init counter )
dup if ( match specified exit name )
.noisy_match not if ( couldn't find it; )
exit ( lib-match will notify; exit )
else
ourExit ! ( found it; store dbref; store 9999 in )
9999 counter ! ( counter; will use for loop-exit test )
then
else
pop ( not doing a specific match; )
loc @ exits ourExit ! ( init ourExit to first one )
then
begin ( BEGIN EXIT-CHECKING LOOP )
ourExit @ while ( break if no more exits )
ourExit @ ( put current exit on stack )
dup exit? not if ( we're only interested in exits )
pop ourExit @ next ourExit !
continue
then
dup getlink not if ( exit linked? )
dup unparseobj
" is unlinked (not secure)." strcat
me @ swap notify
then
$ifdef runningM2 ( only check room-to-room exits; M2+ only )
dup getlink room? not if
pop ourExit @ next ourExit !
continue
then
$endif
dup "_/sc" getpropstr not if ( has a @succ? )
dup unparseobj
" needs a success message." strcat
me @ swap notify
then
dup "_/osc" getpropstr not if ( ... @osucc? )
dup unparseobj
" needs an osuccess message." strcat
me @ swap notify
then
dup "_/odr" getpropstr not if ( ... @odrop? )
dup unparseobj
" needs an odrop message." strcat
me @ swap notify
then
dup "_/de" getpropstr not if ( ... @desc? )
dup unparseobj
" needs a description." strcat
me @ swap notify
then
pop
counter @ 9999 = if ( break if we're only checking one )
break
then
counter @ 1 + counter ! ( increment counter )
ourExit @ next ourExit ! ( increment ourExit )
repeat ( END EXIT-CHECKING LOOP )
counter @ intostr ( report how many exits checked. )
Plural? if
" exits"
else
" exit"
then
" checked." strcat strcat Tell ( all done! )
;
: main
strip
"me" match me !
dup if ( check: wants help? )
"#help" smatch if
Help exit
then
then
$ifdef runningM1 ( bail out if someone else's room; M1 only )
loc @ owner me @ dbcmp not if
"Sorry, this program is only for rooms that you own."
me @ swap notify exit
then
$endif
CheckExits ( go check those exits )
;
====================================
Comments:
This version is properly commented. A header comment provides the author
of the program, its purpose, discusion of how to install and use it, and
a statement of conditions for porting the program to other MUCKs. Each
function includes a stack effect comment, which would be helpful when
debugging the program and would be useful for someone deciding whether
to borrow a function for use in another program. Additional comments
provide a close narration of the program's execution, making it
considerably easier for someone to read through the code and figure out
what is (or should be) doing what.
Preprocessor Directives:
This version makes use of several `preprocessor directives'...
additional steps the compiler performs before compiling the program.
'$define' replaces all occurances of the first word following `$define'
with any remaining words between the first word and the `$enddef'
directive.
The first of these directives, $define runningM1 "yes" $enddef, defines
the word `runningM1' as the string "yes".
***bookmark***
3.2.1 Mucker Levels
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 run
as if they were level 1 Muckers.
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. 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 NEXTOBJ 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.
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.
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. A program cannot be set to Mucker Level
Zero, since it has no meaning for programs. (You expect them to use the
MUF editor or something?)
When a program is created, it is automatically set to the same
Mucker level as the creating player. When a program is loaded from the
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.
~
Compiler directives for MUF:
$define <defname> <definition> $enddef
Basically the same as C's #define <defname> <definition>
$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
$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:
1) Use "@register lib" to list what libraries exist.
2) Use "@view $lib/<libraryname>" to list the docs on that library.
3) 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>
then 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:
1) create a program with several useful generic subroutines.
2) DOCUMENT those subroutines in a commented out header in the prog.
3) @set <program>=_docs:<command to list those DOCS you made>
4) make sure that all the functions are declared PUBLIC.
5) Make sure the program is set LINK_OK.
6) Globally register the program with the @register command with a
prefix of "lib/". ie: @reg lib strings=lib/strings
7) 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
8) 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.
~
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 refer 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, refer 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 refer to the outer
loop)
dup intostr me @ swap notify
dup 1 = until pop (This UNTIL ends the outer loop)
~
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 (BLOCKED) run in preempt mode, regardless of
the mode of the program. ie: a foreground program, while running in a
program set BLOCKED, 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 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.
3.2.2 MUF Libraries
3.2.3 MUF Macros
3.2.4 MUF Examples
3.2.5 MUF Reference
Bitwise Operators:
bitor bitxor bitand bitshift
Connection-Handling Primitives:
awake? online concount condbref conidle
contime conhost conboot connotify condescr
descrcon descrflush descriptors nextdescr
Control Structures:
if else then begin for
while break continue until repeat
jmp exit execute call abort
kill
Data Conversion Primitives:
atoi intostr dbref int variable
ctoi float int ftostr itoc
stod strtof
Error-Handling Primitives:
clear clear_error error? error_bit error_name
error_num error_str is_set? set_error
Input/Output Primitives:
notify read tread notify_except
notify_exclude
Lock-Handling Primitives:
locked? getlockstr setlockstr parselock prettylock
testlock unparselock
Math and Comparison Primitives:
+ - * / % < > = <= >=
strcmp stringcmp strncmp number? dbcmp
and or not cos tan
sine acos atan asine ceil
floor round exp pow fabs
random frand inf log log10
modf pi pow sqrt
Miscellaneous Primitives:
pennies addpennies location owner moveto
set flag? match rmatch part_pmatch
copyobj contents exits next setlink
setown newobject newroom newexit recycle
stats prog trig caller checkpassword
checkargs dbtop exits force getlink
mlevel next nextowned part_pmatch sysparm
version interp
Multitasking:
preempt background foreground sleep fork
queue kill mode setmode bg_mode
fg_mode pr_mode
Message-Management Primitives:
desc name succ fail drop
osucc ofail odrop setname setdesc
setfail setdrop setosucc setofail setodrop
Property-Handling Primitives:
getpropval getpropstr getpropfval getlockstr addprop
remove_prop envpropstr nextprop propdir?
Stack-Handling Primitives:
pop depth swap over rot
rotate pick put dup dupn
ldup reverse lreverse popn
String-Handling Primitives:
toupper tolower instring rinstring striplead
striptail strip unparseobj smatch strlen
strcat instr rinstr strcut explode
subst pronoun_sub fmtstring midstr split
strdecrypt strencrypt stringpfx
Time Primitives:
systime timesplit timefmt date gmtoffset
time timestamps
Type-Checking Primitives:
ok? flag? float? int? dbref?
string? number? ispid? lock? room?
program? player? room? thing? exit?
propdir?
Variable-Handling and Declaration Primitives:
var lvar public localvar variable
! @
+ - * / % ( x1 x2 -- i )
These words perform arithmetic operations on integer and floating point
numbers.
+ is addition: x1 + x2
- is subtraction: x1 - x2
* is multiplication: x1 times x2, or x1 * x2
/ is division: x1 divided by x2, or x1 / x2
% is modulo: remainter of x1 / x2, or x1 % x2
The result of an integer division is truncated of fractoins.
Modulo cannot be used on floating point values: see MODF.
All math operations may also be performed where x1 is a variable type.
This is mainly useful in calculating an offset for a variable array.
< > = <= >= ( x1 x2 -- i )
Perform relational operations on integers or dbrefs x1 and x2. These
return i as 1 if the expression is true, and i as 0 otherwise.
@ ( v -- x )
Retrieves variable v's value x. (Pronounced `fetch'.)
! ( x v -- )
Sets variable v's value to x. See also variable, var, lvar, localvar,
and miscellaneous. (Pronounced `store'.)
ABORT ( s -- )
Aborts the MUF program with an error. ie: `"Bad vibes." abort' would
stop the MUF program and tell the user a message like:
Programmer error. Please tell Revar the following message:
#1234 (line 23) ABORT: Bad vibes.
ACOS ( f -- f' )
Returns the inverse cosine of f.
ADDPENNIES ( d i -- )
d must be a player or thing object. Adds i pennies to object d. Without
Wizard permissions, addpennies may only give players pennies, limited to
between zero and MAX_PENNIES.
ADDPROP ( d s1 s2 i -- )
Sets property associated with s1 in object d. Note that if s2 is null
"", then i will be used. Otherwise, s2 is always used. All four
parameters must be on the stack; none may be omitted. If the effective
user of the program does not control the object in question and the
property begins with an underscore `_', the property cannot be changed.
The same goes for properties beginning with a dot `.' which cannot be
read without permission. If you store values, you must ensure that it
they are never zero. Otherwise, when the user stores a non-zero number
into the string field, (users may only access string fields) the next
time TinyMUCK is dumped and loaded up again, the value field will be
replaced with atoi(string field). If it is necessary to store zero, it
is safer to just add 1 to everything.
ADDRESS? (? -- i)
Returns true if the top stack item is a function address.
AND ( x y -- i )
Performs the boolean `and' operation on x and y, returning i as 1 if
both i1 and i2 are TRUE, and returning i as 0 otherwise.
ASINE ( f -- f' )
Returns the inverse cosine of f. Operates in the range of -pi/2 to pi/2.
ATAN ( f -- f' )
Returns the inverse tangent of f. Operates in the range of -pi/2 to
pi/2.
ATOI ( s -- i )
Turns string s into integer i. If s is not a string, then 0 is pushed
onto the stack.
AWAKE? ( d -- i )
Passed a players dbref, returns the number of connections they have to
the game. This will be 0 if they are not connected.
BACKGROUND ( -- )
A way to turn on multitasking. Programs in the background let the
program user go on and be able to do other things while waiting for the
program to finish. You cannot use the READ command in a background
program. Once a program is put into background mode, you cannot set it
into foreground or preempt mode. A program will remain in the background
until it finishes execution.
BEGIN ( -- )
Marks the beginning of begin-until or begin-repeat loops.
BG_MODE ( -- i )
pr_mode
fg_mode
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.
BITOR (x x -- i)
Does a mathematical bitwise or.
BITXOR (i i -- i)
Does a mathematical bitwise exclusive or.
BITAND (i i -- i)
Does a mathematical bitwise and.
BITSHIFT (i i -- i)
Shifts the first integer by the second integer's number of bit
positions. Same as the C << operator. If the second integer is
negative, its like >>.
BREAK ( -- )
Breaks out of the innermost loop. Jumps execution to the instruction
after the UNTIL or REPEAT for the current loop.
CALL ( d -- ?? )
Calls another program d. d must have been compiled already. d will
inherit the values of ME, LOC, TRIGGER, and all other variables.
CALLER ( -- d)
Returns the dbref of the program that called this one, or the dbref of
the trigger, if this wasn't called by a program.
CEIL ( f -- f )
Returns the next highest integer number as a float.
CHECKARGS (??? s -- )
Takes a string argument that contains an expression that is used to test
the arguments on the stack below the given string. If they do not match
what the expression says should be there, then it aborts the running
program with an appropriate Program Error Message. The expression is
formed from single character argument tests that refer to different
argument types. The tests are:
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.
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.
CHECKPASSWORD ( d s -- )
Returns true is the password of player d. (wizbit only)
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) See DESCRIPTORS, DESCRCON.
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.
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.
COS ( f -- f' )
Returns the cosine of f. Operates in the range of -pi/4 and pi/4.
CTOI ( s -- i )
Converts the first character in a string to its ASCII equivalent
integer.
DATE ( -- i i i )
Returns the monthday, month, and year. For example, 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. See DESCRIPTORS, CONDESCR.
DESCRFLUSH (i -- )
Flushes output text on the given descriptor. If -1 is passed as the
descriptor, it flushes output on all connections.
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. See DESCRCON, CONDESCR.
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.
DUPN ( ?n...?1 i -- ?n...?1 ?n...?1 )
Duplicates the top N stack items. See also LDUP.
ENVPROPSTR (s d -- s d )
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. See also
player?, program?, room?, thing?, ok?.
EXITS ( d -- d' )
Returns the first exit in the linked exit list of room/player/object d.
This list can be transversed with `next'.
EXP ( f -- f' )
Returns e raised to the fth power.
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.
FABS ( f -- f' )
Returns the absolute value of f.
FAIL ( d -- s )
Takes object d and returns its fail (@fail) string field.
FG_MODE ( -- i )
pr_mode
bg_mode
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.
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.
FLOAT ( i -- f )
Converts i to a floating point.
FLOAT? ( x -- i )
Returns true if x is a floating point.
FLOOR ( f -- f )
Returns the next lowest integer number as a float.
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)
FRAND ( -- f )
Returns a random number between 0 and 1.
FTOSTR ( f -- s )
Converts floating point number s to a string. s will be in the format
xxx.yyy or xxx.yyyEzz: the form which requires the fewest characters
will be returned. Use FMTSTRING to format the output. See also STRTOF.
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.
Added GETLINKS ( d -- dn..d1 n )
Returns
muf primitive, for getting info on metalinks.
Returns 0 when the obj is an unlinked exit, or if the obj is a program.
Returns 0 if the obj is a room with no dropto. Returns #-3 and a count of 1
if the dropto is linked to HOME.
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.
GETPROPSTR ( d s -- s' )
Retrieves string associated with property s on object d. The value
stored in s must be a string. If the property is cleared, "" (null
string) is returned.
GETPROPFVAL ( d s -- f )
Retrieves the floating point associated with property s on object d. The
value stored in s must be a float. If the property is cleared,
<<<?>>> 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 GMT 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 DUP) it before the if. For every IF in
a word, there MUST be a THEN, and vice-versa. ELSE is optional.
INF ( -- f )
Returns an infinite result.
INSTR ( s s1 -- i )
Returns the first occurrence of string s1 in string s, or 0 if s1 is not
found. See also RINSTR.
INSTRING ( s s1 -- i )
Returns the first occurrence of string s1 in string s, or 0 if s1 is not
found. Non-case sensitive. See also RINSTRING, INSTR, and RINSTR. 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 an int.
INTERP <<<check>>>
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. NOTE: since the
program that is running is not on the timequeue WHILE it is executing,
but only when it is swapped out letting other programs run, `pid ispid?'
will always return 0.
ITOC ( i -- s )
Converts an integer to its ASCII equivalent character. If it is not a
valid display character, a null string is returned.
JMP (a -- )
The JMP primitive takes an address like those supplied by `funcname and
moves execution to that point. It is one early way that was used to do
tail-recursion loops without as much overhead, and without failing due
to system stack overflows. It is 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
;
A better ways to do the same thing with looping primitives would be:
: countforever ( i -- )
begin
1 +
dup intostr .tell
repeat
;
KILL (i -- i)
Attempts to kill the given process number. Returns 1 if the process
existed, and 0 if it didn't. Any process can kill itself; killing other
processes equires Mucker Level 3.
LDUP ( {?} -- {?} {?} )
Duplicates a stackrange on top of the stack. See also DUPN.
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. See also GETPROP,
SETPROP,
PARSELOCK, UNPARSELOCK, PRETTYLOCK, and TESTLOCK.
LOCKED? (d d -- i)
Takes, in order, the dbref of the object to test the lock on, and the
dbref of the player to test the lock against. It tests the lock, running
programs as necessary, and returns a integer of 0 if it is not locked
against her, or 1 if it is.
LOG ( f -- f' )
Returns the natural log of f. f must be greater than zero. Very small
values will return INF.
LOG10 ( f -- f' )
Returns the log base 10 of f. f must be greater than zero. Very small
values will return INF.
LREVERSE ( ?n...?1 i -- ?1...?n i )
Reverses top N items, leaving count. See also REVERSE.
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.
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.
Also see PR_MODE.
MODF ( f -- f f )
Returns the integral and fractional parts of f, both as floating point
numbers. Ex:
1.5 MODF
would put
1.0 0.5
on the stack.
MOVETO ( d1 d2 -- )
Moves object d1 to object d2. MOVETO is affected by the following rules:
a) 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.
b) 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.
c) 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. If
the object to be moved is an exit, the program must be M3.
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.)
NEXTOWNED (d -- d)
Returns the dbref of the first object owned by player d. When called
this object's dbref, NEXTOWNED returns the next object owned by the same
player. When there are no more objects left owned by that player, then
#-1 is returned. The order of the objects is not guarenteed, but when
used correctly, each object owned by that player will be returned
exactly once. The player object itself will NOT be returned. This is
used similarly to the NEXT primitive. Ex:
me @ begin dup while dup unparseobj .tell nextowned repeat
NEXTPROP (d s -- s)
This takes a dbref and a string that is the name of a property and
returns the next property name on that dbref, or returns a null string
if that was the last. To *start* the search, give it a propdir, or a
blank string. For example,
#10 "/" NEXTPROP
or
#28 "/letters/" NEXTPROP
A blank string is the same as "/". (Requires Mucker Level 3) Nextprop
will skip properties if they would not be readable by the program with
the given permissions and effective user id.
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'. See also NOTIFY_EXCLUDE, below, and Directives,
above.
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. See also
EXIT?, PLAYER?, PROGRAM?, THING?.
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.
See also UNPARSELOCK, LOCK?, PRETTYLOCK, TESTLOCK, GETLOCKSTR, SETLOCKSTR,
and LOCKED?.
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 {&cmd} variable, and an integer
that should either be 1, for when you want {delay} messages to be sent
to the player only, and 0, when you want the rest of the players in the
room to get the omessages. NOTE: for security reasons, you cannot use
PARSEPROP on an object you don't control, if the property is not a _prop
or a ~prop. The exception to this is if the muf program is at least
Mucker Level 3. Then parsing of normal props is allowed. If the muf
program is wizbit, it can also parse @props and .props.
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.
PI ( -- f )
Returns pi.
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.
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?, OK?.
POP ( x -- )
Pops the top of the stack into oblivion.
POPN ( ?n...?1 i -- )
Pops the top N stack items.
POW ( f f' - f'' )
Returns f raised to the f'th power. If f is zero, f' must be greater
than zero. If f is less than zero, f' must be an integer value.
PR_MODE ( -- i )
fg_mode
bg_mode
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.
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.
See Multitasking, above.
PRETTYLOCK (l -- s)
Unparses a lock into a string fit for players to see. Also see 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?, 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,
%n/%N for the player's name. (Himself/Herself/Itself)
PROPDIR? (d s -- i)
Takes a dbref and a property name, and returns whether that property is
a propdir that contains other props. (Requires Mucker Level 3)
PUBLIC
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 objets 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.
(NOTE: There is a slight bug with REMOVE_PROP in versions fb5.46 and
earlier. If you use the primitive to remove a prop, and then later in
the same process try to remove a prop whose name contains that of the
earlier prop, the second property will not be removed. For example:
loc @ "banned_lock" remove_prop
loc @ "banned_lock/program" remove_prop
If these two lines were executed in this order, no error would be
issued, but property "banned_lock/program" would not be removed. If the
order of the two lines is reversed, both properties will be removed.)
REPEAT ( -- )
Jumps execution to the instruction after the BEGIN in a BEGIN-REPEAT
loop. Marks the end of the current loop.
REVERSE ( ?n...?1 i -- ?1...?n i )
Reverses the order of the top i items on the stack, returning the number
of items reversed. See also LREVERSE.
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. See also INSTRING, INSTR, and RINSTR. 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.
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.
ROUND ( f -- f' )
Returns f, rounded to the nearest whole number, as a floating point.
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. See also SETNAME, SETDESC, and FLAG?.
SETDESC SETSUCC SETFAIL SETDROP SETOSUCC SETOFAIL 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. Wizbitted
programs can SETLINK regardless of whether the exit is already linked or
who controls it.
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 BLOCK will run PREEMPT, ignoring this
mode.
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. See also SET, NAME, and
SETDESC.
SETOWN (d d -- )
Sets the ownership of the first object to the player given in the second
dbref. (wizbit only)
SINE ( f -- f' )
Returns the sine of f. Operates in the range of -pi/4 and pi/4.
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 s -- 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, separated 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:
(a) contains spaces,
(b) do not follow a wildcard, space or beginning of string,
(c) 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 separated 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 `?'.
SQRT ( f -- f' )
Returns the square root of f. f must be greater than or equal to zero.
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. (Requires 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, and returns i as 0 if they are equal.
Otherwise, STRCMP returns i as the difference between the first
non-matching character in the strings. For example, "a" "z" strcmp
returns 25. While returning 0 (false?) for a match may seem
counter-intuitive, this arrangement allows the primitive to be used for
things such as string sorting functions. Unlike STRINGCMP, STRCMP is
case sensitive. See also STRNCMP.
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.
STRINGPFX ( s s2 -- i )
Returns 1 if s2 is a prefix of s. Case insensitive. Returns 0 if s2 is
NOT a prefix of s.
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. See also stringcmp.
STRTOF ( s -- f )
Converts string s to a floating point number. s may be in the format
xxx.yyy or xxx.yyyEzz. See also FTOSTR.
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.
SYSPARM ( s -- s )
Takes a tuneable system parameter and returns its value as a string. For
an integer it returns it as a string, a time is returned as a string
containing the number of seconds, a dbref is returned in standard dbref
format, and boolean is returned as `yes' or `no' Checking an invalid
parameter or a parameter with higher permissions then the program has
will return an empty string.
Parameters available:
(str) dumpwarn_mesg - Message to warn of a coming DB dump
(str) deltawarn_mesg - Message to warn of a coming delta dump
(str) dumpdeltas_mesg - Message telling of a delta dump
(str) dumping_mesg - Message telling of a DB dump
(str) dumpdone_mesg - Message notifying a dump is done
(str) penny - A single currency
(str) pennies - Plural currency
(str) cpenny - Capitolized currency
(str) cpennies - Capitolized plural currency
(str) muckname - The name of the MUCK
(str) rwho_passwd - Password for RWHO servers (Wizbit only)
(str) rwho_server - RWHO server to connect to (Wizbit only)
(str) huh_mesg - Message for invalid commands
(str) leave_mesg - Message given when QUIT is used
(str) register_mesg - Message for a failed `create' at login
(time) rwho_interval - Interval between RWHO updates
(time) dump_interval - Interval between dumps
(time) dump_warntime - Warning prior to a dump
(time) monolithic_interval - Max time between full DB dumps
(time) clean_interval - Interval between unused object purges
(time) aging_time - When an object is considered old and unused
(int) max_object_endowment - Max value of an object
(int) object_cost - Cost to create an object
(int) exit_cost - Cost to create an exit
(int) link_cost - Cost to link an exit
(int) room_cost - Cost to dig a room
(int) lookup_cost - Cost to lookup a player name
(int) max_pennies - Max number of pennies a player can own
(int) penny_rate - Rate for finding pennies
(int) start_pennies - Starting wealth for new players
(int) kill_base_cost - Number of pennies for a 100 percent chance
(int) kill_min_cost - Minimum cost for doing a kill
(int) kill_bonus - Bonus for a successful kill
(int) command_burst_size - Maximum number of commands per burst
(int) commands_per_time - Commands per time slice after burst
(int) command_time_msec - Time slice length in milliseconds
(int) max_delta_objs - Max percent of changed objects for a delta
(int) max_loaded_objs - Max percent of the DB in memory at once
(int) max_process_limit - Total processes allowed
(int) max_plyr_processes - Processes allowed for each player
(int) max_instr_count - Max preempt mode instructions
(int) instr_slice - Max uninterrupted instructions per time slice
(int) mpi_max_commands - Max number of uninterruptable MPI commands
(int) pause_min - Pause between input and output servicing
(int) free_frames_pool - Number of program frames pre-allocated
(int) listen_mlev - Minimum Mucker level for _listen programs
(ref) player_start - The home for players without a home
(bool) use_hostnames - Do reverse domain name lookup
(bool) log_commands - The server logs commands (Wizbit only)
(bool) log_failed_commands - The server logs failed commands (Wizbit only)
(bool) log_programs - The server logs programs (Wizbit only)
(bool) dbdump_warning - Warn about coming DB dumps
(bool) deltadump_warning - Warn about coming delta dumps
(bool) periodic_program_purge - Purge unused programs from memory
(bool) support_rwho - Use RWHO server
(bool) secure_who - WHO works only in command mode
(bool) who_doing - Server support for @doing
(bool) realms_control - Support for realm wizzes
(bool) allow_listeners - Allow listeners
(bool) allow_listeners_obj - Objects can be listeners
(bool) allow_listeners_env - Listeners can be up the environment
(bool) allow_zombies - Zombie objects allowed
(bool) wiz_vehicles - Only wizzes can make vehicles
(bool) force_mlev1_name_notify - M1 programs forced to show name on notify
(bool) restrict_kill - Can only kill KILL_OK players
(bool) registration - Only wizzes can create players
(bool) teleport_to_player - Allow use of exits linked to players
(bool) secure_teleport - Check teleport permissions for personal exits
(bool) exit_darking - Players can set exits dark
(bool) thing_darking - Players can set objects dark
(bool) dark_sleepers - Sleepers are effectively dark
(bool) who_hides_dark - Dark players are hidden (Wizbit only)
(bool) compatible_priorities - Backwards compatibility for exit priorities
(bool) do_mpi_parsing - Parse MPI strings in messages
(bool) look_propqueues - Look triggers _lookq propqueue
(bool) lock_envcheck - Locks will check the environment
(bool) diskbase_propvals - Allow diskbasing of property values
SYSTIME ( -- i )
Returns the number of second from Jan 1, 1970. This is compatible with
the system timestamps and may be broken down into useful values through
`timesplit'.
TAN ( f -- f' )
Returns the tangent of f. Operates in the range of -pi/4 and pi/4.
THING? ( d -- i )
Returns i as 1 if object d is a thing, otherwise returns i as 0. See
also PLAYER?, PROGRAM?, ROOM?, EXIT?, OK?.
TESTLOCK (d l -- i)
Tests the player dbref against the given lock. If the test was
successful, then this returns a 1. If the test failed, then this
returns a 0. See also LOCK?, PARSELOCK, UNPARSELOCK, PRETTYLOCK,
GETLOCKSTR, SETLOCKSTR, and LOCKED?
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. Also see LOCK?,
PARSELOCK, PRETTYLOCK, TESTLOCK, GETLOCKSTR, SETLOCKSTR, and LOCKED?.
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 afer 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, above.
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. See also @,
VARIABLE, and LOCALVAR.
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 (return 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. See @, !, and VAR.
VERSION ( -- s)
Returns the version of this code in a string. "Muck2.2fb6.0", 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, above.
3.2.4 MUF Library Reference
The standard database and package of programs includes the following
programming libraries:
lib-strings
lib-stackrng
lib-props
lib-lmgr
lib-edit
lib-editor
lib-match
lib-mesg
lib-mesgbox
lib-reflist
lib-index
lib-look
Note: Since the libararies were written, many of the functions they
provide have been defined as MUF primitives. The libraries are retained
in their current form for compatibility with existing programs. If a
primitive providing the functionality you want is available, it will be
more efficient than a library call. For more information on using
libraries, see Section 3.2.2.
*
Functions by Library:
Lib-Strings
STRblank? STRsts STRsls STRstrip
STRsms STRsplit STRrsplit STRfillfield
STRcenter STRleft STRright instring
rinstring STRasc STRchar
Lib-Stackrng
sr-extractrng sr-copyrng sr-deleterng sr-insertrng
sr-filterrng sr-catrng sr-poprng sr-swaprng
Lib-Props
setpropstr envprop envsearch locate-prop
LIB-LMGR
LMGR-ClearElem LMGR-GetElem LMGR-PutElem LMGR-GetRange
LMGR-FullRange LMGR-GetBRange LMGR-PutRange LMGR-ClearRange
LMGR-DeleteRange LMGR-InsertRange LMGR-MoveRange LMGR-Getlist
LMGR-DeleteList LMGR-Getlist LMGR-PutBRange LMGR-ExtractRange
LMGR-GetCount LMGR-SetCount
Lib-Edit
STRright instring rinstring STRasc
STRchar EDITsearch EDITreplace EDITmove
EDITcopy EDITlist EDITleft EDITcenter
EDITright EDITindent EDITfmt_rng EDITjoin_rng
EDITshuffle EDITsort EDITjoin EDITdisplay
EDITsplit EDITformat
Lib-Editor
EDITOR EDITORloop EDITORparse EDITORheader
Lib-Match
.noisy_match .noisy_pmatch .controls .match_controlled
.multi_rmatch .table_match .std_table_match
Lib-Mesg
MSG-destroy MSG-create MSG-count MSG-info
MSG-setinfo MSG-message MSG-item MSG-setitem
MSG-insitem MSG-append MSG-delitem
Lib-Mesgbox
MBOX-badref? MBOX-ref2prop MBOX-ref2num MBOX-num2ref
MBOX-create MBOX-count MBOX-destroy MBOX-append
MBOX-insmesg MBOX-delmesg MBOX-setmesg MBOX-msginfo
MBOX-setinfo MBOX-message
Lib-Reflist
REF-add REF-delete REF-first REF-next
REF-inlist? REF-list REF-allrefs REF-filter
REF-editlist
Lib-Index
index-match index-matchrange index-envmatch index-setmatchstr
index-getmatchstr index-propname index-add index-add-sort
index-write index-set index-remove index-delete
index-value
*** lib-cases ***
Lib-Look
safecall contents-filter unparse get-contents
long-display short-list short-display list-contents
str-desc dbstr-desc db-desx cmd-look
Range Terminology: A number of library functions handle `ranges': sets
of related items adjacent to each other on the stack. The documentation
for these functions uses the following terms:
range......A set of related items on the stack, and their count.
Example: "mink" "otter" "linsang" 3
count......The number of items in a range. The count of the
range in the above example is 3.
offset.....The number of stack items between the range and the
parameters such as `offset', `position', & `number'.
That is, how `deep' the stack the specified range lies.
Example: "mink" "otter" "linsang" 3 "wolf"
The range of three items has an offset of 1.
position...The position of the first item in a subrange within
a range. The first item in a range is at position 1.
Example: "wolf" "mink" "otter" "linsang" 3
Within this range, "mink" is at position 1, "linsang"
is at position 3, and "wolf" is at position 0.
number.....The number of items within a to handle (e.g., to
copy or delete).
start......The first item in a range, farthest from the top of
the stack.
end........The last item in a range, closest to the top of the
stack.
*
LIB-STRINGS
STRblank? STRsts STRsls STRstrip
STRsms STRsplit STRrsplit STRfillfield
STRcenter STRleft STRright instring
rinstring STRasc STRchar
This library provides a number of routines for formating strings.
~
instring ( s1 s2 -- i )
Returns the position of the first occurance of s2 in s1,
case-insensitive. The same capability is provided by the INSTRING
primitive.
~
rinstring ( s1 s2 -- i )
Returns the position of the last occurance of s2 in s1,
case-insensitive. The same capability is provided by the RINSTRING
primitive.
~
STRasc ( s -- i )
Converts character s to its ASCII number equivalent. The same capability
is provided by the CTOI primitive.
~
STRblank? ( s -- i )
Returns true if s null string or only spaces.
~
STRcenter ( s i -- s )
Centers s in a field i characters wide.
"Welcome to " "muckname" sysparm 78 STRcenter .tell
...would display a welcome line including the name of the MUCK centered
for a standard screen.
~
STRasc ( i -- s )
Converts i to its ASCII character equivalent. The same capability is
provided by the ITOC primitive.
~
STRfillfield ( s1 s2 i -- s3 ]
Returns a string consisting of as many characters s2 as would be needed
to concattenate with s1 to create a string i characters long. Useful for
aligning columns of output.
me @ name " " 20 STRfillfield strcat
...would return...
"Jessy "
~
STRleft ( s i -- s )
Returns s, padded with trailing spaces to a string length of i
characters.
~
STRleft ( s i -- s )
Returns s, padded with leading spaces to a string length of i
characters.
~
STRrsplit ( s1 s2 -- s3 s4 )
Splits s1 on last occurence of delimiter string s2.
"#add here=detail=chair" "=" STRrsplit
...would put...
"#add here=detail", "chair"
...on the stack. If s1 does not include s2, s3 will be identical to s1
and s4 will be a null string. The same capability is provided by the
RSPLIT primitive. See also STRsplit.
~
STRsts ( s -- s' )
Strips leading spaces from s. The same capability is provided by the
STRIPLEAD primitive.
~
STRsls ( s -- s' )
Strip trailing spaces from s. The same capability is provided by the
STRIPTAIL primitive.
~
STRsms ( s -- s' )
Strips multiple internal spaces from s.
"It's a long way to Tipperary" STRsms
...would return...
"It's a long way to Tipperary"
~
STRstrip ( s -- s' )
Strips leading and trailing spaces from s. The same capability is
provided by the STRIP primitive.
~
STRsplit ( s1 s2 -- s3 s4 ]
Splits s1 at the first occurence of delimiter string s2.
"mink otter linsang" "otter" STRsplit
...would put...
"mink ", " linsang"
...on the stack. If s1 does not include s2, s3 will be identical to s1
and s4 will be a null string. The same capability is provided by the
SPLIT primitive. See also STRrsplit.
LIB-STACKRNG
sr-extractrng sr-copyrng sr-deleterng sr-insertrng
sr-filterrng sr-catrng sr-poprng sr-swaprng
This library provides routines for handling items within a specified
range of the stack.
~
sr-copyrng ( range ... offset number position -- range ... range2 )
Copies a subrange of `number' items out of a range in the stack,
beginning with the item at `position'. For example,
"a" "b" "c" "d" 4 0 3 2 sr-copyrng
would make take the 4-item stack "a" "b" "c" "d", and copy from it,
making a new, 3-item range, beginning with the second item in the 4-item
range.
"a" "b" "c" "d" 4 "b" "c" "d" 3
would be left on the stack.
~
sr-extractrng ( range ... offset number position -- range' ... subrange )
Extracts a subrange of `number' items from a range in the stack,
beginning with the item at `position'. The subrange is removed from the
original range, and placed on top of the stack as a new range. For
example,
"a" "b" "c" "d" 4 0 2 2 sr-extractrng
would remove 2 items from the 4-item range, beginning with the second
item, leaving
"a" "d" 2 "b" "c" 2
on the stack.
~
sr-deleterng ( range ... offset number position -- range' )
Deletes a subrange of `number' items from a range on the stack,
beginning with the item at `position'. For example,
"a" "b" "c" 3 "d" 1 2 1 sr-deleterng
would delete 2 items, beginning with the first item in the range, from
the 3-item range. The range has an offset of 1: that is, there is 1 item
("d") between the range and the parameters for sr-deleterng. This would
leave
"c" 1
on the stack.
~
sr-insertrng ( range1 ... range2 offset position -- range )
Inserts a subrange into a range on the stack, between the items at
`position' and `position + 1'.
~
sr-filterrng ( range function_address -- range' filtered_range )
Passes each item in a range to the function at function_address. If this
function returns a non-zero value, sr-filterrng removes that item from
range and puts it in filtered_range. The items in range may be of any
type. To determine the address of a function, preceed the function name
with an ` apostrophe. For example, the following code extracts the items
of type string from all items on the stack.
: StringTest
string? if 1 else 0 then
;
: PullStrings
depth `StringTest sr-filterrng
;
Calling PullStrings with
#123 "a" "b" 666 "c"
*should* leave
#123 666 2 "a" "b" "c" 3
on the stack. Unfortunately, this potentially useful function does not
work as advertised. The code above will actually leave
#123 "a" 666 3 "c" "b"
on the stack.
~
sr-catrng ( range1 range2 -- range )
Concatenates two ranges into one range.
~
sr-poprng ( range1 -- )
Removes a range from the stack. Also defined as `popn' in lib-stackrng.
The same capability is provided by the POPN primitive.
~
sr-swaprng ( range1 range2 -- i range2 range1 )
Swaps two ranges on the stack, inserting a 0-length range before the two
ranges. There must be x items on the stack below range1, where x is
equal to the larger of range1's count or range2's count. That is,
"" "a" "b" 2 "c" "d" "e" 3 sr-swaprng
would crash due to stack underflow, but
"" "null" "null" "null" "a" "b" 2 "c" "d" "e" 3 sr-swaprng
would put
"" "null" "null" "null" 0 "c" "d" "e" 3 "a "b" 2
on the stack. For this reason, it will often be necessary to copy a
`work space' range with sr-copyrng before using sr-swaprng.
LIB-PROPS
setpropstr envprop envsearch locate-prop
This library contains several useful property-handling functions.
~
setpropstr ( d s1 s2 -- )
Sets d's property s1 to the string value s2, or removes prop s1 if s2 is
a null string. Similar capability is provided by the SETPROP primitive.
~
envprop ( d s -- s' )
Searches up the environment tree from object d, looking for a property
with the name s. Envprop returns the value stored in the first occurance
of prop s found, or a null string if it wasn't found.
~
envsearch ( d s -- d' )
Searches up the environment tree from object d for an occurance of
property s. Envsearch returns the dbref of the first object the property
is found on, or #-1 if the propety is not found.
~
locate-prop ( d s -- d' )
Given a property name and dbref, locate-prop finds the property, whether
on the dbref itself, an environment of the dbref, or a proploc
<<<check>>> of the dbref. If no matching property is
found, returns #-1.
LIB-LMGR
LMGR-ClearElem LMGR-GetElem LMGR-PutElem LMGR-GetRange
LMGR-FullRange LMGR-GetBRange LMGR-PutRange LMGR-ClearRange
LMGR-DeleteRange LMGR-InsertRange LMGR-MoveRange LMGR-Getlist
LMGR-DeleteList LMGR-GetCount LMGR-SetCount LMGR-PutBRange
LMGR-ExtractRange
Lib-Lmgr is one of several libraries holding functions used by lsedit.
These functions are also useful for other programs that need to
manipulate lists without going through the list editor, or to create
their own list editors. NOTE: The documentation provided in the
program's header comment, and listed with @view, is inaccurate. The
function LMGR-CopyRange (listed in the header) does not exist, but the
following undocumented public functions do: LMGR-PutBRange,
LMGR-GetCount, and LMGR-SetCount. The public function LMGR-ExtractRange
(undocumented, but included as a _def/) does not work. Despite the
inaccuracies of documentation, the functions provided by Lib-Lmgr are
useful and efficient, and provide a number of capabilities not
duplicated by primitives.
~
LMGR-ClearElem ( i s d -- )
Clears the content of line i from list s on object d. The size of the
list (number of lines) remains unchanged.
~
LMGR-GetElem ( i s d -- )
Returns the content of line i from list s on object d.
~
LMGR-PutElem ( s1 i s2 d -- )
Stores string s1 in line i of list s2 on object d. The previous contents
of the line are over-written.
~
LMGR-FullRange ( s d -- i 1 s d )
Returns the count of lines in list s, an index value of 1, and string s
and dbref d unchanged. These are the parameters that would be needed to
put a complete list on the stack using LMGR-GetRange.
~
LMGR-GetRange ( i1 i2 s d -- range )
Puts i1 lines from list s on object d, followed by their count, on the
stack, beginning with line i2. The last line of the list will be closest
to the top of the stack. See also LMGR-GetBRange.
~
LMGR-GetBRange ( i1 i2 s d -- range )
Returns puts i1 lines from list s on object d, followed by their count,
on the stack, beginning with line i2. The first line of the list will be
closest to the top of the stack. See also LMGR-GetRange.
~
LMGR-PutRange ( sx sx' ... sx'' i1 i2 s d -- )
Stores i1 strings (range sx sx' ... sx'') in list s on object d,
beginning with line i2. The string at the bottom of the range is stored
at line i2, and the remaining strings are stored on successive lines (in
other words, strings are stored in ascending order). on The previous
contents of the lines are over-written. See also LMGR-PutBRange and
LMGR-InsertRange.
~
LMGR-PutBRange ( sx sx' ... sx'' i1 i2 s d -- )
Stores i1 strings (range sx sx' ... sx'') in list s on object d,
beginning with line i2. The string at the top of the range is stored at
line i2, and the remaining strings are stored on successive lines (in
other words, strings are stored in descending order). on The previous
contents of the lines are over-written. See also LMGR-PutRange and
LMGR-InsertRange.
~
LMGR-ClearRange ( i1 i2 s d -- )
Clears i1 lines from lis s on object d, beginning with line i2. The
number of lines in the list does not change. See also LMGR-DeleteRange
~
LMGR-DeleteRange ( i1 i2 s d -- )
Deletes i1 lines from list s on object d, beginning with line i2. Lines
in the orginal list positioned after line i2 are shifted to earlier
positions. See also LMGR-ClearRange.
~
LMGR-InsertRange ( sx sx' ... sx'' i1 i2 s d -- )
Inserts i1 strings (range sx sx' ... sx'') in list s on object d,
beginning with line i1. Lines in the original list positioned after i2
are shifted to later positions. See also LMGR-PutRange
~
LMGR-MoveRange ( i1 i2 i3 s d -- )
Moves the contents of the i2 lines of list s on object d, beginning at
line i3, to the lines beginning at line i1. The contents of lines i1 to
i1+i2 are over-written.
~
LMGR-DeleteList ( s d -- )
Deletes list s from object d.
~
LMGR-Getlist ( s1 d -- s s' ... s'' i )
Puts the contents of list s1 on object d and the total number of lines
on the stack.
~
LMGR-GetCount ( s d -- i )
Returns the count of lines in list s on object d.
~
LMGR-SetCount ( i s d -- )
Sets the count of lines for list s on object d to i.
LIB-EDIT
STRright instring rinstring STRasc
STRchar EDITsearch EDITreplace EDITmove
EDITcopy EDITlist EDITleft EDITcenter
EDITright EDITindent EDITfmt_rng EDITjoin_rng
EDITshuffle EDITsort EDITjoin EDITdisplay
EDITsplit EDITformat
This library includes string-editing routines, with capabilities for
handling ranges of strings such as would be present by reading a list or
range from a list onto the stack.
EDITsearch ( range ... offset s position -- range ... i2 ]
Perfroms a case-sensitive search of the strings in `range' for an
occurance of string s. The search begins with the item at `position'. i2
is the position of the first item that includes an occurance of string
s.
~
EDITreplace ( range ... offset s1 s2 position1 position2 -- range' )
Performs a case-sensitive seach of the range items from position1 to
position1, inclusive, for all occurances of string s1, replacing each
with string s2.
~
EDITmove [ {rng} ... offset dest start end -- {rng'} ... ]
Moves text within a string range from one line to another location,
deleting the original. <<<check>>>
~
EDITcopy [ {rng} ... offset dest start end -- {rng'} ... ]
Copies text within a string range from one line to another, inserting it
in the new location.
~
EDITlist ( range ... offset i1 i2 i3 -- range )
Prints the strings i2 to i3 from range to the user's screen. If i1 is
true, the lines will be prepended with line numbers. See also
EDITdisplay.
~
EDITleft ( range ... offset position1 position2 -- range' )
Left justifies all strings between `position1' and `position2'. That is,
leading spaces are stripped from these strings.
~
EDITcenter ( range ... offset i1 i2 i3 -- range' )
Center justifies all strings between `position1' and `position2' for a
screen i1 characters wide. That is, the strings are padded to a length
of i1 characters with leading and trailing spaces.
~
EDITright ( range ... offset i position1 position2 -- range' )
Right justifies all strings between `position1' and `position2' for a
screen width of i characters. That is, these strings are padded with
trailing spaces to a string length of i characters.
EDITindent ( range ... offset i position1 position2 -- range' )
Indents all strings between `position1' and `position2' by i spaces. That is, the strings are padded with i space characters. If i is a negative number, it reduces indentation by i characters, but will not unindent past the left margin.
~
EDITfmt_rng ( range ... offset i position1 position2 -- range' )
Formats the strings of the range between `position1' and `position2' to
strings i characters wide, splitting long strings and joining short
strings. A string that consists only of spaces is considered a paragraph
delimiter and is not joined. i must be equal to or greater then 20. The
string at `position1' must 2 or more characters long. See also
EDITformat.
~
EDITjoin_rng ( range ... offset position1 position2 -- range' )
Joins the lines of the subrange between `position1' and `position2' into
a single string, returning the string range that results. Leading and
trailing spaces are stripped from the strings to be joined, and a single
space is inserted in the combined string at points where strings were
joined. See also EDITjoin.
~
EDITshuffle ( range -- range' )
Randomizes the order items in a range.
~
EDITsort ( range i1 i2 -- range' )
Alphabetically sorts range. If i1 is true, the sort will be in
descending order: "aardvark" would be near the top of the stack and
"zebra" would be near the bottom. If i2 is true, the sort will be
case-sensitive: "Leviathon" would be come before "lapidary", since "L"
and "l" are two different characters in a case-sensitive comparison,
with "L" preceeding "l".
~
EDITjoin ( range -- s )
Joins a range of strings on the stack into one string.
~
EDITdisplay ( range -- )
Displays the range of strings on the stack to the user. See also EDITlist.
~
EDITsplit ( s c i1 i2 -- range )
Splits string s on the last split character c found between right margin
i1 and wrap margin i2. If no split character is found in this range, the
string is split at right margin i1.
~
EDITformat ( range ... c i1 i2 -- range' )
Formats the strings in `range' to strings between right margin i1 and
wrap margin i2 in length. Short strings are joined to fill this field
width; long strings are split at the last occurance of split character c
found between i1 and i2. See aslo EDITfmt_rng.
LIB-EDITOR
EDITOR EDITORloop EDITORparse EDITORheader
A set of functions providing an interface with the list editor. Note:
this library is in the public domain, but its terms of use state that
the author of the library, Foxen, must be credited in the header comment
of any program that makes use of it.
~
EDITOR ( range -- range' s )
Puts the user in the list editor, using range as the values for the
list. The list can be interactively edited as with command lsedit. Exits
with the modified range and the editor's exit string (`end' or `abort')
on the stack. See also EDITORloop.
~
EDITORloop ( range s1 i1 -- range' s1 i2 s2 i3 i4 s3 )
Puts the user in the list editor, using range as the values for the
lines of the list. The list can be interactively edited as with command
lsedit. The EDITOR function provides similar functionality; EDITORloop
gives greater control over data passed to and from the editor.
EDITORloop takes a range, a space-separated string s1 containing any
commands that can be used to return from the editor in addition to `end'
and `abort', cursor position i1, and the first editor command to be
executed.
EDITORloop returns the modified range, the string s1, the cursor postion
at time-of-exit, exit arguments s2, i3, and i4, and the command string
used to exit the editor on the stack. Exit arguments are parameters
returned to the program when EDITORloop exits. They follow the syntax of
other editor commands: `command start_line end_line = argument_string'.
start_line is i3. end_line is i4. argument_string is s2.
Example: Suppose you create a program that allows players included in a
list holding their dbrefs to update documents in a news reader program.
The program includes and #admin function that puts the user into the
editor to modify this list. You want to include, in your version of the
editor, a command that shows the names of the players who are currently
in the list, optionally followed by information such as the last time
they logged on or their position/title in the MUCK news staff. The user
could then display the names (and other information) for players whose
dbrefs are in the list, or a range from the list, by entering `.names'
or `.names <range>' or `.names [<range>] = <field>'.
You could do this by reading the list onto the stack and supplying
`names' as a command string that would cause EDITORloop to return, with
code such as the following:
"_staff" trig LMGR-Getlist (*read list onto stack as a range*)
"names" over 1 + ".i" EDITORloop (*put user in editor, ready to insert
text, at the next free line, with
`names' defined as a .command that
will cause EDITORloop to return*)
If the user typed `.names' while at line 6 of a 12-line list of dbrefs,
the following would be put on the stack:
... #123, 12, "names", 6, "", 0, 0, "names"
Using comparison primitives such as SMATCH or STRINGCMP, you could check
the top value on the stack and, if it is the string "names" (as it is
here), execute a ShowNames function in your program, then return to the
editor with another instance of EDITORloop.
If the user had typed `.names 1 8', the following would be put on the
stack:
... #123, 12, "names", 6, "", 1, 8, "names"
Your ShowNames function would need to use the values `1' and `8' to show
only names for the dbrefs in lines 1 - 8.
If the user had typed `.names 1 - 8 = title', the following would be put
on the stack:
... #123, 12, "names", 6, "title", 1, 8, "names"
ShowNames would use this information to show the names of players listed
in lines 1 - 8 of the list, concattenated with their title... perhaps a
value stored in their _news/title property. See also EDITOR.
~
EDITORparse ( range s1 i1 s2 -- range' s1 i1 i2 )
Parses range with the editor command s2, returning the modified range,
the original paramaters s1 and i1, and the last line handled as i2.
Example:
"mink" "otter" "linsang" 3
"quit" 1 ".indent 1 3 = 5" EDITORparse
This would enter and exit the editor, indenting each string in the range
by 5 spaces, with the last line handled on top of the stack as i2. The
standard editor output would be shown to the user:
< Indented 3 lines starting at line 1, 5 columns. >
~
EDITORheader ( -- )
Prints the standard header informing the user that he is entering the
list editor and giving succinct help. Called automatically be EDITOR.
< Entering editor. Type `.h' on a line by itself for help. >
< `.end' will exit the editor. `.abort' aborts the edit. >
< Poses and says will pose and say as usual. To start a >
< line with : or " just preceed it with a period (`.') >
LIB-MATCH
.noisy_match .noisy_pmatch .controls .match_controlled
.multi_rmatch .table_match .std_table_match
A library of matching functions.
~
.noisy_match ( s -- d )
Checks the room, objects in the room, the player, objects carried by the
player, and exits that the player may use for objects whose name matches
s, returning the dbref. Partial name strings will work, provided that
enough characters are specified to distinguish the object from other
similarly named objects. The function is `noisy' in that it supplies
explanatory messages for negative or ambiguous results. If no matching
object is found, #-1 will be returned, and the string "I don't see that
here!" will be printed to the user's screen. If the match is ambiguous,
#-2 will be returned, and the string "I don't know which one you mean!"
will be printed.
~
.noisy_pmatch ( s -- d )
Returns the dbref of the player with name s. The player need not be in
the vacinity of the user, but the name must be supplied completely (not
case-sensitive). The function is `noisy' in that it supplies explanatory
messages for negative or ambiguous results. If no matching player is
found, #-1 will be returned, and the string "I don't recognize anyone by
that name." will be printed to the user's screen.
~
.controls ( d1 d2 -- i )
Returns true if player d1 controls object d2. The same capability is
provided by the CONTROLS primitive.
~
.match_controlled ( s -- d )
Searches the vacinity for objects with names matching s, like
.noisy_match and with similar messages for negative or ambiguous
results, but returns #-1 and prints "Permission denied." if the user
does not control the found object.
~
.multi_rmatch ( d s -- d' ... d'' i )
Returns all objects contained by object d whose name matches string s,
with the total number of successful matches. The search string can
include wildcard and grouping operators such as those used by the SMATCH
primitive. See also SMATCH.
~
.table_match ( x1 x2 cn pn ... c1 p1 i x3 address -- cx px )
This function tests successive pairs of `comparator' and `data' elements
with a separate function (that you create), returning the pair that
(according to your function's criteria) `matches'. Although .table_match
is supplied as a matching function, it can have other applications: the
comparator/data pairs in effect constitute a hash table, and the
`matching' function can perform whatever operations you require.
.Table_match takes parameters x1 -- the item to be returned if no match
is found -- and x2 -- the item to be returned if more than one pair
matches. x1 and x2 can be of any type. Example: #-1 and #-2 are the
conventional items used to indicate negative or ambiguous match results
for objects of type dbref. These parameters are followed by
comparator/data pairs: the comparator is the item to be tested for a
match; the data item is a stack item associated with the comparator. An
integer specifying the number of such pairs to be tested is then
supplied, followed by the value x3 -- which will be used to test the
match -- and the address of the testing function. The testing function
should return 1 for true results and 0 for false results. .Table_match
returns the comparator/data pair that matches (cx px), or the paramters
for negative or ambiguous results (x1 or x2)
Example: Suppose you want a function supplementing .pmatch and
.noisy_pmatch that can find players by `nicknames', which are often set
as a player's %n property. One way (among many possibilities) to create
such a function would be to supply comparator/data pairs of players' %n
properties and their dbrefs, and calling .table_match. The nickname to
be matched is stored in lvar ourString. Function GetPairs puts the
prop/dbref pairs and their count on the stack. Function CheckNick
performs a SMATCH, returning 1 if a comparator matches ourString, and 0
if it does not. Code for calling .table_match might then look like this:
#-1 #-2 GetPairs ourString @ `CheckNick .table_match
If a player calls the program with a search for "Dr. Cat", and GetPairs
returns three players who have %n nicknames (and thus are candidates for
possible matches) the stack created by this code might have values such
as the following immediately before .table_match is called:
#-1, #-2, "the Scamper Gal", #2, "the terribly velvet-furred linsang",
#13, "Dr. Cat" #244, "Dr. Cat", `CheckNick
#-1 and #-2 are the codes .table_match is to return for negative and
ambiguous matches. The next six items on the stack are three
comparator/data pairs: The dbrefs of players #2, #13, and #244, paired
with their nicknames. The next item (the second occurance of string "Dr.
Cat") is the string to be matched, which was fetched from lvar
ourString. `CheckNick -- a function name preceded by an ` apostrophe --
is a pointer to the address for the CheckNick function.
In this case, the results are not negative or ambiguous: one of the
players does have the nickname to be matched: player #244 is Dr. Cat.
.Table_match would clear all the above data from the stack, and
return...
"Dr. Cat", #244
See also .std_table_match.
~
.std_table_match ( x1 x2 sn pn ... s1 p2 i sm -- sx px | x1 | x2 )
The standard table match takes i comparator/data pairs in the same
manner as .table_match, and performs a SMATCH on each comparator,
matching against string sm. Comparators must be strings; it is not
necessary to supply a matching functin and its address. .Std_table_match
returns the comparator/data pair that matchs sm, or x1 if no match was
found, or x2 if more than one match was found. See also .table_match and
SMATCH.
LIB-MESG
MSG-destroy MSG-create MSG-count MSG-info
MSG-setinfo MSG-message MSG-item MSG-setitem
MSG-insitem MSG-append MSG-delitem
This library provides functions for handling `messages'. A message is a
set of associated list properties consisting of a `base' (the list
name), one or more `items' (lines in the list), `item strings' (the
strings stored in the list, usually holding players' dbrefs or names),
and an `information' string (the content of the message). Some Lib-Mesg
functions handle `string ranges': sets of strings adjacent on the stack,
followed by their count. Multiple, related messages are stored in a
propdir that constitutes a `message box'. Example:
str /msgs/1#/1:2
str /msgs/1#/2:3
str /msgs/1#/3:13
str /msgs/1#/i:This is the content of a message for players
with dbrefs #2, #3, and #13.
This message has three items (1, 2, and 3) holding the item strings "2",
"3", and "13" respecitively. Its base is `msgs/1'. Its information
string is "This is the content of a message for players with dbrefs #2,
#3, and #13." The message is stored in message box `msgs'.
~
MSG-create ( range s1 s2 d -- )
Creates a new message with the items in a stringe range and the
information string s1, stored as list properties with base s2 on object
d.
Example: The following code reads list `_staff' from the trigger action
onto the stack as a range, and creates a message with the contents of
lvar ourString for each staff member.
"_staff" trig LMGR-Getlist (*read list onto stack as range*)
ourString @ (*put message on stack *)
"st-msgs/" dup trig LMGR-Getcount (*get next available line number*)
1 + intostr strcat (*use count to create message base*)
trig MSG-create (*create message, stored on trig*)
(*note: this same effect could be
achieved more efficiently with
MSG-append or MBOX-append*)
Assume that a staff memeber uses the `stnews' command (#555) with the
message "Please check `+read 17'"; that list `_staff' contains 5 lines,
each holding a staff member's dbref in string form (2, 3, 13, 99, and
244); and that there are currently two other staff messages. In this
case, the code would put the following values on the stack:
"2", "3", "13", "99", "244", 5, "Please check `+read 17'",
"st-msgs/3", #555
Then, MSG-create would be called, creating propdir `st-msgs/3#/', which
other functions could use to relay the message to staff members online,
at log-in, or when they check staff news. `Ex #555 = st-news/3#/' would
show the following values:
str /st-msgs/3#/1:2
str /st-msgs/3#/2:3
str /st-msgs/3#/3:13
str /st-msgs/3#/4:99
str /st-msgs/3#/5:244
str /st-msgs/3#/i:Please check `news staff'
The data passed to MSG-create would be cleared from the stack.
~
MSG-destroy ( s d -- )
Clears and removes the message with base s from object d.
~
MSG-count ( s d -- i )
Returns the number of items in message with base s on object d.
~
MSG-info ( s d -- s2 )
Returns the information string for the message with base s on object d.
~
MSG-setinfo ( s1 s2 d -- )
Sets the s1 as the information string for message with base s2 on object
d.
~
MSG-message ( s d -- range )
Reads the items for the message with base s on object d onto the stack
as a string range.
~
MSG-item ( i s d -- s2 )
Returns item number i from message with base s on object d.
~
MSG-setitem ( s1 i s2 d -- )
Sets the value of item i in message s2 on object do the the string value
s1.
~
MSG-insitem ( s1 i s2 d -- )
Inserts a new message item with string value s1 at position i into the
message with base s2 on object d.
~
MSG-append ( s1 s2 d -- )
Appends message item s1 to the message with base s2 on object d.
~
MSG-delitem ( i s d -- )
Deletes message item i from the message with base s on object d.
LIB-MESGBOX
MBOX-badref? MBOX-ref2prop MBOX-ref2num MBOX-num2ref
MBOX-create MBOX-count MBOX-destroy MBOX-append
MBOX-insmesg MBOX-delmesg MBOX-setmesg MBOX-msginfo
MBOX-setinfo MBOX-message
~
MBOX-badref? ( i s d -- i' )
Returns true if message item i in the message with base s on object d
does not exits.
~
MBOX-ref2prop ( i s d -- s' d )
Returns the propterty name of message number i in the message box with
base s on object d. Note: The first message created for a box, number 1,
is stored in property <base>#/0 (example: "1" "+news" trig
MBOX-ref2prop would return "+news/0#" #123). This is also the the data
that will be returned if message i does not exist. Code that uses
MBOX-ref2prop should include error checking to deal with this
contingency. See also MBOX-ref2num and MBOX-num2ref.
~
MBOX-ref2num ( i s d -- i' )
Returns the absolute message number (the number assigned when the
message was created) for the message with base s on object d with
reference number i (the reference number of a message is its current
position in the message list). Note: the first message created has
absolute message number 0. This is also the value that will be returned
if no message at postion i exits. Code that uses MBOX-ref2num should
include error checking to deal with this contingency. See also
MBOX-num2ref and MBOX-ref2prop.
~
MBOX-num2ref ( i s d -- i' )
Returns the reference number (the current position in the message list)
for the message with base s on object d that has the absolute number i
(the number assigned when the message was created). If no such message
exits, 0 is returned. See also MBOX-ref2num and MBOX-ref2prop.
~
MBOX-create ( s d -- )
Creates a new message box with base s on object d with no messages in
it. This consists of a property `<base>#/i' with the string 0
stored in it.
~
MBOX-count ( s d -- i )
Returns the number of messages contained in message box is on object d.
~
MBOX-destroy ( s d -- )
Destroys message box s on object d and all of its contents.
~
MBOX-append ( range s1 s2 d -- i )
Creates a new message with base s2 on object d, with items `range', on
object d, appending it to existing messages in the box. The
newly-created message's number is returned.
~
MBOX-insmesg ( range s1 i1 s2 d -- i2 )
Creates a new message with the given message items and info string and
inserts it before the given message number in the message box. Returns
the message's number.
MBOX-delmesg [refnum base dbref -- ]
Delete the given message number in the message box. It moves the
rest of the messages after it up in the message box.
MBOX-setmesg [{strrange} infostr refnum base dbref -- ]
Sets the given message number in the given message box to contain the
given message items and info string.
MBOX-msginfo [refnum base dbref -- infostr]
Returns the info string of the goven message number in the message box.
MBOX-setinfo [refnum base dbref -- ]
Sets the info string for the given message number in the message box.
MBOX-message [refnum base dbref -- {strrange}]
Returns the contents of the given message number in the message box
as a range of strings.
LIB-REFLIST
REF-add REF-delete REF-first REF-next
REF-inlist? REF-list REF-allrefs REF-filter
REF-editlist
A `reflist' is string, stored in a property, containing space- and #
octothorpe-delimited dbrefs, such as "#2 #3 #13 #3175 #244". A reflist
will contain only one instance of any one dbref. Like all strings stored
in properties, a reflist is limited to 4096 characters (about 500
dbrefs).
~
REF-add ( d1 s d2 -- )
Adds dbref d2 to reflist s on object d1. If d1 is already a member of
the list, it is moved to the final position in the list. REF-add does
not check to ensure that d1 is a valid dbref.
~
REF-delete ( d1 s d2 -- )
Removes dbref d2 from reflist s on object d1.
~
REF-first ( d s -- d' )
Returns the first dbref in reflist s on object d.
~
REF-next ( d1 s d2 -- )
Returns the next dbref after d2 from reflist s on object d1. If there
are no dbrefs after d1, #-1 is returned.
~
REF-inlist? ( d1 s d2 -- i )
Returns true (1) if dbref d2 is a member of reflist s on object d1, or
false (0) if it is not.
~
REF-list ( d s -- s' )
Returns a string containing a comma-separated list of the names of all
objects with dbrefs in reflist s on object d.
~
REF-allrefs ( d s -- d' ... d'' i )
Returns the contents of reflist s on object d as a range of dbrefs
~
REF-filter ( a d s -- d' ... d'' i )
Tests each dbref in reflist s on object d in the filter function at
address a, returning the those for which the function returns true as a
range of dbrefs. The filter function (supplied by your code) should
return 1 for true or 0 for false.
Example: the following code tests the dbrefs in reflist `_members',
stored on the trigger action, filtering out garbage dbrefs and returning
the others as a range.
: CheckRefs
ok? if 1 else 0 then
;
: GetMembers
`CheckRefs
trig "_members"
REF-Filter
;
In function GetMembers, `CheckRefs (a function named joined with an
apostrophe) puts a pointer to the CheckRefs function on the stack. The
next line reads the reflist onto the stack. REF-Filter then tests each
dbref in the list, using the test provided in CheckRefs: those dbrefs
which are currently valid will be returned as a range.
~
REF-editlist ( i d s -- )
Puts the user in an interactive editor that allows dbrefs to be added
and removed from reflist s on object d. If i is true, only player dbrefs
may be added. If i is false, objects of any type may be entered. In
either case, the editor rejects invalid dbrefs. The reflist must exists,
and all dbrefs contained in it must be valid. REF-editlist displays the
following header when the user enters the editor:
To add an object, enter its name or dbref. To remove an object,
enter its name or dbref with a ! in front of it. ie: `!button'.
To display the list, enter `*' on a line by itself. To clear the
list, enter'#clear'. To finish editing and exit, enter `.' on a
line by itself.Enter `#help' to see these instructions again.
LIB-INDEX
index-match index-matchrange index-envmatch index-add
index-add-sort index-write index-set index-remove
index-delete index-value index-first index-last
index-next index-prev
This library provides a set of routines for handling `indexes': an index
is a set of name/value pairs. The index as a whole is stored as a set of
associated properties, in a single propdir, consisting of a list of all
elements (stored as a single string) and a property for each `name',
which holds a `value' associated with the name.
Most routines are also available in `std-' form (the routine name is
prefaced with `std-', such as .index-add to .std-index-add). Routines
which store information (add members to the index) have the following
stack effect:
( d s1 s2 s3 -- d s1 s2 s3 i )
where d is the object the index is stored on, s1 is the name of the
index, s2 is the `name' value, and s3 is the `value' value. All four
items are left on the stack unchanged, and an integer error code is
returned: 1 for `no error: item successfully added', and 0 for `error:
s2 is already a member of the index; index unchanged'.
Routines that retrieve information (perform matches) have the following
stack effect:
( d s1 s2 s3 -- d s1 s2' s4 i )
where d is the object the index is stored on, s1 is the name of the
index, s2 is the name to be matched, and s3 is a string holding 1 - 3
characters specifying matching criteria:
x: exact match only, ignores the index itself
e: exit-style match: exact match of ;-separated value, and select the
first match found if there are more than one
w: normal operation: match the beginning of a space separated word,
and fail if more than one matched. So, `mat' matches `mattress'
and `lit match', but not `rematch'.
Arguments d and s1 are left on the stack unchanged. The name to be
matched is, if found, returned as s2'. If the match was unsuccessful,
s2' will be a null string. If s2 were a partial match, s2' would be
returned as the full name. The match criteria paramters, s3, are
returned as null string s4. Finally, an error code is returned (1 is no
error, match successful; 0 is error, match unsuccessful).
The default matching criteria (employed with routines called *without*
the `std-' prefix) is `xew': all three criteria are used, and the first
match made by any of the criteria will be returned.
NOTE: There are two versions of this library in circulation. Currently,
basedb.db and fbmuf provide the older version. The second version --
which may or may not be available on your MUCK -- provides the
additional public routines index-setmatchstr, index-getmatchstr, and
index-propname. Use `@view $lib/index' to determine which version you
have. The standard version is discussed here. Also, the standard version
as implemented by basedb.db and the upload script in fbmuf only set
_def/ props in the .period-prefix form: routine names must be joined
with a leading period in your code, unless the wizards on your MUCK have
added the no-period form. Example: to use the routine `index-add', put
`.index-add' in your code. (The newer version may or may not require the
.format).
~
index-match ( d s1 s2 -- s2' i )
Returns name s2 from index s1 on object d and error code 1 (no error) if
s2 is a member of index s1. If s2 is not a member of s1, index-match
returns a null string and error code 0 (error: no match). If index s1
was created with index-add, or with index-setmatchstr with the `w' name
parameter, index-match will return the first match found. That is, there
is no check for ambiguity. If the index was created with index with
index-setmatchstr without the `w' parameter, only complete, explicit
matches will be returned, in which case ambiguity is impossible.
std-index-match ( d s1 s2 s3 -- d s1 s2' s4 i )
Performs a name match like index-match, using the match criteria
specified in parameter string s3. Arguments d and s1 are left on the
stack; parameter string s3 is returned as null string s4.
~
index-matchrange ( d s1 s2 -- string_range )
Performs a partial-word match search on all members of index s1 on
object d, returning those which match true as a string range. Ignores
match-type parameters: any full or partial matches will be returned. Not
available in `std-' form.
~
index-envmatch ( d s1 s2 -- s3 i )
[ dbref index name -- name' error ]
Returns name s2 from index s1 on object d and an error code (1 if no
error; 0 if no match). If no match is found on d, continues searching up
the environment tree, checking indexes called s2 on these objects as
well. If index s1 is was created with index-add, or with
index-setmatchstr with the `w' name parameter, index-envmatch will
return the first match found. That is, there is no check for ambiguity.
std-index-envmatch ( d s1 s2 s3 -- d s1 s2' s4 i )
Performs an environment match like index-envmatch, using the match
criteria specified in paramater string s3. Arguments d and s1 are left
on the stack; parameter string s3 is returned as null string s4.
~
index-add ( d s1 s2 s3 -- i )
Adds name s2, associated with value s3, to index s1 on object d. Returns
error code i. If s2 is already a member of the index (matching exactly),
index-add returns error code 0, and no changes are made to the index.
Otherwise, the name and value are added to the index and error code 1 is
returned (operation successful). A `std-' form is defined in the
library,
std-index-add ( d s1 s2 s3 -- d s1 s2 s3 i )
Like index-add, this routine adds name s2 and value s3 to index s1,
stored on object d. All four items are left on the stack unchanged, and
error code i is returned: 1 is `no error: item added', 0 is `error: name
already a member of index; index unchanged'.
~
index-add-sort ( d s1 s2 s3 -- i )
Like index-add, index-add-sort adds name s2 and value s3 to index s1,
stored on object d. index-add always adds a name to the end of the
index; index-add-sort, by contrast, inserts the new name in alphabetical
order, immediately before the element it would precede alphabetically.
If names are always added to the index with this routine, the index will
remain in alphabetical order. Returns error code i: 1 is `no error: item
added', 0 is `error: name already a member of index; index unchanged'.
~
std-index-add-sort ( d s1 s2 s3 -- d s1 s2 s3 i )
Alphabetically adds a name/value pair to an index, like index-add-sort,
but leaves all four items on the stack, returning error code i: 1 is `no
error: item added', 0 is `error: name already a member of index; index
unchanged'.
~
index-write ( d s1 s2 s3 -- i )
In index s1 on object d, sets the value of existing index member with
name s2 to value s3. Returns error code i: 1 is `no error: value
changed', 0 is `error: name not a member of this index; index
unchanged'.
std-index-write ( d s1 s2 s3 -- d s1 s2 s3 i )
Sets a value for an existing index member, like index-write, but leaves
all four items on the stack and returns an error code.
~
index-set ( d s1 s2 s3 -- )
Adds name s2, associated with value s3, to index s1 on object d. Unlike
index-add and index-write, this routine does not check for and return
errors: if the name is not presently a member of the index, it will be
added; if the name is already a member, its value will be edited.
std-index-set ( d s1 s2 s3 -- d s1 s2 s3 )
Adds a name/value pair to an index, with no error checking, like
index-set. All four items are left on the stack unchanged.
~
index-delete ( d s1 s2 -- )
Removes name s2, and its associated value, from index s1 on object d,
with no error checking.
std-index-delete ( d s1 s2 -- d s1 s2 )
Removes name s2, and its associated value, from index s1 on object d,
with no error checking. All three items are left on the stack unchanged.
~
index-value ( d s1 s2 -- s3 )
Returns the value associated with name s2 in index s1 on object d. If
the index does not include name s1, s3 will be a null string.
std-index-value ( d s1 s2 s3 -- d s1 s2' s4 )
Performs a match for name s2 in index s1 on object d, using matching
criteria specified in parameter string s3. The dbref and index name are
left on the stack unchanged. Name s2 is returned in complete form
(partial matches are expanded). Returns the value associated with name
s3 as string s4. If the match was unsuccessful, s4 will be a null
string.
Lib-Look
safecall contents-filter unparse get-contents
long-display short-list short-display list-contents
str-desc dbstr-desc db-desx cmd-look
A set of routines adapted to `look' functions. NOTE: the standard
version of lib-look as implemented by basedb.db and the upload script in
fbmuf only set _def/ props in the .period-prefix form: routine names
must be joined with a leading period in your code, unless the wizards on
your MUCK have added the no-period form. Example: to use the routine
`safecall', put `.safecall' in your code.
~
safecall ( x d -- )
Calls program d, passing x (usually a string) as an argument. This
routine ensures no garbage is left on the stack by the program called,
and that the variables `me', `loc', `trigger', or `command' are
unchanged: even if they are modified by program d, they will have their
original values after the program call.
~
unparse ( d -- s )
Returns the name of object d, concattenated with its dbref and flags
(such as "Bulletin Board(#177S)") if the user controls object d. If the
user does not control d, or if the user is set Silent, only its name is
returned ("Bulletin Board").
~
contents-filter ( a d -- d' ... d'' i )
Takes the address of a `filter' function and a dbref, and returns the
objects from d's contents for which the filter function returns true (1)
as a range on the stack. The first item found (the `top' of a Contents
or Carrying list) will be at the start of the range. Example:
: PlayerCheck ( d -- i )
player? if 1 else 0 then
;
: GetPlayers ( -- d' ... d'' i )
`PlayerCheck me @ location contents-filter
;
This code puts all the players in the room on the stack as a range of
dbrefs, filtering out objects of other types. `PlayerCheck (a function
name joined with an ` apostrophe) puts the address of the the filter
function PlayerCheck function on the stack.
~
get-contents ( d -- d' ... d'' i )
Passes the contents of object d through a standard filter that emulates
a server contents list: dark rooms do not have contents lists, unless
you control the objects or the room; dark objects you don't control do
not show, unless you control them; you do not show. Those objects which
would show in a Contents/Carrying list by these criteria are returned as
a range of dbrefs. The first contained object (the `top' of a Contents
or Carrying list) is at the start of the range.
~
long-display ( d' ... d'' i -- )
Prints the string form of a range of dbrefs to the user's screen, using
unparse to determine the strings' format. The start of the range is
printed first. Example:
me @ location get-contents long-display
This code duplicates the `Contents' portion of a server look in a room
(note: the same effect could be achieved with a single library call to
`list-contents').
~
short-list ( d' ... d'' i -- s )
Returns a range of dbrefs as a space- and comma-separated string,
punctuated and formatted intellegently. For example, the contents of a
room might be returned as
"Kenya, Passiflora, PowerMac 7100, and Sign"
~
short-display ( d' ... d'' i -- )
Calls short-list for the range of dbrefs on the stack, then prints "You
see <contents string>" to the user. NOTE: Contrary to
documentation provided with @view, short-display will crash if not
passed a range of valid dbrefs containing at least one member.
~
list-contents ( s d -- )
Calls get-contents followed by long-display to print out all of the
contents of the given dbref. If there are any contents listed, then the
string on the stack is printed out, for "Contents:" or the like. If the
contents list is empty, the string is ignored. The triggering player's
name is omitted from the contents list of a room (that is, you don't see
yourself listed).
~
str-desc ( s -- )
Prints s as a description, matching the `@###' and `@$prog' values
properly, and uses them with the present trigger value. If neither of
these exist, or if they are invalid, the string is simply printed. The
string is not parsed for MPI.
~
dbstr-desc ( d s -- )
Prints s as a description, like str-desc, using d as the effective
trigger value. The string is not parsed for MPI.
~
db-desc ( d -- )
Prints a description of, including the name and triggering succ and fail
if d is a room. The desc is not parsed for MPI. Programs run with d
stored in the variable `trigger'.
~
cmd-look ( s -- )
Does a match function, then calls db-desc with the results, simulating
the server `look' command.
*****************************************************************************
4.0 TUTORIALS
This section provides tutorials on how to use the commands and programs discussed throughout the MUCK Manual to perform common tasks and projects. Note: in many cases, there is more than one way to accomplish the goal.
4.1 Using the List Editor
4.2 Making a Multi-Action
Over time, many players end up creating several handy little macro
commands that provide shortcuts for frequent tasks, or create rooms that
have a number of specific, local commands. Rather than creating a
separate action for each command (an approach that quickly leads to
dbase bloat and eats up your quota), you can combine a number of
commands in a single action. The basic technique is to give the action
an alias name for each command, store MPI strings in properties with the
same names as the aliases, and use the command name typed by the user to
determine which property should be executed.
The following example creates a multi-action that lets you determine the
dbref of something in the same room, enter or review a page of `to do'
notes, and remotely lock or unlock the door into your home. First,
create the action attached to your character, and lock it to a condition
that always fails.
====================================
> @act ref;note;notes;lockhome;unlockhome = me
Action created with number 9456 and attached.
> @lock ref = me&!me
Locked.
====================================
The lock will fail unless the user *is* and *is not* you... it will
always fail. Now, set the action's @fail with an MPI string that will
cause other MPI strings stored in properties on the object to be
executed.
====================================
> @fail ref = {exec:{&cmd}}
Message set.
====================================
{&cmd} is a variable... it holds whatever command name the user typed.
If you used the action by typing `ref', then the string `ref' would be
substituted for {&cmd} when the @fail is parsed; if you used the the
action by typing `notes', then `notes' would be substituted for {&cmd}.
{exec} evaluates the property following it, executing any MPI contained
in it, and returning any resulting strings to the user. So, typing
`notes' would cause the `notes' property on the object to be evaluated:
{&cmd} would be replaced by `notes', nad {exec} would use this value to
determine which property it should evaluate.
Now, set a property for each alias, containing MPI that performs a
function. One of the simplest ways to do this, is to force yourself to
use a command. In order to do so, you need to be set X(forcible) and
force_locked to yourself.
====================================
> @set me = X
Flag set.
> @flock me = me
Force lock set.
> @set ref =ref:{ref:{&arg}}
Property set.
> @set note =note:{force:me,lsedit notes=notes}
Property set.
> @desc note ={list:notes}
Description set.
> @set notes =notes:{force:me,look notes}
Property set.
> @set lockhome =lockhome:{force:me,@lock #17212=me&!me}
Property set.
> @set unlockhome =unlockhome:{force:me,@unlock #17212}
Property set.
====================================
The one action can now be used to do several different things. Typing
`ref here' would show the dbref of the room you are in ({&arg}, like
{&cmd}, a variable: it holds whatever was typed following the command
name. If you typed `ref here', the &arg variable would hold the string
`here'). Typing `note' would force you to use lsedit to edit your page
of notes. Typing `notes' would force you to look at the notes: the list
would be printed on your screen. Typing `lockhome' would force you to
lock the exit into your home, specifying it by dbref so that it doesn't
matter where on the MUCK you are located. Typing `unlockhome' would
unlock the exit in the same way.
A single multi-action like this can be extended indefinitely, by adding
aliases and a corresponding prop. To add a `look at my watch and check
the time' function, you could rename the action and set a `watch'
property that uses simple MPI.
====================================
> @name ref = ref;note;notes;lockhome;unlockhome;watch
Name set.
> @watch watch = watch:You glance at your watch. The time is {time}.
Property set.
> watch
You glance at your watch. The time is 14:18:46.
====================================
4.3 Building Rooms and Areas
Quality MUCK building requires a blend of creativity and technical savvy. At a
minimum, you should ensure that rooms in your areas are literately desc'd, and
that exits have the standard message props (@desc, @succ, @osucc, and @odrop).
The building commands are discussed elsewhere in the manual. What follows is a
narration of building a village inn, with cross-references to relevant
commands. The process should illustrate most of the issues a builder will
face.
Creating an Environment Room:
If you are building an area, as opposed to one or a few rooms for personal
use, it's a good idea to parent the area to an environment room. Doing so will
allow you to create commands that can be used throughout the area, and will
let you do a backup of your work with a single @archive command. As discussed
in <a href="rooms1.html">Section 2.2</a>, rooms by default have the same
parent room (or environment room) as the room from which they are are created.
A room can be reparented by @teleporting it to a new environment room. A
reasonable approach to building an area is to @dig an environment room, @dig
the first room in the area with the just-created environment room as its
parent, and move to the new room before creating additional rooms in the area.
This way, standard @dig commands will cause the additional rooms to be
parented to the area's environment room.
====================================
> @dig Amberside Environment Room (create the environment room)
Amberside Environment Room created with room number 4801.
> @register #4801 = aer (give it a registered name for easy access)
Now registered as _reg/aer:Amberside Environment Room(#4801) on
Cara(#1131PBJ)
> @set $aer = A (set env room Abode, so it will show up in @trace)
Flag set.
> @dig Amberside Inn: Tavern = $aer
Amberside Inn: Tavern created with room number 4802.
Trying to parent...
Parent set to Amberside Environment Room(#4801RA).
> @register #4802 = ai (register this too, since we'll be going there)
Now registered as _reg/ai:Amberside Inn: Tavern(#4802) on Cara(#1131PBJ)
> @tel me = $ai (go there)
You feel a wrenching sensation...
Amberside Inn: Tavern(#4802R)
Teleported.
====================================
If system parameters on your MUCK are set such that you cannot teleport to
your new room, it will be worthwhile to create a personal exit that takes you
there, for use while you are building the area. After the area is built and
linked to the rest of the MUCK, you can recycle it.
====================================
> @act ai = me
Action created with number 4803 and attached.
> @link ai = $ai
Linked to Amberside Inn: Tavern(#4802)
> ai
Amberside Inn: Tavern(#4802R)
> @trace here
Amberside Inn: Tavern(#4802R)
Amberside Environment Room(#4801RA)
Environment: Lowlands(#285RA)
Rainforest Parent Room(#121RWA)
Rainforest: Main Prarent(#118RA)
Master Environment(#101RA)
**Missing**
====================================
The Amberside Environment Room is parented to Environment: Lowlands(#285RA),
because we were under it when we issued the first @dig command. This may be
where we want it when the area is finished, or there may be some other area of
the MUCK that is more suitable. After the area is finished, you would contact
the MUCK's builder wiz and discuss where to put the area. For now, the current
location should be fine. Additional rooms that we @dig while under The
Amberside Environment Room(#4801RA) will automatically be parented to there.
====================================
> @dig Amberside Inn: West Wing
Amberside Inn: West Wing created with room number 4804.
> @trace #4804
Amberside Inn: West Wing(#4804R)
Amberside Environment Room(#4801RA)
Environment: Lowlands(#285RA)
Rainforest Parent Room(#121RWA)
Rainforest: Main Prarent(#118RA)
Master Environment(#101RA)
**Missing**
====================================
Creating and Propping Exits:
To avoid leaving floating rooms lying about, it's a good idea to create the
exits linking rooms immediately after @digging the rooms. As discussed in <a
href="exits.html">Section 2.3</a>, exit names can include aliases: alternate
names, separated by semi-colons, that can be used in place of the full name.
The first alias is the one that will be shown by obvious-exits programs. A
common and worthwhile convention is to set the first alias as a combination of
the full name and a notation indicating valid abbreviated aliases.
And, since putting message props on exits is the kind of niggling detail
that's easy to forget if you leave it to later, it's also a good idea to set
the message props immediately after @opening the exits.
====================================
> @open West Wing <W>;west wing;west;w = #4804
Exit opened with number 4805.
Trying to link...
Linked to Amberside Inn: West Wing(#4804R)
> @desc w = A sturdy wooden door leading to rooms on the west wing.
Description set.
> @succ w = You pull open the door to the West Wing hallway...
Message set.
> @osucc w = goes into the West Wing.
Message set.
> @odrop w = comes in from the Tavern.
Message set.
====================================
Exits are one way: in order to create a `door' between rooms, you need two
exits, one leading in each direction. So, we complete the door between the
Tavern and the West Wing by going to the West Wing and making another exit
leading back to the Tavern. We gave the Tavern the registered name `ai', so it
will be easy to link back to. But, if we had not done this, and the room's
dbref had scrolled off the screen, we could determine it with the @find
command.
====================================
> w
You pull open the door to the West Wing hallway...
Amberside Inn: West Wing(#4804R)
> @find tavern
Amberside Inn: Tavern(#4802R)
***End of List***
1 objects found.
> @open Tavern <T>;tavern;t;east;e = #4802
Exit opened with number 4806.
Trying to link...
Linked to Amberside Inn: Tavern(#4802R)
> @desc t = A strong wooden door.
Description set.
> @succ t = You open the door into the inn's tavern.
Message set.
> @osucc t = goes into the Tavern.
Message set.
> @odrop t = comes out of the west hallway.
Message set.
> t
You open the door into the inn's tavern.
Amberside Inn: Tavern(#4802R)
====================================
We gave the exits user-friendly aliases, but the exits are not showing up at
all when we look at the room. The server `look' command, and most user-created
look programs as well, do not show obvious exit lists by default. In order to
have such a list appended to our rooms' descriptions, we will need to set the
@succ message on the rooms to trigger an obvious-exit programs. You will
probably need to page a wizard or helpstaff member to determine the dbref or
registered name of such a program. As discussed in <a
href="triggers.html">Section 2.1.4</a>, the dbref or regname of MUF programs
triggered by message props need to be prefaced by an @ at-mark.
====================================
> l
Amberside Inn: Tavern(#4802R)
> p jessy = Hiya... Can you tell me the dbref or regname of the obvious exits
program?
You page, "Hiya... Can you tell me the dbref or regname or the obvious exits
program?" to Jessy.
Jessy pages, "It's dbref #183... reg name $obvex."
> p = OK, thanks.
You page, "OK, thanks." to Jessy.
> @succ here = @$obvex
Message set.
> l
Amberside Inn: Tavern(#4802R)
Obvious Exits:
West Wing <W>
====================================
We will need to set this @succ message on all rooms in the area for which we
want obvious-exit lists.
Describing Rooms:
Room descs are a somewhat demanding genre. You need to convey a sharp sense of
place in a very brief space. You often need to describe a number of rooms with
similar characteristics without becoming repetitive. The description often
needs to incorporate queues that geographically orient the player. Since other
events online are competing for the reader's attention, your writing needs to
be exceptionally clear. The following discussion first covers technical
aspects of setting room descs, then offers some editorial suggestions for
writing them.
As with any other object, the description of a room can be set with the @desc
command. And, as with any other object, you may want to do some hanky-panky
with lsedit and MPI to provide formatted descriptions (indentation, paragraph
breaks, etc.) A desc string bracketted with an MPI {eval} function will cause
any MPI in the desc itself to be parsed. The following description of the
tavern uses this technique to include the names of present players in the
description.
====================================
> @desc here = {eval:{list:maindesc,here}}
Description set.
> lsedit here = maindesc
< Welcome to the list editor. You can get help by entering '.h' >
< '.end' will exit and save the list. '.abort' will abort any changes. >
< To save changes to the list, and continue editing, use '.save' >
< Insert at line 1 >
The tavern is little changed from days when pirate sloops
found haven in the coves nearby: the beams are still low and smoke-
stained, the tables still rough-hewn and knife-hacked, the floorboards
still trecherously uneven. What light there is comes from three
flickering oil-lamps and wood fire burning steadily on the hearth.
Glasses and bottles along the back wall catch and toss the dim, moving
light. The innkeeper standing easily behind the bar is a grave of
secrets.
< Editor exited. >
< list saved. >
====================================
4.4 Making Puppets
A puppet (or `zombie') is a player-like object of type thing, set up so that
it can move and act independently, relaying everything it sees and hears to
the controlling character.
In the strictest sense, all that is required to turn an object into a
zombie is to set its Z(ombie) flag. This will cause it to relay
messages, and to be treated as a zombie by programs which distinguish
between zombies and players. In practice, two other steps are required
to create a working puppet: locking and setting the puppet so that it
can be forced, and creating an action to control it. First, create the
puppet object. Since the puppet will often be in a different location
than your character, it's a good idea to give it a registered name as
well. Then, set its Z(ombie) flag.
====================================
> @create Squiggy == pup
Squiggy created with number 128629.
Registered as $pup
> @set squig = Z
Flag set.
====================================
Next, set the puppet's X(forcible) flag, and force_lock it to you.
====================================
> @set squiggy = X
Flag set.
> @flock squiggy = me
Force lock set.
====================================
It would be possible to stop at this point, and use the @force command
to make the puppet do what you want.
====================================
> @force $pup =:jumps!
Squiggy jumps!
====================================
In practice, it will be more convenient to create an action that
simplifies frequent typing. Use an action name that's short and easy to
type, and won't conflict with other common exit names. `Z' is a
frequently used command name for controlling a zombie. Then, lock the
action to a condition that always fails, such as `me&!me', and set its
fail with an MPI string that forces the puppet.
====================================
> @act z = me
Action created with number 128630 and attached.
> @lock z = me&!me
Locked.
> @fail z = {force:$pup,{&arg}}
====================================
'&arg' is a variable: it holds whatever was typed after the command. If
you typed `z :jumps!', &arg would hold the string `:jumps!'. The fail
set on the control action would force the puppet with `:jumps!'.
====================================
> z :jumps!
Squiggy jumps!
> z out
Squiggy heads out to the park.
Squiggy has departed.
Squiggy> You head out to the park...
Squiggy> Alcot Park
Squiggy> A sweep of close-cropped green grass extends...
====================================
As indicated in the example above, output from the puppet is preceded
with the puppet's name, and a > greater than symbol to distinguish it
from your own output. This prefix string can be changed with the @pecho
command: @pecho <puppet object> = <prefix string>
====================================
> @pecho squiggy = *
Message set.
> z look
*Alcaot Park
*A sweep of close-cropped grass extends...
====================================
====================================
====================================
====================================
====================================
4.4 Making Vehicles
4.5 Archiving Your Belongings
5.0 ADMINISTERING A MUCK
Putting a MUCK online, creating a world that will attract players, and
dealing with the minor and major crises that will inevitably crop up
over time is an inherently demanding and time-consuming task. For most,
though, it is a labor of love, and the burdens can be shared among staff
members. Administering a MUCK involves both technical and non-technical
issues. Both can be quite insistent and pressing during a MUCKs early,
formative stages: there are innumerable technical details to attend to,
and the small population creates an artificially incestuous atmosphere
in which non-technical issues -- especially personality conflicts --
easily get blown out of proportion. As the world develops and attracts
players, things stabilize, but both issues will remain. On the technical
side, problems of dbase management and backward compatibility will
replace the tasks of getting everything working right. On the
non-technical side, player relations and changing levels of commitment
from staff members will come to the fore. Both sets of issues are
discussed in this section of the Manual.
5.1 Technical Issues
5.1.1 Selecting a Site
Of the various matters you'll need to consider, selecting a site is in
many ways the easiest. You need a 7 x 24 connection to the Internet and
a stable IP address, for a machine running some version of UNIX, with
permission to run a constant process. This may reduce the number of
options to one or none. If it's one, the decision is made: go with the
site you have. If it is none, and you're set on running a MUCK, your
options are:
1) Buy 7 x 24 access, with a stable IP address. In most markets,
at the current time, this costs about $100 per month. You will
of course also need a computer at the receiving end of that
connection.
2) Find someone who will let you run a MUCK on their site. This
is not impossible. Both requests and offers for sites appear
rather frequently on the rec.games.mud.announce newsgroup.
Bulletin board posts and public shouts on large M*'s may well
turn up altruists: the freeware and volunteerism ethos remains
alive and well in the M* universe.
If you are in the fortunate position of being able to choose sites,
consider the following factors:
1) Connection speed, connection reliability, and sizable RAM are more
important than processor speed. A MUCK can be run quite success-
fully on a `486 under Linux. A faster CPU is of course nicer,
especially if you do other things on the machine, but in all
likelihood, processor speed is the last bottleneck you'll hit.
2) It's hard to judge connection reliability ahead of time. If you
know someone who works on a site you're considering, or at least
through the same ISP, solicit their feedback.
3) Faster connection hardware is, obviously, better than slower
hardware. A 28.8 modem is adequate, but an ISDN is better.
A T1 or partial T1 connection is also acceptable.
4) Hardware is not the only consideration for connection speed.
Some ISP's simply cannot provide reliably fast connections.
Sometimes this is their own fault (they sold more bandwidth
than they have), and sometimes it's due to factors beyond their
control (the ISP's ISP sold more bandwidth than *they* have,
or the whole set up is situated behind some chronic bottleneck).
You can get a rough idea of comparative speeds by doing a
traceroute to sites under consideration. The first hops shown
will be those on your end of the connection, and are less
relevant: other user's won't have to make those hops. The
last several hops, however, are telling. If one site consistently
posts better times than another on the last two or three hops,
this is worth taking into consideration. Although the times
you see are in scant milleseconds, final hops of more than
300 - 400 milleseconds may indicate a bottleneck at the server.
Also, try pinging the sites (`ping <address>') and comparing the
indicated times. Let ping run for a couple minutes, then stop it
with ctrl-c. You should see a percentage for `packets lost'.
Dropped packets have to be resent, which significantly slows
transmissions between a client and server.
5) You need adequate RAM. MUCK is memory-based. That is, it keeps
the database loaded in RAM while operating. If this results in
a process larger than available RAM, portions of memory are
frequently swapped to disk (`paged'). This causes a significant
degradation in performance. So, have enough memory: for a small
MUCK, it's not a lot. A dbase with 2500 objects should create
a process of 4 - 4.5 megs.
The ideal is to run the MUCK on a machine that you own: compiling the
server will be considerably easier, and you'll be able to restart the
MUCK quickly in the case of a power outage or other failure. Console
access is also a significant security consideration: see Section 5.1.4
5.1.2 Compiling a MUCK
UNIX gurus and C buffs should have little difficulty compiling a MUCK.
For the rest of us, it is a potentially frustrating experience. This
section of the manual is addressed to the rest of us: sysadmins and C
developers, you can use this time to go toggle in a new kernal from the
front panel of a PDP-11, just to keep your hand in.
MUCK is not a shrink-wrapped, plug-and-play product. It is, rather, a
large freeware application developed over a number of years by skilled
coders who are willing to devote innumerable hours to making something
for other people to use and enjoy. It is assumed that you -- the site
administrator -- have reasonable facility with the UNIX operating system
and a basic understanding of how to configure the program by editing C
source code configuration and header files. In other words, like UNIX
itself, MUCK is quite user-friendly, but rather choosy about who its
friends are. The following overview may help you get on speaking terms
with your new server.
It is of course madness to try to set up a MUCK without knowing UNIX.
Nonetheless, people often try, and often succeed. A good book on UNIX
will be a worthwhile investment if you are going to be the MUCK's site
administrator, but a very brief crash course in the UNIX commands and
programs you'll need to use to get the MUCK set up is provided in
Appendix B.
If the set up goes smoothly -- that is, if your system has everything
where MUCK expects it to be -- this information should be all you need.
If you encounter compilation errors, you'll need to enlist help. Those
sysadmins and C developers will be through toggling in their
microkernals by the time you've gotten that far, and will no doubt be
MUCKing somewhere. Go to a large MUCK, and try a public shout, or paging
helpstaffers and wizards, asking if someone can lend a hand compiling a
MUCK.
Getting your server up and running involves the following steps:
1) Getting a compressed, archived file containing the source code.
2) Uncompressing the files.
3) Editing configuration files
4) Compiling the source code
5) Specifying database files
6) Starting and logging onto the server
Getting the Server:
The MUCK platform has evolved over a number of years, from TinyMUD,
written by James Aspnes, to its current incarnation: TinyMUCK, FuzzBall
version 6.0, developed primarily by Garth Minette. The most current and
authoritative version should be available at ftp.belfry.com. You may
want to get the archive of standard MUF programs and a start-up database
as well.
pub/fuzzball/fb6.0.tar.gz
pub/fuzzball/fbmuf.tar.gz
pub/fuzzball/basedb.tar.gz
Put the fb6.0 file where you want the top level of your MUCK directory
to go, perhaps in your home directory.
*
Uncompressing the Files:
The files you just got are compressed archives of a great many files and
directories.
To uncompress them, type `gunzip <filename>. For example
gunzip fb6.0.tar.gz
If you get something like `gunzip: command not found', try `unzip':
unzip fb6.0.tar.gz
This uncompresses the archive. You now need to extract individual files
from the archive with the `tar' command (`tar' for `tape archive').
tar -xvf fb6.0.tar
The switches -xvf tell the system that you want to eXtract files from an
existing archive File, and that you'd like it to do so Verbosely, so you
can see what it's doing.
Type `ls' to `list files' in your current directory. You should see,
among other things, an entry for `fb6.0/' (the / slash may or may not
appear). This is the directory holding the server.
If you got the dbase and MUF files, move them to the correct spots in
the server directories...
mv fbmuf.tar.gz fb6.0/game/muf
mv basedb.tar.gz fb6.0/game/data
... and change directories (cd) down to the directories holding the
files and unpack them in the same fashion.
*
Editing the Configuration Files
In directory fb6.0, you should see a file called `INSTALLATION'. It
gives succinct instructions for setting up the MUCK. Type `cat INST*' to
list it on your screen.
You will be editing a few files (include/config.h, game/restart, and
possibly include/params.h or include/autoconf.h). It is strongly
recommended that you make a copy of these files before you start
modifying them, so you can start over if something obscure goes wrong.
In the appropriate directories...
cp config.h config.cp
cp params.h params.cp
cp autoconf.h autoconf.cp
cp restart restart.cp
You can either edit the files directly on the server, with text editors
such as vi or pico, or you can download the files to your computer, make
changes, and then upload them. Appendix B gives (miserly) instructions
on using vi and pico; the steps you'll need to take to download and
upload will depend on how you're connected to the server. Hereafter, the
Manaul will simply instruct you to `edit' the files; do so in whatever
way works best for you.
Much of what you'll be doing when editing these files consists of
`defining' or `undefining' terms. A term is defined by beginning a line
with the #define preprocessor directive, followed by the term and
(optionally) its definition.
If a term is defined without a definition, such as...
#define GOD_PRIV
... this simply means that the term is `true': the compiler can in
effect check `Are we using God privileges?', and get a yes/no answer. In
this case, the term is defined; it has a true value: so, yes, we're
using God privileges.
If a definition is supplied, then the term is true, and has a specific
value. For example,
#define TINYPORT 8000
This means that, yes, we do have a specified default port to connect to:
port 8000.
You can `undefine' a term in either of two ways: you can comment it out,
or you can explicitly undefine it. To undefine a term, use the #undef
preprocessor directive:
#undef ANONYMITY
To comment out a term (that is, to change it into a comment that people
can read, but to be ignored by the compiler), enclose it in the strings
`/*' and `*/'
/* #define DISKBASE */
In general, you should #undefine terms rather than commenting them out:
doing so will undefine the term, even if it was defined somewhere else.
You won't need to change a very much.
In include/config.h:
Edit the file to the port you want to use.
#define TINYPORT 8000
Port numbers below 1024 are reserved for system processes; use something
higher than 1024, and lower than ****.
It's recommended that you leave all other settings the same, until
you're familiar with each of them and have a specific reason for
changing them.
You shouldn't need to change anything in include/params.h.
In game/restart:
This file is a shell script, a set of commands that execute
conditionally, rather like a DOS batch file. In addition to starting and
restarting the MUCK, it does some logging and error checking: it bails
out if the MUCK is already running, so you won't have duplicate
processes running, keeps a log of when the MUCK was restarted, and warns
of conditions such as missing or damaged database files, or insufficient
memory. You will need to make a couple changes to this file.
Near the top of the file, change the line which sets the variable
holding the path name for the MUCK. If you left the name of the
directory created when you un-tar'd the server as fb6.0, and didn't
rename any sub-directories in the server directory, you would set the
path variable as follows:
set GAMEDIR = $HOME/fb6.0/game
The port number needs to be specified in restart as well:
set PORT = 8000
The server process is called `netmuck' (the executable file that
actually runs the server is `netmuck'). `Restart' includes necessary
references to `netmuck'. On sites that have several M*'s running, it's
polite to rename `netmuck' to something else, or to call it by an alias,
so that the sysadmin can tell at a glance what's what. If you're running
the MUCK on your own machine, and know you'll only have one MUCK, the
following step can be omitted.
Find the line that says...
You probably won't need to edit anything after this line.
... so you'll know where to start making changes. A few lines into
forbidden territory, you'll see the following line:
set muck = `ps -aux | grep netmuck | wc -l`
Replace the word `netmuck' with something indentifiable as your MUCK. If
your MUCK is called `Vanity Fair', you might change it to:
set muck = `ps -aux | grep VanFair | wc -l`
And, the second to last line of the file:
./netmuck $DBIN $DBOUT $PORT >& logs/stdouterr.log &
Change `netmuck' here too.
./VanFair $DBIN $DBOUT $PORT >& logs/stdouterr.log &
*
Compiling the Source Code:
Now it's time to compile the server.
A very brief rundown on what's happening here: In addition to
information files like README and INSTALLATION, and the server you just
downloaded consists of quite a few files of `source code'...
human-readable text files written in the C programming language. You'll
use the `make' and `configure' utilities to create machine-executable
code from the source files.
Change directories to game/src, the directory holding the source code.
Type `configure'. This determines what flavor of UNIX you're running
under, the location of certain files and executables, and so forth. This
part should be quite straightforward. If it's not -- if you get messages
such as `No processor installed' or `Welcome to Macintosh' -- log onto a
large MUCK and find someone who can help.
Now, the (first) moment of truth: while still in game/src, type `make'.
Watch arcane messages scroll by. Then, when they seem to have all done
so, type `make install'. Watch more arcane messages. You may see some
labled `Warning'. As long as the warning isn't followed by a `Fatal
error', you should be OK. (Fatal errors are bad.)
If you get other compilation errors at this point, you'll need to track
down a guru to help you out. Again, wizzes, helpstaff, and @shouts on
large MUCK's are a good place to start looking for one.
Once you have the server compiled, you should tidy up a bit. In the
compilation process, a number of `object files' were created... Object
files are intermediate files created as the compiler generates the
executables. After compiliation, you don't need them any more; they just
take up disk space. In the game/src directory, type `make clean' to get
rid of them.
*
Specifying Database Files:
You need to provide the server with a database to use at start up. You
can use either the minimal database included with the server, or the
standard start-up database included in basedb.tar.gz. The minimal
database includes only two objects: Room #0, and God, player #1. The
start-up database includes about 70 objects, including important
programs and a couple rooms.
The start-up database is of course more convenient, but you may wish to
use your own versions of the programs or to set aside some low dbrefs
for players and other important objects. If you use the start-up
database, the first objects you create will have dbrefs in the high
60's.
The minimal database is, well, minimal. You'll need to do a bit more
work to get the place going, but you'll have greater control.
The files to be used for the database are defined in the `restart'
script. We didn't change those: the server will expect to find files
`std-db.db', `std-db.old', and `std-db.new'. The default files are fine,
but we need to create them.
In directory game/data... If you're using the start-up database
gunzip basedb.gz
This should create a file named `basedb.db'. Type `ls' to make sure. If
it created something else, use that file name below:
cp basedb.db std-db.db
cp basedb.db std-db.old
cp basedb.db std-db.new
If you're using the minimal database:
cp minimal.db std-db.db
cp minimal.db std-db.old
cp minimal.db std-db.new
These commands will make copies of the database file where the server
expects to find them.
*
Starting and Logging onto the Server:
You're now *almost* ready to start the MUCK. One last thing... If you're
on a public site, and edited the restart script changing `netmuck' to
something like `VanFair', you need to either rename `netmuck', or create
an alias for it. On the principle of `change as little as possible until
you know how everything works', creating an alias is recommended.
In the `game' direcectory, type `ls'. You should see file `netmuck'.
Create an alias (or `symbolic link') to that file with the following
command:
ln -s netmuck VanFair
You also need to make netmuck, VanFair, and restart executable (i.e.,
make these files runable commands).
chmod +x netmuck
chmod +x VanFair
chmod +x restart
Now, type `restart'. You should see some messages like `restarting at
<time>'.
Type `ps -aux'. This will list all the processes running on the machine.
If all is right with your world, you should see a process for it, a line
with something like...
./VanFair data/std-d
...in the final column.
Quick and Dirty Trouble-Shooting:
If the MUCK compiled correctly, but you don't have a process running,
then something went awry in the restart script. You should confer with
your sysadmin or some other knowledgable UNIX-type about it. Meanwhile,
though, you can use a simplified restart script. If the problem truly is
in the restart script, and not in the server, this should get you up and
running while you enlist outside help.
Move your current restart script to another file for safe keeping:
mv restart restart.cp2
Edit a new, simplified restart script, that includes the following three
lines:
mv data/std-db.db data/std-db.old
mv data/std-db.new data/std-db.db
./VanPoint data/std-db.db data/std-db.new 8000 >& logs/stdouterr.log &
(`VanPoint' and `8000' are specific to our example: use the MUCK name
and port number for your MUCK.)
Make the new script executable:
chmod +x restart
This script won't provide all the error checking and logging that the
full-blown one will, but there's also less to go wrong in it. With the
new script in place, type `restart' again.
We'll assume that you now have a MUCK process running. Congratulations.
Now you need to log on. There is only one character on the MUCK... #1,
who is probably named `One'. #1's initial password is `potrzebie'.
Connect to the MUCK with your normal client, and log in:
connect #1 potrzebie
If you're running the minimal database, type @stats: savor this pristine
and perfect universe.
***************************************
*** IMPORTANT: CHANGE #1's PASSWORD ***
***************************************
It is imperative to change God's password from the default.
@password potrzebie = <whatever>
5.1.3 Setting Up the Database
Growing the database into a lively and attractive world is of course an
on-going, never-ending process. When you're just starting out, the
primary concerns are installing the necessary programs and setting up
some kind of organization.
*
Initial Tidiness:
If you used the minimal database with an eye toward setting aside low
dbrefs for Very Important Players and the like, @create some things to
hold the dbrefs until needed, before you create other objects.
@create 2
@create 3
@create 4
@create 5
.
.
.
etc.
Then, when you want to use a low dbref for a player, @recycle the
appropriate object and immediately @pcreate.
====================================
> @rec #2
Thank you for recycling.
> @pcreate Agamemnon = bartlegast
Player Agamemnon created as object #2.
====================================
Setting up at least a minimal environment tree now, while things are
manageable, also saves effort later on. Most MUCKs end up with a storage
room for MUFs, a room for new players to start in, and a guest room.
Most also have a central meeting place. Use whatever structure you like,
but something like the following should work well while you're getting
started:
Room #0
|
Main Environment Room
| |
IC Environment Room OOC Environment Room
| |
Village Well |_ Guest Room
|_ Player Start
|_ MUF Vault
*
Porting Global Programs:
The files provided in the fbmuf.tar are a genuine help. These are upload
scripts that not only provide necessary programs, but also set up
necessary exits, macros, and properties. To install them, uncompress and
extract the files (`gunzip fbmuf.tar.gz', `tar -xvf fbmuf.tar'), and
quote, paste, or upload the resulting files onto the MUCK, using
whatever method works best for you.
The file for cmd-@register should be uploaded first: the other upload
scripts will use the @register command in installing the programs. Next,
install the libraries, in the following order:
lib-strings
lib-stackrng
lib-props
lib-lmgr
lib-edit
lib-editor
lib-match
lib-mesg
lib-mesgbox
lib-reflist
lib-index
lib-cases
lib-look
The remaining programs can be installed in any order.
If you're not uploading scripts from fbmuf.tar, you'll need to install
all the programs `by hand'. Even if you are using fbmuf.tar or the
standard database, you will need to install some programs without the
benefit of a script. The following gives an example of porting a
library; the same techniques can be used for any program. First, get the
code, perhaps by @listing and logging the program on an established
MUCK. The example uses the logging and quoting syntax for TinyFugue;
other clients will have different syntax.
====================================
On the established MUCK...
> /log lib-props
% Logging to file lib-props
> @list $lib/props
<output output output>
> /log off
On your MUCK...
> @prog lib-props
Program created with number 26.
Entering editor.
> i
Entering insert mode.
> /quote -0 `lib-props
> .
> c
Error in line 78: Unrecognized word lines.
> 78 l
77 lines displayed.
> 78 d
1 lines deleted.
> c
Compiler done.
> q
Editor exited.
====================================
As the example indicates, listing and quoting a program picks up an
extra, unwanted line: the @list command follows its output with a line
indicating how many lines of program code were listed... 77 in this
case. You need to remove that line, either with a text editor on your
system, or -- as in this example -- by uploading, compiling, noting and
deleting the offending line, and then re-compiling.
Once you have the program compiled, you need to set its flags
appropriately. All libraries should be set M3 and L; lib-lmgr,
lib-props, and lib-reflist should also be set S, B, and H. Lib-look
should be set S. Other programs should be set with whatever flags they
have on the MUCK you're porting from.
Libraries -- and other programs frequently used by players, such as
do-nothing and obv-exits -- will need to be registered. You can do this
either with the @register command, or by setting the property directly.
====================================
> @reg lib-props = lib/props
Now registered as _reg/lib/props: lib-look(#26FLM3) on Room Zero(#0R)
or...
> @propset #0 = dbref:_reg/lib/props:#26
Property set.
====================================
Some programs will also need properties set. For libraries, this
information is readily available with the @view command; for other
programs, you will probably need to get a wizard or the program owner to
help you view the props.
====================================
> @view $lib/look
Command to view: @list $lib/props=1-20
Run this command? (y/n)
> n
Read definitions? (y/n)
> y
.envprop = "$lib/props" match "envprop" call
.envsearch = "$lib/props" match "envsearch" call
.locate-prop = "$lib/props" match "locate-prop" call
.setpropstr = "$lib/props" match "setpropstr" call
envprop = "$lib/props" match "envprop" call
envsearch = "$lib/props" match "envsearch" call
locate-prop = "$lib/props" match "locate-prop" call
setpropstr = "$lib/props" match "setpropstr" call
====================================
The first bit of output in this series...
Command to view: @list $lib/props=1-20
...tells you that the program documentation appears in lines 1 - 20 of
the program. To set things up so that players on your MUCK can view the
program, set the _docs property on the program:
====================================
> @set lib-props = _docs:@list $lib/props=1-20
Property set.
====================================
The definitions are stored in propdir _defs/ on the program object. They
provide information needed for calling programs to communicate with the
library. The definition...
.envprop = "$lib/props" match "envprop" call
... means `Where a program that uses this library contains the word
`.envprop', use the function `envprop' in this library'.
Set the _def properties for each definition.
====================================
> @set lib-props = _defs/.envprop:"$lib/props" match "envprop" call
Property set.
<Etc. Copy, find/replace, and paste are your friends.>
====================================
Setting up libraries is also discussed in Section 3.2.2, MUF Libraries.
*
Other Porting Considerations:
Permission: all programs in fbmuf.tar and the start-up database are in
the public domain. For other programs, you should make a good faith
effort to honor the conditions for porting programs. Read the program's
header comment, looking for notes about permission and/or the author of
the program. If the program says it can't be ported without permission,
don't: instead, contact the program's author and ask for permission, or
find a similar program that can be freely ported.
Sometimes you just can't get in contact with the author, usually because
he is no longer MUCK'ing. In this case, contact the MUCK's MUF or
Globals wizard, and let her know that you want to port the program.
Usually there is no problem with this. And, even if the program says it
can be ported freely, sending page #mail that you've done so is a good
idea: people make programs freely available because they would like to
see them widely used; letting them know you are using their program is a
thoughtful gesture.
Connect and Disconnect Calls: Programs called from these queues (and
related queues such as _arrive and _listen) must be set Link_OK. Again,
when uploading from scripts, this is handled for you, but when you're
manually porting the program, you will need to set the calling property
yourself.
====================================
> @set con-announce = L
Flag set.
> @propset #0 = dbref:_connect/announce:#82
Property set.
> ex #0 = _connect/announce
ref _connect/announce:con-announce(#82FWLM3)
====================================
Sometimes a program needs to be called from a prop like _connect,
_disconnect, or _listen -- and so should be set Link_OK -- but also
needs to be kept *not* Link_OK for security reasons. This is handled by
creating a small, Link_OK stub program that calls the real program. An
example of this is provided below, in the discussion of setting up Guest
characters.
*
Macros: Programs uploaded from scripts or provided with the start-up
database will set up any macros they need. For programs that you install
yourself, you will sometimes need to define macros. If a program that
works fine on another MUCK will not compile on yours because of an
unrecoginized word...
Error in line 273: Unrecognized word otell.
... the problem is probably an undefined macro. On the MUCK from which
you are porting the program, go into the program editor, type `s' to see
a list of defined global macros, and look for the offending word...
`otell' in this example. Copy the macro definition. Then, on your MUCK,
define the macro.
====================================
> @edit lib-look
Entering editor.
Line not available for display.
> def otell ( s -- ) loc @ me @ rot notify_except
Entry created.
> c
Compiler done.
> q
Editor exited.
====================================
MUF Macros are also discussed in Section 3.2.3, MUF Macros.
MPI Macros: You will probably want to set up global MPI macros as well.
These are stored in the _msgmacs/ directory of Room #0. Set a property
in this directory, with the name of the macro as the prop name, and the
MPI to be used in its place as the stored value. For example, to set up
a simple {look-notify}...
====================================
> @set #0=_msgmacs/look-notify:{null:{tell:[ {name:me} looked at
you. ],this}}
Property set.
====================================
Wizards on an established MUCK may well be willing to email you a file
containing their MUCK's MPI macros. MPI macros are also discussed in
Section 3.1.1.
*
Tuning System Parameters:
The @tune command lets you adjust a number of system parameters. Type
`@tune' without arguments to view the parameters and their current
settings. Most can be left at their default settings. Of those that you
may want to change, some only make cosmetic or formatting changes, while
others significantly affect the operation of the MUCK. The following are
some parameters you may want to change. The syntax for resetting a
parameter is `@tune <parameter> = <value>'. The value must
be compatible with the data type indicated in the left column of @tune
output: (str), (bool), etc.
dumpwarn_mesg These parameters can be freely changed to alternate
deltawarn_mesg save messages. Note, however, that some players
dumpdeltas_mesg configure clients to be triggered by the ## charac-
dumping_mesg ters in a save message. So, it's a good idea to
keep this format: enclose your new save messages
in ## double octothorpes ##
penny Declaring new currency denominations is a time-
pennies honored wiz pastime.
cpenny
cpennies
muckname This you should change. Set it to the name of
your MUCK. It's a good idea to use a muckname
setting that does not include any spaces.
huh_mesg You may want to supply something more imaginative
leave_mesg for these.
dump_interval Four hours is the default interval between saves.
This is quite workable, though it's often shorter
on new MUCKs and longer on large, established ones.
max_pennies If money is actually signifcant on your MUCK, you
may want to lower this. Note that M2 Muckers can
make very simple programs that give pennies freely.
penny_rate Lower this if you want fewer `You found a penny!'
messages; raise it if you want more.
command_burst_size It is unlikely that you will need to change these.
commands_per_time However, if for some reason you believe your server
command_time_msec is performing poorly, you may wish to try adjusting
max_delta_objs these system-performance parameters.
max_loaded_objs
max_process_limit
max_plyr_processes
max_instr_count
instr_slice
mpi_max_commands
pause_min
free_frames_pool
playermax_limit The default limit is 64. Higher limits allow more
players, but setting an unreasonably high limit
wastes memory.
listen_mlev This parameter controls the minimum Mucker level
of programs which can be called by _listen. The
default is M3, which is a good choice. The decision
whether to raise or lower it should be based on
how closely player programming is monitored.
player_start This should be changed. Set it to the dbref
of the room where you want new players to start.
use_hostnames The default for this parameter is `no', but tuning
it to `yes' is convenient. Wizards see connection
information when typing `WHO*' (use `WHO' without the
asterix for normal formatting). With use_hostnames
set to `yes', domain names rather than numeric IP
addresses will be shown for all players logged on.
Note: the change won't be immediately apparent.
Host names will be supplied for players who log on
after you tune the parameter to `yes'; those who are
logged on now will still have numeric addresses.
log_commands Whether or not to log and what you do with the logs
log_failed_commands are fairly significant decisions. See also Section
log_programs ***, Security Concerns, and Section ***, Privacy
Issues. As for the technical aspects of logging,
note the following:
- All commands (including says and poses) entered
by wizards are logged, regardless of the logging
parameters. If log_commands is off, and you want
to have a private discussion that won't go into
the logs, set yourself Quell.
- Log files pile up. You will need to follow some
schedule for deleting old log files. (The files
are in the server directory game/logs.) Either
by hand, or with a script, or with a crontab
script that runs automatically, follow a routine
for copying the current logs to storage files.
For example:
mv com2 com3
mv com1 com2
mv commands com1
Doing this once per day, say, will keep one-day-
old log_commands files in `com1', two-day-old logs
in `com2', three-day-old logs in `com3'. After
three days, they're gone.
- Raw logs are difficult to read. If you do need
to review log files, mastering the UNIX `grep'
command will be very helpful.
dbdump_warning Until your MUCK grows to past several thousand
deltadump_warning objects, full saves will take only a couple seconds,
and delta saves will be practically instantaneous.
You might want to turn these off, out of anti-spam
sentiment.
realms_control The Realms Wizard system has advantages and disad-
vantages. See Section ***.
The remaining parameters can safely be left at their default settings.
For a (terse) description of what each parameter does, see the entry for
SYSPARMS in Section 3.2.5, MUF Reference.
Editing Server Files:
The screen shown at log in, and the information provided in `info',
`news', `help', `man', `mpi', and `motd' (Message of the Day) are all
stored in the server directory game/data.
One of your first tasks will be providing a new log in screen, to
replace the TygressMUCK screen supplied with the server. To do so, edit
the file game/data/welcome.txt. Note: Though many players currently have
large screens, it's a good idea to limit the file to 78 characters by 20
rows. This is all that can be seen at one time by someone running
TinyFugue in `visual' mode on a standard 80 x 24 monitor, or a similarly
limited terminal program on some other platform.
You can add to or edit the documentation provided in `news', `info',
`help', `man', and `mpi' by editing the files `news.txt', `info.txt',
`help.txt', `man.txt', and `mpihelp.txt' respectively. Or, you can add
files to the directories `news', `info', `help', `man', and `mpihelp'.
Adding a file called `join' to the `news' directory would create an
entry that players can read by typing `news join'.
The MOTD will usually be updated online, with the `motd' command
(syntax: `motd <message>' to add an entry; `motd clear' to clear
all entries). The motd command gives no control over formatting,
however, and you can only clear *all* the entries, not one or some. If
you want to make more precise changes to the MOTD, edit the file
game/data/motd.txt.
Setting Up Guest Characters:
You will probably want to allow Guest characters. A program that
shuffles incoming connections to the next available Guest character is
available in fbmuf.tar and the start up database: con-multiguest. There
is also a small `stub' program -- con-callmultiguest -- that calls the
main program when players connect as Guests. The reason for this is that
programs called from _connect must be set Link_OK, but the password
creation scheme for Guests should be kept private, for security reasons.
Rather than calling con-multiguest directly (which would require it to
be set Link_OK), con-callmultiguest is set Link_OK and called on
connection. Then, this small program calls con-multiguest.
If you don't have con-multiguest and con-callmultiguest ported and
registered yet, do so now. Then set both program Wizard. Set
con-callmultiguest Link_OK and Set_UID.
====================================
> @prog con-multiguest
Program created with number 88.
Entering editor.
> i
Entering insert mode.
< quote or paste program >
> .
> c
Compiler done.
> q
Editor exited.
> @reg con-multi = con/multiguest
Now registered as _reg/con/multiguest: con-multiguest(#88FM3) on
Room Zero(#0R)
> @set #88 = W
Flag set.
> @prog con-callmultiguest
Program created with number 89.
Entering editor.
> i
Entering insert mode.
< quote or paste program >
> .
> c
Compiler done.
> q
Editor exited.
> @set #89 = W
Flag set.
> @set #89 = L
Flag set.
> @set #89 = S
Flag set.
====================================
If you haven't created a room for the Guests to start in, do that now as
well.
====================================
> @dig Guest Room
Guest Room created with number 90.
====================================
@Pcreate the proto-Guest character.
====================================
> @pcreate Guest = guest
Player Guest created as object #91.
====================================
Then @pcreate the actual Guests. By default, the con-multiguest program
is set up to handle eight Guests. If you want more or less, find the
following line in the program...
$def NumGuests 9 (Max guests allowed connected + 1)
... and edit it appropriately. That is, change 9 to some other number.
====================================
> @pcreate Guest1 = guest
Player Guest1 created as object #92.
.
.
.
> @pcreate Guest8 = guest
Player Guest1 created as object #99.
====================================
@Teleport the Guests to the Guest Room, and @link them there.
====================================
> @tel *guest = #90
Teleported.
> @link *guest = #90
Home set.
<etc.>
<etc.>
<etc.>
====================================
@Set the _connect/multiguest property on each Guest to call
con-callmultiguest.
====================================
> @propset *guest=dbref:_connect/multiguest:#89
Property set.
> @propset *guest1=dbref:_connect/multiguest:#89
Property set.
<etc.>
<etc.>
<etc.>
====================================
This version of the multi-guest program changes Guest passwords by
forcing a wizard (not the most elegant approach). You'll need to edit
line 14 of the program, designating a wizard to do the forcing. In the
original file, #1 is designated, but God cannot be forced if the MUCK is
compiled with GOD_PRIV. (If you don't have other wiz characters yet, you
need to make one.)
You should probably also change the password creation scheme. This is in
line 20. It's not really crucial what you change it too: just make it
something that returns a string.
====================================
> @edit con-multiguest
Entering editor.
Line not available for display.
> 14 l
$def Wizard #1 (Change this to a wizard's dbref. Preferably not #1)
> 14 d
1 lines deleted.
> 14 i
Entering insert mode.
> $def Wizard #2 (Change this to a wizard's dbref. Preferably not #1)
> .
> 20 l
$def PassWdMake (i -- s) 3 + 9 * intostr "TimE" swap strcat "tWINe" strcat
> 20 d
1 lines deleted.
> 20 i
Entering insert mode.
> $def PassWdMake (i -- s) "snerk" 5 * 7 intostr swap strcat "aVast" strcat
> .
> c
Compiler done.
Editor exited.
====================================
*
Creating a `Gohome' Exit:
A `gohome' action that will let players return to their homes without
losing things they're carrying is a worthwhile and easy-to-install
convenience.
====================================
> @act gohome = #0
Action created with number #100 and attached.
> @link gohome = home
Linked to HOME.
====================================
*
Using the Realms Wizard System:
This is not something you must decide immediately, but if you are going
to use realms wizards, there a few advantages to doing so from the
outset.
In order to use the realms wizards system, the system parameter
realms_control must be tuned to `yes'. The effect is to give the owners
of rooms set Wizard extended control over objects in that room, and over
objects in rooms parented to that room. A realm wizard can examine, set
properties on, and link objects within his realm as though he owns them.
He cannot chown objects belonging to others, unless the objects are set
Chown_OK, and he can only force objects that are set xForcible and force
locked to them, but -- since he can @force_lock and set flags on objects
in the realm -- he can essentially chown and force anything in the realm
as well. He can @teleport anywhere within the realm, just as a wizard
can.
There are decided advantages to making your staff builders realms
wizards. The extended control is a genuine help as they construct the
area, and their realm wizard status may well be a motivating factor:
they are lord in their realms, but that will only be meaningful if
people use the areas, so they have good reason to make the areas as well
constructed and attractive as possible. Once the area is built, they
will be able to help players with matters such as linking homes. Also,
making staff builders realms wizards rather than wizards avoids the
problem of having several surplus wizards once the world is constructed.
The one significant disadvantage -- or at least consideration -- is
security. Wizards have virtually unlimited control over the database,
but they also have built-in accountability: all wizard commands are
logged, regardless of whether log_commands is tuned to `yes' or `no'.
Within their realms, realms wizards have comparable control, but their
commands are not automatically logged. A clever and malicious realms
wizard could set locks and flags on a true wizard who enters his area,
and use these to directly or indirectly force the true wizard to do
something destructive or harmful elsewhere. If (im)properly handled, the
properties could erase themselves once they have done their job, leaving
no evidence, and the logs would show the true wizard as the guilty
party. The only real safeguard is the same safeguard provided against
true wizards: accountability. If you want to use the realms wizard
system, turn on command logging.
The realms wizard system works best if you set up a consistent,
geographically structured environment tree. This is much easier if done
when the MUCK is new. The following schematic shows how a science
fiction MUCK might be set up to use realms wizards. Rooms `Starport Env.
Room' and `Earth Env. Room' would be chowned to staff builders, and set
Wizard. These players who own these two rooms would then have primary
responsibility for and control over those two areas. Additional areas
could be parented to IC Environment Room, and the two realms control
rooms could also include environment rooms, perhaps with other players
holding realms wizard control over those smaller areas.
Room #0
|
Main Environment Room
| |
IC Environment Room OOC Environment Room
| | |
Starport Env. Room Earth Env. Room |_ Guest Room
| | |_ Player Start
|_ Some room |_ Some room |_ Staff Offices
|_ Some room |_ Some room |_ Help Room
|_ Some room |_ Some room |_ MUF Vault
|_ etc. |_ etc.
5.1.4 Security Concerns
Security problems are, fortunately, rather rare on MUCKs. Most MUCKs
function -- quite successfully -- in a climate of trust, but giving
thought to security issues is one of your responsibilities as an
administrator. The issues are magnified if you become an administrator
on a large MUCK, or if your MUCK attracts a sizeable player base.
In this section, `security' is meant as `protection against unauthorized
modification or destruction of the database itself, or of database
objects'. This is somewhat different than the related issue of privacy.
Privacy issues are discussed in Section 5.2.4.
*
Access to the MUCK Account:
Being able to log onto the account the MUCK is run from is the trump
card of all security concerns. With access to this account, someone bent
on mischief or destruction can do anything: change God's password, alter
logs, or destroy the database and all backups. Someone bent on
safeguarding the MUCK can undo any damage: no matter what has gone wrong
or been destroyed on the MUCK, the world can be restored to sane and
healthy condition by restoring from back ups.
So, control over and awareness of who has access to this account is the
foremost security concern. If you own the machine the MUCK runs on, and
are able and willing to do all site administration tasks, the issue is
considerably simplified: don't give anyone else the password to the
account.
For most MUCKs, the situation is a bit more murky. Often someone else
owns the machine. Sometimes the site administrator is a wizard on the
MUCK, but only marginally involved in its day-to-day affairs. Sometimes
several staff members end up having access to the account: God has
access because it is, after all, her world; the site admin has access
because it is, after all, his computer; the player relations and
security wiz ends up getting access so he can review logs in situations
where one player has charged another with some kind of offense; the wiz
responsible for creating new characters gets access so she can check
email for char requests; perhaps another wizard is given access so he
can update news, info, and help files. (For some things, you can enlist
server-side help from staff members without giving them access to the
account. For example, a separate account could be set up for the
security wiz, and you could copy the log back ups to a directory in that
account, rather than game/logs. A separate account can be set up for the
wizard who does character creation, with char requests to be mailed
there, or mail can be forwarded to her.)
If this is a team of trustworthy people, then things are grand. Work is
shared among several people, and any one of them could log on to deal
with an emergency, such as restarting the MUCK after a power failure.
But, be aware: if you share access to the MUCK account, you no longer
have total assurance that the MUCK is safeguarded. It is conceivable
that one of these people will get mad at you, or at life, the universe,
and everything, and destroy the MUCK, or that one will give the account
password to someone you don't know.
*
Keeping Backups
The server does a certain measure of backing up on its own. At restart
(assuming you are using the standard database filenames) the database
used at the previous restart, std-db.db, is copied to std-db.old, and
the most current form of the database (std-db.new, created from the most
recent dump) is copied to std-db.db. So, at any given moment, you have
three versions of the database on hand.
You may want to take this a step further. Copying the most recent
database file to another file and compressing it gives you a safe copy.
Depending on your energy level and disk space, you may want to do a
rotating swap of database back ups similar to the one suggested for
logs.
mv backup2.gz backup3.gz
mv backup1.gz backup2.gz
cp std-db.new backup1
gzip backup1
The reason for keeping older back ups is that it's possible for a
database to become corrupt during normal operation: some bug in the
server or on-line programs creates inconsistencies in the database file.
In this situation, the most recent back-up file is not necessarily the
best one: it too could be affected.
Also, to safeguard against hardware or access problems, you may want to
do an offsite back up. With File Transfer Protocol, this is a simple
(but potentially time-consuming) process. FTP your most recent backup to
some other host. If your server goes down, or one of your wizards goes
bonkers and deletes the backups, you can set up on an alternate site.
*
Access to #1:
Next in the hierarchy of security issues is access to the God character.
If the MUCK is compiled with God privileges, only God can set players W
or !W, or change wizards' passwords. Also, only God can use the
utilities for analyzing and repairing the database, @sanity and @sanfix.
On most established MUCKs, God is not used as an actual player. The
primary wizard of the MUCK will create a wizard character for daily use,
and only log onto #1 to only set or unset players' wizbits or to use the
database utilities. In part this is for security: just as UNIX sysadmins
do their normal work from an account other than root, MUCK Gods do their
normal work from a different character. In part it is simply a
convenience: wizards sometimes need to force themselves, or use programs
that force them, and #1 can't be forced. Also, #1 always gets the
full-data WHO screen (which wizards see when typing WHO*), whether she
wants it or not. And in part it's a matter of facilitating
administration of the MUCK. Sometimes the de facto God of the MUCK (the
overall administrator who appoints wizards, determines policy, etc.) and
the most technically accomplished staff member (the person who would
handle matters such as running @sanfix) are two different people, so
both have reason for using #1. Or -- a rather common situation -- there
is no single wizard with total control; rather, leadership is shared
among a core group of wizards, each having access to the God character.
Whatever set up you use, the password to #1 is an important piece of
information, and should only be given out on a need-to-know basis.
*
Wizards:
Most wizards are committed to their worlds, and would never directly
harm it, but the possibility exists. It's not unheard of for an immature
wizard to get angry and destroy a world. The MUCK can recover from this
by restoring from back ups, but obviously this is an unpleasant chore.
More common problems come about inadvertently. Most are minor: a wizard
with wayward fingers mistypes #321 for #312, and recycles some important
room or command. So, you fix it.
Sometimes players @force lock themselves to each other. Wizards
shouldn't. When you appoint a new wizard, check his force lock. When he
was a player, it was fine for his roommate to be able to force his
sleeping body downstairs when she had visitors, but it's not fine for
her to be able to force him once he is a wizard.
Wizards should also be aware of a specific line of attack that can be
used to modify objects with the wizard's permissions. You can set
properties on objects you control (you control everything). Also,
objects you *own* can set properties on other objects you own. And,
properties can include MPI that causes programs or other properties to
execute. (This is true for players too, but the implications are less
threatening.) For wizards, these events are carried out with wizard
permissions. In short, and without providing specific recipes, a naughty
player can make objects which -- if they are chowned by a wizard -- can
do naughty things. Whenever you chown an object, examine its properties,
with particular attention to MPI that stores values or calls properties
or programs ({store}, {exec}, {lexec}, {muf}, and the like).
*
Programs:
Wizard programs can do pretty much anything a wizard can do, and M3
programs are quite powerful as well. As with security issues regarding
wizards, the trick is to identify and support trustworty people (and
programs), and to be aware of the issues, rather than trying to
anticipate and safeguard against every possible threat.
Your best defense against security breaches through programs is to
appoint a good MUF wizard. This staff member determines who gets Mucker
bits, with special attention to M3's, and reviews global and public
programs, with special attention to programs that players ask to port
from elsewhere. If you are not particularly MUF savvy, or if you are a
good coder but lack the sneaky mindset necessary to be a good hacker or
anti-hacker, you should recruit someone with these qualities.
(Surprisingly, it *is* possible to find honest sneaky people.)
Some general points...
The apparent purpose of a program is no guarentee of its potential
threat or lack thereof. If someone asks you to port a 2000-line Poker
program that needs to be set Wizard so it can keep scores in a protected
.scores/ directory, approach it as a wizbitted program large enough to
hide some Trojan horse feature, and not as `just a card game'.
*
Programs set Link_OK are public: they can be listed, linked to, and
*called by* other programs. Many are a little too trusting: they assume
that you (the person using the program) are who you're supposed to be.
And, if you use them in the normal way, you are. But it is a trival
matter to concoct a small stub program that stores an incorrect dbref in
the `me' variable, puts an argument string on the stack, and then calls
a public program. An M2 morphing program may seem perfectly safe --
after all, people won't put harmful things in their own descs -- but
consider: JoeHacker(#666PBJM2) might be able to store #1 or the dbref of
some other wizard in `me', put a string holding naughty MPI onto the
stack, and then call the morph program, creating a situation where the
next time someone looks at the wizard, untoward things will happen.
Fortunately, there is a rather simple way to plug this hole. Check all
Link_OK programs; if they don't guard against such assualts, edit them,
adding a line that does so. Before the first line of the last function
in the program, insert the following line:
"me" match me !
This explicitly matches the dbref of the triggering player or puppet,
and stores it in the `me' variable.
*
In general, any program should be run with with the lowest permissions
level that will work. If a program will run at M2, set it M2, not M3 or
W. If a program doesn't need to be owned by a wizard, consider chowning
it to some mortal, possibly an NPC you use for just this purpose.
*
You owe it to yourself and your players to make your policies on
security and privacy concerns as they pertain to programming explicit.
Providing a document stating this policy, readable through the `news' or
`info' command, is a very good idea. A sample policy is provided in
Appendix C. The sample policy may be freely copied and edited to meet
your MUCK's needs.
5.2 Nontechnical Issues
The following discussions of nontechnical issues are necessarily
subjective and editorial. They should be read with a critical eye, but
not ignored: new MUCKs succeed or fail for nontechnical reasons, not
technical ones.
5.2.1 Conceptualizing the World
The historical bias of MUCK toward socializing presents the would-be
administrators of a new world with a special challenge. On platforms
such as MUSH, with its emphasis on role playing, creating a successful
new world is not intrinsically difficult: one develops a well-written
geography and sound command structure, plants TP seeds with timelines
and background events, advertises the MUSH, and the world has a good
chance to survive. If it's well done, and if it taps into a new or
popular genre, it should attract players. But, MUCKs tend to be
primarily places to socialize rather than RP. There is no technical
reason why MUCK is not as good as or better than MUSH for RP, but the
trend is there. So long as players' motivation for MUCKing is
socializing, established worlds will have a powerful advantage over new
worlds in attracting players: if one goes to MUCKs in order to meet and
be with people, it makes good sense to go to a world where there are 300
people online rather than a struggling new place where there are three.
Unless the new world offers something that established worlds do not,
the administrators will, after a great deal of time and effort, find
themselves lords of a very lonely domain.
Dealing with this problem is beyond the scope of this manual, but it is
mentioned and even stressed here because it is very easy for new
administrators to lose sight of. Their new world seems grand to them --
at least in part -- because now they are *wizards*, now they are *in
charge*. It's a grand new world because, in short, it is their world.
But if players are to make it their world as well, the administrators
will need to give thought to a fundamental question: Why should anyone
come here?
Does the MUCK put a new genre online? Are there intriguing adventures or
quests, or well-wrought gaming programs? Does it appeal to some audience
beyond that of current MUCKs? Are players brought together by a common
and heretofore unserved interest? The answer to at least one of these
questions needs to be `yes'.
5.2.2 Recruiting a Staff
Recruiting and keeping a good staff of wizards can be surprisingly
difficult. The best wizards already *are* wizards somewhere, and have
little incentive to take on another world and stick with it through the
long haul.
Putting and keeping a MUCK online requires the sustained efforts of
several people. At least one person on the staff should have solid
technical skills, and all staff members should have a thorough
understanding of the difference between a #dbref and a hole in the
ground. But it is not necessary nor even advisable to recruit wizzes
exclusively from a pool of technical hot-shots. Technical expertise is
one (and only one) of several skills required among staff members.
Interpersonal, organizational, and writing skills are important as well.
A strong staff will have a balance of these skills among them, plus
time, energy, and commitment.
Time, energy, and commitment are in fact the most scarce and valuable of
VR resources. And, wizards who become inactive after a first flush of
enthusiasm are the most common management problem. There are no magic
bullets for these problems, just hard-to-follow advice:
* Try first to find the ideal candidates for wiz positions.
There are two flavors:
* Good, active wizards who would like to move on from
a world where there is friction among staff, or their
area of responsibility is limited.
* Good, energetic players who demonstrate maturity and
skill in one of the areas a new MUCK needs. Helpstaffers
on large MUCKs are a good pool: these are people with a
demonstrated willingness to spend their online time
making things work.
* Recruit friends if you want, but don't do so on the basis of
friendship. Recruit friends who have something to offer, and
know from the outset that one day you may need to ask your
friend to resign, or be stuck with an inactive wizard.
* Be willing to perform the unpleasant task of firing wizards
who don't work out.
5.2.3 Sharing Responsibility
Most MUCK administrators find it necessary or at least advisable to
recruit a staff, to share responsibilities for building, programming,
technical maintenance, player relations, and so forth, with a team of
people with aptitude for a specific area of responsibility.
Use whatever pigeon holes and job desciptions you like. The following
are common:
* Site Administration: This wizard is responsible for maintaining Net
access. Sometimes the site admin is only marginally involved in
the MUCK's day-to-day affairs, acting essentially as a landlord.
Even in this situation, there are reasons for making the site admin
a wizard: for example, he can log onto the MUCK and do a clean
@shutdown if it's necessary to shutdown the server for maintenance
or other RL reasons. The site admin may also be responsible for s
server-side chores such as keeping back-ups, updating news and info
files, and answering email addressed to the MUCK staff.
* Programming: This wizard sets and unsets Mucker bits, based on
players' programming expertise, trustworthiness, and committment
to the world. She also reviews programs to be ported, checking
security and efficiency considerations. She may also be responsible
for creating and maintaining a listing of publically available
programs.
* Player Relations: This wizard arbitrates grievances between players
and charges of AUP violations. He is empowered to act as appropriate
in such situations, using disciplinary tools such as recording
warnings and charges in a log kept on the character, temporary
@newpasswording, @toading, and site banning.
* New Characters: This wizard @pcreates new characters. She needs
a way to read emailed character requests, and she needs information
about any players, sites, and addresses that have been the source
of player-relations problems. For a small staff, it makes sense
to combine this job and that of Player Relations.
* Building: This wizard is, in the MUCK's early days, charged with
building the world, or coordinating the efforts of a team of
builders. Once the world is built, the Building wizard will have
the most complete understanding of how everything is set up, and
is the best person to decide matters such as planning or
incorporating new areas. Often, the Building wizard also determines
policy on quota issues.
The exact form of your organizational set up isn't crucial, but it is
important that the staff has a good understanding of who's responsible
for what, when it's OK to do something that affects another staffer's
area, and that God or the core administrators keep a sense of
proportion. Silly, unproductive `turf wars' are a common reason for
staffs failing to gel as a team, and worlds burdened with squabbling
wizards seldom thrive. Some guidelines...
* God should refrain from micromanagement. If you've given a wizard
authority to handle Player Relations, let him handle it.
* Good communication solves most problems before they become problems.
Set up a global page alias for wizards and staff. All staff should
page mail each other when they do something that affects the MUCK as
a whole, or affects others' areas of responsibility.
* If instant action isn't required (and it seldom is) let the wizard
who's responsible for an area handle that area. The Builder wizard
may think that JoeHacker's actions obviously call for toading, and
she may be right, but it's better for her to simply @newpassword
JoeHacker, and let the Player Relations wiz handle the actual
toading. Not only is it his job, but he may have worked out a
procedure for @chowning the character's objects, notifying the
player, and so forth.
* And the flipside of the same coin... If you and the players
frequently find that something needed just doesn't get done because
a key wizard is unavailable (the Programming wiz hasn't logged in
in three weeks, say), then something is amiss with staff organ-
ization. God should step in, handle the immediate situation, and
consider making changes to the staff roster.
5.2.4 Privacy Issues
5.2.6 Toading
Occassionally you will need to toad players: sometimes for particularly
grave violations of the AUP, more often because the player wants to
leave the world.
5.2.7 Record Keeping
5.2.8 Keeping a Sense of Perspective
Wizbits have a curious side-effect: they can greatly aggravate the least
tendency one has toward pomposity, arrogance, or being meddlesome.
APPENDIX A: GETTING A CLIENT PROGRAM
Dalua says, "The best clients are Zmud, Pueblo, Phoca, and MUSHclient.
APPENDIX B: UNIX CRASH COURSE
ftp
cd
ls
mv
cp
ln
tar
gunzip
ps
kill
cat
pico/vi
*****************************************************************************
Apendix C: Sample Acceptable Use Policy and Programming Policy
GenericMUCK's Acceptable Use Policy
-----------------------------------
The staff of GenericMUCK respects your privacy and intellectual
property rights, and requires that you extend the same respect to others.
Please read this file completely, and enter the command @AUP to
acknowledge that you have read the file and agree to abide by its terms.
'Residents' refers to all players and staff. Where the distinction
between staff and players is important, this will be explicitly noted.
1.0 Access and Legal Responsibility
Access to GenericMUCK, and the computing resources required to operate
GenericMUCK, is granted on a revokable basis, and at no time is this
access guaranteed.
GenericMUCK services may be used only for lawful purposes. Transmission
or solicitation for reception of material which violates US Federal or
Hawaii State Law, any Policy of the site where the MUCK operates, or
state or local law of the area in which you reside is prohibited. This
includes, but is not limited to, material that is threatening, libelous,
or violates trade-secret, patent, or copy-right protections.
You agree to indemnify and hold harmless GenericMUCK, its staff, the
owners/operators of the computing resources, and all other parties
connected with the administration of GenericMUCK from all claims which
are a result of your usage, without limitation. You agree that any
traffic which originates from your character or connection is your legal
responsibility.
Notwithstanding the above, you agree that should GenericMUCK or its staff
be found liable in a court of law for any action or lack of action related
to your use of GenericMUCK, our liability is limited to $0.00.
2.0 Privacy
As a resident of GenericMUCK, you have a right to reasonable privacy.
2.1 Residents may not use programs, zombie objects, or other methods to
monitor your conversations or activities inappropriately.
2.1.1 Residents may use zombies, broadcasting exits, programs, etc.,
as detailed in `news programming'.
2.1.2 Staff may monitor intrusively, by setting the Dark flag on
themselves or referring to logs, if they have reason to believe that a
player or group of players is actively conspiring to destroy or damage
the MUCK's database, or is engaged in illegal activities.
2.1.3 Electronic Communications Privacy Act (ECPA) NOTICE: The staff
of GenericMUCK reserves the right to monitor any and all communications
through or with GenericMUCK computing facilities. You agree that
GenericMUCK facilities are NOT to be considered a secure communications
medium for the purposes of the ECPA.
2.2 Residents may not use programs or other methods to retrieve
information stored in properties on your character or belongings
inappropriately.
2.2.1 Residents may create and use programs that retrieve information
in ways that meet the the guidelines detailed in `news programming'.
2.2.2 Staff may use the `examine' command and other methods of
retrieving information remotely as needed.
2.3 Residents may not harrass you.
2.3.1 If you indicate that you are not receptive to intimate or
sexual contact with another resident, that resident is obligated to
respect your wishes. If someone persists in making unwanted advances,
repeat your demand that he or she stop, and page a staff member
immediately.
Residents guilty of sexual harrassment are liable to disciplinary
action up to and including @toading and site-banning.
2.3.2 Repeated attempts to talk to, page, or otherwise interact with
a resident who has clearly requested to be left alone are a violation
of Acceptable Use.
2.3.3 Racial, ethnic, and religious slurs directed at a player are a
violation of Acceptable Use.
2.4 Information about your life outside GenericMUCK is privileged. Your
RL name, gender, age, phone number, email address, and place of residence
are priviledged information. That is, unless you explicitly indicate that
this information may be dispersed, residents are obligated to treat the information as confidential.
2.5 Privacy as regards alternate characters is left to residents'
discretion.
2.5.1 You may have alternate characters, and you are not obliged to
inform others of the relationships between your characters.
2.5.2 If you do not wish others to know of the relationships between
your characters, do not give out this information. If you do not mind
other residents knowing about the relationships between your characters,
it would be helpful if you indicated this, by conversation, pinfo, or
other means.
3.0 Intellectual Property Rights
The staff of GenericMUCK honors intellectual property rights as they
pertain to the MUCK, and requires that residents do so as well. The staff
claims no particular expertise in the complex and evolving field of
international copyright law and the Internet. This does not, however,
invalidate or limit the AUP as it pertains to intellectual property
rights: GenericMUCK policies on intellectual property rights stand
as detailed below.
3.1 Residents may not create programs, rooms, or other objects
incorporating copyrighted material without verifiable permission from
the copyright holder.
3.2 The staff of GenericMUCK become joint holders of intellectual
property rights for public rooms or other creations which become an
integral part of GenericMUCK and are used by a substantial portion of
the residents. The owners of such creations may improve and add to them
as they see fit, but may not @recycle the object or remove the properties
or code that make it integral to the MUCK without permission from the staff.
In the event that a player inappropriately destroys or changes public
creations, the staff reserves the right to restore such creations from back
ups. Should such occassions arise, intellectual property rights for that
creation as the pertain to the MUCK will from that point lie solely with
the staff of GenericMUCK. That is, the creating player forfeits rights to
determine if and how the creation is used on the MUCK.
3.3 Programs which include notices that permission to port is requested
or required may not be ported to or from GenericMUCK without such
permission. If you wish to port such a program and are unable to contact
the author, notify a staff member. The staff will attempt to contact the
author, and if unable to do so, will determine ona case-by-case basis
whether the port meets AUP requirements.
3.4 The staff will not modify or remove any of your programs without
your permission, with the following exceptions: in the case of programs
which pose a threat to the integrity of the database or violate privacy
as detailed in `news programming' and the AUP, the staff will either
request that you modify or remove the program, or will do so themselves.
4.0 Violations of Acceptable Use.
Residents who violate the Acceptable Use Policy, or who commit acts not
explicitly covered by this policy but deemed a vilotation of the policy's
spirit by the staff, are liable to consequences including:
- Suspension of access to the Muck and its computing resources for
a time to be determined by the administrators.
- Removal of your character and termination of access to the Muck
and its computing resources without prior notice.
- Notification of your site and/or system administrators
- Notification of civil and/or law enforcement authorities.
*****************************************************************************
GenericMUCK's Mucker Policy
-----------------------------
1.0 How can I be a Mucker?
We welcome both experienced and neophyte Muckers. We ask only that (a)
you help the general public, not just yourself, by writing useful programs
of some social benefit or aid to building, and (b) that you abide by the
spirit and letter of our Mucker policy.
If a program you would like to write or use falls into a "gray area" of
these guidelines, please ask us for clarification. We may be able to
suggest ways to accomodate your needs.
2.0 What does a Mucker do?
2.1 Learning to Program
Start by reading the MUF tutorial and the MUCK Manual, also the
CHANGES files. Find them with the INFO command. If you need more help
than this, we may be able to put you in touch with a Mucker willing
to tutor you. If you write small programs to test something, or no
longer need a program, please remember to clean up after yourself.
A clean database is an effcient database, with less lag.
2.3 Public Programming
Whenever you write a program, and especially when a program is publicly
accessible (Link_OK), please make sure it adheres to our guidelines:
1. It should be useful in some way, social or building.
2. It should not violate guidelines of privacy, respect, or
honesty. (see section 3.0 of this policy)
3. It should not be wasteful-- do not use more space or CPU time
than is reasonable, or duplicate things that already exist.
If one of your programs meets the guidelines above, you may ask to have
it made publicly available. Such a program must be set link_ok in order
for other people to use it. A program that would be useful as a command
for everyone may be installed as a global. Type `globals' to see some
commands available.
Many programs are already publicly available; type `programs' for a
list, then list these programs for more information, or go to the
Programming Room off the Administrative Nexus and look through the
files. If you are looking for a program that would be a modification
of an existing one, you might find it more convenient to ask the
programmer to change it appropiately.
3.0 Guidelines to Proper Programming Etiquette
3.1 Privacy
Players of GenericMUCK are entitled to privacy. If you couldn't
find something out by normal means or without the permission of the
users involved, you should not find it out with a program.
***** Normal means does NOT include abuse of the powerful MPI command
language. That means one does not use MPI to violate the Privacy of others,
or attempt to manipulate or look at things or rooms you do not own. Please
see NEWS MPI for more information. ****
However, when you use certain programs, it is understood that the
program may store, relay, or use *reasonable* information for
*reasonable* purposes. If you aren't sure a program would fit this
guideline, please ask.
(A) Bugs relay information to another person, room, or stores it for
later reading, without your implicit consent.
Examples of legal programs:
1. Public programs such as page and spoof, which only use information
for administrative purposes, and are documented as to this use.
2. Programs that broadcast messages for the purposes of "virtual
reality" such as a program to let you be heard from a stage. However
it is possible to disguise the use of such programs. This is
unethical.
3. Bulletin boards, mailing systems, and other programs meant to
record and display messages for the public. By entering messages
into such a program, the user gives implicit consent that they be
stored and displayed.
Examples of illegal programs:
1. Programs that duplicate "page", "whisper", "say", or "pose" in order
to record or relay information without the player's knowledge.
(B) Scanners find information about other players, their properties,
or belongings, that would not normally be available, and which
the player does not wish revealed. This includes programs written
in MPI.
Examples of legal programs:
1. A program that only shows you messages or properties which are set
specifically for that program. E.G. a smell program might show you
people's smell messages, but it would be unethical to write programs
to read people's smell messages at a distance, without their consent.
2. Programs that show you information which you could obtain another way,
e.g. a program to tell you which of a selected group of people are on
the WHO list, or a program to tell you what exits go from rooms that
you own. Owners can always examine anything they own.
3. In reasonable circumstances, programs may show you information
such as which players are in another room if it is known to the
people in this room that they may be observed. E.G. a transparent
exit description for windows.
Examples of illegal programs (in MUF or MPI):
1. Programs that show you properties or messages on players, objects,
and so forth that you do not own and could not normally find out.
2. Programs that reveal private exits in rooms without the permission
of the room's owner. (similarly, programs to locate players without
their permission)
3.2 Respect
Certain programs may, while not invading a player's privacy, harass
that player, or make it possible to do so in a way that is undetectable.
Players are entitled to respect and dignity.
(a) Spoofers that allow a player to simulate another player's actions.
This would allow players to forge incriminating or insulting
messages under that player's name. Messages that could potentially
be spoofed should be made apparent in some plain manner or changed
to remove this danger.
(b) Markers are programs that change, add to, or remove player
properties without their implicit permission.
Examples of legal programs:
1. Programs may set temporary properties, or properties that obviously
belong to the program, and do not interfere with other programs or
the user's convenience. E.G. the page program sets a number of
properties for records keeping.
2. Programs that explicitly give the user full knowledge of what changes
are about to be made. E.G. role-playing systems and shape-shifting
programs that modify your description.
3. Programs for building assistance, which change your properties and/or
objects in an approved way.
Examples of illegal programs (in MUF or MPI):
1. Programs to overwrite another player's descriptions, messages, etc.
without their consent.
2. Programs meant to harass them by insulting, annoying, or otherwise
inconveniencing them, e.g. programs to send a spoof message directly
to a player without the player's permission, or to whisper to all but
one player.
3.3 Other Prohibited Programs (MUF or MPI)
GenericMUCK prohibits general teleporter programs that would allow
players to invade private rooms or that are intended to violate
virtual reality, e.g. encouraging people to teleport directly to a
room, ignoring intervening areas. We also dislike programs that add
pennies for no valid reason. Pennies are spent and used for things,
and available at the GenericMUCK bank.
Teleporters may be allowed in limited cases, but only for very
specific reasons and purposes. They must follow these restrictions:
1. Players must agree explicitly, or implicitly by entering a vehicle,
following another player, being picked up by that player, etc. to
be moved.
2. Programs to move players can only move players from or to rooms
for which they have permission, and under such circumstances as are
appropiate, e.g. a taxi might have stops in different rooms with the
permissions of these rooms' owners.
3. Such programs must be appropiate to the circumstances, the "virtual
reality" of the situation in question, etc.
3.4 What Happens If I Make A Mistake?
There are three steps, depending on seriousness of the offense.
Accidents and oversights happen; on the other hand, a deliberate
infraction may well lose you your Mucker bit immediately. You will be
informed of the reasons for any actions we take as regards you or your
programs. If you misuse MPI, your BUILDER bit will be removed.
1. If you write a program considered abusive or forbidden, you will be
talked to about why you need such a program.
(a) If the reasons are acceptable, the program may be allowed as is,
or we may suggest how it can be modified to make it fit the
guidelines.
(b) If the reasons are unacceptable or inadequate, you may be warned
to remove the program, or else modify it so that it will be
acceptable.
2. If you don't comply with requests to modify or remove a program that
is particularly abusive, then the program may be removed. Programs
that may crash the server may also be confiscated or removed. You
will be told how and why the program crashes the server
3. If you repeatedly upload programs that were removed as abusive, or
crash the server, or otherwise abuse your Mucker bit, then you may
be deMuckered and offending programs will be removed. Violations with MPI will result in the loss of your BUILDER bit as well.
Appeals will be allowed under extenuating circumstances.
4.0 Program Libraries and Macros
4.1 Documentation
Please document your programs where possible, so that those who are
meant to use them can do so. If programs are Link_OK, therefore publicly
usable, you should put comments at the top. Public programs should also
follow the convention of including a #help function.
We suggest that programs have comment headers describing the basic code
(two or three lines to synopsize the program's purpose, how it should be
used, and unusual things that users should know), naming the owner, and
providing any copyrights you wish to include.
Please don't complicate your code more than MUF normally reads;
deliberately obfuscating your code beyond a capable Mucker's ability to
read is considered impolite. Macros should be commented, or else obvious
from name or definition as to what they are intended to do.
4.2 Information Ownership
Many programs are set Link_OK so that they can be readily used. This
does not mean that you are free to copy them to other systems, or for
your own uses. Please ask the permission of the creator before you copy
programs!
5.0 The Final Word
If you have any questions about this policy, MUCKing, or other related
issues, please ask a knowledgeable player, Mucker, or Administrator.
They may be able to offer you answers, suggest where you can look
quickly and conveniently for information, or suggest how Mucker policy
applies to your question.
In all disputes related to Mucker policy and programming on GenericMUCK,
the judgement of the MUF Administrators is final, and supercedes the
guidelines of this policy.
6.0 Mucker bit levels and getting your mucker bit.
There are 3 Mucker levels.
M1 - Starter, or Apprentice
M2 - Standard, or Journeyman
M3 - Special, or Master
When you ask for a Mucker bit on GenericMUCK, you will be set M1. This
is where all Muckers will start. This gives you access to the @program and
@edit commands and allows 75% of MUF functions. This is a safety feature
to allow you to learn MUF without fear of damaging anything.
To get to Level M2, you should have written, tested, and debugged some
useful programs and then ask the MUF Administrator or hir assistants
to look at them for programming style and usefulness. The Administrators
may then grant you the M2 level. This allows 95% of MUF features to work.
Level M3 is needed only in very special programs that must directly
manipulate sensitive data from the database. This level can only be granted
by the MUF Administrators.
TO GET A Mucker BIT: Page or page #mail a wizard. Any wizard can give you
an M1 bit. M2 and M3 bits are set by the MUF Administrator.
To obtain a Mucker2 or Mucker3 bit, you should present a program which
*****************************************************************************
What do $lib/edit EDITmove and EDITcopy do?
Check .props ... wiz or m3?
Discuss `Function addresses
Discuss .format ... .period before macros and lib calls
Double check vehicle matters
If a library routine has the same name as a primitive, and the library is $included, which will run: the primitive or the routine?
Add .safecall to discussion of program security
Miskallaneous:
Cerulean purrs, "MUF knowledge, server knowledge, player relations"
Cerulean purrs, "Command comprehension"
of the chain and executing what's there."
You say, "And if the end is a room, does one move to the end room?"
Winged nods.
Jessy nods.
Winged says, "Same if it's linked to a player... if that player's J, then you
go to the location of that player."
Jessy had a very scary bug -- or it sure seemed like one -- here with exits
locked ot a program last week. And duplicated it. But then, when trying to
simplify the program to demonstrate in a bug report, lost track of it.
Couldn't duplicated. But it hung the server totally.
Winged says, "Multi-linking exits... it runs through the links, one at a time,
from left to right. The action of the exit is not over until it's all run
through."
You say, "Keep going... I'm just babbling. I need to know this stuff."
Winged says, "That's probably wizbitted-MUF called from MPI in the @succ/@fail
of of exit."
====================================
*****************************************************************************
Response:
text/plain