MUSH Manual Version 2.007 Written for TinyMUSH Version 2.0.9 patchlevel 2 PennMUSH Version 1.50 patchlevel 8 Copyright 1993, Lydia Leong (lwl@eniac.seas.upenn.edu / 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 Applications of @dolist 6.5 Time synchronization: semaphores, complex @wait, @notify, @drain 6.6 Security problems in programming, INHERIT, ESCAPE(), and SECURE(), @fsay, @femit, @fpose 6.7 Debugging: PUPPET and VERBOSE 6.8 On the New Programming Style 7. What to do next 7.1 Hints and tips 7.2 Index of @-commands 7.3 List of functions 7.4 List of flags 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 14. List manipulation 14.1 Adding to, removing from, and comparing lists 14.2 Generating lists: ITER() 15. Efficiency 15.1 Function building blocks: U() and SWITCH() 15.2 How the queue works 15.3 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@eniac.seas.upenn.edu. This manual should be current through TinyMUSH version 2.0.9 patchlevel 2, and PennMUSH version 1.50 patchlevel 8. Differences between the two versions will be noted where necessary. 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, and/or try to get their hands on one of the partially-completed MUSE manuals currently being written. 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 ninth revision of this manual. Not much has changed in either of the two servers since the previous revision, except for the implementation of certain 1.50 features in 2.0. Thus, this manual contains a few updates, some clarifications, and a few more thoughts in the final section, which covers advanced programming. I have once again attempted to clarify the description of semaphores; I hope this explanation is better than my last few attempts. I've also added in some examples of common programming mistakes, and attempted to back up my statement, "%0 is better than [v(0)]" by using %0 whenever v(0) is not required to make some kind of point. The eight 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. I am at work on a document tentatively titled, "The Insider's Guide to MUSH." This will be a "lab manual" for MUSH, with detailed analysis of complex objects and the techniques used to create them. Much of the material originally intended for the guide has been added to the new section of this manual, but the guide will be intensely example-oriented. It will also cover server maintenance and similar specialized topics. When this will actually be distributed is anyone's guess... 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. This manual may be distributed freely as long as none of its text is changed. You are welcome to quote it, put it on-line as part of your help system, etc. as long as it is not used as part of any other major document (such as another manual). -- Amberyl, August 29, 1993.