MUSH Manual Version 2.008
Written for TinyMUSH version 2.2.1
TinyMUSH version 2.0.10 patchlevel 5
PennMUSH version 1.50 patchlevel 12
MudCore Starter Database version 1.0
Copyright 1993, 1994, 1995, Lydia Leong (lwl@netcom.com / Amberyl)

Section I: Getting Started. Basic commands and objects.

Introduction: A brief history of MUSH. Configurations and server differences.

1. The Basics
1.1 Some information
Common terms used on MUSHes.
The format of this manual.
1.2 Basic commands
Looking around: look, examine, @decompile, TERSE, MYOPIC, @grep
Communications: ", :, @emits, page, whisper, basic flags and @set,
HAVEN, GAGGED, NOSPOOF
Going places: JUMP_OK, @tel, @whereis, UNFINDABLE
Objects: get, drop, give, ENTER_OK, inventory
Command syntax, @set and flags, special commands, @list
1.3 Attributes: @desc, @succ, @fail, @drop, @kill, IMMORTAL, @move, @sex
1.4 Editing: @edit, @mvattr, @cpattr
1.5 Do it! -- basic character set-up
1.6 A parser discussion
2. Objects
2.1 Basic object commands: @create, @destroy, @force, @name, VISUAL
2.2 Puppets - the PUPPET flag. ROBOTs.
2.3 A Note about Privacy: @sweep
2.4 Attributes on Objects: Action Lists
2.5 Machines: @cost, @pay, and @clone, QUIET and DESTROY_OK flags, @parent
2.6 Limiting object uses: @charges and @runout
2.7 Reacting to the environment: @listen and @ahear, ^, LISTENER/MONITOR
2.8 Keeping your objects safe: @lock, @unlock, @chown, CHOWN_OK, STICKY,
@search, @find, @stats
2.9 Do it! -- falcon

Section II: Building and an introduction to programming

3. Building.
3.1 Creating a room: @dig, FLOATING flag
3.2 Connecting rooms: @open, @link and @unlink, LINK_OK flag, @entrances
3.3 Refinements: ABODE and JUMP_OK flags, drop-tos and STICKY flag on rooms
3.4 Exit conventions and the TRANSPARENT flag
3.5 Do it! -- home
4. Introduction to Programming
4.1 The stack and string substitutions - % substitutions
4.2 General attributes and action lists - @trigger and GET()
4.3 The queue: @ps, @wait, and @halt. HALT flag
4.4 Decision making: @switch
4.5 Other ways of triggering: @use and @startup
4.6 User-defined commands: $command, @scan, @verb
4.7 Introduction to functions: ADD() and other math, RAND(), TIME()
4.8 Do it! -- falcon control

Section III: Programming applications

5. Vehicle programming
5.1 Entering and leaving objects: @enter, @aenter, @oenter, @oxenter,
@leave, @aleave, @oleave, @oxleave
5.2 Inside vehicles: @idesc, @listen, relays, and commands, @remit,
AUDIBLE, @prefix, @filter, @forwardlist
5.3 Do it! -- Wagon controller
6. Complex programming
6.1 Useful functions:
General use: NUM(), LOC(), NEARBY()
List creation: LCON(), LEXITS(), LWHO()
Parsing: POS(), FIRST(), REST(), STRLEN(), MID(), WORDS()
Matching: EXTRACT(), MATCH(), MEMBER(), UCSTR(), LCSTR(), CAPSTR()
6.2 Non-standard attributes: & and attribute flags
6.3 Introduction to @dolist
6.4 Time synchronization: semaphores, complex @wait, @notify, @drain
6.5 Security problems in programming, INHERIT, ESCAPE(), and SECURE(),
@fsay, @femit, @fpose
6.6 Debugging: PUPPET and VERBOSE
6.7 On the New Programming Style
7. MUSH Programming: QuickStart Guide
7.1 Basic syntax
7.2 Conditional and loop constructs
7.3 Functions


Section IV: A Guide for Administrators

8. Owning and seeing everything
8.1 Special privileges, ROYALTY, and Powers
8.2 Attribute ownership - @atrchown and @atrlock
8.3 Object ownership - @chown and @chownall
8.4 The queue - @ps and @allhalt, @kick
8.5 The database - @entrances, @find, @search, and @stats
8.6 A note about security and privacy
8.7 The Master Room and command processing
9. Wiz-specific commands
9.1 Talking to other wizards: @wizwall and @wizemit
9.2 Messages: @wall, @listmotd, @motd, and @wizmotd
9.3 Locking out players: @login and @rejectmotd
9.4 Dealing with players: @newpassword, @pcreate, @boot, @toad, and @destroy
9.5 Dumping the database: @dump and @shutdown
10. Database control
10.1 Quota system: limited object creation - @allquota, @quota, and @squota
10.2 Money control: give and @poor
10.3 Consistency checking: @dbck and @purge, @dump/paranoid, @cut, @fixdb
11. Zones
11.1 Object zones
11.2 Parent room zones
11.3 ZoneMaster players
11.4 Some notes on local wizard control
12. The Fundamental Laws of Wizarding
12.1 Wizard Etiquette
12.2 The Five-Step Method of player management
warning - nasty warning - gag - boot - newpassword
12.3 Wizard commands and when they ought to be used

Section V: The Art of Psychocoding
13. Basic Concepts
13.1 Attribute naming and coding style
13.2 String concatenation and the switchless style
13.3 What the parser really does
13.4 Zones in TinyMUSH 2.2
14. List manipulation
14.1 Adding to, removing from, and comparing lists
14.2 Function building blocks: U() and SWITCH(), @function
14.3 Formatting strings: SPACE(), REPEAT(), LJUST(), and RJUST()
14.4 Lists instead of @dolists: ITER() and FILTER()
14.5 Recursion: theory and practice, FOLD()
15. Efficiency
15.1 Parameter passing: U(), ULOCAL(), local registers, SETQ(), and R()
15.2 How the queue works
15.3 Pipelining
15.4 Queue cycles vs. CPU cycles

-----------------------------------------------------------------------------


This is the table of contents for Amberyl's MUSH manual. She can be
found on PernMUSH, or at lwl@netcom.com. This manual should be current
through TinyMUSH version 2.2.1, and PennMUSH version 1.50 patchlevel 12.
Much of it should also apply to TinyMUSH version 2.0.10 patchlevel 5
(from which TinyMUSH 2.2 is derived). Differences between the two
versions will be noted where necessary; in general, 2.0 will refer to
features common to both 2.0 and 2.2, and 2.2 will denote features
specific to 2.2. Do note that because 2.0.10p5 is now an obsolete
version, and 2.0.10p6 is not much more advanced, that there may be
sections of this manual which simply do not function under those
code versions, or which require modification (for example, 2.0.10p5
does not have the %q-substitution, though it does have the R() function).

This manual version also covers commands that are softcoded in MUSH,
found in the MUSHcode starter database called MudCore. MudCore global
commands are found on a variety of MUSHes, most notably PernMUSH and
AmberMUSH; it is convenient to mention them in this manual, since
many tasks can be simplified by use of these globals, and even those
MUSHes that don't use MudCore or the equivalent do have globals which
perform similar functions.

The 2.0x manual series is a complete rewrite using the 1.15 manual as
a starting base. Unlike the previous manual, this one is intended to
replace anything that has come before, including Croaker's manual,
which is pretty much obsolete for this version of code.

Those programming MUSE should probably look at the 1.15 manual release
instead, or use Falryx's MUSE Manual, which is based upon this manual
(with permission). The MUSE parser is quite close to the original 1.x
parser, and the basic examples in this manual should work without any
problems. The MUSE powers system and related issues are beyond the
scope of this manual (and the author's knowledge, for the most part);
the helptext for MUSE and consultation with a MUSE programmer are
probably the best ways to figure out how to program MUSE.

TinyTIM players may still find Croaker's manual helpful. There is also
a TinyTIM supplemental manual, since TIM has diverged quite a bit from
the "mainstream" MUSH. The contents of the PernMUSH 1.15 manual and
this manual may or may not apply to TinyTIM. The parser on TIM,
however, is fairly similar to the standard 1.x parser. There is,
however, probably little of interest in this manual for the TinyTIM
player, since most of the features mentioned here do not exist on TIM.

This is the tenth revision of this manual. There have been some major
revisions in the servers since the prior revision, though these
primarily affect advanced programming techniques and administrative
commands. This manual only documents the most important of these; for
the rest, the helptext should suffice.

I have also corrected a number of previous errors, and further
expanded the notes on advanced programming techniques, which seem to
be in great demand. There are also a number of formatting changes,
which, in my opinion, make the text easier to read. A fair amount of
the text has been expanded (and hopefully clarified); I've also chosen
to introduce more "advanced" programming techniques earlier in the
manual. Finally, I've taken the opportunity to explicitly debunk a few
myths about MUSH programming, as well as provide specific methods for
things that I often see programmed incorrectly or inefficiently.
There are a lot of small changes, and a few sections added and
removed. The structure of this manual is slowly becoming obsolete,
due to the changing methods of MUSH programming, and, specifically,
learning to program MUSH; it is likely that future revisions of the
manual will restructure substantial portions of the text.

The tenth revision is also the first version of the manual to document
a softcoded package of MUSHcode, in this case, the MudCore Starter
Database. I regard the standardization of certain core pieces of
softcode as something which will ultimately make the transition from
one MUSH to another much easier, and thus I'm going to attempt to
support a standard by placing it in the manual. MudCore is slated
for an early-summer 1995 release; portions of it can be found on
games such as PernMUSH and AmberMUSH.

The ninth revision of the manual was relatively minor, correcting
previous mistakes, expanding various bits of material, attempting to
clarify the somewhat confused earlier explanation of semaphores, and
adding additional material on advanced programming topics.

The eighth revision of the manual was the first to cover advanced
programming, in a newly added section. The rest of the manual,
however, is not meant to be a guide to advanced programming, nor does
it necessarily show the "best" way to do something. It is intended to
show the most intuitive and basic way to get something done in MUSH.
It is also not a complete guide to MUSH; for that, you need to look at
the helptext. This manual is meant to act as a tutorial and as a
pointer to some of the more useful things available in MUSH, as well
as to clarify some of the things that are not easily covered in the
helptext. For the precise syntactic details on a command, look up the
help text; especially in the latter sections, this manual attempts to
avoid duplicating material found in the help, concentrating instead on
techniques and details.

The final "advanced programming" section of the manual convers the
"new" style of MUSH programming, which relies heavily on list
manipulation functions and string concatenation to produce the desired
result. This is commonly referred to as the "switchless style". While
I believe this is something best learned on one's own, an overview of
the common techniques is presented here. It also includes a discussion
of how to write programs that are efficient in their use of queue
cycles, without overburdening the server itself with very large,
complex function evaluations.

If you spot any errors in the manual, PLEASE send me email. You should
mention the specific MUSH version you are using, and mention as
specifically as possible where the error is.

Finally, by way of thanks to the various people who have, in the past,
contributed examples/typo reports/etc. to this manual, I've thrown
their names in as player examples in various places. I hope they enjoy
their brief moment of fame.

A "README.mushman" file accompanies this manual distribution,
and must be retained with any electronically-retrievable version of
this manual. To summarize the copyright notice contained therein:

This manual was written by Lydia Leong (lwl@netcom.com), and any
rights and privileges of reproduction are hers, in accordance with
United States or international Copyright Laws. Users are granted
permission to print and reproduce this manual in its unmodified
entirety, as long as this copyright notice is retained and due credit
given, and the material remains free of charge. It can be quoted, with
credit, within the bounds set by standard academic protocol. It may
NOT be used within another major document (such as another manual),
nor published in print form (whether or not the publisher makes a
profit from such publication), nor may it be hypertextified or
otherwise changed in format, without the explicit permission of the
author.


-- Amberyl, May 22nd, 1995