Lua script extensions |
---|
MUSHclient has some scripting extensions which are only available to Lua scripting. This page describes them. Lua "sandbox" To help block out dangerous functions, for example:
... MUSHclient has a 'preliminary script' box in its Global Preferences -> Lua section. Into this you can place code that disables some 'dangerous' functions (like 'os') by setting them to nil. The code in this box is executed every time the Lua script engine is instantiated, in other words for every world, and every plugin. You can modify the sandbox code to remove all restrictions, add more, or fine-tune them to your requirements. For example, if you wanted to use os.date and os.time (and others), but not os.execute, os.remove or os.rename, you could use:
'print' function To make it easier to use Lua examples in MUSHclient, the function "print" is defined to effectively call the world "Note" function. However, unlike Note, print adds a space between each argument (like the Lua "print" does). eg.
world functions available from global scope Although the normal MUSHclient script functions are defined in the "world" table, MUSHclient adds a metatable to the _G table and uses the __index entry to make the script functions available at global scope. Put another way, you can either write:
Both methods call the world.Note script function. If you wish to change the behaviour of an inbuilt script function you must replace the world.XXX version (eg. change world.Note) rather than simply replacing the global version. 'check' function Many script functions return error codes (see the error_code table described below). A quick way of checking that the function has succeeded is to wrap the 'check' function around it. For example, instead of:
you could do this:
This raises an error (and shows the appropriate error message) if the function fails. Note that this is not relevant to all functions, only those which are documented to return eOK on success, and some other code on failure. Constants To make it easier to write scripts, MUSHclient's Lua interface has various built-in tables of constants. Trigger flags for AddTrigger These are in the 'trigger_flag' table.
Trigger flags for AddAlias These are in the 'alias_flag' table.
Trigger flags for AddTimer These are in the 'timer_flag' table.
Custom colour flags for AddTrigger These are in the 'custom_colour' table.
Error codes - map error names to numbers These are in the 'error_code' table. You can use these to check individual error codes. eg.
Also see above about the 'check' function. Error codes - map error codes to descriptions These are in the 'error_desc' table. You can use these to give meaningful error messages. eg.
Colour names - map colour picker names to RGB values These are in the 'colour_names' table. You can use these to look up colour names (eg. "red") and find the corresponding RGB value. Extended colour codes - map colour selector numbers to RGB values These are in the 'extended_colours' table. You can use these to see what the RGB equivalent is for the 256 extended colours (keyed by 0 to 255). Send-to codes - map scripted "send" names to a number These are in the 'sendto' table. You can use these to make functions like DoAfterSpecial more self-documenting. For example, instead of sending to '12', you can send to 'sendto.script'. eg.
Miniwindow constants These are in the 'miniwin' table. You can use these to make functions like WindowCreate, WindowRectOp, WindowCircleOp etc. more self-documenting. For example, instead of doing WindowRectOp action 1, you can use 'miniwin.rect_frame'. eg.
progress This provides functionality for displaying a "progress" dialog box during lengthy operations. First you create the progress dialog with: progress.new (description) That returns a userdata item that you can then use in subsequent operations:
Example of use:
The dialog box is a "modal" dialog, so make sure you arrange to close it, even on a script error, or it will lock out attempts to use the GUI interface. If necessary, use "pcall" on whatever it is you do while the dialog is open. See Also ... Topics
Lua base functions
(Help topic: general=lua) |
Enter a search string to find matching documentation.
Information and images on this site are licensed under the Creative Commons Attribution 3.0 Australia License unless stated otherwise.