Lua tutorial

Lua (or RCLua, when used in RigidChips), is a way to make your models do things on their own, react to there surroundings and themselves, and display information. It takes the form of a simple code, easy enough to learn. As with any code, programming or scripting language, it is useful to set it out neatly. A common way is to indent every level of code with [Tab].

If you are using RCD, then you can just start typing the Lua directly into the Lua section. Otherwise, Surround the Lua in Lua{ and }

Functions
The first thing you need to know about in RCLua are functions.

In every model using Lua you need to have either function main or the three On* functions.

In function main, every line of code is executed once per frame. It is a more basic way to use RCLua.

The On* functions consist of three different functions, but you need to use all of them for the script to run correctly. The functions are: function OnInit function OnReset function OnFrame

OnInit
function OnInit is executed on the first frame after you load the model from file (via Open or [Ctrl]+[O] or [Ctrl]+[U]). This function is typically used to set variables.

OnReset
function OnReset is executed on the first frame after you reset (via [U] or [R]) the model. Usually, this is the same as function OnInit.

OnFrame
function OnFrame is like function main in that it is executed every frame. The OnFrame has higher priority than main, meaning that if there are both OnFrame and main in the same file, main would not be called.

Extra functions
To add extra functions, you must type: function [NameOfTheFunction]

Then, to execute this function, you must write [function] in another executed function.

e.g. Lua{ function example end function main example end }

Absolute Statements
The simplest thing you can do in Lua is create an absolute statement, or something that happens no matter what, as long as the function it is in is executed. This is done by saying [Variable] = [value] {operator} [value]

e.g.

ELEVATOR = ROLL + PITCH

The operators are = + addition - subtraction / division ^ to the power of
 * multiplication

As with most things, surrounding something in brackets tells the Lua to perform that operation first. e.g. ELEVATOR = (ROLL + PITCH) * 2 is equivalent to ELEVATOR = ROLL * 2 + PITCH * 2

=='If' statements

The next thing you can do is create a statement that only happens if something is happening, or while something is happening.

The basic if statement is :

if [logic statement] then [code to execute] end

e.g.

if MODE == 1 then ELEVATOR = ROLL + PITCH end

The logic comparers are = == is equal to =~ is not equal to < is smaller than > is greater than <= is smaller than or equal to >= is greater than or equal to

NOTE: "==" Checks equality, "=" forces it. In other words, "==" is used in logic statements, and "=" is used to alter variables. This is very important, as it may affect the operation of your vehicle.

You can also combine logic statements, using {and} or {or}

e.g.

if MODE == 1 and GEAR > 0 then ________ end

In this case, if MODE is one, and the gear value is larger than zero, it will execute the command.

if MODE == 1 or GEAR > 0 then ________ end

In this one, if MODE is one, OR the gear value is larger than zero, OR both, it will execute the command.

After the [if True statement]s, you can add in else, or elseif.

Like this (for else):

if [logic statement] then [code to execute if logic is true] else [code to execute if logic is NOT true] end

Or like this (for elseif):

if [logic statement1] then [code to execute if logic1 is true] elseif [logic statement2] then [code to execute if logic2 is true] end

Or like this (combined): if [logic statement1] then [code to execute if logic is true] elseif [logic statement2] then [code to execute if logic2 is true] else [code to execute if ALL logic is NOT true] end

NOTE: You can use "elseif" as many times as you want, but "else" can only be used once.

e.g.

if MODE == 1 then ELEVATOR = ROLL + PITCH else RUDDER = YAW + ROLL end

Here, if the MODE = is one, then the ELEVATOR is the roll plus the pitch, but if that is NOT true, the RUDDER = YAW + ROLL.

if MODE == 1 then ELEVATOR = ROLL + PITCH elseif GEAR > 0 then RUDDER = YAW + ROLL end

Here, if the MODE = is one, then the ELEVATOR is the roll plus the pitch, but if that is NOT true, AND the GEAR is greater than zero, the RUDDER = YAW + ROLL.

NOTE: if statements can be stacked multiple times. Functions can also be executed in if statements.

'While' Loops
A while loop is another type of loop, controlled by a single logic comparison.

The syntax is:

while [logic comparison] do [code here] end

It is a pretty simple function to understand, seeing as it is so easy to read!

An example would be:

Lua{ local count = 0; local hiddenValue = 34; local found = 0;

function count(max) while(count < max) do          if(count == hiddenValue) then found = count; end

count = count + 1; end

if(count >= max) then count = 0; end end

function main count(100); out(0, "The hidden value found is "..found.."!"); end }

Note: Strings cannot be joined with a + sign in Lua. Instead, use a double period/full stop: ..

Don't be intimidated by this code, it's not as complicated as it looks! First off, we start by creating a local variable. A variable is a number that you can change within the code to whatever you want. They can also be character strings (Such as "Hello World!") or Boolean values (Either true or false).

I made a variable called count, which is created with a value of 0. Notice how I made it outside of the main function, because the main function is called every frame, therefore the value would be set to 0 every frame if it was in the main function! Then is my function called count. It takes a single argument, in this case a number called "max". When a function takes an argument, you pass it that argument by calling the function like this: foo(bar); Where foo is the function, and "bar" is the argument.

Inside that function, I have my while loop. Inside that while loop, I have the code to be executed if "count" is less than "max". What that code is doing is checking whether the count value is equal to this "hiddenValue". If it is, we set "found" to the value of "count", therefore the value of "hiddenValue"! Follow me? =P

If not, we increment "count" by one so the loop can go back around and check again.

Also in that function is a check to make sure count doesn't go above the max value we specified, in this case 100. If it does, it gets set back to 0.

Only thing to do after that is call the function inside main. I do this by writing "count(100);". This calls count and sets "max" to 100. Then I output the hidden value using out.

The syntax is:

out(lineNumber, "text");

Simple, eh?

'For' loops
A very important ability in Lua is to call the same function multiple times per frame. This is especially useful in things like chainguns, radar and some other models.

The basic format for a for loop is this:

for [declaration] do [code here] end

The [declaration] usual looks like this:

[variable] = min,max,increment

The [variable] is a new local variable, that is created by the for loop and changes during each frame. It is only usable inside the loop.

for i = 1,5 do      out(i,i+2) end

returns:

line1: 3 line2: 4 line3: 5 line4: 6 line5: 7

The for loop will perform the code inside it multiple times per frame, (max-min)/increment times. The variable, in this case "i", changes each time the code is performed. Basically, it is this: 1) The variable starts as [min].  2) [code] is performed. 3) [increment] is added to the variable (default is 1 if left blank)  4) Repeats steps 2-3 until the ariable is over [max].

for j = 1,5,2 do      out(i,i+2) end

returns:

line1: 3 line2: line3: 5 line4: line5: 7

AS another example, we will try to script a 3D line contrail/cord.

timer = 0 x,y,z = {},{},{}

function cord

x[timer] = _X(0) y[timer] = _Y(0) z[timer] = _Z(0)

_SETCOLOR(16711680)

for tdisp = 1,timer do          _MOVE3D(x[tdisp],y[tdisp],z[tdisp]) _LINE3D(x[tdisp-1],y[tdisp-1],z[tdisp-1]) end

timer = timer + 1 end

Im guessing some of this looks like nonsense to you. First off, tables. To create a table, you create a variable and instead of assigning a number, boolean or string to it, you assign a table value, or "{}". Then, to call or assign a specific value, you use the "[]" brackets. You contain the assigner in the curly brackets, this can be either a number or "string" value.

Example:

table["any_value"] = 6 table[7465] = true table["another_string"] = table[7465]

The next thing you may/may not know is 3D lines. They are pixel wide lines that are drawn in the RC world, often used as "targetting lasers".

_SETCOLOR(col) _MOVE3D(x,y,z) _LINE3D(x,y,z)

_SETCOLOR Takes the decimal version of a #****** 6 digit hex color code, and sets the color for all lines after it is called. _MOVE3D Sets the start position for the line. _LINE3D Sets the end position for the line and draws it. It also sets the start possition for the next 3D line. (can be overwritten with _MOVE3D)

function cord works by setting up a table for the X,Y, and Z co-ordinates every frame. Then, the function stores the co-ordinates every frame in these tables. Then, it sets the color for the line to red. Finally, it uses a for loop to set the line starting position at the very first position, the draing to the next. This repeats until the end of the line is reached.

Another function that works well with for loops is _G[]. _G[] is for calling a variable (or chipname). It takes "strings" and/or numerical values as its input.

Example:

for i = 1,4 do      local gunangle = {} gunangle[i] = _G["GANG"..i]  end

Where GANG1, GANG2, GANG3, GANG4 are variables defined in the VAL section of RCD. Seperate inputs are seperated with ".."

End
This is most of what you need to start scripting using Lua in RC! Have fun!