This screen is used to define parameters for scripting MUSHclient. Scripting allows you to create custom triggers, aliases and timers that react in ways limited only by your imagination.
Available script functions are documented under the Help menu -> Functions List.
Lua 5.1 is supplied as part of the MUSHclient download. It consists of an extra DLL (Dynamic Link Library) - lua5.1.dll.
The recommended language to use if you do not already have scripts is Lua. For one thing, Lua is automatically supplied with MUSHclient and is thus always available for scripts. Some extra functionality is available exclusively to Lua scripts.
If you install plugins they can also do scripting. The script language used in a plugin can be different from the one used by the "main world".
This must be checked to enable the scripting engine.
If you see the word "(active)" next to "Enable script" it means the script engine is currently active.
If you see the words "(not active)" next to "Enable script" it means the script engine is not currently active.
If it possible for the script engine to be active even with "enable script" unchecked, if you have just unchecked it, because the disabling is done when you close the preferences dialog.
Similarly it is possible for the script engine to be inactive, even with "enable script" checked, because the enabling is done when you close the preferences dialog. Also, the script file may have caused a compile error, which means that the script was not successfully activated.
This is optional, however normally if you are using scripting you would specify a script filename. You would type this in using any editor capable of producing ordinary "text" files, for example, NotePad.
If you specify a script filename, and check "Enable script" then MUSHclient will attempt to process that file when you close the "world configuration" dialog box. If any errors are detected you will be notified. Note however that some errors (such as "type mismatch", or "wrong number of arguments") are only detected when individual script subroutines are executed, and thus will not appear at this stage.
Click on the "browse" button to locate a script file by using the file browsing dialog box.
Click on the "new" button to create a script file by using the file browsing dialog box. If you choose a file name and click OK, then a new, empty script file of that name will be created for you.
By clicking on this button, your script file is opened in your specified editor (the default editor is Notepad).
Click on this button to choose a different editor to edit your script files.
Use inbuilt notepad to edit scripts
If checked, MUSHclient's internal notepad is used to edit scripts.
Warn if inactive
If checked, you will get a warning in the output window if a trigger, timer or alias tries to call a script (in the script file) but it cannot, because scripting is disabled, the function is not available, or the script file had a parse error.
If checked, errors in scripts will be displayed in the output window (using world.Note) rather than having a dialog-box pop up at an inconvenient time.
Be warned that if the error occurs in "send to script" for a trigger that is "omit from output" then the error message will also be omitted. If such a trigger does not seem to be working, you may want to uncheck this box temporarily to see if there was a script error.
In the script language you can make "notes" which appear in the output window. You can choose which colour you want the notes to appear in. To make a note, you would say something like:
world.Note "Here is a note"
in your script. The colour is chosen from the world's custom colours pallette.
You can change the colour for notes inside a script by using various script functions, such as world.ColourNote.
You can put the names for subroutines (functions) that you want called for the various events below. The name must match the name of a function in your world's script file. For example, if you specify "OnWorldOpen" for the "open" event below, then your script should look like this (in Lua):
function OnWorldOpen ()
Note ("World has been opened")
end -- function OnWorldOpen
Alternatively, if the world event name starts with the "!" character, then the rest of the string is sent to "Execute" - that is, the MUSHclient command processor.
For example, under "Connect" you might have: !/Sound ("ding.wav")
This would play a sound when you connect (if the script prefix was "/").
Alternatively, you might put the name of an alias there to handle doing multiple things upon connecting. For example: !connection_alias
Called when the world file is opened (once per world).
Called when the world connects to the MUD. You might use this to send initial commands needed after connection, or to enable/disable triggers etc.
Called when the world gets the "focus". The focus is obtained when the particular world window becomes the active window (ie. the title bar changes to the active colour).
Called when the world loses the focus, as described above.
Called when the world has been disconnected.
Called while the world is being closed.
Called just before the world file is being saved. You can use this event to save internal script variables to MUSHclient variables, so they are saved as well.
Click to set extra script functions to be called when MXP is active.
If scripting is not working you can try clicking this to cause the script engine DLL to be "registered" with Windows. You should only need to do this once per PC. It is not necessary to do it for Lua, and is only implemented for VBscript, Jscript and PHP script.
Recompile when script changes:
When a script file changes MUSHclient may detect this (depending on the Operating System version). Select what behaviour you want when this happens:
You can set the scripts to automatically recompile when you edit and save the script file by setting this option to "always".
To ask whether ot not to recompile, set this option to "confirm".
To never recompile, set this option to "never".
You can enter one or more characters here which will act as a "script language" prefix. The recommended prefix is the "/" character. If you type the "script prefix" in the command window, then the rest of the command window (which can be multiple lines if you press Ctrl+Enter) is sent to the script engine. For example:
/ Note ("Hi there!")
would display a note in the output window.
An alternative way of entering small test scripts is to use the Immediate scripting window.
See Also ...
Lua base functions
Lua bc (big number) functions
Lua bit manipulation functions
Lua coroutine functions
Lua debug functions
Lua io functions
Lua LPEG library
Lua math functions
Lua os functions
Lua package functions
Lua PCRE regular expression functions
Lua script extensions
Lua SQLite (database) interface
Lua string functions
Lua table functions
Scripting callbacks - MXP
Scripting callbacks - plugins
Scripting data types
Scripting functions list
Scripting return codes
(ConfigureScripting) Sets scripting options
(Help topic: dialog=IDD_PREFS_P17)