Lua is a powerful, fast, lightweight, embeddable scripting language. Lua scripts can be used anywhere in Helm, in place of ‘classic’ Helm scripting. Lua scripts bring significant power and flexibility to Helm including the following features.

See also an update on this article here //

  • Conditionals: if… then … else …
  • Loops: ‘for’ and ‘while’ loops
  • Subroutines : Write re-useable code sections.
  • Stored variables
  • I/O : Read and write files
  • XML processing : Use XML files for additional system configuration

You can learn about Lua from and from these books below

Lua modules provided with Helm include LuaXML and LuaFileSystem.

To enable Lua scripting in Helm, either set the root panel’s “LuaScripting” = true (all scripts must now be written in Lua), or place a “–lua” comment line at the beginning of each Lua script. This allows mixing of Lua and Helm ‘classic’ scripts in the same panel. Note that you can’t mix languages within a single event script – the entire script is treated as either Lua or ‘classic’ script.

There are three Lua extensions to allow scripts to interact with Helm components: helm.get, helm.set and helm.exec.

  • helm.get(object, property) – return value of a property.
  • helm.set(object, property, value) – set an object’s property to a value
  • helm.exec(object, action , params…) – execute a helm objects’ action. Any number of parameters can be passed.

Example 1:


--make the label font size 4 points larger.

local oldsize = helm.get("LABEL_1","Font:PointSize")

helm.set("LABEL_1","Font:PointSize", oldsize + 4)

Example 2:


--Use the root panel's RunScript action to run a script from a file
--This is equivalent to the Helm script line RootPanel:RunScript(myfile.txt)

helm.exec("RootPanel","RunScript", "myfile.txt")


When passing parameters to Helm functions with helm.exec you can use literal strings, variables, or computed values.

The following should all have the same effect of setting a label’s text to “123”

local f = "123"
local g = 100 + 23

helm.exec("LABEL_1","SetText","123") -- literal
helm.exec("LABEL_1","SetText",f) -- variable string
helm.exec("LABEL_1","SetText",g) -- variable number 
helm.exec("LABEL_1","SetText","1" .. "2" .. "3") -- concatenated string

Helm automatically to convert strings to integers and vice-versa as required, but where  a  command requires “Enumeration” parameters they must be passed as a string. An example of this is the Label’s SetAlignment command:

helm.exec("LABEL_1","SetAlignment", Left) -- FAILS 
helm.exec("LABEL_1","SetAlignment", "Left")  -- OK

local align = "Left"
helm.exec("LABEL_1","SetAlignment", align) -- OK

Converting scripts using Helm ‘Variables’ to Lua

Standard Helm scripting allows you to use the current value of any object property as a parameter. To do the same with Lua, you must use Helm.get to read the current value.


In Lua, this becomes

local v = helm.get("FADER_1", "Value")
helm.exec("LABEL_1", "SetText", v)

Or more concisely…

helm.exec("LABEL_1", "SetText", helm.get("FADER_1", "Value"))

If you pass just one parameter to helm.exec, then it’s treated as a ‘wrapped’ classic script line, so you could also convert the above script to Lua like this.