Quick start with Lua scripting

Lua is a lightweight, efficient and easy-to-learn scripting language and is one of the most popular scripting languages for embedding in applications to provide users with an interface to customize and control the application according to their own needs.

The main advantage of Lua is its simplicity and flexibility. Lua code is easy to understand and requires minimal programming skills to get started. A Lua script does not need to be compiled before execution. This allows for quick and easy customization of the code as needed.

In VxCraft, Lua is used for various areas such as settings, tool scripts and especially postprocessors.

Basics

Even though Lua is a simple scripting language, a complete documentation would go beyond the scope of this manual. Therefore, this chapter focuses only on the absolute essentials and provides a brief overview of the basics of Lua. Nevertheless, it should be sufficient to make your own adjustments to existing scripts and to create simple scripts yourself.

For more in-depth information on Lua, there are numerous online resources that are easily accessible.

In the script examples in this chapter, the vxPrint() function is used to output to the screen. vxPrint() is a function provided by VxCraft that is used to display content in the postprocessor console. It is important to note that this function is not a native Lua function, but was developed specifically for use in VxCraft.

Comments

Comments are an important addition in a script to make the code more understandable and to leave hints and explanations to other developers or even to yourself. In Lua there are two types of comments:

Single line comments

Single-line comments start with two hyphens (--) and extend to the end of the line. Lua ignores everything after the hyphens and does not interpret it as code.

local myvar = 1+2 -- This is a one-line comment after an expression

Multiline comments

Multiline comments start with --[[ and end with ]]. Everything between these marks is treated as a comment and ignored by the interpreter.

local myvar_a = 1+2 --[[
This is a multiline comment
and extends over
several lines.]]
local myvar_b = 2+myvar_a

Lua case sensitivity

It is important to note that Lua, like many other programming languages, is case sensitive. This means that case is distinguished in variable names, function names, and keywords. For example, the variables myVariable and MyVariable are treated as two different variables. Therefore, always make sure to use the correct notation to avoid errors and unexpected behaviors.

Variables and data types

Lua supports various data types such as nil, number, string, boolean, table, function and userdata. Variables do not need to be declared and automatically get the data type when they are assigned a value. For example:

Conditions and control structures

Conditions and control structures are fundamental elements of any programming language and allow you to control the program flow depending on conditions. In Lua there are several control structures, such as if-then-else, while and for loops.

if-then-else

The if-then-else structure in Lua is a control structure that allows you to execute different blocks of code based on one or more conditions. With this structure, you can control the flow of your program by providing alternative code paths depending on a particular condition.

The basic syntax of the if-then-else structure is as follows:

if Condition1 then
  -- Codeblock1 is executed if condition1 is true
elseif Condition2 then
  -- Codeblock2 is executed if condition1 is false and condition2 is true
else
  -- Codeblock3 will be executed if all previous conditions are false
end

The if-then-else structure begins with the if keyword followed by a condition that can be either true or false. If the condition is true, the code block is executed after the then keyword. If the condition is false, the code block is executed after the else keyword, if any.

The optional 'elseif' script block can be used to check additional conditions if the previous conditions are false. It is possible to use multiple elseif blocks in the if-then-else structure to check different conditions one after another. The structure ends with the end keyword.

The following table shows the comparison operators in Lua and their meaning:

while loop

A while loop is used to execute a block of code as long as a certain condition is met.

local i = 1
while i <= 5 do
  vxPrint("Value from i: ", i, "\n")
  i = i + 1
end

Value from i: 1
Value from i: 2
Value from i: 3
Value from i: 4
Value from i: 5

for loop

The for loop is another type of loop that allows a block of code to be executed for a specified number of iterations. Lua supports numeric for loops and generic for loops.

Numeric for loop:

local i = 1
for i = 1, 5 do
  vxPrint("Value from i:", i)
end

Value from i: 1
Value from i: 2
Value from i: 3
Value from i: 4
Value from i: 5

Generic for loop:

local t = {"red", "green", "blue"}
for k, v in pairs(t) do
  vxPrint("Key: ", k, " Value: ", v, "\n")
end

Key: 1 Value: red
Key: 2 Value: green
Key: 3 Value: blue

Functions

Functions are reusable blocks of code that perform a specific task. They can accept parameters and return values. Functions are useful for better organizing code and avoiding repetitive tasks.

To define a function in Lua, use the keyword "function" followed by a name for the function and parentheses containing the parameters. The function body is terminated by the keyword "end".

function printPosition(x, y, z)
  vxPrint("Pos X: ", x, " Pos Y: ", y, " Pos Z: ", z, "\n")
end

To call the function with the desired coordinates, use the function name followed by parentheses and the corresponding parameters:

printPosition(1, 3.5, 50.0)

Pos X: 1 Pos Y: 3.5 Pos Z: 50.0

The next example creates a function that rotates the X and Y coordinates of a position by a specified angle around the Z axis and returns the newly calculated coordinates.

-- Rotates x and y by the specified 
-- angle around the Z axis
function rotateZ(x, y, deg)
  local rad = math.rad(deg)
  local newX = x * math.cos(rad) - y * math.sin(rad)
  local newY = x * math.sin(rad) + y * math.cos(rad)
  return newX, newY
end

local pos_x = 10
local pos_y = 20
local pos_z = 50
printPosition(pos_x, pos_y, pos_z)
-- Rotates the coordinates by 45°
-- using the rotateZ function:
pos_x, pos_y = rotateZ(10, 20, 45.0)
printPosition(pos_x, pos_y, pos_z)

Pos X: 10 Pos Y: 20 Pos Z: 50
Pos X: -7.071 Pos Y: 21.213 Pos Z: 50

Script flow and function calls

This subsection explains the basic flow of Lua scripts and how functions are used. It is important to understand how Lua scripts are executed and how functions are used in this flow.

A Lua script is executed from the top down. This means that the code is executed in the order in which it appears in the script. However, if a function is defined in the script, it will not be executed automatically. A function will only be executed if it is explicitly called in the script.

Note that functions must be defined before they are called in the script. Otherwise, Lua will not be able to find the function and an error will occur. So make sure your functions are always defined before their first call.

Here is a simple example to illustrate these concepts:

--Variablen
local home_x = -200;
local home_y =  200;
local home_z =  100;

--Function which outputs a fixed defined home position
function printHome()
  vxPrint("Homeposition: ", 
           home_x, " ", 
           home_y, " ", 
           home_z, "\n")
end

-- Main part of the script
vxPrint("This is the beginning of the script.\n")
vxPrint("The following is the output of the home position:\n")
printHome()
vxPrint("after the output of the home position,\n"
        .."the script continues here.")
        
-- End of the script

This is the beginning of the script.
The following is the output of the 
home position:
Homeposition: -200 200 100
after the output of the home position,
the script continues here.

In this example the code is executed from top to bottom. First, the variables home_x, home_y, and home_z are defined, then the printHome() function is defined to output the predefined home position. Then the main part of the script is executed, calling the printHome() function to output the home position. Finally, the last line of the script is executed, stating that the script continues here.