Moving Light Assistant

Scripting Tutorial

LUA Language and Syntax

Before we start, we will cover some basic LUA syntax and specific Moving Light Assistant functions. LUA is a scripting language used in a wide variety of applications. You can find out more at: www.lua.org

It is worth noting that on Mac OS X some text editors will do clever text replacement as you type. This can cause issues with LUA and will result in scripts failing with an unhelpful error message. The common text replacements are the double quote characters(“). This is often replaced with opening and closing double quotes like “my text”. LUA will only accept plain double quote characters i.e. (“). The same is also true for single quote characters i.e. ‘my text’. Using two dash characters one after the other, which is used in LUA to indicate a comment, are often replaced with a single long dash. This will throw up an error in LUA. The script editor in MLA will not perform any text replacement/substitution as you type.

For details of the Moving Light Assistant specific functions, classes, and options, please visit the scripting documentation Wiki at www.wiki.movinglightassistant.com/wiki

Comments

Comments are a way of adding your own notes in the code so that they are not treated as actual code to be processed. To comment, a line in LUA it should start with --. For example:

-- This is my comment in the code

Commenting a line of code is also a useful way to disable a line of code. For example:

-- io.write("write out something")

Within Moving Light Assistant, there are some special comments to set options as to how the script may be triggered, or if an output window should be opened.

-- TriggerType=Menu
DisplayOutputWindow=True

Variables

Variables are a temporary place to store data. Variables in LUA do not have to be defined before they are used. When you assign a value to a variable it is created at that point in the code and can be used from then on. For example:

myNumber = 1
myText = "MLA"

Here we have created two variables. One is called ‘myNumber’ which is assigned the numeric value of 1. The other is called ‘myText’ and is assigned the string ‘MLA’. Strings in LUA are wrapped with either double or single quotes. 

firstNumber = 5
secondNumber = 6 
finalNumber = firstNumber + secondNumber

In the example above, you will see how we can do some maths using variables. firstNumber is assigned the value 5, secondNumber is assigned the value 6. The finalNumber variable will be assigned the result of adding the variable firstNumber and secondNumber together. In this case, the variable finalNumber will have the value 11 ( 5 + 6 = 11).

If we just want to add say 1 to the value of a variable, the long way of doing this would be:

firstVariable = 6
secondVariable = firstVariable + 1
firstVariable = secondVariable

Variable firstVariable would now have a value of 7 (i.e. it is now 1 greater than it was before). Thankfully there is a quick way of doing this.

firstVariable = firstVariable + 1

String variables are a little different. You cannot add strings together with the + character (called an operator). You have to use what is called the concatenation operator. In LUA, this is the double dot (..) For example:

myText = "Hello" .. " World"

The above line would result in the variable myText with the string “Hello World”.

As we did with numeric variables, if we want to add a string to the end of an existing string variable we would use:

myText = "Hello" 
myText = myText .. " World"

Functions

A function is a named section of a program that performs a specific task. A function can be considered a procedure or a routine. LUA and Moving Light Assistant have a set or predefined functions you can use in a script. It is also possible to define your own functions. These should generally always be done at the top of the script. Only once a function has been defined can it be used. To define a function, you use the syntax:

function NameOfFunction(parameters) 
    -- The code you want to execute 
    myVariable = 1
    return myVariable
end

A function must have a unique name (which should not be the same as LUA functions or reserved words). A function can optionally have parameters that are passed to the function when it is called in the code. A function can also return a value at the end. When a function is called from a script, it will simply execute the code in the function.

Note the function keyword to show the start of the function definition, and the end keyword to indicate the end of the definition. It is common to tab in the lines of code within the function for easier reading of the code.

function PrintMyName()
    io.write("MLA")
end

The above is a simple function definition. It defines the function PrintMyName. It has no parameters. This is indicated by the (). The code to execute, writes out to the output window “MLA” (more on the io.write function later). This function could be called in the script by simply having the line:

PrintMyName()

If you want to pass some parameters and get a result back:

function AddNumbers(a, b)
    c = a + b
    return c
end

This function accepts two parameters, which are created as variables, in this case ‘a’ and ‘b’. The values are added together and assigned to variable ‘c’, then we return the value of ‘c’ at the end of the function. This could be called:

varA = 5 
varB = 7
varC = AddNumbers( varA, varB )

LUA Library Functions

There is a library of functions you can call within LUA. It is best to read the LUA documentation at www.lua.org for details. One of the most common functions you will see in Moving Light Assistant scripts is the function io.write.

io.write will write out to the output window the parameters passed to it. A parameter can be a string or a number. Multiple parameters can be passed, but they must be separated by commas.

io.write("M", "L", "A") 
io.write("MLA")

Both the io.write calls above will give the same result. The first is just to show how to pass multiple parameters. If you wish to add a return or new line to the output of io.write, you should add a new line character. This is indicated by "\n". There are several characters like this that have special meanings. You can research further if you wish to know more. 

io.write("MLA", "\n")

Will write out MLA and a new line, so the next call to io.write will appear on a new line. If the "\n" was missing, the next io.write call would write out on the same line as the previous call.

You can use io.write to write out the value of variables.

myText = "The Variable has a value of " 
myNum = 5
io.write(myText, myNum, "\n")

The output of this would be: “The Variable has a value of 5”.

Moving Light Assistant Library Functions

Moving Light Assistant library functions are documented on the Moving Light Assistant Wiki. Many of the functions are part of a class (a grouping of functions). For example, one of the classes is the OSC class. Functions within the class are accessed with the colon separator. For example:

OSC:EOS_SendKey("1")

This is calling the EOS_SendKey function of the OSC class.

Some of the commands you will see commonly in the example scripts are:

OSC:EOS_SendNewCommandLine

If you type the following into the script editor:

OSC:EOS_SendCommandLine("Chan 1 Thru 5#")

Now when you run the script, you should see the “Chan 1 Thru 5” on the command line completed. The # is to indicate a terminated command (i.e. like you pressed Enter). The # is optional, but you would then have to terminate the command yourself. This function will clear the command line (and the channel selection) before the command.

OSC:EOS_SendCommandLine

If you type the following into the script editor:

OSC:EOS_SendCommandLine("Chan 1 Thru 5#")

Now when you run the script, you should see the “Chan 1 Thru 5” on the command line completed. The # is to indicate a terminated command (i.e. like you pressed Enter). The # is optional, but you would then have to terminate the command yourself. This function will append to the command line in the same way as if you typed on the console. So you could do the following with a combination of EOS_SendNewCommandLine and EOS_SendCommandLine.

OSC:EOS_SendNewCommandLine("Chan 1 Thru 5#")
OSC:EOS_SendCommandLine("At Full#")

OSC:EOS_SendKey

This OSC command enables you to send a key push in the same way a user or macro can push keys. Note that some key names are not really the same as they are physically on the button key caps. To achieve the same “Chan 1 Thru 5#” on the command line using keys, you would type the following (into the empty script editor):

OSC:EOS_SendKey("1")
OSC:EOS_SendKey("Thru")
OSC:EOS_SendKey("5")
OSC:EOS_SendKey("Enter")

When you run the script, you will see it type the command on the command line of the console (and hopefully channels 1 thru 5 are selected).

This command does actually send a key down OSC message and a key up OSC message. If you wish to only send a key down, or key up, then use:

OSC:EOS_SendKeyDown("Data") 
OSC:EOS_SendKeyUp("Data")

The data key is used just as an example.

Wait

The Wait function is not part of any class, hence there is no colon separator. The Wait function accepts a numeric parameter which is the number of seconds you want the script to stop and wait for.

Wait(1)

To wait for 1 second, or

Wait(0.5)

To wait for half a second.

Conditional Statements (Making Decisions)

Often in a script you will want to decide that if certain conditions are met, you do one thing, otherwise you do something else. In LUA, like many programming languages you use the “if then else” language syntax.

If condition is true,
then do this,
else do that
end

Else is optional so you can do:

If condition is true,
then do this
end

The condition will be evaluated if it is true. If it true, the code following the then statement will be executed until the else (or end, if there is no else statement). If the condition is evaluated to be false, the code after the else statement until the end statement will be executed. If there is no else statement, the code will just continue from after the end statement.

if varA > varB then 
    io.write("Variable A is bigger")
else 
    io.write("Variable B is bigger")
end

Evaluating the condition will either be true or false. The comparison (relational) operators are:
> greater than.
>= greater than or equal to.
< less than.
<= less than or equal to.
== is equal to. (Note it is a double == sign. A single = sign would be treated as a variable assignment.)
~= is not equal to.

Looping

If you want to loop through the same piece of code, you would use the “while do” statements.

while condition is true do
Do this
end

For as long as the condition is true, it will loop through the code after the do statement and before the end statement. Each time it encounters the while statement it will evaluate the condition. When the condition is false it will no longer run the code after the do statement but will jump to the code after the end statement. For example:

counter = 1 
while counter <= 10 do 
    io.write("Counter = ", counter, "\n")
    counter = counter + 1
end
io.write("Finished counting.", "\n")

The counter variable is incremented on every pass through through the code. Eventually counter will have a value of 11, at which point the condition count <= 10 will evaluate to false.
In the example above, a common mistake when writing your own loops is to forget counter = counter + 1. If you do forget this one line, your script will be stuck in a loop forever as the counter variable would never be incremented. A script that is in an endless loop may cause Moving Light Assistant to become unresponsive.

Was this helpful?

Yes No
You indicated this topic was not helpful to you ...
Could you please leave a comment telling us why? Thank you!
Thanks for your feedback.