Scripting with Lua

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(mapargs)

The function 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.

By default the context is populated with keys lazily which can improve callback performance, but can make certain meta-operations a challenge such as deep table duplication or serialization. By accessing one of the members of the context listed below you will trigger the table to be populated. For most situations, this is completely transparent. Alternatively you can use a command line option to Lua to always pre-populate the table for Lua callbacks:

-olua,lazy_context=0

The following keys are available inside the context’s table but may be nil if not applicable for the context.

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
end
                 

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)
end
            

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))
end
            

Advanced Lua callbacks give developers more powerful ways to organize and architect their code into modular and well-encapsulated behavior. The Lua script action gra.lua has always been able to call global functions in your Lua scripts, developers have much more flexibility with their Lua function callbacks.

Advanced callbacks allow developers to invoke functions that are nested in other tables. This can be done with a . for tables or a: for Lua object methods where self is the first parameter. As long as the top-level variable is global, nested objects and functions can be found.

An advanced Lua function may look like parent.child.grandchild.func if the first parameter of the func function is mapargs, or like parent.child.grandchild:func if the first parameter of the function is self and the second is mapargs, where self is parent.child.grandchild in this example.

Selecting the ADVANCED entry will open the Advanced Lua Callback Function Wizard which allows developers to select an instance of a Lua Object and a method to invoke in the Lua Action.

Example Advanced Lua Callback Scripts

This section shows some snippets of code to define and create Lua objects and how to annotate them appropriately for Lua to be able to infer types of the variables in your scripts. To get more detailed information and examples of Lua code annotations, refer to.

scripts/callbacks.lua

This script has a global table that holds onto all the buttons of our application. The use of @field in this manner helps Storyboard to understand the contents of the buttons table and their types and provide more information back to the developer.

local ToggleButton = require("widgets.toggleButton")

---
--@type buttons
--@field widgets.toggleButton#toggleButton togglePower
--@field widgets.toggleButton#toggleButton toggleStar
buttons = {}

---@param gre#context mapargs
function CBInit(mapargs)
  buttons.togglePower = ToggleButton.new("Layer.power", false)
  buttons.toggleStart = ToggleButton.new("Layer.start", false
end

scripts/widgets/toggleButton.lua

This script is an example of a toggleButton class. An advantage of Object Oriented programming is that you can maintain state together with the functionality of the object. This module returns a table with a single method on it, new and it returns a toggleButton#toggleButton. This object created with new has a single method, press which takes two parameters, self and mapargs. Pressing an instance of a toggleButton will flip it' it's self.state and trigger "buttonUp" or "buttonDown" animation accordingly.

---@module toggleButton
local ToggleButton = {}

---
--@type toggleButton
--@field gredom#control control
--@field #table context
--@field #boolean state
local toggleButton = {}

--- Create a new toggle button
--@param #string controlName fully qualified name of control
--@param #boolean initialState the initial state of the button
--@return #toggleButton
function ToggleButton.new(controlName, initialState)
  local button = {}
  setmetatable(button, {__index=toggleButton})

  button.control = gredom.get_control(controlName)
  button.context = {context=controlName}
  button.state = initialState
  return button
end

---
--@param #toggleButton self
--@param gre#context mapargs
function toggleButton:press(mapargs)
  self.state = not self.state
  if(self.state) then
    gre.animation_trigger("buttonDown", self.context)  
  else
    gre.animation_trigger("buttonUp", self.context)
  end
end

return ToggleButton

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. Care should also be taken with Lua and asset file naming standards with respect to portability as some OSes are case sensitive whereas others are not.

It should be noted that in most OSes the filesystem directory API does not apply any ordering and only utilities like ls and dir apply sorting logic primarily for display purposes. When the Storyboard engine loads Lua files, it loads them based on unsorted content in a directory and hence to manage dependencies as mentioned above the use of Lua require() declarations is recommended good practice.

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

The asynchronous Lua support is provided in two fashions:

Lua Action: To create an independent Lua thread in response to an action, the user can add an 'async' parameter to any existing Lua script and it will automatically create and run that action outside of the main UI thread.

Lua Script There is a new Lua API call gre.thread_create() that takes a single parameter which is a function to execute. This function will be executed and scheduled to run in an independent thread of execution.

Threads are created using the system's underlying native operating system thread support. Operations are synchronized explicitly through locks in the Lua VM, however there is no explicit support for data synchronization (i.e. mutexes, condition variables)

The suggested communication pattern for inter-thread communication is to use Storyboard IO to inject event data into the system. This is similar to the idea behind LuaLanes or WebWorkers where inter-task communication is based on message passing.

Threads will be hard-terminated at exit. Clients should establish their own protocol where a soft shutdown is required to trigger any asynchronous threads to terminate.

The Storyboard Lua Debugger enables the developer to monitor the flow of execution of the Lua scripts used by the Storyboard application. Using the debugger it is possible to step line by line through a Lua script while examining the variable values that are being used by the Lua functions.

The Designer debugging environment communicates with the application's Lua script plugin using network sockets in a client/server model. The Storyboard application acts as the client and is controlled by the Designer debug environment which acts as the server.

Creating and launching the debug server is an automated process. To configure Lua debugging it suffices to take the following steps:

The first two steps are part of a one-time configuration required to set-up the simulator launch configuration. After the initial set-up, only the last step needs to be performed in order to launch an application with the Lua debugger running.

When enabling the Lua debugger you may find it convenient to create a second launch configuration for the same project with debug enabled. This will allow you to quickly switch from a development/debug simulation to a standard simulation. To enable the Lua debugger simply check the Enable Lua Debugger option associated with the Lua plugin options.

Once the Lua debugger is enabled, run the Storyboard application the same as you would a normal simulation.

This will launch the Storyboard application and at the same time initialize the debug client within the Storyboard application and the server running within the Designer environment. The two will connect automatically over a network socket and your application should immediately begin running. To confirm that the connection has taken place and the Lua debugger is running, check the output console for the following:

If you change to the Debugger perspective, the Debug view should look like this:

You are now able to start debugging your Lua code

The Lua debugger, when a breakpoint is activated will automatically switch to the Debug Perspective. This perspective provides an alternative layout of views that are specifically related to debugging activities.

Storyboard includes a few stand-alone Lua executables packaged for the convenience of customers who are working with Storyboard in environments where it is possible to use shell programs to interact with the environment, most notably Windows, Linux, Mac and QNX environments.