GGMud implements LUA 5.1, the interpreter is builtin in the executable so you don't need additional libraries to use it. The scripts should be ASCII files, the interpreter supports both DOS-like and unix-like files. The access to LUA script is provided in two different ways:
#script test
... the client will search for test.lua in your current directory. Obviously you can use #script inside alias or triggers.
Syntax: show( string )
This function let you show some string on the main output window of the client, the string may
contain classical DIKU like color codes to change the font color ($c0000 is black
$c0015 is white). The string is only show on the output window, the text you enter
is not sent to the mud.
Example:
show ( "$c0009Script loaded, client version $c0015" .. VERSION)...this will print the text "script loaded, client version" in RED with appended the version string of GGMud in white.
Syntax: clear( name )
This function will clear the entire contents of the window name you pass as parameter. It is useful to refresh status windows that don't need history.
Syntax: window( name, text )
This command will open a new window named name and will draw text to it, if the window is already opened the text will be appended to the end. You can draw multiple lines at once using \n inside the string to specify a newline.
Example:
window("speaks", "(" .. charname .. ") '" .. text .. "'" )...this will open a window named "speaks" (if the window is not already opened) and will print a string to it (something like (Mongo) 'hello everyone!'),
Syntax: trigger( string, function_name )
This command let you define a LUA trigger. LUA triggers are different since the normal ones since you cannot edit them by hand, you cannot edit them through GUI, they are of a class of their own called scripting, this trigger class can only be created through LUA (but you can enable/disable it with the Trigger Class window). The first argument of the function is the string that will trig the trigger, this argument, as you'll see in the example, obeys to all the usual trigger rules. The second parameter of the function is the function name as string you want to call when the parser find a match for your string. It's very important to remember HOW the arguments are passed to your function: you have up to nine variables (%1, %2 ... %9) you can use inside the match string, these will be passed, if used, to your trigger function in order, so if you use %1 and %3 instead of %1 and %2 your function will have two parameters and the contents of %3 will be placed in the second parameter.
Example:
trigger("^[%1] shouts '%2", "handle_shout");
function handle_shout(charname, text)
window("speaks", "$c0009(" .. charname .. ") '" .. text .. " (shout)" )
end
This code will invoke the function handle_shout every time a character shouts something with a string similar to [Mongo] shouts 'hello everyone!', the function will redirect the string to the window named speaks with a different formatting and red color.
Syntax: untrigger( string )
This function simply remove a LUA trigger previously defined, it's useful since you cannot remove a LUA trigger from the GUI interface, the string you pass to the function must be the same you passed to the trigger() function, notice, you can obtain the same effect using send() and #unaction from the command line.
Example:
untrigger("^[%1] shouts '%2")Remove the trigger defined in the trigger() function example.
Syntax: send( string )
This function is very important since it is not only the only way to send something to the mud through a LUA script, but it's also the way to interact with GGMud command line commands and aliases. The argument of the function is a string that is parsed by GGMud and then, if not filtered, sent to the mud. Inside the string you can use any GGMud command or any user defined alias, you can also use semicolon to send the mud multiple commands (or perform multiple GGMud commands).
Example:
send("stand;get $weapon;wield $weapon")Provided you have a variable pointing at your weapon name called weapon with this command you'll stand up and you'll get your weapon from the ground and wield it. This is just an example to show the fact you can use the GGMud parser in the send() argument string.
Syntax: idle_function( function_name )
This function will inform GGMud to call the function named function_name (the parameter has to be passed as string) every second. This can be very useful to add actions that do not depend on mud inputs. You can access any global variable or function in the idle function. The only thing to remember is to be careful to avoid too complex idle functions, they can slow down your client. You can only have an idle function at time, another call to this function will replace the first idle_function with the new one.
Example:
idle_loops = 0
function myidle()
idle_loops = idle_loops + 1
if idle_loops > 75 and combat == false and is_afk == false then
idle_loops = 0
send("score")
end
end
idle_function("myidle")
This example will add an idle function to your client so that your character will perform the score command every 75 seconds, this may be useful for instance to update a status window, is_afk and combat are variables defined and updated elsewhere in your code.
You can access any non local LUA function from GGMud, this can be useful to embed LUA code in you aliases, to call a LUA function you have to prefix his name with the & character, you can then include function parameters in between braces, the function must be called with the correct number of parameters or you will get a LUA runtime error.
Example:
GGMud alias (provided you have three weapons called pierce slash blunt):
#action slash {&changeweapon(slash)}
#action blunt {&changeweapon(blunt)}
#action pierce {&changeweapon(pierce)}
LUA script (previously loaded via #script or at GGMud startup):
weapontype = "UNDEF"
function changeweapon(wt)
if wt == weapontype then
show("You are already using damage type " .. wt)
return
end
if weapontype="UNDEF" then
send("rem slash;rem pierce;rem blunt")
else
send("rem " .. weapontype)
end
send("wield " .. wt)
weapontype = wt
end