Slyme: Remove that warning at the top.

2024-10-06T01:13:33Z

Remove that warning at the top.

← Older revision		Revision as of 01:13, 6 October 2024
Line 1:		Line 1:
	{{Notice~~/Warning~~		{{Notice
	\|content=~~''''''~~		\| content = I highly recommend reading the [https://www.lua.org/manual/5.2/ Lua Reference] and [https://www.lua.org/pil/contents.html Programming in Lua] if you have the time. I provide a basic rundown of the most used functionality for Figura, but not everything gets covered.
	}}		}}
	~~----~~
	~~{{Notice~~
	\|content=I highly recommend reading the [https://www.lua.org/manual/5.2/ Lua Reference] and [https://www.lua.org/pil/contents.html Programming in Lua] if you have the time. I provide a basic rundown of the most used functionality for Figura, but not everything gets covered.}}

	==How a computer reads code==		==How a computer reads code==

Slyme: Ported Katt's Lua Basics page to MediaWiki and made a few minor edits.

2024-10-06T01:13:05Z

Ported Katt's Lua Basics page to MediaWiki and made a few minor edits.

New page

{{Notice/Warning
|content=''''''
}}
----
{{Notice
|content=I highly recommend reading the [https://www.lua.org/manual/5.2/ Lua Reference] and [https://www.lua.org/pil/contents.html Programming in Lua] if you have the time. I provide a basic rundown of the most used functionality for Figura, but not everything gets covered.}}

==How a computer reads code==
Code is basically just a list of instructions telling the computer step by step what to do. It is read line-by-line and the instructions are executed right away.
==Comments==
When there are 2 minus signs <code>--</code>, everything after it is ignored by Lua. These are called comments. They have no effect on the code that is executed and can be safely removed. Their primary purpose is to add raw text that can be used to aid in the understanding of code.
<syntaxHighlight lang="lua">
-- Comments are not compiled and do not affect code
local a = 2 -- Everything up to the next newline will be ignored.
-- Can also be used to hide code from the compiler without actually removing it:
-- local b = 4
</syntaxHighlight>
Another form of comment is <code>--[[ ]]</code>. When this is used, everything between the square bracket pairs will be ignored. Newlines do not affect this. This type of comment is commonly referred to as a Long Comment.
<syntaxHighlight lang="lua">
local a = 2
--[[ comment comment
ignores newlines
ignores pretty much everything
]] local b=2 --long comments end strictly at the `]]`
</syntaxHighlight>
==Variables==
Variables store values. Lua is a dynamically typed language, meaning any variable can store a value of any type. You can define a variable using the `local` keyword. Local variables are accessible below the line they were declared, but will not breach their scope.
<syntaxHighlight lang="lua">
local a
</syntaxHighlight>
Most of the time, you will want to instantly assign a value to that variable. In lua, if you use `=` it will store the value on the right inside the variable on the left.
<syntaxHighlight lang="lua">
local a = 2 -- the variable named "a" now stores the value 2
</syntaxHighlight>
After a variable has been declared, you can assign a new value to it by using <code>=</code> again. Note that the <code>local</code> keyword is only used when creating the variable for the first time.
<syntaxHighlight lang="lua">
local a = 2
a = 4 -- the variable "a" now stores 4
</syntaxHighlight>
Multiple variables can be declared and assigned on one line.
<syntaxHighlight lang="lua">
local a, b = 1, 2
</syntaxHighlight>
Variables are limited in what characters can be used as an identifier (variable name). Only letters, numbers, and `_` can be used in a valid identifier, and it cannot start with a number. None of Lua's keywords (<code>and</code>, <code>or</code>, <code>if</code>, <code>while</code>, etc.) can be used as a variable name.
<syntaxHighlight lang="lua">
local a123
local _b
local KEKW
local 123A -- invalid. Starts with a number.
local has-water -- invalid. Uses character `-`
local and -- invalid. `and` is a lua keyword.
local local -- invalid. `local` is a lua keyword.
local _ -- This name specifically is used to denote throwaway variables in loops.
</syntaxHighlight>
If you assign a value to a value to a variable that has not been declared using <code>local</code>, you will create a ''global'' variable. Global variables are accessible from the entire Lua environment. This may seem like a good thing to the inexperienced, but because they are accessible anywhere it is common for users to make mistakes when they reuse global variables for other purposes and accidentally overwrite it. 
There is almost never a good reason for using global variables, so always stick to <code>local</code>.
<syntaxHighlight lang="lua">
-- c was not declared local beforehand,
-- meaning there is now the value `10` at global variable `c`
c = 10
</syntaxHighlight>
Variables can be used in place of values.
<syntaxHighlight lang="lua">
local a = 2
print(a) --> prints `2` to the chat
a = a + a
print(a) --> prints `4` to the chat
a = a + a
print(a) --> prints `8` to the chat
</syntaxHighlight>
When you try to use a variable that hasnt been assigned a value, the value `nil` will be returned.
<syntaxHighlight lang="lua">
local a
print(a) --> nil
print(d) --> nil

print(c) --> 10 (the global variable we declared earlier lol)
</syntaxHighlight>

==Functions==

A function contains code that can be executed by calling the function. This is useful if you want to use the same code multiple times and can make your code more structured.

To define a function you use the <code>function</code> keyword, then the name of the function and <code>()</code>. 
Any code after it will be considered inside this function, until you tell Lua that the function is done here by using the <code>end</code> keyword. For better readability we indent the code inside the function using spaces or tabs. 
The print statement will not execute until the function is called.

<syntaxHighlight lang="lua">
function hello()
print("Hello function!")
end
</syntaxHighlight>

Whenever you call a function by putting <code>()</code> after the function name, all the code inside the function will run line by line first, before continuing with the rest of your code.

<syntaxHighlight lang="lua">
print("Outside.")
hello()
print("Below hello.")
</syntaxHighlight>
This will output the following:
Outside.
Hello function!
Below hello.
You can also give the function some values to work with by putting variable names inside the <code>()</code>. These variables are called parameters. The function can also return a new value itself that is accessible from where the function is called. If no <code>return</code> is specified, the function returns <code>nil</code> (see "Types" section below). 
Here is an example of a function that calculates the sum of two numbers.

<syntaxHighlight lang="lua">
function sum(a,b) -- parameters seperated by commas
local s = a + b -- calculate the sum
return s -- return the sum to be used by tha caller
end

local var1 = 2
local var2 = 8
local var3 = sum(var1, var2) -- call the function and pass two variables. note that these do not have to be called a and b
print(var3) --> 10, as you might have noticed, `print` is also a function that takes a parameter
</syntaxHighlight>

==Values==
Values represent some form of data. 
There are many types of values for storing different types of data.

===boolean===
A boolean is a data type with 2 distinct values: <code>true</code> and <code>false</code>.

Most operators return a boolean and it's current state can be inverted with <code>not</code>.
<syntaxHighlight lang="lua">
local a = true
print(a) --> true
print(not a) --> false
a = not a -- a = false
print(a) --> false
print(not a) --> true
</syntaxHighlight>
===number===
A number is, well, a number. 
Numbers can use arithmetic operators.
<syntaxHighlight lang="lua">
local a = 14
local b = 4
print(a+b) --> 18
print(a-b) --> 10
print(a*b) --> 56
print(a/b) --> 3.5
print(a%b) --> 2
local c = 3.1459
local d = math.pi
</syntaxHighlight>
===string===
A string is a sequence of characters. 
Mostly used for holding and manipulating text data.

[https://www.lua.org/manual/5.2/manual.html#6.4 String functions] are accessible through the <code>string</code> global variable. All string values also contain these functions within themselves.

Strings are defined by encasing text in double quotes (<code>"</code>) or single quotes (<code>'</code>).

If you try to put a newline in a string, Lua will refuse and throw a syntax error. Newlines must be encoded into a string using other characters. Specifically <code>\n</code>. 
If you need to have either a <code>"</code> or <code>'</code> in a string and you cannot wrap the string in another quote type, you can escape the quote using <code>\</code>

Long Strings are defined by encasing text in 2 square brackets (<code>[[]]</code>). Long strings capture every single character between the pairs of square brackets including raw newlines.
<syntaxHighlight lang="lua">
local str = "foo"
print(str .. " bar") --> foo bar

local a = "This string has \"quotes\" in it."
print(a) --> This string has "quotes" in it.

local b = "This will result in
a syntax error"

local c = "This \nwill \nnot"

local d = [[neither
will
this]]
</syntaxHighlight>
===table===
A Lua table is a data structure that stores many values.

Tables operate on key-value pairs. You give the table a key in the form of a value, and it returns a value. 
Assigning works the same way. Give the table a key, and assign a value to the table at that key.
<syntaxHighlight lang="lua">
-- Define an empty table
local tbl = {}
-- Store the value 23 in the table with the key 54
tbl[54] = 23
-- Store the value false in the table with the key "stringKey"
tbl["stringKey"] = false

-- variables can be inputted, using their value as the key.
-- For instance, let's use our global c (which, if you don't remember, was set to 10) from earlier.
tbl[c] = "123"

tbl[67] = tbl[54]

print(tbl[54]) --> 23
print(tbl["stringKey"]) --> false
print(tbl[10]) --> "123"
print(tbl[67]) --> 23
</syntaxHighlight>
If your key is a string, you can use a different way of indexing that is easier to do. Do note that only strings that abide by identifier rules can be used this way. If the string is not a valid identifier, use <code>[]</code> indexing
<syntaxHighlight lang="lua">
local data={}
data.name="Chocolate"
data.amount=100
data.delicious=true
</syntaxHighlight>
Unlike other values which are passed around by value, tables are passed by reference. 
What this means is that when you create a table and assign it to a variable, then assign it to a different variable, you do not have 2 tables. You have 2 variables pointing to the same table.
<syntaxHighlight lang="lua">
local a = {}
local b = a
local c = {}
print(a) --> table4b8ab37d
print(b) --> table4b8ab37d
print(c) --> table82f1e9c2
-- table equality works on "is this the same table?".
-- The values inside do not matter.
print(a == b) --> true
print(a == c) --> false
-- same table in memory.
a.reeee = 2
print(b.reeee) --> 2
</syntaxHighlight>

===nil===
<code>nil</code> is commonly referred to as the absence of data. 
It is what is returned when no data is present.

===function===
Yes, functions are also a type of variable.

An alternative way to name a function to what we learned before is by assigning a function to a variable. 

<syntaxHighlight lang="lua">
local a = function()
print("function was called")
end
</syntaxHighlight>

This is functionally the same thing as:

<syntaxHighlight lang="lua">
local function a()
print("function was called")
end
</syntaxHighlight>

Like tables, functions are passed by reference, and equality is based on "is this the same function?". The actual contents of the function are not evaluated, so identical looking functions, while similar, are not equal.
<syntaxHighlight lang="lua">
local a=print
print(a == print) --> true

local b=function() end
local c=function() end
print(b == c) --> false

c = b
print(b == c) --> true

print(b()) --> nil, because b does not return anything
</syntaxHighlight>

Since functions are just another value type, they can be used as arguments to other functions.
<syntaxHighlight lang="lua">
local function do10(func)
for i=1,10 do -- this just means "repeat 10 times" increasing the variable `i` every time
func(i)
end
end

do10(print) --> 1,2,3,4,5,6,7,8,9,10
do10(function(v)
print(v*2)
end) --> 2,4,6,8,10,12,14,16,18,20
</syntaxHighlight>
Functions have access to all variables defined above where the function gets defined. Variables below where the function is defined is considered "out of scope" of the function. 
If a variable is used that is not defined above the function, the global variable with that identifier will be used
<syntaxHighlight lang="lua">
local a = 10
local b = "string lol"
local function d()
print(a)
print(b)
print(c) -- there is no `c` variable defined above here, so the global `c` will be used.
end
local c = 20
d()
--> 10
--> "string lol"
--> 10
-- If you forgot the countless times we've used the global c through this entire page, c is still 10.

local function e(b)
print(a)
print(b) -- variable `b` is redefined as a function parameter, so the other `b` is scope gets overshadowed
print(c) -- There *is* a `c` variable within scope this time
end
e("string kek")
--> 10
--> "string kek"
--> 20
</syntaxHighlight>
If a function is one of the values in a table, special syntax can be used to have the table itself be the first argument to the function. By indexing the function with colon (<code>:</code>) Lua will put the table itself as the first argument.

This is used heavily in Figura for many of its APIs. All objects of the same type share the exact same functions, differentiated only by the object placed in the first argument.
<syntaxHighlight lang="lua">
local tbl={}
tbl.key = function(t, a, b)
t[a] = b
end

tbl:key("a", "b")

-- this is functionally equivalent
tbl.key(tbl, "a", "b")

-- You can also use `:` when creating functions. The implied `self` argument will be used to refer to the first argument
function tbl:key(a, b)
self[a] = b
end
</syntaxHighlight>
===userdata===
Lua is commonly used when embedded in other software. In this case, it is embedded inside of Figura. 
userdata is the means of communicating with that software.

userdata is basically data initialized in Figura that gets interpreted as a Lua value. They function most similar to tables in the fact that they are indexed the same way to receive values, mostly functions.

This is why knowing when to use `:` to index userdata is important.
<syntaxHighlight lang="lua">
-- `models` is a value of type userdata. More specifically, it is a ModelPart created in Java and made accessible in Lua.
-- userdata commonly overrides what the print and tostring functions return to improve the ability to debug code.
print(models) --> models (ModelPart)
</syntaxHighlight>
==Variable Scope==
A Variable's Scope is the area the variable is accessible from.

A variable's scope begins when it is declared, and extends until the end of the current block. 
The scope of global variables is the Lua environment itself and will not clear until Lua itself is shut down.

All [[#control_statements|control statements]] will create new scopes when used. Functions also create their on scope when declared 
The `do end` statement can be used to create scopes, and doesn't have any other functionality. I will be using it to showcase how scopes affect variables, as explaining it raw will not get the point across.

<syntaxHighlight lang="lua">
local a=4
local b=8
do
-- a and b are accessible here
local c = 12
-- a, b, and c are accessible here
a = 16 -- variable `a` in the outer scope is now `16`

local b = 20 -- b in the other scope has been overshadowed by this variable. All future references to `b` will refer to this variable (until the end of the scope)

print(a,b,c,d) --> 16, 20, 12, nil
end
print(a,b,c,d) --> 16, 8, 10, nil
-- Global c is still 10.

local e
do
local f=0

-- interesting thing is that functions capture the current scope.
-- Even if we leave the scope, the function remembers the upvalue `f` and will continue to use it even if the scope `f` belongs to ends
-- oh yea `a` is overshadowed here too. But thats not as interesting.
e=function(a)
f=f+1
print(f, a)
end
e()--> 1, nil
e()--> 2, nil
end

e() --> 3, nil
e("a") --> 4, "a"
</syntaxHighlight>
==Value Truthiness==
All values have an implicit truthiness when used in the context of a boolean.

It's simple to remember: <code>nil</code> and <code>false</code> are both considered "falsely", and every other value is considered "truthy".

Truthiness is used in control statements, see the section about it below.

==Operators==
Operators, similar functions, take 1 or 2 values and outputs a result. 
They commonly take the form <code>leftSide operator rightSide</code>. 
I will continue to refer to the 2 values that operators operate on as <code>leftSide</code> and <code>rightSide</code> for the duration of this section. 

Operators have a priority system. It is surprisingly intuitive, but can be forced by surrounding the code you want to guarantee execute first in brackets `()`. For the true priority list, check out the [https://www.lua.org/manual/5.2/manual.html#3.4.7 Lua Reference Manual].

Do note that despite me saying that "Only x can use this operator", tables and userdata types are always exempt from this rule. However, they must be explicitly written to support these operators, so most will not support it by default.
===Arithmetic Addition (+)===
Its addition. 1+1 returns 2. Basic stuff. 
Only numbers can use this operator.
===Arithmetic Subtraction (-)===
Its subtraction. 2-3 returns -1. Basic stuff. 
Only numbers can use this operator.
===Arithmetic Multiplication (*)===
Its multiplication. 2*4 returns 8. Basic stuff. 
Only numbers can use this operator.
===Arithmetic Division (/)===
Its division. 5/2 returns 2.5. Basic stuff. 
Only numbers can use this operator.
===Arithmetic Modulo (%)===
Division actually has 2 components. The whole component, and the remainder component. 
Modulo returns this remainder component after the division leftSide/rightSide is done. 
5%2 returns 1, because 2 goes into 5 2 whole times, 2*2=4, 5-4=1. 
Only numbers can use this operator.
===Arithmetic Exponentiation (^)===
Its exponents. 2^3 returns 8. Basic stuff. 
Only numbers can use this operator.
===Arithmetic Negation (-)===
Only operates on the rightSide. 
This operator negates the number, similar to just adding a negative symbol in front of it. 
<syntaxHighlight lang="lua">
local a= -2
a=-a
print(a) --> 2
</syntaxHighlight>
===Relational Equality (==)===
Returns `true` if both values are considered the same value, `false` otherwise. 
All values can use this operator.
===Relational Inequality (~=)===
Returns `false` if both values are considered the same value, `true` otherwise. 
All values can use this operator.
===Relational Less Than (<)===
Returns `true` if the leftSide is considered less then the rightSide, `false` otherwise. 
Numbers compare as expected.
Strings compare using their ascii representations, comparing each character left to right until they are not equal. Then the operator is applied to those 2 character's ascii numbers and returned.
===Relational Greater Than (>)===
Returns `true` if the leftSide is considered greater then the rightSide, `false` otherwise. 
Numbers compare as expected.
Strings compare using their ascii representations, comparing each character left to right until they are not equal. Then the operator is applied to those 2 character's ascii numbers and returned.
===Relational Less Than or Equal To (<=)===
Returns `true` if the leftSide is considered less then or equal to the rightSide using equality operator rules, `false` otherwise. 
Numbers compare as expected.
Strings compare using their ascii representations, comparing each character left to right until they are not equal. Then the operator is applied to those 2 character's ascii numbers and returned.
===Relational Greater Than or Equal To (>=)===
Returns `true` if the leftSide is considered greater then or equal to the rightSide using equality operator rules, `false` otherwise. 
Numbers compare as expected.
Strings compare using their ascii representations, comparing each character left to right until they are not equal. Then the operator is applied to those 2 character's ascii numbers and returned.
===Logical And (and)===
This operator operates on truthiness. 
If the leftSide is considered truthy, it returns the rightSide. Otherwise, it returns the leftSide. 
This ends up with the return value being truthy only if both leftSide ''and'' rightSide are truthy. 
The following table puts this visually. L is leftSide, R is rightSide. F and T represent if the value is falsy or truthy, and the column under O represents which value actually gets returned by `and` as well as the truthiness of it.
{| class="wikitable"
|-
! Left !! Right !! Output
|-
| False || False || False (Left)
|-
| False || True || False (Left)
|-
| True || False || False (Right)
|-
| True || True || True (Right)
|}
The reason this is so complex is because it doesn't just work on booleans. It works on all value types.

===Logical Or (or)===
This operator operates on truthiness. 
If the leftSide is considered truthy, it returns the leftSide. Otherwise, it returns the rightSide. 
This ends up with the return value being truthy either the leftSide ''or'' rightSide are truthy. 
The following table puts this visually. L is leftSide, R is rightSide. F and T represent if the value is falsy or truthy, and the column under O represents which value actually gets returned by `or` as well as the truthiness of it.

{| class="wikitable"
|-
! Left !! Right !! Output
|-
| False || False || False (Right)
|-
| False || True || True (Right)
|-
| True || False || True (Left)
|-
| True || True || True (Left)
|}

The reason this is so complex is because it doesn't just work on booleans. It works on all value types.

===Logical Not (not)===
Only operates on the rightSide. 
This operator evaluates the truthiness of the value, then returns the boolean representation of the opposite. 
<code>not true</code> is <code>false</code>, <code>not 2</code> is <code>false</code>, <code>not false</code> is <code>true</code>, <code>not {}</code> is <code>false</code>, and <code>not nil</code> is <code>true</code>. 
All values can use this operator.
===String Concatenation (..)===
This returns a string from the values concatenated together. 
Only strings can use this operator.
===Length Operator (#)===
Only operates on the rightSide. 
This returns the length of the value 
For strings, its the amount of bytes stored in the string. (UTF-8 characters are more than one byte) 
For tables, lua iterates over <code>t[1], t[2], t[3] ... t[n]</code> until a nil value is found and returns the number of non-nil values found.

==Control Statements==
Control Statements affect the scope and flow of the program.
===<code>if then end</code>===
<code>if</code> statements allow for executing code only when a condition is met.

The basic structure looks like
<syntaxHighlight lang="lua">
if condition then
print("condition is true")
end
</syntaxHighlight>

<code>if</code> statements have an optional <code>elseif</code> clause, where if the previous condition failed this condition will be checked. In an <code>elseif</code> chain, only the first successful condition will actually execute, after which all other <code>elseif</code>s are ignored.

<syntaxHighlight lang="lua">
if condition then
print("condition")
elseif condition2 then
print("condition2")
elseif condition3 then
print("condition3")
end
</syntaxHighlight>

<code>if</code> statements also have an optional <code>else</code> clause, where if ''all'' previous conditions fail, the <code>else</code> clause will execute.

<syntaxHighlight lang="lua">
if condition then
print("condition")
else
print("not condition")
end

if condition then
print("condition")
elseif condition2 then
print("condition2")
else
print("not condition or condition2")
end
</syntaxHighlight>

<code>else</code> statements operate on [[#value_truthiness|Value Truthiness]]
<syntaxHighlight lang="lua">
local rand = math.random()<0.3
-- Use booleans as raw input to if statements
-- the `==` operator just returns a boolean anyways and is just wasted instructions
if rand then
print("random print statement lol")
end

-- getVehicle returns either an Entity userdata, or nil
local vehicle=player:getVehicle()
if vehicle then
print("Riding: ", vehicle:getName())
else
print("No Mount")
end
</syntaxHighlight>

===Loops===

<syntaxHighlight lang="lua">
for i=1,10 do
print(i)
end
--> 1,2,3,4,5,6,7,8,9,10

local x = 1
while x < 10 do
x = x + 1
print(x)
end
</syntaxHighlight>

--TODO this has been sitting locally for several months. I'm uploading it and finishing it later

Lua Basics - Revision history

Slyme: Remove that warning at the top.

Slyme: Ported Katt's Lua Basics page to MediaWiki and made a few minor edits.