Gammon Forum

This page can be quickly reached at http://mushclient.com/scripting

An introductory tutorial video on scripting is at http://vimeo.com/80333485.

Why use scripting?

Scripting is optional, but if you choose to do it you can extend the power of the client by doing such things as:

• Conditional tests (eg. warn if HP low)
• Arithmetic (count things you kill)
• Fancy displays (different colours)
• Stats rollers
• Automated attacks
• Auto healer
• Health bar
• Level timer
• Wilderness walker
• Random socials
• Lots more ...

Setting up for scripting

The first thing you need to do for each MUSHclient "world" is to enable scripting in the world configuration dialog box. This does a number of things:

• Indicates you wish to use scripting
• Declares which script language you are going to use
• Initializes the appropriate scripting "engine"
• Declares which script file (to hold your scripts), if any, you want to use
• Defines a "scripting prefix" for typing script commands into the main command window
• Optionally lets you specify script handlers for "events" such as when you connect to a MUD

Example:

The important things to configure here are:

1. Language - I have chosen Lua, however you can choose from (at present):
   • VBscript (a form of Visual Basic)
   • JScript (a form of JavaScript)
   • PerlScript (Perl scripting language)
   • Python
   • Tcl
   • Lua (recommended)
   • PhpScript
2. Enable scripting - this tells MUSHclient to "turn scripting on".
3. Script file - this selects the name of the file you are storing scripts in. This is optional and can be omitted initially. A script file is simply a text file you create with a text editor, and save with the appropriate suffix (eg. .lua for Lua files, .vbs for VBscript files).
4. Script prefix - this is a character string that you will use for entering script commands into the main command window. The default is "/", which the examples below will assume you are using.

Which language?

• Lua is easy to learn, yet very powerful
• The Lua script DLL is shipped with MUSHclient - you can be sure the other MUSHclient users (assuming they have a reasonably recent version) will also have Lua.
• The scripting support for Lua lets you do some more powerful things (like named wildcards in triggers) very easily
• Lua's "table" structure, and inline functions are very powerful and let you write some very complex scripts
• Lua is cross-platform, so if you ever want to use MUSHclient on Unix (under the Wine program) you can still use your Lua scripts

The documentation for Lua is at Lua Documentation.

Where do I put my scripts?

Script commands can go in one or more of 4 main places:

• Type into command window
• The "Immediate" scripting window
• Directly into triggers, timers, aliases ("Send to script")
• Your script file

You can use any or all of the above. Typically the command and intermediate windows are used for quick tests of script commands or short scripts.

Also you can put scripts into plugins, in which case they can also go directly into triggers, aliases and timers (send to script), or into the script part of the plugin.

Let's look at each one in turn. I will demonstrate a "hello, world" script for each one. These examples will use Lua, although they would look very similar in other languages.

Command window

Note that in some languages, such as Lua, script function names and keywords are case-sensitive, so you must use 'Note' rather than 'note'.

In this example the script command is simply typed into the MUD "command" window, prefixed by the scripting prefix, in this case a "/" symbol. This is useful for testing commands to see how they work, eg.

The command window is most suitable for single-line commands, although you can do multiple lines by pressing Ctrl+Enter to insert linebreaks into the command window. Multiple-line commands are more easily entered in the Immediate window, described below.

Immediate window

You access the Immediate window from the Game -> Immediate menu (or press Ctrl+I). This opens a dialog box, as shown above, that lets you type in multi-line script commands, and then press "Run" to execute the script. The contents of the window are remembered for the current MUSHclient session, when you click on the Close button.

For ease of editing you can click on the "Edit..." button to open a larger, resizable, dialog box that has a monospaced font.

The Immediate window is handy for testing larger script snippets, where you might want to test a loop or function definition. If you are planning a lengthy script for a trigger, alias or timer, it could be helpful to test your ideas out first in the Immediate window.

The Immediate window and command window share the same "script space" so that variables or functions declared in one are accessible in the other one (and also in the script file, and "send to script").

An example of what you might try in the Immediate window is:

This example shows a multi-line script, and also shows the "Edit" dialog box being opened for easier editing. I have resized it a bit to make the screen dump smaller, but it shows the general idea. Again you can see that by using Note (or ColourNote or similar) you can display information in the main MUSHclient world window.

In triggers, aliases, timers (send to script)

The third method is to script directly in a trigger, alias or timer. This is known as the "send to script" method, because the text in the trigger/timer/alias is not sent to the MUD but to the script engine.

This method is an easy way of scripting your triggers/timers/aliases because it does not require the use of a separate script file.

Let's start of with our "hello, world" example ...

The example above shows that the script command is now in the "send" box of the alias, and the "send to" field is set to "script". Thus the command is sent to the script engine. So when I type the word "test" in the command box, the alias matches it, and sends the script command to the script engine, thus "hello, world" appears in the output window.

In the case of "send to script" the script commands are not executed (and thus checked for syntax) until the alias matches, so any syntax errors are only detected then. Thus you need to make sure you check your aliases, triggers and timers after writing scripts for them.

The more elaborate example above shows a trigger designed to test for low health. It uses an "if" test on wildcard 1 (%1 in the script) to see if your health is below 100, and if so, to do a red warning in the output window.

The asterisks in the trigger match text are to match the variable information (ie. hp, mana, movement points, xp).

In the "send" box is the script, however since it is too big to easily edit there, I have clicked on the "..." button which opens up a larger, monospaced font, editing window.

Once again, "send to script" is chosen, so the script commands are executed whenever the trigger matches.

In order to test triggers, it is handy to "force through" something you know will match. Rather than waiting for it to occur in the heat of battle, you can use the "Debug simulated world input" dialog box to pretend that the relevant line has arrived. Press Ctrl+Shift+F12 to open the dialog box. If your trigger matches on specific colours or special text (such as bold) then you can use the "specials" dropdown menu and "insert special" button to insert the desired ANSI codes into your dialog window.

Above is an example of how I tested the trigger described earlier. Press Ctrl+Enter to enter multiple lines.

In your script file

The final approach to scripting is to put your scripts into a script file (or in the case of plugins, the script area of the plugin). This has the advantages of:

• Centralising your scripts into a single place, where they can be easily inspected.
• Share one script routine between multiple triggers, aliases, and timers.
• Have "helper" scripts that are shared between other scripts (ie. subroutines)
• Handle special events like:
  • On world open
  • On world close
  • On getting the focus
  • On losing the focus
  • On connecting to the MUD
  • On disconnecting from the MUD
  • On world save
  • Other things, inside a plugin
• Various MXP-related events, such as a variable being set
• You can also initialise variables when the script loads, by placing scripts outside of any function.

To put your script in a script file, first you have to create the file (an empty file if necessary), and save it using the appropriate filename suffix for your chosen language (eg. myscript.lua). Then choose that file as your "script file" in the scripting configuration tab, as shown earlier up. Once you have done that you can edit the file using MUSHclient's text editor by using Game -> Edit Script File menu item (or pressing Shift+Ctrl+H), or simply edit it in an external editor of your own choosing.

Whenever the script engine is initialised the script file is read in. If you make changes to it you must reprocess the script file. MUSHclient tries to detect when you do that and offer to reload it automatically, but you can force it to do that by using Game -> Reload Script File menu item (or pressing Shift+Ctrl+R).

When using a script file in this way, any syntax errors in your script are immediately detected, so you can fix them before trying to test the scripts. However runtime errors (such as divide by zero) will not be detected.

Once, again, let's do our "hello, world" example, using a script file...

In this case we are using a script file function, so the "send to" field is still set to "world" (the default). In practice we can use the "send" box to send things to wherever we want and call the script function.

The important part is that the "script" box is filled in with the name of the script function. This is the name used in the function declaration inside the script (in this case, "test_alias").

The function declaration in the script file must follow the conventions documented for the type of thing calling it.

In the case of triggers and aliases, that is:

• Name - the name of the trigger or alias (the contents of the "label" field)
• Line - the entire line that matched the trigger or alias
• Wildcards - an array of the matching wildcards (if any)

In the case of timers, it is:

• Name - the name of the timer (the contents of the "label" field)

The purpose of passing down the name of the trigger, alias or timer, is to let the script function share the same function between different things, and let the function detect which one called it by testing the name.

Below is a more elaborate example, that shows how you can process wildcards passed down to an alias, and also pass down a name to it.

Interesting points here are:

• The script function is now in a separate file - the script file, shown in the upper window. This file could be shared between different MUSHclient world files.
• The alias has a name (a label) which is "target_someone". That is not the name of the script it calls. Names must be unique - that is, only one alias can have a particular name. The name is passed down to the script. In this case it simply displays it. The name is highlighted above in green.
• The alias calls a script whose function name is "target_alias". Many aliases can call the same script, however only one function of that name can be in the script file. The script name is highlighted above in yellow.
• I have used a regular expression as the match text so I could use a named wildcard. In this case the wildcard is named "target". This is passed down in the wildcards array (as wildcards.target) so it can be directly used to set a variable. This named wildcard is highlighted above in blue. Named wildcards are a powerful feature that removes the worry of "counting wildcards". You can access a named wildcard directly from the wildcards array in Lua, as shown above. In other languages use the GetAliasWildcard or GetTriggerWildcard script function.
• Wildcard 1 and wildcard "target" are the same thing - the first wildcard.
• Wildcard 0 is the entire text that matches the regular expression
• The "line" argument is the entire matching line that triggered the trigger. In this case wildcard 0 and "line" are identical, however if the regular expression only matched part of the line they would not be.

We can check that the script functioned correctly and set the variable by looking at the variables configuration screen ...

Another approach would be to simply type "/Note (GetVariable ("target"))" into the command window and check that the word "nick" was echoed in the output window.

Using variables

Scripts can use two type of variables:

• Variables supported by the script language itself
• MUSHclient variables

Each has their pluses and minuses.

Script language variables

These are built into the script language, and are typically:

• Numbers
• Strings
• Booleans (true or false)

and may also include:

• Arrays
• Lists
• Dates/times
• COM objects
• Functions

Using the inbuilt variables is easy, you simply script them the way your language supports. The drawbacks are:

• Variables are lost when the script engine is re-initialised, which might happen a lot during testing
• Variables are not saved when you close your world
• Variables are not loaded next time you open your world

MUSHclient variables

The drawbacks of MUSHclient variables are:

• Clumsier to access - you have to use GetVariable and SetVariable to use them
• They are only strings - thus things like numbers and dates have to be converted to/from strings, and special structures like lists and arrays are harder to store.

You can work around the drawbacks above by scripting appropriately. For example, you can load script variables from MUSHclient variables on world open, and save them back again on world close.

Scripting functions you can call

Apart from the functions you write yourself, and those provided by the script language itself, there are many functions built into MUSHclient that you can call (about 295 of them). They are all documented in the help file that ships with MUSHclient, and also on at MUSHclient scripting functions and MUSHclient online documentation.

As an example, here is the documentation for ColourNote.

The documentation is extensively cross-referenced, for example the ColourNote documentation references other ways of doing notes (eg. not in colour) and also various ways of manipulating colours.

Handling errors

It would be a rare scripter that does not make some sort of mistake during development. The first type is syntax or compile-time errors. An example is below ...

In this case I have deliberately called a non-existant function "blah". It is worthwhile reading the error message, as it usually tells you a fair bit. In this case it tells me the error is on line 2 (which I can find by counting down my script), and also the nature of the error, in this case that "blah" is a "nil value". In Lua parlance, that means "blah" is not defined.

Strictly speaking, the above error is not a syntax error but a runtime error. However the general idea is the same, you will see a dialog box similar to the one above.

Recent versions of MUSHclient have an extra option in the scripting configuration dialog that lets you redirect error messages to the output window, rather than a dialog box, which can be more useful if errors occur during a battle.

Logic errors can be harder to find, that is if the script simply isn't doing the right thing. However judicious use of Note can be helpful to display values from inside your script to see what is going wrong.

• They are self-contained, so you can easily distribute a plugin to other MUSHclient users, or simply share them between different worlds of your own.
  
  
• You can use a different script language in each one, so one plugin might use Lua, and another use VBscript.
  
  
• Plugins automatically save and restore their variables (if told to), so they can "save their state" for next time they are run.
  
  
• You don't clutter your main world file with triggers, aliases and timers that are only needed in a plugin.
  
  
• Plugins each have their own "script space" so you don't need to worry about a variable or function in one plugin clashing with another one.
  

Useful references

• MUSHclient scripting functions
• MUSHclient online documentation
• Lua scripting forum
• Jscript forum
• Perlscript forum
• Python forum
• VBscript forum
• Plugins forum
• Script callbacks for MXP
• Script callbacks for plugins
• List of script return codes
• Functions help list

Lua-specific items

• Lua script extensions
• Lua tables
• Lua tables in detail
• Converting Lua tables to MUSHclient variables
• Accessing MUSHclient variables by using a Lua pseudo-table
• Using the string library: find, gfind and gsub
• Extending Lua with your own DLLs
• Building pauses into scripts by using coroutines
• Pausing a script until certain output arrives from the MUD
• Using Perl-Compatible Regular Expressions (PCRE) in Lua
• Doing AES encryption
• Compression and decompression
• Hashing, base64 encoding and decoding
• Accessing COM objects from Lua
• Accessing MySQL database from Lua
• Bit manipulation

Also, our own versions of the help on Lua base, coroutines, debug, io, math, os, package, string, and table functions.

Documentation from other sites

• Programming in Lua
• Lua documentation
• VBscript and Jscript help files

Script engine downloads from other sites

• Perlscript download site
• Python script download site

Tutorial videos

• Video showing how to make a trigger
• Video showing how to make a targetting alias
• Video showing how to make a plugin

• JScript
  
  
• Lua
  
  
• Perl
  
  
• Python
  
  
• VBscript
  

• Find things out (eg. name of the world, its IP address, how long you have been connected, how many lines are in the output window).
  
  
• Add, delete, and modify triggers, timers, aliases, variables.
  
  
• Enable or disable individual, or groups of, triggers, timers, and aliases. You might do this to enable a trigger only under certain circumstances.
  
  
• Find out, and change, configuration options.
  
  
• Script an interface to the Chat system.
  
  
• Script special things to be done when you connect to, or disconnect from, the MUD.
  
  
• Write to the "info bar" - a special status bar reserved for scripters to display information into.
  
  
• Add "accelerator" keys. That is, you can dynamically configure what keystrokes do what commands.
  
  
• Simply do groups of things at once - for example an alias could set a variable, and send a command to the MUD.
  
  
• Interface with other programs using COM (eg. send data to a spreadsheet)
  
  
• Store data in a database
  
  
• Keep lists of useful things, eg. mobs you have killed
  
  
• Use a random-number generator to do things, like randomly say different things
  
  
• Do arithmetic, eg. counting things you have killed, see how long to the next level, work out how much damage your sword does
  
  
• Make some sort of maze or wilderness walker, that tries each exit, and remembers which ones it has been through.
  
  
• Send things to other open worlds (eg. a "send to all worlds" script), or notify you when playing one MUD if you have an interesting message from another one.
  
  
• Script building activities, to automate things you do frequently.
  

• Notepad window: Ctrl+Space
  
  
• Command window: Shift+Tab
  
  
• Editing inside a GUI dialog box: Alt+C
  

Here is a screenshot of function-name completion at work ... I typed "do" and pressed Shift+Tab:

1. Current health
   
2. Maximum health
   
3. Current mana
   
4. Maximum mana
   
5. Current movement
   
6. Maximum movement
   
7. Current xp
   
8. XP needed to level
   

percent = math.floor (%1/%2 * 100)  -- percentage of health left
SetStatus ("Health = %1 / %2 (" .. percent .. "%%)")

<triggers>
  <trigger
   enabled="y"
   match="&lt;*/*hp */*m */*mv */*xp&gt;*"
   send_to="12"
   sequence="100"
  >
  <send>
percent = math.floor (%1/%2 * 100)
SetStatus ("Health = %1 / %2 (" .. percent .. "%%)")
</send>
  </trigger>
</triggers>

function health_trigger (name, line, wildcards)
  local health = wildcards [1] 
  local maxhealth = wildcards [2]

  local percent = math.floor (health / maxhealth * 100)
  SetStatus ("Health = " .. health  .. " / " .. maxhealth .. 
             " (" .. percent .. "%)")

end -- function health_trigger 

<triggers>
  <trigger
   enabled="y"
   match="&lt;*/*hp */*m */*mv */*xp&gt;*"
   script="health_trigger"
   sequence="100"
  >
  </trigger>
</triggers>

Matching line was: <21/21hp 143/143m 110/110mv 0/10000xp>
Wildcards ...
1="21"
2="21"
3="143"
4="143"
5="110"
6="110"
7="0"
8="10000"
"maxhealth"="21"
"move"="110"
0="<21/21hp 143/143m 110/110mv 0/10000xp>"
"maxmana"="143"
"xp"="0"
"health"="21"
"maxmove"="110"
"mana"="143"
"xptolevel"="10000"

percent = math.floor (%<health>/%<maxhealth> * 100)
SetStatus ("Health = %<health> / %<maxhealth> (" .. percent .. "%%)")

function health_trigger (name, line, wildcards)
  local health = wildcards.health 
  local maxhealth = wildcards.maxhealth

  local percent = math.floor (health / maxhealth * 100)
  SetStatus ("Health = " .. health  .. " / " .. maxhealth .. 
             " (" .. percent .. "%)")

end -- function health_trigger