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:
    os.execute "del mushclient.exe"
... MUSHclient has a 'preliminary script' box in its Global Preferences -> Lua section. This has code that disables some 'dangerous' functions (like 'os') by setting them to nil. If you are not planning to run untrusted scripts (eg. plugins) then you can edit that code and comment-out any parts you feel comfortable with having available to your scripts. The code in this box is executed every time the Lua script engine is instantiated, in other words for every world, and every plugin. There are suggestions in the default script for how you might modify it to block certain plugins (or worlds) but not others, from having access to dangerous commands. You can do this by using GetWorldID and GetPluginID to find the unique indentifier of the current world or current plugin. The default behaviour of the sandbox is to disable the following libraries: package.loadlib (so DLLs cannot be loaded, which may have malicious code) io (so files cannot be created or opened) os (some functions) (so operating system calls, such as "execute", cannot be made) The package library is modified so that the "require" statement will not load DLLs. 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 would replace:
    os = nil -- no operating system calls
by:
    os.execute = nil  -- no executing OS commands
    os.remove = nil   -- no removing files
    os.rename = nil   -- no renaming files
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.
    Note "hello, world"
    print "hello, world"    --> does the same thing

    Note (1, 2, 3) --> 123
    print (1, 2, 3) --> 1 2 3
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:
    world.Note "hello, world"  --> calls Note function in world table

    Note "hello, world"        --> does the same thing
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. 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.
    print (trigger_flag.OmitFromOutput) --> 4
Trigger flags for AddAlias These are in the 'alias_flag' table.
    print (alias_flag.AliasQueue) --> 4096
Trigger flags for AddTimer These are in the 'timer_flag' table.
    print (timer_flag.OneShot) --> 4
Custom colour flags for AddTrigger These are in the 'custom_colour' table.
    print (custom_colour.NoChange) --> -1
Error codes - map error names to numbers These are in the 'error_code' table. You can use these to check individual error codes. eg.
    if AddTimer (blah blah blah) ==
         error_code.eTimerAlreadyExists  then
      error ("That timer already exists")
    end
    print (error_code.eBadRegularExpression) --> 30021
Error codes - map error codes to descriptions These are in the 'error_desc' table. You can use these to give meaningful error messages. eg.
    status = AddTimer ("a", 0, 0, 0, 0, 0)
    if status ~= error_code.eOK  then
      error (error_desc [status]) -->  Time given to AddTimer is invalid
    end
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). progress This provides functionality for displaying a "progress" dialog box during length operations. First you create the progress dialog with: progress.new (description) That returns a userdata item that you can then use in subsequent operations:
    dlg:status (msg) --> set a status message (eg. "processing 'foo' ")
    dlg:range (low, high) --> sets the range of operations (eg. 1 to 100)
    dlg:position (pos)  --> sets where we are in the range (eg. 80)
    dlg:checkcancel ()  --> returns true if the user clicked on the cancel button
    dlg:setstep (amount)  --> sets the step amount (eg. 5)
    dlg:step ()  --> increase the position by the step amount
    dlg:close ()  --> dismiss the progress dialog
Example of use:
    local dlg = progress.new ("Loading things ...")
    dlg:range (0, 3)  --> 3 steps
    dlg:setstep (1)  --> step 1 per step
    dlg:status ("Processing foo")  --> first step
    dlg:step ()
    -- do something lengthy here
    dlg:status ("Processing bar")  --> second step
    dlg:step ()
    -- do something lengthy here
    dlg:status ("Processing fruit")  --> third step
    dlg:step ()
    -- do something lengthy here
    dlg:close ()  --> all done
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 Lua bc (big number) functions Lua bit manipulation functions Lua coroutine functions Lua debug functions Lua io functions Lua math functions Lua os functions Lua package functions Lua PCRE regular expression functions Lua string functions Lua table functions Lua utilities Scripting Scripting functions list (Help topic: general=lua) Documentation contents page