Get your own Free Home Page
Get your own Free Home Page
====UNDER CONSTRUCTION====Last Updated 20th May 1997
Getting StartedBeginning a SessionBasic LayoutSaving and Loading Session FilesCommand HistoryBeautificationStandard FeaturesBacktrackingGagsTriggersAliasesInterface In DepthThe Input WindowThe Palette WindowsCommand ModeScript ModeHistory ModeEditing ModeHot Keys and ExtrasAdvanced FeaturesChannelsJourneys and MappingReferenceRegular Expressions in RapscallionSome ExamplesHow do I...?
To begin new mud session, start Rapscallion, and select New from the File menu. A session window will open, with a dialog box requesting the connection information. You need to enter the address and port number of the MUD/MUSH/MUG/whatever. You can ignore the other fields for the time being. If you are entirely new to mudding, and don't know of the addresses of any Muds, or perhaps are confused about this whole address business, there are a number of websites which can provide you with a decent starting point. A good example is The MUD Connector.
It is a good idea, if you intend using triggers, gags or channels, to fill in the Prompts: field with the standard prompt(s) that'll be in regular use on the MUD. When commmands are queued, lines coming from the MUE will sometimes be appended to the end of a blank prompt, which can interfere with the text matching engine. When attempting to match, Rapscallion will strip anything matching the prompt strings from the beginning of a line.
Clicking on the OK button will automatically start to connect you to your chosen site, and all you need to know is how to actually use Rapscallion...
On the surface, Rapscallion is very simple to use. You enter a command into a small floating window at the bottom of the screen. When you press the return key, the command is sent to the MUD. All output received from the MUD appears in the main session window.
You can save all the configuration information for one session in a standard document in the normal Macintosh way - simply select Save or Save As from the File menu, and save the document in the normal way. In handling documents, Rapscallion acts in the standard Macintosh fashion in all respects except one - if you create a new session, you will not be prompted to see if you want to save changes when closing or quitting, unless you've already saved it once. This is simply to provide for quick one-off connections.
Rapscallion keeps a record of the last one hundred commands that you've entered. To recall them, simply hold down the command key, and press the up arrow. Using the up and down arrows with the command key held down will simply cycle through them one at a time. For further details, see Command History in Detail
Select General from the Configure menu. Click on any of the four colour boxes to change the colours for the background, text that comes from the MUD, messages from Rapscallion, or your own commands (and those from triggers & aliases.) There will be other options for changing the appearance of a session, but these will come later.
To aid you in your travels and for exploration, there is a simple system for backtracking, which won't work on all MUDs, but should work most. It relies on the principle that direction commands have direct opposites, which are for the most part pretty constant - for example, north & south, east & west, and so on. Each directional command that you enter is stored in its own history, and you can recall the opposite by choosing Backtrack from the Travelling menu. You can backtrack up to 500 commands, which should be plenty. To return again, choose the Retrack option - its very similar in concept to the multiple-undo/redo idea.
To automatically retrace your steps back to where you started, choose the Back to Start menu item, which executes your backtracking history as a travel alias. Reset Travel Alias will delete your travel history, which means that the spot you're currently standing on becomes the place that backtracking will ultimately take you to. Forget Last removes your last travel command from the travel history, which is useful if you accidentally use a non-existant direction, but want to keep the travel history valid. Rapscallion will not attempt to pick up on any mistakes you might make, or on anything odd that the MUD might do.
Rapscallion defines a set of opposites, which it uses to determine which commands are direction commands, and what their opposite numbers are. By default, it implements the following pairs:
| north | south |
| east | west |
| northeast | southwest |
| northwest | southeast |
| up | down |
| in | out |
| n | s |
| e | w |
| ne | sw |
| nw | se |
| u | d |
To alter or add to these, select Opposites... from the Configure menu. An additional facility provides for non-standard directions. If you enter a command in the form xxx##yyy, it is used as a direction command xxx, with the opposite yyy. So enter "gatehouse##out", and it'll send the command "gatehouse" to the MUD. If you then backtrack, it'll send the command "out".
For the more sophisticated travelling facilities, see Journeys and Mapping.
Gags are used to block out certain events so that you don't see them. You might want to do this because someone's shouting or being abusive, and the MUD won't filter it out for you. To create a new gag, select New Gag... from the Actions menu, or choose Gags... from the Configure menu and click on the New button.
Name the gag by filling in the Name field, and enter one or more lines of text into the Gag Strings: field. Each one of those lines is used as a regular expression in filtering the output from the MUD. A simple example might go as follows:
This will block out any text containing either "Fabian shouts" or "Fabian tells you". See Regular Expressions in Rapscallion for details on how to do more complex things.
Triggers are automated responses. They can be useful for a host of reasons - to automatically regenerate magical shields when they fail, to telling people that you're busy when they try to communicate with you, or whatever - they're a major reason for the existance of MUD clients.
Rapscallion aliases carry out a double role. The first is as described above. The second is to execute quick and simple macros with a single keypress, menu selection or click on a palette window (see The Palette Windows.)
Aliases, as described in the next section, can be used for this second purpose as well, but they aren't quite as quick, because of some of the more powerful features that they've been given.
To create a new trigger, select New Trigger... from the Actions menu, or choose Triggers... from the Configure menu and click on the New button.Fill in the Name field with the name you want to give it. In the Script field you put the command or commands that should execute when the trigger is activated. In the Trigger on String(s) field, you put the lines to be matched, as with gags. You can also extract parameters from the matched lines, to be used in script. In the Hot Key field, you can enter a key you want to press to activate the trigger by hand. To use hot key, press command, shift, and the respective key. If you want the commands to be displayed when they execute, check the Show Commands checkbox, otherwise leave it blank.
To trigger an alias by hand you can use its hot key, if there is one, or pick the correct item from the Do Trigger sub-menu in the Actions menu, or click on the corresponding button on the Triggers floating palette window, if you have it visible.
To turn a trigger on or off, you can use the checkbox in the Triggers palette, or check or uncheck it via the Active Triggers sub-menu in the Configure menu.
An example trigger:
Trigger on Strings:
Script:
This one could be used to automatically log you in when connecting. I'd advise having the Show Commands box unchecked for this one....
An more complicated example illustrates the use of parameters:
Trigger on Strings:
Script:
For more details on regular expression matching, see Regular Expressions in Rapscallion
An alias is simply a set of commands, which you define and execute at will. There's no trigger to set them off, so they need to be executed from the Do Alias sub-menu in the Actions menu, or from the Aliases palette window.
What they give you is a controllable way of executing a long series of commands. You can vary how fast an alias runs, both before and during execution - speeds vary from one command every two minutes or so, to five commands in a tenth of a second. You can pause it, or step through it a command at a time, or abort it during execution.
Rapscallion runs aliases concurrently with everything else you're doing, so you can still enter commands in the normal way while an alias is running, and you can run as different many aliases at the same time as you like.
As usual: to create a new alias, select New Alias... from the Actions menu, or choose Aliases... from the Configure menu and click on the New button.
Give the alias a name, in the Name field, and put the list of commands into the Script window. Use the Speed slider to set the desired speed - the maximum speed feeds commands to the MUD every tenth of a second. The minimum gives an interval of about two minutes. The Block Size field specifies how many commands are fed to the MUD in one go - if its set to 3, for example, with the speed at 0, Rapscallion will feed commands to the MUD in clumps of three, every two minutes. The Show Commands check box defines whether the commands are displayed when they're executed. If Loop is checked, the alias will keep repeating itself until you stop it. Auto-Start determines whether the alias runs as soon as you select it, or whether begins in pause mode.
When you run an alias, a little floating palette window appears to let you control it. The window has a speed slider with which you can adjust the speed while the alias is running, a progress indicator to show you how far through it is, and a set of buttons for pausing, playing or stepping through the alias. To cancel an alias, simply click in the close box of the palette window.
The channel facility allows you to separate different types of MU* event into different windows. This is easiest illustrated with an example: On my main regular MUD, there are a number of chat channels. The main one is the chat channel, and everything said on it is prefaced by the text CHAT:. To send a message to the chat channel, you just:
Rapscallion allows you to set up a channel window such that all text prefaced by "CHAT:" is directed to it. If you type something to that window, the text: "chat " is attached to the beginning before the command is sent to the MUD.
To create a new channel, choose New Channel... from the Actions menu, or Channels... from the Configure menu and click the New button.
Enter a name for the channel in the Name field. In the Prefix field you put the prefix that you want each command to begin with. Into the Catch Strings: field go the match strings, which work in the standard Regular Expression fashion. Use the Hot Key field to specify a cmd-shift keypress to bring up the channel window. The Activate On Triggers: field should be used to hold strings that you want to use to automatically trigger the window to open.
When automatically triggering, you can extract parts of the text that triggered the window to use in the Catch Strings field. See the examples for an illustration of how this is done.
Rapscallion uses a semi-intelligent journey system to handle travel aliases. In the ideal case, all you need to do is define a set of possible destinations, and fill in a set of key routes between them to establish a network of possible journeys. As an example, you have destinations A, B, C and D. If you define the journey from A to B, from B to C, and from B to D, Rapscallion will now be able to automatically take you from B to A, A to D, D to C and so on. This facility is aided by the ability to automatically reverse directions, but doesn't rely on it.
Choose two locations that you want to join up, and go and stand on one. Reset Backtracking (from the Travel menu.) Now take your desired route to the other location. Be aware that it will record any direction commands you enter, so if you make a mistake you need to correct it. If the mistake sends you in the wrong direction, you can just use Backtrack to get you back on your proper route. If you typed in the command for an inappropriate direction, use Forget Last.
When you reach your destination, choose Journey... from the Configure menu. Create the destinations, if you haven't already defined them, by clicking on the New Destination button, and naming them appropriately. Now use the popup menus to select your startpoint as the From: destination, and your end point as the To: destination. At this point, and not before, click on the Import From History button, which will import all your travel commands since the last reset into the Script field.
To actually travel, go and stand on the spot you want to leave from, and choose Start Journey... from the Travel menu. Select your current location in the From: popup menu, and your intended destination from the To: menu. Bear in mind that the To: menu will only show destinations which are connected by your routes to the From: item - if Rapscallion can't work out a route, it won't tease you with the possibility. In each case, it'll pick the shortest route between two points.
If you need to, choose your speed and block size - these work the same way as with aliases.
Then click on Start Journey, and away you go. A floating palette will appear to help control your journey - you can vary your speed, pause and step the trip as with aliases. The travel palette has two extra buttons, which allow you to step back the way you came, or to completely reverse your journey and go back to the beginning.
I think that everyone will find their own way to use this feature, but the way that works for me is to pick two different kinds of destination point - I think of them as end points and intermediate points.
An end point is a prominent place in the MUD, which is near to one or more important feature that I might want to visit - it may be a town square, or a town gate, or a glade in a forest, but the important part is that I'll want to be able to find it to start a journey from it, so it has to be prominent.
An intermediate point is more of a time-saving idea. If you're following a road, and the road forks - one fork leads to a town, and the other to a leper colony, define a destination at the fork. You will vary rarely want to stop there, but from there, you can define a route to the town and another to the colony, which saves enormously on work.
What you will ultimately do is build up a set of destinations all over your MUD, with an endpoint near every place of importance, so you can travel between them with an absolute minimum of effort.
To rename a destination, pick one in the From: or To: field with the Journey Editor dialog box, then change the name in its edit field and press the TAB key.
To delete a destination, select it in the From: field, then click on the Delete button. Remember that this action will delete all the journeys that are associated with the destination.
Ideally, you need to pick routes that can be reversed - sometimes this takes a bit of care,
as it is possible that a route in one direction won't take you the same way as the way you'd go
back. You may have to make use of the xxx##yyy notation, as described in the
Backtracking section. If it just isn't possible to define a reversable
journey, or possibly if you can have a much shorter route one way than the other, you can
simply define the trip in the other direction as well. Just take care about using the step and
play backwards facilities when running the aliases.
The system certainly isn't foolproof. Beware of accidentally starting off from the wrong spot. Beware of entering direction commands while a travel alias is executing. There is a lot that can cause an alias of this sort to fail, depending on the MUD. Used with care, however, the system can be incredibly useful.
A straightforward example. This particular channel has two modes of use: normal and emoted. To do a normal chat, this is the command and result:
chat Hello.
CHAT:Fabian: Hello.
The emoted mode goes like this:
chat@ bids you welcome.
CHAT:Fabian bids you welcome.
We want to be able to use chat normally, but also use emotes without having to switch to the main window and typing the command in full, which is a little jarring. We do it like this...
In the Activate On Triggers: field:
^CHAT:
In the Catch Strings: field:
^CHAT:
In the Prefix field:
chat%0
In the Tags field:
@
The tough part of this example is the triggering part. We want this window to trigger on the following text and to extract the name of the other party, and to catch any future tells from Dek in that one window. This is how we do it....
You tell Dek: Hello.
You ask Dek: Hello?
You tell Dek exclaiming: Hello!
Dek tells you: Hello.
Dek asks you: Hello?
Dek tells you exclaiming: Hello!
In the Activate On Triggers: field:
^(.*) tells you
^(.*) asks you
^You tell ([^\: ]*)
^You ask ([^\: ]*)
In the Catch Strings: field:
%1 tells you
%1 asks you
You tell %1
You ask %1
In the Prefix field:
tell %1
Get your own Free Home Page