Total War Modding - User contributions [en]

Lua:Keywords

2021-07-22T06:17:14Z

MrIncongruous: Explained what a keyword is

A keyword is a special word that has been taken for the program, so we can't use it in our own as the name of a variable, function, etc.

We’ve covered the majority of the Lua keywords, but there are a few left that we have to cover. We’ll cover the final keywords that aren’t loop/table-based in this tutorial, and we’ll cover tables and loops in the next! We only have three to touch on.

==== If, Elseif, Else ====
So, we’ve seen conditional statements – if these things, then do this. But we haven’t covered their full usage!

First things first – if you want stuff to happen based on a condition, you use that word I just used twice – <code>if</code>.
<code>local var = 5

if var == 5 then
-- <nowiki>[[ do stuff ]]</nowiki>
end</code>
Note that <code>then</code> defines a new scope here, and that scope ends at, well, <code>end</code>. The conditional is the statement between <code>if</code> and <code>then</code>.
<code>local var = 5

function example()
if var == 5 then -- if var is equivalent to 5 then...
out("This is 5!")
return
end
out("Not 5!")
end

example() → This is 5!

var = 10

example() → Not 5!</code>
In this example, we’re checking whether var is <code>5</code>. If it is, we print “This is 5!”; if it isn’t, we print “Not 5!”. We prevent the printing of ''both'' of them by using the <code>return</code> – otherwise, if the var were <code>5</code>, ''both'' outs would be called.

We can also do this by using the <code>else</code> keyword:
<code>local var = 5

function example()
if var == 5 then
out("This is 5!")
else
out("Not 5!")
end
end

example() → This is 5!

var = 10

example() → Not 5!</code>
Functionally, exactly the same. However, it’s prettier to look at, and makes more sense to read. Do note that <code>else</code> also creates its own scope; in this instance, there is a scope between <code>then</code> and <code>else</code>; and another between <code>else</code> and <code>end</code>.

What if we wanted to check for more than one specific condition? We can use <code>elseif</code>!
<code>local var = 5

function example()
if var == 5 then
out("This is 5!")
elseif var == 7 then
out("This is 7!")
else
out("Not 5 or 7!")
end
end

example() → This is 5!

var = 7

example() → This is 7!

var = 10

example() → Not 5 or 7!</code>
We can use more than one elseif, too. Only one <code>if</code> or <code>else</code> within that block between <code>if</code> and the first <code>end</code>, though.

Do keep in mind that whichever “path” works first is the one that will be used, and the ones following it will be ignored, until the <code>end</code> of the conditional.
<code>local var = 10

function example()
if var > 5 then
out("This is greater than 5!")
elseif var == 5 then
out("This is 5!")
elseif var == 7 then
out("This is 7!")
else
out("Less than 5, not 7!")
end
end

example() → This is greater than 5!

var = 5

example() → This is 5!

var = 7

example() → Less than 5, not 7!</code>
Even though the var matches the second conditional statement – <code>var == 7</code> – for the final assignment, it also matches the first condition, so that’s the one and only path the code takes here.

Do note that you can do just one if and elseif, or an if and an else, or all three, or just an if, or like twenty elseif’s. Though that’s bad code, don’t do that.

==== End, Then, Do ====
The keyword <code>end</code> is needed to denote the end of a scope, when that scope is defined by something other than the entire file. Each of the following keywords need an <code>end</code> to finish their scope:

* then
* do
* function

And the keyword <code>then</code> is needed after the conditional statement for an <code>if</code> or <code>elseif</code>.

The keyword <code>do</code> is used in two instances; one, to create a new scope without needing any other keywords (see example below).

<code>local var = 5

do
local var = 10
out(var) → 10
end

out(var) → 5</code>
The other, and more common, usage of <code>do</code> is to attach it to loop keywords. Read on to the next chapter!
[[Category:Lua Tutorials]]

Lua:Variables & Types

2021-07-22T06:06:26Z

MrIncongruous: small changes to make it clearer for people who have no previous experience programming.

''NOTE: I recommend you have the Devtool Console handy to mess around with some of the stuff covered here.''

Following the concept of chunks and statements, the next most important subject to cover is variables, and types.

Variable: A custom-made keyword that can be used to represent a value

Type: The sort of value that is in a variable. Lua types include: boolean, string, number, table, nil, function. There are more, but we won’t need them.

But before going deeper into a definition, let’s look at an example:
<code>a = 10
b = 5
c = a + b</code>
We can see that each of those letters in the chunk above is a variable, which are each assigned a value. In this case, variable <code>a</code> is assigned the value <code>10</code>, variable <code>b</code> is assigned the value <code>5</code>, and the variable <code>c</code> is assigned the <code>value of a plus the value of b</code>. This instance (c = a + b) works a lot like algebra – you aren’t making “c = ab”, but you’re adding the value of a (10) to the value of b (5), to get the result of 15.

The coolest thing about variables is their dynamism. They can be assigned to any type, change to any type, and they can infinitely change values. Let’s take the above code, and mess with it a little bit.

''NOTE: From this point on, you’ll see → after out() calls. This is to specify what text is actually output.''
<code>a = 10
b = 5
c = a + b

out(a) → 10
out(b) → 5
out(c) → 15

a = 25
out(a) → 25

out(c) → 15

c = a + b
out(c) → 30</code>
I wanted to point out an important thing with this example. If a variable is assigned to the values of some other variables (c = a + b), it will do the calculation and assignment the moment that the statement is called. If either variable (a or b) is changed after the assignment statement, the assigned variable’s (c) value (15) won’t change. It takes the ''variable’s value'', not the ''variable itself''.

So, we see here that variables can be numbers, which is one of the primary types in Lua.

Number: ''any'' numerical value, within a specific number range (a much bigger number than needs to be worried about)

As we saw above, we can perform some basic arithmetic on numbers.
<code>a = 5
b = 2 - 0.34
c = a + b
d = c * 2
e = d / 3

out(c) → 7.56
out(d) → 15.12
out(e) → 5.04</code>
String: ''any'' alphanumerical value, within quotation marks (“” or ”). Similar to numbers, size ''does not matter'', Lua can handle millions of characters within a string.

Like arithmetic for numbers, one can concatenate strings (along with many other stuffs!) to combine several, using the <code>..</code> operator.
<code>a = “This “; b = “is “; c = “an “; d = “example.”
out(a .. b .. c .. d) → This is an example.</code>
''NOTE: Yes, you can have several statements on the same line in Lua! The semi-colons are not necessary, I added them for extra readability.''

While on the subject, you can concat (cool-kid for concatenate) string literals and variables.
<code>a = "example"
out("This is an " .. a) → This is an example</code>
Boolean: a <code>true</code> or <code>false</code> value.
<code>a = false
out(a) → false
out(a == false) → true</code>
The above probably looks a little weird, but that’s because we’re learning a new operator! The <code>==</code> operator checks for ''equality'', whereas the <code>=</code> operator ''assigns a value''. The final statement above reads “output the result of a == false”. Since <code>a</code> DOES equal false, it prints “true”.

It’s very important to note that any variable can be ''treated'' as a boolean, such as when using the “if something then” statement, or by comparing it to a boolean. If a non-boolean variable is treated as a boolean, it will be converted to <code>false</code> if the value is <code>nil</code> or <code>false</code>; otherwise, it will be converted to <code>true</code>.
<code>a = 0
b = nil
out(a) → 0
out(a == false) → false
out(b == false) → true</code>
In this case, <code>a</code> does NOT equal <code>false</code>, because it has a value to it that isn’t <code>false</code> or <code>nil</code>. By the same card, <code>b</code> DOES equal <code>false</code>.

You’re probably asking by now, what IS nil? I’ve mentioned it a number of times already, you’re probably ready to lear about it. Here we go!

Nil: the absence of data.

If one were to try to print a ''non-existent'' variable, the result would be <code>nil</code>. That’s because there is no data for that variable.
<code>out(a) → nil
a = 5
out(a) → 5</code>
Nil is a good way to check whether or not something exists, and we’ll, towards the bottom of this lesson, talk about how to type-check this data in our scripts to see if variables are NOT nil, and thus exist.

Nil is also a good way to clear away variables that you don’t want to use anymore. There’s a more realistic way of doing it, and this probably won’t be necessary for most of what you will be doing, but I like to give a full knowledge.
<code>a = 5
out(a) → 5
a = nil -- Memory deallocated, bye "a"!
out(a) → nil</code>
Lastly, it’s important to note that <code>nil</code> is not the same as <code>null</code>, though they look quick similar. We’ll cover that soon-ish, when we get into more CA script interfaces (like FACTION_SCRIPT_INTERFACE that we saw a few lessons ago).

Function: a definition for a chunk that can be called at any point, after being defined.

There are two types of functions – an anonymous function, and a named function. An anonymous function has no name (clearly), so it cannot be called further on in the script. We use anonymous functions relatively frequently, but our focus now will be on named functions, which are functions assigned to a variable.
<code>a = 10
example = out
example(a) → 10</code>
Yes, that’s valid! You can actually assign a variable to a function like, it’s pretty cool! We have syntactic sugar for assigning a variable to a function, however, and it’s more common to see script like that:
<code>function example(text)
out(text)
end

example("Testing!") → Testing!

example("A Cooler Test!") → A Cooler Test!</code>
As an added bonus, we’re getting a quick sneak peak at one of the upcoming tutorials: parameters and arguments, for functions. In the above function, “text” is a parameter for <code>example()</code>, which is then passed along to <code>out</code> and triggers that function within the chunk.

Table: a collection of more than one piece of data.

There are several types of tables, which we’ll cover later on. I’d like to first look at the ''array'' version of tables, the simplest and most common.
<code>a = 5
b = 10
c = 17

table = {
a,
b,
c
} -- assign the three *values* of the variables to the table

out(table[1]) → 5 -- Lua tables start at index 1: we're showing the first element of our table, that is, the item on index 1!
out(table[2]) → 10
out(table[3]) → 17
out(table[4]) → nil -- doesn't exist!</code>
''NOTE for programmers:'' ''Arrays in Lua start at index ONE, not index ZERO. <code>table[0]</code> would be invalid in the above example! If you get into other programming languages, you'll understand why explaining this was important.''

Arrays are numbered automatically, so it really reads “the first index of table is 5, the second index of table is 10”, and so on. You ''access'' those indexes by using the <code>[num\]</code> operator, which we’ll look further at in the next tables tutorial later on. The reason this works, however, is because Lua is automatically numbering these values, giving them a ''key''. When you make an array like that, Lua reads it more like the following:
<code>a = 5
b = 10
c = 17

table = {
[1] = a,
[2] = b,
[3] = c
}</code>
The other major type of tables is a map, which works by manually assigning the key of a value instead of letting Lua automatically number them, like in arrays.
<code>a = 5
b = 10
c = 15

table = {
["five"] = a,
["ten"] = b,
["fifteen"] = c
}

out(table["five"]) → 5
out(table["ten"]) → 10
out(table["fifteen"]) → 15</code>

Maps will come into some great use pretty soon, but for now I just wanted to introduce you to how they look.

For now, you’ve done well, and I haven’t even challenged you yet!

==== Challenge 1 ====
Go to repl.it (covered in the Foreword), and mess with all this stuff! Use <code>print(whatever)</code>, where whatever is what you want to print, in lieu of <code>out()</code>.

==== Type-Checking ====
And before we say goodbye, let’s look at a few more CA functions. These ones can type-check for us, seeing if a variable is, for instance, a string.

The list is as follows:

* is_nil(variable)
* is_string(variable)
* is_number(variable)
* is_boolean(variable)
* is_function(variable)
* is_table(variable)

<code>a = 5
b = nil
c = {1, 2, 3, 5, 70}
function d() end

out(is_number(a)) → true
out(is_nil(b)) → true
out(is_table(c)) → true
out(is_function(d)) → true</code>

Lua:Main Page

2021-07-22T05:54:43Z

MrIncongruous: itmakes much more sense to have variables and types before expressions and operators, since E&O assumes knowledge of, for example, what a string is, and so on.

Howdy, internet stranger, and welcome. My name’s Vandy, and I’ll be guiding you through this new chapter of your life. This section of the Total War Modding Resources is dedicated to the learning and appreciation of the Lua language.

==== What Is Lua? ====
One of the primary types of modding, in Total War, is the use of the programming language <code>Lua</code>. In case you were wondering, Lua is Portugese for ‘moon’, and the dude who made the language was born in 1960, and at the time of this writing the language is only 26 years old.

Using Lua, you can establish chains of events, create flexibility on when units can be recruited or when lords are spawned, and you can set up new quest battles. The entire Chaos Invasion mechanic from WH2 is scripted; from 3K, the randomly-spawned ancillaries from master-craftsmen buildings are scripted.

Unlike db entries, which are compiled during the initial loading screen of the game and turned into engine data, and are often static with few exceptions, Lua is a dynamic energy within the game, and is the only direct way to access a multitude of game features, background data, and more.

==== From Poop To OOP ====
From here to the end of this series, the goal is to get you from writing poop – or, in some of your cases, absolutely nothing – to writing in OOP, like a true-blooded programmer, though that’s by no means necessary and you can stop any time prior to that.

To begin, I’m going to take you on a quick field-trip as we download some new software that will help us write better code using smart programs, and we’ll talk about some really easy ways to test Lua code.

After that, our next journey is through the Lua basics. We’ll learn about strings, and booleans, and functions, and tables, and loops, and return values. All of the basic details of the knowledge that are necessary for even the simplest scripts.

Next, we turn to Total War specifics. There are some concepts that we need to cover while writing Lua in Total War, such as events, interfaces, when to call your scripts, stuff like that.

Towards the end, I’ll progress from simple scripting to some more high-minded scripting, using what the biz refers to as “Object-Oriented Programming”. It’s a more advanced topic that won’t do well being talked about here, but getting a firm grasp on it will help propel your scripting to a new level.

All throughout this series, I’ll seek to keep the information as game-agnostic as possible, I’ll seek to cover all gaps of knowledge and point out any common troubleshooting tips where necessary, and I’ll be covering these topics in the order of which I believe they should be learned. It is highly recommended you don’t skip around or skip ahead, the order of these tutorials are deliberate.

=== Order ===
[[Lua:Chunks & Statements]]

[[Lua:Variables & Types]]

[[Lua:Expressions & Operators]]

[[Lua:Scopes & Stuff]]

[[Lua:Keywords]]

[[Lua:Tables & Loops]]

[[Lua:Functions, Arguments & Parameters (Also Returns)]]

[[Lua:Commands, Interfaces & Listeners]]

[[Lua:Calling Scripts]]

[[Lua:Advanced Conditionals]]

Lua:Expressions & Operators

2021-07-22T05:53:18Z

MrIncongruous: added a few explanations that don't appear on the "chunks and statements" section, which goes right before this one

As we’ve seen, Lua is made up of <code>chunks</code> and <code>statements</code>. Statements can contain variables, and all variables have a type, though it can change at any point.

Expressions are the section of a statement that, essentially, tell Lua ''what to do''. They come in a billion different shapes and sizes. For now, we’ll cover all the basics you’ll need, and some basics you really don’t need but I’ll hand it to you anyway, and we’ll go back and review some older stuff. Here we go!

==== Math Operators ====
Sweet. This is what all of those quizzes in grade school trained you for. We have the big four from algebra – addition, subtraction, multiplication, and division.
<code>out(2 + 3) → 5
out(5 - 1) → 4
out(16 * 3) → 48
out(9 / 3) → 3</code>
We can also use a <code>-</code> to ''negate'' a value, or, in simple terms, turn a positive number into a negative and vice versa.
<code>a = 10
b = -20
out( -a ) → -10
out( -b ) → 20</code>
We also have a couple other fun math things. We can raise numbers to any power, using an exponential expression.
<code>a = 2
b = 4
c = 3
out( a^a ) → 4
out( b^c ) → 64
out( 64^0.5 ) → 8 -- getting the square root of a number!</code>
We can also use some modulo math. It’s a way of dividing two numbers that gives you the amount ''remaining'', and it’s a great way to read if a number is a ''multiple'' of another.
<code>out(8 % 2) → 0 -- 8/2 = 4, and divides evenly, so nothing is remaining!
out(7 % 2) → 1 -- 7/2. "6/2" divides evenly, so we subtract 6 from 7, and get "1" as the remainder!
out(8 % 3) → 2 -- 8/3. "6/3" divides evenly, so we subtract 6 from 8, and get "2" as the remainder.</code>
As said, it’s a great way to read if a number is a multiple of another. If a modulo expression returns “0”, that means it divided evenly, and is therefore a multiple of the number divided by.

And that’s math!

==== Comparison Operators ====
This sounds a lot more complicated than “math”, eh? It’s not that complicated – we’re comparing how two variables relate to one another, using expressions we’ve all seen before. The list of comparison operators are as follows:

* < — “less than”
* > — “greater than”
* <= — “less than or equal to”
* >= “greater than or equal to”
* == “equal to”
* ~= “not equal to”

All of these expressions result in a boolean value, that is, it tells you if the result of what you're saying is true or false.
<code>a = 10
b = 7 + 3
out(a == b) → true -- they ARE equal!
out(a ~= b) → false -- they ARE NOT not equal (weird, I know)!

c = 8
d = 7

out(c > d) → true -- 8 is greater than 7
out(c < d) → false -- 8 is NOT less than 7</code>
It’s important to note that Lua will consider different types to be different values. A string (ie a group of characters, like the word "hello" or the character sequence "15") and a number will always be different. Lua will throw an error if you attempt to compare – using less-than or greater-than – any two separate types. Lua will not throw an error for “==” and “~=”, and if they are separate types, they will always be inequal.
<code>a = 15
b = "15"
out(a == b) → false -- they are different types!
out(a >= b) → error (attempt to compare number with string)</code>
Do note that you can compare strings using greater or less than, but it compares the alphanumerical order of the first character. “0” is less than every number or letter, whereas “a” is greater than every number and less than every letter, and “z” is greater than every number or letter. Again, not really important, but you came here to read me ramble on about random stuff.

And that ends our comparison operators!

==== Logical Operators ====
Next up are our logical operators! We have three operators to concern ourselves with here: ''and'', ''or'', and ''not''.

''Not'', as a logical operator, is pretty simple and super handy. It basically converts the value to the right of it into a boolean, and reverses it. Any value other than <code>nil</code> or <code>false</code> will be converted into <code>false</code>; <code>nil</code> or <code>false</code> will be converted to <code>true</code>. Let’s take a look:
<code>a = true
b = nil
out(not b) → true -- prints a double negative - not false, so true
out(not a) → false -- reverses the value of "true"

c = 100
out(c) → 100
out(not not c) → true -- c is a number, "not c" would become "false", and "not false" would become "true"</code>
The operators ''and'' and ''or'' are the hearts of a lot of logic in Lua. “If this and this, then do this”.
<code>a = 15
b = false
if a == 15 and not b then -- "if a is equal to the number fifteen, and "not b" returns true, then ... "
out("It does the thing!") -- " ... print the text! "
end</code>
You’ll practically always see these two used in this way, for ''conditional statements'' like that – if these conditions work out, then do this other thing.

==== Homeless Operators ====
I don’t really have a category for these two operators, but they’re incredibly important.

First off, we have concatenation, which we’ve seen before. It’s a way to add two strings of characters together, and make them into one happy family, using a simple pair of dots.
<code>a = "Hello"
b = "World!"
out(a .. " " .. b) → Hello World!</code>
A couple of notes real quick – I have the blank space in a string in the middle, to make sure it doesn’t print “HelloWorld!”. Also, I like to add spaces on either side of my concatenation operator, but that’s personal taste, this would also be valid:
<code>out(a.." "..b) → Hello World!</code>
And lastly, we have one more operator, and this time for the table type. The character <code>#</code> can be used to read the number of entries within an array (NOTE: an array is a set of different elements under one variable name).
It’s pretty awesome, let me show you:
<code>table = {"this", "is", "an", "example", "array"}
out(#table) → 5 -- there are five strings within the table!</code>
Please note that you really shouldn’t use the <code>#</code> operator if the table is not definitely an array. I’ll show you why using it on maps might mess something up:
<code>table = {
[1] = "test",
[2] = "example",
[5] = "boom",
[7000] = "woo",
[3] = "argh"
}

out(#table) → 7000</code>
In technicalities, it’s doing that because it’s reading the ''highest index in that table'', or the highest numerical key. Those are assigned automatically, in order, for arrays; in maps, there’s no such guarantee.

==== Challenge 1 ====
As before, go to repl.it and mess with everything.

Some suggestions on what to try:

* Make an array out of various strings, concatenate them together using <code>table[1]</code> and so on.
* Apply arithmetic to a series of 3 or more numbers
* Compare the length of two separate tables