Lua Action Callback Function

When a Lua callback function is invoked by the Lua action it will be invoked with a single parameter as in the following prototype:

script_function_name(table mapargs)

The argument mapargs, is a Lua table whose keys provide the context in which the action is being invoked along with any action specific argument and parameters.  This context includes the application, screen and control the action was associated with, the currently focused control, any arguments provided to the action as well as all of the event data that cause the action to fire.

The following keys are always available inside the context’s table:


The application context of the current action


The screen context of the current action (the current screen)


The layer context of the current action (the current layer)


The group context of the current action (the current group)


The control context of the current action (the current control)


If the context_control is a table then this is the row index of the current cell


If the context_control is a table then this is the column index of the current cell


The fully qualified name of the model object that invoked the action. If that object is the application, this will be the empty string.


The name of the event the triggered the action


A pointer to a Lua table containing any event data. The event data is different for each event and is defined in the event definition.


A Lua type called 'context' has been defined inside Storyboard's custom Lua module 'gre' to represent the mapargs object for the purpose of auto completion inside the editor. However since Lua is untyped by default, a Doxygen comment describing the mapargs parameter must be added to a function in order to get auto completion on it, as follows:

--- @param gre#context mapargs
function CBMyFunc( mapargs )
    -- I now have auto completion on mapargs

Functions created by Storyboard will automatically be prepended with this comment.

Example of using context data:

--- @param gre#context mapargs
function CBGetContext( mapargs )
    print("Triggered by event : " .. mapargs.context_event)
    print("Event was targeting : " .. mapargs.active_context)

Passing Extra Parameters to Functions

Lua actions are identified using an action type of Lua and setting the specific Lua function and extra parameters (if required) in the action arguments.  Any extra parameters will be transferred directly to the Lua function through first argument (a Lua table) and the data can be accessed by using the parameter name as the table index.

--- @param gre#context mapargs
function CBUserParameter( mapargs )
    local p = mapargs.paramter1
    print("my_lua_func was passed : ".. tostring(p))

Lua Execution Environment

The Storyboard Engine Lua plugin provides a slightly different execution environment when compared to normal Lua script execution.

Normally a single Lua script serves as the starting point of script execution and all other scripts would be included using the Lua require() declaration. The Storyboard Lua plugin provides a slightly different loading behavior in that it will pre-load all of the Lua scripts contained in the scripts directory at engine initialization time. The load ordering can be controlled by using the require statement to explicitly order dependencies. Since the require mechanism is used to perform the loading, any project files that use the same names as built-in Lua modules (i.e. table.lua, string.lua or io.lua) will generate a load time warning indicating the potential load time resource collision.

A side effect of this early module loading and execution is that any Lua script that is located outside of function blocks will have the opportunity to run before the application is fully initialized. This can be used to seed early execution environments or load preferences before the UI is in place and ready to render. Alternatively, this early initialization is possible by binding a callback to the gre.init event.

In addition to loading all of the script files in the scripts directory, the Lua plugin modifies the package.path variable and ;; default search path to automatically search the scripts directory.

A convenience variable, gre.SCRIPT_ROOT is pushed into the execution environment that contains the path from the current working directory to the scripts directory. This variable can be used to locate additional resource files or to include extra script directories in a manner that is relative to the overall deployment bundle. Each seperate path is delineated by a single ';'.

print("Script base directory: " .. tostring(gre.SCRIPT_ROOT))
-- Look for additional module files in the scripts/modules directory. 
-- This will search the added directory first
package.path = gre.SCRIPT_ROOT .. "/modules/?.lua;" .. package.path



Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request



Please sign in to leave a comment.