Difference between revisions of "Lua"

From The Foundry MODO SDK wiki
Jump to: navigation, search
(Created page with "Lua is a configuration language commonly used in game development. Lua scripts are executed in the same way as Perl and Python scripts within ''modo'', and provide...")
(No difference)

Revision as of 14:40, 3 March 2012

Lua is a configuration language commonly used in game development. Lua scripts are executed in the same way as Perl and Python scripts within modo, and provide the same level of functionality.

For the official Lua documentation, visit http://www.lua.org .

modo Extensions to Lua

A number of new functions have been added to Lua in modo. The most common batch include lx, lxq, lxqt, lxeval, lxok, lxres, lxout and lxtrace. Errors are reported to the Event Log Viewport, so it’s useful to have one open while developing Lua scripts.


The lx function is used to execute commands using the standard modo command syntax. This returns 1 if the command executed successfully, and nil if it failed for any reason. lxres can be used to get more specific information about why a command failed. Also be sure to check the Event Log viewport.

 -- lua
ok = lx( "tool.set prim.cube on" )
     -- handle errors here


The lxq function queries a command using the standard question mark syntax, returning a table of values. Note that this always returns a table, even if there is only one value in the table. Table keys are simple indices starting from 1. table.foreach can be used to walk the array, or a simple for loop can be used. If there was an error querying the command, nil is returned.

Via table.foreach:

 -- lua
 function ProcessSelMaterialNames( index, name )
     -- Process material names here
 -- Get an array of names, one for each selected material
 selMaterialNames = lxq( "material.name ?" )
 table.foreach( selMaterialNames, ProcessSelMaterialNames )
 -- Just look at the first value in the array.
 firstValue = selMaterialNames[1]

via a form loop:

 -- lua
 -- Get an array of names, one for each selected material
 selMaterialNames = lxq( "material.name ?" )
 table.foreach( selMaterialNames, ProcessSelMaterialNames )
 -- Just look at the first value in the array.
 for k in pairs(selMaterialNames) do 
     -- Process 'k' (the material name) here


The lxqt function queries ToggleValue commands like tool.set, returning a simple true or false value. lxq can be used to get the current actual value of a ToggleValue command, which can be of any datatype and can be one of a number of possible values depending on the command. lxqt can be used to more easily see if the commands is "on" or not. This example checks to see if the Cube tool is currently active.

 -- lua
 isActive = lxqt( "tool.set prim.cube on" )


The lxeval function is a hyrid of lx and lxq. If the command string contains a question mark, the command will be queried and returned; otherwise, the command is executed and success or failure is returned. As with lxq, querying with lxeval will always return a table.

 # lua
 -- Execute
 lxeval( "user.defNew MyValue" )
 lxeval( "user.value MyValue {Test Value}" )
 -- Query
 value = lxeval( "user.value MyValue ?" )
 if value[1] then
     -- Do something here

lxok() and lxres()

The results of lx, lxq, lxqt and lxeval can be tested with lxok and lxres. lxok returns 1 if the last call was successful and 0 if not. lxres returns the LxResult code, which provides more specific details about result of the commands execution. A list of standard result codes and their meanings can be found in the error codes message table, resource:msglxresult.cfg

 -- Lua
 isOK = lxok
 result = lxres


The lxtrace function toggles tracing on and off. When tracing is enabled, all commands executed or queried by lx, lxq and the other execute/query functions are output to the Scripting sub-system of the Event Log viewport. This can also be used to see if tracing is on or not by not passing in an argument.

 -- perl
 isTracing = lxtrace()
 lxtrace( 1 )              -- Turn on tracing


The lxout function can be used to output debugging information to the Scripting sub-system of the Event Log viewport, and can be any string.

 -- lua
 lxout( "My Debug Output" )

Here's another example that outputs the first element of a table representing the number of items in a scene through lxout.

 -- lua
  n = lxq( "query sceneservice item.N ? all" )
  lxout( n[1].." items in scene." )

lxoption() and lxsetOption()

The lxoption and lxsetOption functions allow the script to set properties that determine how the other lx functions operate. Each option is defined by a tag string and an associated value, and the options can be changed at any time.

Currently there is only one tag defined, queryAnglesAs, which determines if angles queried through lxq are returned in radians or degrees. This defaults to degrees to maintain backwards compatibility with previous versions of modo. While this behavior is helpful for new scripters, it is generally more useful to work in radians. The value can be set to either radians or degrees, and once set all future queries on angles through lxq will return those units. The following shows how to change this option and query its current state.

 -- lua
 lxsetOption( "queryAnglesAs", "radians" )
 lxout( lxoption( "queryAnglesAs" ) )


Arguments passed to a Lua script are handled in the same way as they are in a stand-alone Lua script. The global arg table contains all of the arguments, as well as the name of the script at index 0, which is standard Lua practice.

This simple example outputs all of the arguments to the Event Log. Remember that there will always be at least one argument at index 0 representing the name of the script being run.

 -- lua
 for k,v in pairs(arg) do
     lxout( "Arg "..k..": "..v )

Progress Monitors

Progress bars, or monitors, are also supported in Lua through the lxmonInit and lxmonStep functions.


To initialize the progress bar, call lxmonInit with the total number of steps in the bar. lxmonInit should be called only once per script.

 -- lua
 lxmonInit( 20 )


To step the progress bar, use lxmonStep. By default, this increments the bar one step, but you can also increase the bar by an arbitrary number steps.

 -- lua
 lxmonInit( 20 )
 lmonStep()        -- Increment by one
 lxmonStep( 2 )   - Step the progress bar by two

The return value of lxmonStep is used by the script to determine if the hit the "abort" button in the progress dialog. If lxmonStep returns false, the script should abort. The following is a common test for a user abort.

 -- lua
 -- Initialize the monitor
 lxmonInit( 20 );
 for i = 0; i < 20;  i++ do
    -- Do work here
    -- Step the monitor and check for an abort
    if !lxmonStep()  then
        -- Do clean-up here
        error "User Abort";

Monitor Example

This simple script demonstrates progress bars through the use of monitors. It busy loops so the progress bar will open. If the script executes fast enough, the progress bar will not appear.

 -- lua
 -- Initialize the monitor with 20 steps
 lxmonInit( 200 );
 -- Loop through our 200 steps 
 for i=0,200 do
     -- Do work (i.e.: busy loop )
     for j=0,1000000  do
     -- Step the monitor and check for an abort
     if !lxmonstep() then
         -- Clean up and exit
         error "User Abort";

More Information