Lua for GrandMA3 Episode 1 - Functions and Data Types

 Hey lighting folks! The following is the transcript from my YouTube video, Lua for MA3 Ep 1 - Functions and Data Types

This is the first video in my Lua for GrandMA3 Tutorial series. Please check out my channel, From Dark To Light, on YouTube, and you can find the code to go along with my tutorials here on GitHub.

Hello lighting people, welcome back to my Lua for GrandMA3 tutorial series! In this episode we're going to be talking about Lua functions because functions are the backbone of code; you cannot have readable code without a function, so let's dive in.

I'm going to open up Visual Studio Code and make sure I'm in my folder, create a new file. This file is going to be called Ep 1 - Functions and Data Types, because that's what we're talking about today, and always put “.lua” at the end of your file name. I'm going to start by making a main function; so the way you make a function is, type “function” and give it a name. I'm just going to call it “main,” and then you put parentheses. VS Code automatically completes your parentheses so you can type inside of them, but just type another one at the end to end it and then I'm going to hit enter twice and type “end;” that's how you end the function and then “return main,” so what this does is when the code interpreter goes through and reads the code it finds this return and goes, “oh, okay so we have to return ‘main.’” Main is a function, so it calls the function and whatever is in the function gets executed at that point.

Now, as I said this code gets read whenever it is returned. There is another way that you can call a function and that is by, well calling it rather than returning it, so let's say now… I have to have a main function to start with, but within this I can have another function, so let's say I have another function called “example,” and this one ends and then down here I want to call the function. I'm going to do so by typing “example()” and that calls it, but you might wonder what the parentheses are actually for, so what the parentheses are for is to specify an argument. Whenever you create a function you can put arguments in the parentheses that then are used in executing whatever is inside the function. That will make more sense later, but for now with these kinds of functions you can just put empty parentheses and you don't really need to be making functions at the moment anyway so we'll get into that at the right time. Until then I'm going to talk about data types.

You have to understand variables and data types in order to get started in Lua. So a variable is a container that holds data. When you declare a variable you can determine what data it holds. This will stay the same until you overwrite it. A variable's name can be anything but cannot contain special characters and cannot start with a number, but can contain a number. Variable names are case sensitive, so to show you an example of that I can name a variable “myVar;” if I call this I have to capitalize the V and nothing else because it that's how it was set and so that is the name of the variable.

I cannot name a variable “1my…” - that doesn't work, but I can name it My1Var; so it can contain a number, it just can't start with a number.

Now there are three important data types in Lua: strings, numbers, and booleans. I'm going to create variables with a different data type so that you can see how they work; so I'm going to create a string and a string is absolutely anything you can type, just put it in quotes. So single or double quotes will work but for neatness I prefer to use single quotes. You cannot use the same type of quotes inside one another, so let's say I'm going to set this string to ‘My string says ‘ - I can't put another set of single quotes to use quotes, but I can use double quotes. So, ‘My string says “hi”’ so that works. It will interpret it as text but you can't use multiple sets of single quotes inside of single quotes. There is another option; if you absolutely have to, you can use the backslash as an escape symbol so then that escapes it and it gets viewed as text, and then go “hi,” back slash again another single quote, that works, it's just not very easy, so it's easier to use whatever type of quotes you don't want to use inside your string.

A string always stays exactly the same as you typed it and when strings are compared they are case sensitive so when I look at the string it's always going to have a capital M and it's also going to have a space at the end. If a string contains only a number it will still be read as a string, however, unless you convert it to an integer. So what is an integer? Well, a number can be any number and it can include a decimal point, mathematical operators, and so on. Trailing zeros after a decimal are cut off though and that's very important to our work with MA3 as you'll see. So I can set my number to be 1.31 but if I want to set it to 1.310 when I call it it's only going to be read as 1.31. That is critical to understand when working in MA3 because we have executor numbers that are labeled 301 through 315; actually, and beyond that, but the main ones that we use are 301 through 315, and so if I try to do 310 and I try to plug that into my console, my console is going to go, “Page 1.31? What? I don't know what that is,” and it's just going to throw an error, so in that case you would have to use a string because if you put, and I'm going to create another one, “string2,” if you put it in quotes it's not going to cut off that zero, it's going to look like this.

So the other type of value is a boolean. A boolean is either true or false, so my boolean can be true or it can be false. When you compare two things to another the returned answer that you get will be a boolean but you can also set a variable to a boolean if you need to, and you'll understand more about that later when we start using it.

The one other thing I do need to talk about is nil. So nil is nothing. myVar equals nil, nil is absolutely nothing. If you try to compare something to nil you'll always get an error. It will just be like, “I can't con- I can't concatenate a nil value,” or whatever. Instead, if you have a variable that could be nil you'll have to first say, “if the value is valid then do this.”

So now that you understand data types we're going to go back to functions. With this main function that I have I'm going to call an MA3 function, Printf, which requires a string as an argument. So Printf is the name of the function and then I get to put a string in these parentheses and whatever string I put in here will be used to execute the Printf function. In this particular case the Printf function takes my string and prints it in the system monitor and the command line history. So I'm going to type “Hello World” and I'm going to take this and copy it and paste it into this plugin right here, save, and when I run it it says “Hello World” in both of these places.

Now I can also put a variable in place of the string as long as I first declare the variable with a string. So I can turn this string into “Hello World” and then instead of this string here I can put “string” the variable, no quotes, and when I plug that into MA3 it is going to do the same thing. Now the reason for this is because my variable “string” is equal to “Hello World” so whenever it sees variable “string” it just replaces it with “Hello World,” now just to show you how this is working behind the scenes I'm going to do an example of making my own function with an argument built in.

This is going to be a redundant example because Printf already does this, but I'm going to make a print function with a variable “myString,” as an argument, so this is a local variable, local to this function; it's not going to exist outside of this, it's just whatever's in that parentheses, so myString, and then we're going to call another function, Printf, to print myString so we end it, we go down here, we call it, print and then we can put whatever we want here; we could put a variable again or we could put words, we can put a string, whatever it says, so now what's happening is it's taking this right here, here, and whatever the first thing is in this parentheses is going to be matched to the first thing in this parentheses, so it goes, okay, I have a variable “myString,” this must be in place of the variable “myString,” so anywhere in here that I see “myString” I'm actually going to use this. You can put multiple arguments, you would just separate them by a comma; so you can do this, and then another one. I don't have any use for any other ones but basically that's how it works. Hopefully that gives you a good visual to understand what's really happening when you put arguments into functions and of course I can run this and it's going to – what?

And it printed hello world but it gave me an error. I wonder why that might be. Well, at least I get to troubleshoot so you can see what that looks like. So it says “Lua API syntax error at 11,” that means line 11. It says Printf string returns nothing. Okay, let's see what's at line 11. It says Printf, ahah, so I used incorrect capitalization here and it doesn't match the one up there, so now I have done that; that should work now. Control A, control C, try that again, and there we go! It works this time.

So that's kind of what your error messages might look like. Syntax errors are relatively easy; there are harder errors to deal with that you will run into, hopefully not too often.

Now before I finish I'm going to make an example of a more complex MA3 function. This one is called Confirm. So the confirm function will display a popup with several customizable elements. It takes two strings. Let me type this out actually so we're going to go, Confirm, two strings for the title and main text; I'm going to go, “Title,” here's the main text, “Hello, this is my text,” there we go. And an optional integer which should be set to nil that determines, otherwise, which screen it goes onto, and then lastly an optional boolean which determines whether or not there will be a cancel button in the popup. True means there will be, false means there will not. The default value is true, so the Confirm function can be called with only two strings and it will work perfectly, but to specify that there should not be a cancel button you have to write it out as follows. So put a nil and then a false that will prevent there from being a cancel button. I'm going to run this and show it to you. So it gives me this popup and I can hit okay; there is no cancel button. If I go back and remove this, or it would be the same if I changed this to true, then what happens is it has an okay and a cancel button.

Later we will find out how to actually make use of the information of whether the user pressed the okay or the cancel button, but in the next video we are going to get into if statements and conditional loops. These are really fun and one of the big things that set Lua apart from normal console use and make it so powerful. I really hope you're as excited to get into it as I am. See you in the next video!