Scripting with Lua

The Storyboard Lua API (Lua API) gives developers access to the Engine though a Lua scripting interface.  This API is a library of functions which allow interaction with the Engine by manipulating data and working with events and user interface components.  Through the Storyboard Lua API developers can:

Lua function parameters

Each Lua function invoked from the Storyboard is passed two arguments:

script_function_name( table mapargs, string allargs)

The first 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 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 current context (app, screen, layer, or control) that the event was targeted at


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.

The second argument, allargs, provides a string containing the exact same string that was provided to the data arguments of the action.  

Example of using context data:

function get_context( mapargs, stringargs )
  print("triggered by event : "..mapargs.context_event)
  print("event was targeting : "..mapargs[mapargs.context_target])
  print("stringargs : ", stringargs)

Passing extra parameters to lua 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’s name as the table’s index.

function my_lua_func (mapargs , allargs )
  local paramter1 = mapargs.paramter1
  print("my_lua_func was passed : ".. paramter1)

Storyboard Lua integration

Since Lua has a tight integration with the Storyboard, there are some additional functions that have been added to facilitate access directly to data in the Storyboard model without having to use the Storyboard IO communication channel to access data and generate events.

The complete Lua API can be found in the Storyboard Lua API section of this document.

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 behaviour in that it will pre-load all of the Lua scripts contained in the scripts directory at engine initialization time. This initialization will include executing any script elements that are not contained within function blocks. Since the load order of multiple files is not specified, scripts that require order dependant initialization should add a Lua callback action to the Application Start event (gre.init).

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.

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