Jump to content

Lua for absolute beginners

NanoBob

By NanoBob
in User Guides

Recommended Posts

  • Popular Post
NanoBob Rat

NanoBob

Posted
  • Popular Post
Posted (edited)

Lua tutorial for absolute beginners

This tutorial can also be viewed on GitHub

This tutorial aims to teach the Lua scripting language to those with 0 previous experience with programming / scripting.
This guide will start with explaining some Lua concepts, and will later on move to explaining MTA:SA specific concepts.

Table of contents:

  • Lua
    • Scripts
    • Variables
    • Data types
    • Operators
    • If statements
    • Functions
    • Return values
    • scopes & locals
    • For loops
    • Tables
    • Iterators (pairs/ipairs)
    • Callbacks
    • Anonymous functions
  • MTA
    • Server & Resources
    • Server vs client
    • MTA functions & wiki
    • Elements (userdata)
    • Command handlers
    • Event handlers
    • predefined globals
    • server <-> client communication
  • Now what?

Lua

This part of the tutorial discusses Lua itself. No MTA-specific concepts will be discussed here.

Scripts

The Lua scripting language is a language which is interpreted by a "Lua interpreter". MTA:SA's resources use such an interpreter to run Lua code. For the beginning of this tutorial you can use the online Lua interpreter available on https://www.Lua.org/demo.html. Any code in the Lua part of the tutorial can be run on this website.

Lua is written in "plain text". This means it exists of regular characters like any other text you are writing. To edit Lua files you will require a text editor. You could use Notepad, but there are many far better alternatives. My personal favourite is Visual Studio Code, but there are many other good options, to name a few: Atom, sublime text, notepad++
Lua files are usually saved with the .Lua file extension

Variables

The first concept we're going to discuss is variables. Variables allow you to store a value in your code.
For example: 

x = 10

print(x)

print(x) will output the value of the x variable. We will get into what exactly print is later in the tutorial.

Variables can have any name you want, as long as you follow some specific rules.

  • variable names must start with a letter (lower or upper case), or an underscore (_)
  • variable names may contain letters (lower and upper case), numbers and underscores. 
x = 10
y = 20
z = 30

print(x)
print(y)
print(z)

The convention in Lua is to name your variables in "camelCase". This means if a variable exists of multiple words you start every word with a capital letter, except for the first one. 

camelCaseVariable = 5

Data types

So far we've seen variables used to store numeric values, but there are many different types of data Lua can handle. These are:

  • number
    Any numeric value
  • string
    A piece of text, a string is surrounded by " or '. For example "Hello world" or 'Hello world'
  • boolean
    A boolean is a data type that has only 2 options, true and false.
  • nil
    nil is a value indicating nothing. It's the absence of a value. (Not the be confused with 0)
  • table
    Tables will be discussed later in the tutorial
  • userdata
    Userdata will be discussed later in the tutorial
  • function
    Functions will be discussed later in the tutorial
  • thread
    Threads are out of scope for this tutorial and won't be discussed

So we can use these different data types, and store them in variables: 

numberVariable = 10
stringVariable = "Hello world"
booleanVariable = true
nilVariable = nil

Operators

Operators are symbols in Lua which can be used to do "things" with variables. Here's a list of operators and an example for each:

+ operator

Adds two values together 

x = 10 + 10
print(x)

y = 20
print(y)

z = x + y
print(z)

- operator

Subtracts a value from another value 

x = 10 - 10
print(x)

* operator

Multiplies two values 

x = 10 * 10
print(x)

/ operator

Divides a value by another value 

x = 10 / 10
print(x)

% operator

This is the "modulo" operator. This will divide a value by another, and return the leftover. 

x = 10 % 4
print(x)

The result of this is 2

and operator

The and operator will return true if both variables are "truthy". Otherwise it returns false
(A "truthy" value is anything except for false and nil) 

x = true and false
print(x)

y = true and true
print(y)

or operator

The and operator will return true if one of the variables are "truthy". Otherwise it returns false 

x = true or false
print(x)

y = false or false
print(y)

== operator

The == (equals) operator will return true if both of the variables are the same. Otherwise it returns false 

x = "hey there" == "hello there"
print(x)

y = 150 == 150
print(y)

~= operator

The ~= (does not equal) operator will return true if both variables are not the same. Otherwise it returns false 

x = "hey there" ~= "hello there"
print(x)

y = 150 ~= 150
print(y)

> operator

The > (greater than) operator will return true if the first value is greater than the second value. Otherwise it returns false 

x = 10 > 5
print(x)

y = 10 > 15
print(y)

y = 10 > 10
print(y)

>= operator

The >= (greater than or equals) operator will return true if the first value is greater than, or equal to, the second value. Otherwise it returns false 

x = 10 > 5
print(x)

y = 10 > 15
print(y)

y = 10 > 10
print(y)

< operator

The < (less than) operator will return true if the first value is less than the second value. Otherwise it returns false 

x = 10 < 5
print(x)

y = 10 < 15
print(y)

y = 10 < 10
print(y)

<= operator

The <= (less than or equals) operator will return true if the first value is less than, or equal to, the second value. Otherwise it returns false 

x = 10 < 5
print(x)

y = 10 < 15
print(y)

y = 10 < 10
print(y)

.. operator

The .. (string concatanation) operator allows you to add two strings together. 

x = "Hello"
z = "World!"

combined = x .. " " .. z
print(combined)

If statements

An if statement allows your code to decide to do something, or not. Depending on a value. Often times if statements are used in combination with some of the above operators.

An if statement is written as : if <expression> then <code> end 

x = 10
if x > 5 then
    print("X is higher than 5")
end

Any code between then and end will only be executed when the expression is true. You might also have noticed that the code between the then and end is moved over a bit to the right. This is called "indentation". Whenever we open a new scope (scopes will be discussed later in the tutorial) we move our code to the right. This is usually done by either a tab or several spaces . Many code editors will convert a tab to spaces.

Else

Within an if statement, you can also add an else block. The code in such a block will be executed when the code in the if block is not executed. 

x = 10
if x > 5 then
    print("X is higher than 5")
else
    print("X is not higher than 5")
end

Elseif

If you want to do multiple if statements, you can use an elseif: 

x = 15
if x > 10 then
    print("X is higher than 10")
end
if x > 5 then
    print("X is higher than 5")
end
x = 15
if x > 10 then
    print("X is higher than 10")
elseif x > 5 then
    print("X is higher than 5")
end

The difference between the first example and the second is that if x is higher than 10 in the first example both lines "X is higher than 10" and "X is higher than 5" will be output. Whilst in the second example only "X is higher than 10" will be output.

And if statement must always start with an if, can contain multiple elseifs, and may only have one else. 

name = "NanoBob"
if name == "NanoBob" then
    print("Hello world!")
elseif name == "Brophy" then
    print("Black 123")
elseif name == "Tombaa" then
    print("Stupid")
else
    print("I have no idea")
end

Functions

Functions allow you to write less code, by reusing pieces of code.

The syntax to create a function is function <name>(<parameters>) <code> end 

function foo()
    print("Hello world #1")
    print("Hello world #2")
end

In order to execute code in the function, you "call" the function. You do this by writing the function name followed by (). 

function foo()
    print("Hello world #1")
    print("Hello world #2")
end

foo()
foo()
foo()

Functions also allow you to send a variable to the function, for it to do something with. This is what's called a function parameter. Function parameters are defined in the brackets () after the function name. 

function foo(x)
    print(x)
end

foo(10)
foo("50")

You may notice that this looks a lot like the print() we have been using. This is because print is a built-in Lua function.

Return values

A function not only can execute code, it can also give something back to where it was called. This is called a return value. In order to return something from a function you use the return keyword. 

function foo()
    return 10
end

x = foo()
print(x)

print(foo())

Just like in an if statement, all code within a function is indented.

Now let's combine everything we have learnt so far: 

function foo(x)
    if x > 10 then
        return "X is higher than 10"
    elseif x > 5 then
        return "X is higher than 5"
    else
        return "X is not higher than 5"
    end
end

y = foo(15)
print(y)

print(foo(10))
print(foo(0))

Scopes & locals

We quickly encountered scopes before, and said we indent our code whenever we enter a new scope. But scopes allow you to do more than that. Most importantly, "local" variables.

A local variable is only available in the scope it was defined in (or scopes that were created from within that scope)

You can create a new scope using a do block (functions and if statements also have their own scope). 

do
    local x = 5
    print(x)
end
print(x)
do 
    local x = 5
    do 
        local y = 10
        print(x)
        print(y)
    end
    print(y)
end

For loops

(For) loops are ways in scripting / programming to have code executed multiple times, without having to write the same thing multiple times.
An example of such a loop: 

for i = 1, 10 do
    print(i)
end

The first part : i = 1, 10 defines a variable called i. Which start at 1. This will be incremented by 1, until it reaches 10. The code within the loop then can use this variable.

You can also increment with a different number than 1 (including negative numbers) using this construct. 

for i = 20, 0, -2 do
    print(i)
end

This code sample will start with i at 20, and keep adding -2 (thus subtracting 2), until it reaches 0

Tables

Tables are a datatype in Lua which allows for lists of things.
Here's an example: 

x = {
    [1] = 100,
    [2] = 200,
    [3] = 300
}

print(x[1])
print(x[2])
print(x[3])

Tables consist of key/value pairs. In the example above the key 1, has the value 100, 2 has the value 200, and 3 has the value 300.
You can get the value in a table, by putting the key in between square brackets []. Like in print(x[1]). 

x = {
    100,
    200,
    300
}

print(x[1])
print(x[2])
print(x[3])

You can choose to not include the keys in a table. Doing so will automatically add numbers as keys, starting at 1. So the above example would be the exact same as the first example.

Table keys and values can be of any data type, including other tables. This allows you to create (very) complex table structures. 

t = {
    [1] = {
        100,
        200,
        300
    },
    ["x"] = 100,
    [true] = "something"
}
print(t["x"])
print(t[true])

print(t[1][1])
print(t[1][2])
print(t[1][3])

When using a string as the key in a table, you can leave out the square brackets and the quotes. This goes for both when defining the table, and for indexing it (getting a value from it). For example 

t = {
    x = 100,
    y = 200,
    z = 300
}

print(t.x)
print(t.y)
print(t.z)

A table's values can be modified / set after creating the table as well. 

t = {}

t[1] = 10
t[2] = 20
t[3] = 30

t["x"] = "banana"
t[true] = false
t.x = "banana"

When using tables you will often want to add something to the "end" of a table. This is most common when you are using tables with numeric keys.
In order to do this you can use a # to get the amount of items currently in the table. 

t = {
    10,
    20,
    30
}

t[#t + 1] = 40

This will store the value 40 on the key 4 , because #t is 3.

Iterators (pairs/ipairs)

Iterators are a mechanism that allow you to make a loop, which goes over a set of values. Writing your own iterators won't be discussed in this tutorial. But there are two functions which are often used to create an iterator to iterate over a table. These are pairs and ipairs. 

t = {
    10, 20, 30, 40, 50
}

for key, value in ipairs(t) do
    print(key, value)
end

The difference between pairs and ipairs is the order in which the key/value pairs are iterated over, and which of the key/value pairs are iterated over.
Where ipairs will always use numeric keys, starting at 1, and going up by 1 every time, until there is no entry in the table. This also means it won't iterate over anything key that is not numeric. 

t = {
    ["x"] = 5,
    [1] = 10,
    [2] = 20,
    [3] = 30,
    [5] = 50,
}

for key, value in ipairs(t) do
    print(key, value)
end

A pairs loop will iterate over any value in a table, but the order is not guaranteed. Meaning that between different runs of the script the order could be different. 

t = {
    ["x"] = 5,
    [1] = 10,
    [2] = 20,
    [3] = 30,
    [5] = 50,
}

for key, value in pairs(t) do
    print(key, value)
end

Callbacks

Callbacks are when you pass a function as an argument to another function. To have the function you passed be called later on. This is used often within MTA.

An example of a Lua function which uses a callback is table.sort. table.sort will sort a tables values, by default these values are sorted numerically. But you can use a callback to change this behaviour. 

values = {
    5, 4, 3, 6, 8, 1, 2, 9, 7
}

function sortFunction(a, b)
    return b > a
end

function reverseSortFunction(a, b)
    return a > b
end

table.sort(values, sortFunction)
print("Sorted: ")
for _, v in ipairs(values) do
    print(v)
end


table.sort(values, reverseSortFunction)
print("\nReverse sorted: ")
for _, v in ipairs(values) do
    print(v)
end

In the first call to table.sort (table.sort(values, sortFunction)) you can see the sortFunction function is passed as second argument to the function. Note that we don't write sortFunction() here (notice the brackets difference) because that would call the sortFunction function, and pass its return value to table.sort.

table.sort will then call this function when it compares two different values, this function should return true or false depending on whether its second argument (b in this case) is larger than it's first argument (a), in the context of sorting.

Anonymous functions

It is also possible to use an "anonymous function" when passing a callback to a function. 

values = {
    5, 4, 3, 6, 8, 1, 2, 9, 7
}

table.sort(values, function(a, b)
    return b > a
end)

print("Sorted: ")
for _, v in ipairs(values) do
    print(v)
end


table.sort(values, function(a, b)
    return a > b
end)

print("\nReverse sorted: ")
for _, v in ipairs(values) do
    print(v)
end

MTA

This part of the tutorial discusses MTA specific constructs. Code in this part of the tutorial won't run in the online Lua interpreter. You will need to set up a (local) server for this.

Server & Resources

By default when installing MTA:SA a server is installed as well. This server is located in the "server" directory of your MTA directory. This is usually at C:\Program Files (x86)\MTA San Andreas 1.5\server. This directory contains an MTA server.exe file, running this file will start a server.

Scripts on a server are grouped by resources, a single resource can consist of multiple script files and other assets such as images, sounds, fonts, mods and more.

Resources are placed in your mods\deathmatch\resources folder in your server folder. A resource is always in its own directory. A resource must always have a single meta.xml file. This file tells the server (among others) what script files to load. A typical meta.xml file looks like this: 

<meta>
    <script src="vehicleSystem.Lua" type="server"/>
    <script src="vehicleMods.Lua" type="client"/>
</meta>

You will need an entry for every .Lua file you want to have executed on the server.

You can start a resource by typing start <resource name> in the server console (the window that opened when you started MTA Server.exe). The resource name is the name of the directory your meta.xml is in. (This may not have spaces).
Starting a resource will start running the Lua scripts, if you've changed your scripts you will need to restart the resource for the changes to take effect. (restart <resource name>).

Server vs client

Lua code can be executed in one of two places. The server, or the client.
Server sided scripts are executed on the actual machine that is running the MTA server.exe process.
Client sided scripts are executed on the computer of every player that connects to your server.

Server sided and client sided scripts have a distinct difference in responsibility and possibility. Some functions for example are only available on the client, whilst others are available only on the server (and many on both).

Note: Some of these functions which are available both server sided and client sided are different on server and client

MTA functions & wiki

In plain Lua there's not much you can do to affect a game engine like MTA:SA. This is why MTA:SA offers a (large) list of functions available for you to use in your scripts which interact with the actual GTA world.
You can find a list of all of these, what they do and how to use them on the MTA wiki.

An example of such a function is createObject(). This function will create a physical object in the game. The wiki page contains information on how to use it (what arguments it expects, and in what order). And often shows an example of how to use it. 

createObject(1337, 0, 0, 3)

Elements (userdata)

At the start of this tutorial we quickly mentioned userdata data types. These are data types configurable by the implementation of Lua. In this case, MTA.
MTA uses userdata to represent "elements". Many things in MTA are elements, like objects, markers, peds, players, user interfaces, vehicles, etc.
On the MTA wiki you will notice many functions either return elements, or require an element as arguments.
A list of different types of elements can be found on the MTA wiki.

Elements also have a hierarchical structure to them. Elements can have a "parent", and multiple "children". This will result in a tree of elements, the element at the top of this tree (and thus the grandparent of all elements) is called the root element.

Command handlers

Often times in MTA you want certain things to happen when a player enters a command. This is done using command handlers, command handlers use a callback, which we previously discussed.
The wiki contains a page for the addCommandHandler() function. For this example we will be using the server side version. 

function handler(player, command, argument)
    outputChatBox("You entered " .. command)
    if argument ~= nil then
        outputChatBox("You used the argument " .. argument, player)
    end
end

addCommandHandler("banana", handler)

This example also uses the outputChatBox() function, this will output a piece of text to the chat.(in this case, only for the player who executed the command)

The callback function passed to addCommandHandler will be called every time a player uses the /banana command ingame.

Event handlers

Besides having your script do things when a user executes a command you likely want the game to respond to many different types of things that happen in the game. Like players taking damage, coming close to something, etc.
These things are called events. Whenever an event is triggered you can run a piece of Lua code. You do this using event handlers. Event handlers are created using the addEventHandler().

The first argument to the addEventHandler() function is the string name of the event. These can be found on the MTA wiki as well.

An event is always triggered for a specific element, for example "onPlayerWasted" is triggered on the player that was wasted (killed).
You can attach an event handler to a single element to only have your callback function be called when the event is triggered on that specific element. But you could also use the root element here and your function will be called for every element the event is triggered on. 

function handlePlayerDeath()
    outputChatBox("You died!!", source)
end
addEventHandler("onPlayerWasted", getRootElement(), handlePlayerDeath)

The getRootElement() function used in this example returns the root element discussed earlier.
You can also see source is used in this code snippet, we'll talk about that some more in the next section.

predefined globals

MTA has some predifined global variables for you to use in your script.
A list of them can be found on the wiki.

Here's a couple notable ones and what they're used for

  • root The root element, same as the return value of getRootElement())
  • source
    The element an event handler was called on. An event's wiki page always describes what the event source will be for the event.
  • localPlayer The player element for the player whose client the script is running on. (Thus only available client sided)
  • client Will be discussed in the next section

server <-> client communication

As stated earlier in this tutorial scripts can run either on the server, or one of the connected clients. However often times you would want to trigger something on the server from a client, or the other way around.

An example of this would be when the user clicks the login button on a GUI (Graphical user interface) the server should try to log that person in, and send him back whether or not this was successful.

This can be done using events. MTA allows you to create and trigger your own events, and these events can be triggered from server to client (and the other way around). You can do this using the addEvent() function.
Once an event has been added (and marked as remotely triggerable by passing true as second argument to addEvent()) you can call it from server/client. You do this using [triggerClientEvent()]https://wiki.multitheftauto.com/wiki/TriggerClientEvent() and triggerServerEvent() respectively.

Server sided: 

function handlePlayerLogin(username, password)
    outputChatBox("You tried to log in with the username " .. username, client)
end
addEvent("LuaTutorial.Login", true)
addEventHandler("LuaTutorial.Login", root, handlePlayerLogin)

Client sided: 

function pretendLogin()
    triggerServerEvent("LuaTutorial.Login", localPlayer, "username", "password")
end

pretendLogin()

This example will trigger the "LuaTutorial.Login" event from the client sided script. And passes the "username" and "password" arguments to the event.
The server then handles this event in the handlePlayerLogin() function, which in our case just outputs something to the chatbox.

In this example you can see the previously mentioned client global variable.
This variable is set to the player element corresponding to the client the event was triggered from. (And is thus only usable when used in an event handler which has been triggered from a client).

Now what?

With this information you should be able to start scripting, and making things in MTA! If you didn't understand it all in one go, or you have any more questions there is no shame in that!
You can find myself and many others willing to help you with your scripting questions in the #scripting channel on the MTA discord.
Another good source for programming / scripting related questions is stack overflow.

Edited by NanoBob
  • Like 10
  • Thanks 10
Link to comment
Go to topic listing

  • Recently Browsing   0 members

    • No registered users viewing this page.
×
×
  • Create New...