# Lua:Tables & Loops

Alright, here we go – tables, and loops. We’ve covered tables in a good depth so far, but this should get you to full comfort. We’ll also talk about loops, and iterating through tables, and using maps. It’ll be cool. Let’s start with arrays and looping.

#### Arrays and Looping

Arrays, for those who don’t recall, are tables with incremental indexes starting at `1`. Lua automatically assigns values to an index, not the Lua-author. An example would be:

```    ```local example_array = {5, 4, 3, 2, 1}

out(example_array[1]) → 5
out(example_array[5]) → 1```
```

Arrays are always numbered incrementally. It’s easy enough to assign new values to existing arrays – and, after all, that’s 90% of their usefulness.

```    ```local example_array = {5, 4, 3, 2, 1}

out(example_array[1]) → 5
out(example_array[5]) → 1

out(example_array[6]) → nil -- doesn't exist!

example_array[6] = 20
out(example_array[6]) → 20```
```

Say you don’t know how many indexes there currently are in an array; say you’ve edited it a bunch of times, and there’s no easy way to read how many indexes there are (which is the norm). You can add on to the end of an array using the following:

```    ```local example_array = {5, 4, 3, 2, 1}

out(example_array[1]) → 5
out(example_array[5]) → 1

out(example_array[6]) → nil -- doesn't exist!

-- some stuff that randomizes the array, woo hoo

example_array[#example_array + 1] = 20 -- #example_array would be the current number of indexes; +1 is incrementing it, assigning '20' to an unused index
out(example_array[#example_array]) = 20 -- now #example_array is one higher than the previous statement, due to the assignment of '20'!```
```

Remember that the # operator returns the number of indexes in that array, and that it should not be used with maps.

With that remembered, let’s look at a loop!

```    ```local example_array = {5, 4, 3, 2, 1}

for i = 1, #example_array do
out(example_array[i]) → 5, 4, 3, 2, 1
end```
```

And that’s really it! The keyword `for` is hyper important, and allows us to loop over various indexes in an array. `for` defines a local variable – in this case, `i`, though it can be WHATEVER – to a minimum value, and a maximum value. In this instance, the minimum value of `i` is 1, while the maximum value of `i` is 5. And then, it runs the `for` chunk once for each value of `i`. That means, it runs `out(example_array[i])` once with i == 1, then once with i == 2, with i == 3, i == 4, and i == 5.

Loops for arrays like this are super useful, as I’ve hinted at. But how does this matter for Total War, you might be asking? Well, look no further! List interfaces!

Remember the script interface chapter, we saw something called a `CHARACTER_LIST_SCRIPT_INTERFACE`? List interfaces are common, and they’re a cool type of array that we can kinda use just like the above one, but differently. Since it’s an object, not just an array, we have to do a couple of different things. I’ll show you, then we’ll talk, kay?

```    ```local faction_name = cm:get_local_faction()
local faction = cm:get_faction(faction_name)

local character_list = faction:character_list()
for i = 0, character_list:num_items() - 1 do
local character = character_list:item_at(i)
-- check stuff about the character
end```
```

There are THREE important distinctions to make here.

First off – the minimum is `0`, NOT `1`, and the maximum has to be the number of items in that list minus one. That’s because these lists are defined in C++, where indexes start at 0, unlike Lua where indexes start at 1.

Secondly – the maximum can’t be defined as `#character_list`, because it’s not an array! `character_list:num_items()` returns the total number of items in that array, and there’s a `num_items()` method for every list interface.

Thirdly – you can’t use `character_list[i]` to read the index. IT’S NOT AN ARRAY! `character_list:item_at(i)` grabs the item at the index in the array; there’s an `item_at()` method for every list interface.

Arrays are really common in the CA script interfaces, and having a healthy grasp of them will allow you to do much more with your scripts.

#### Maps and Looping

While maps aren’t used in CA script interfaces, like arrays kinda are, they’re still really vital and can allow some super ease of scripting.

Reminder for what maps are: they’re tables with user-defined indexes.

```    ```local example_map = {
["first"] = 1,
["second"] = 5,
["third"] = 10
}

out(example_map["first"]) → 1```
```

Looping in maps is pretty similar to arrays, though you have to define two local variables, instead of just one.

```    ```local example_map = {
["first"] = 1,
["second"] = 5,
["third"] = 10
}

for key, value in pairs(example_map) do
out(value) → 1, 5, 10
end```
```

As before, we define the local variables with `for`. Those local variables are `key` and `value` – though, just like `i` in the above example, those variables can be named whatever you’d like. Using `key` and `value` is simply convention, same with `i`.

Using the keyword `in` is syntax here, it’s necessary between the two variables, and the pairs() function call. The function `pairs` basically defines that you want to iterate through the table (provided as a parameter to `pairs`). It doesn’t require understanding – just know that, to iterate through a map, use the above.

Now, where’s the usefulness? There’s a LOAD.

For one, a map loop is quicker than an array loop, and easier to write using Excel

```    ```-- you
local lame_units = {"wh_dlc02_vmp_cav_blood_knights_0", "wh_dlc04_vmp_veh_corpse_cart_0", "wh_dlc04_vmp_veh_corpse_cart_1", "wh_dlc04_vmp_veh_corpse_cart_2", "wh_main_vmp_inf_crypt_ghouls", "wh_main_vmp_mon_crypt_horrors", "wh_main_vmp_mon_vargheists", "wh_main_vmp_mon_varghulf", "wh_main_vmp_mon_varghulf"}

for i = 1, #lame_units do
cm:add_event_restricted_unit_record_for_faction(lame_units[i], "wh2_dlc11_vmp_the_barrow_legion")
end

-- the guy she told you not to worry about
local kill_units = {
["wh_dlc02_vmp_cav_blood_knights_0"] = true,
["wh_dlc04_vmp_veh_corpse_cart_0"] = true,
["wh_dlc04_vmp_veh_corpse_cart_1"] = true,
["wh_dlc04_vmp_veh_corpse_cart_2"] = true,
["wh_main_vmp_inf_crypt_ghouls"] = true,
["wh_main_vmp_mon_crypt_horrors"] = true,
["wh_main_vmp_mon_vargheists"] = true,
["wh_main_vmp_mon_varghulf"] = true,
["wh_main_vmp_veh_black_coach"] = true
}

for unit, _ in pairs(kill_units) do
cm:add_event_restricted_unit_record_for_faction(unit, "wh2_dlc11_vmp_the_barrow_legion")
end```
```

For another, it allows you to iterate through a lot of data at once, with real ease. (the following is a further example from the Return of the Lichemaster mod!)

```    ```local subtypes = {
["AK_hobo_nameless"] = {
["forename"] = "names_name_666777891",
["family_name"] = "names_name_666777892",
["clan_name"] = "",
["other_name"] = "",
["age"] = 50,
["is_male"] = true,
["agent_type"] = "general",
["agent_subtype"] = "AK_hobo_nameless",
["is_immortal"] = true,
["art_set_id"] = "AK_hobo_nameless"
},
["AK_hobo_draesca"] = {
["forename"] = "names_name_666777893",
["family_name"] = "names_name_666777894",
["clan_name"] = "",
["other_name"] = "",
["age"] = 50,
["is_male"] = true,
["agent_type"] = "general",
["agent_subtype"] = "AK_hobo_draesca",
["is_immortal"] = true,
["art_set_id"] = "AK_hobo_draesca",
["ancillary1"] = "AK_hobo_draesca_helmet"
},
["AK_hobo_priestess"] = {
["forename"] = "names_name_666777895",
["family_name"] = "names_name_666777896",
["clan_name"] = "",
["other_name"] = "",
["age"] = 50,
["is_male"] = true,
["agent_type"] = "general",
["agent_subtype"] = "AK_hobo_priestess",
["is_immortal"] = true,
["art_set_id"] = "AK_hobo_priestess",
["ancillary1"] = "AK_hobo_priestess_trickster",
["ancillary2"] = "AK_hobo_priestess_charms"
}
}

for key, subtype_data in pairs(subtypes) do
cm:spawn_character_to_pool(
"wh2_dlc11_vmp_the_barrow_legion",
subtype_data.forename,
subtype_data.family_name,
subtype_data.clan_name,
subtype_data.other_name,
subtype_data.age,
subtype_data.is_male,
subtype_data.agent_type,
subtype_data.agent_subtype,
subtype_data.is_immortal,
subtype_data.art_set_id
)
end```
```

Yep! You can have tables within tables, maps within maps, loops within loops.

And yes, you can access an index using `table.index_key`, if that index is a string. You obviously can’t do that with a number. That syntax is really common – using `table["index_key"]` to define an index’s value, and then accessing that using `table.index_key`, though you can use them interchangeably; they’re literally the exact same thing, no functional difference.

#### Other Loops

There are a couple other ways to loop, that don’t involve tables.

The most common other one – especially in the Total War context – is a `while` loop. For instance, we can see the following example in the wh_main_chs_chaos_start.lua file:

```    ```local x = desired_spawn_point[1]
local y = desired_spawn_point[2]
local valid = false

while not valid do
if is_valid_spawn_point(x, y) then
valid = true
else
x = x + 1
y = y + 1
end
end```
```

In this instance, the `while` chunk is run once entirely through, continuously, until “not valid” returns false – aka, until `valid` is `true`.

Don’t be frivolous with your use of `while` loops – they should last no more than, like, 0.05s. Using them causes the rest of the Lua environment to come to a screeching halt, as basically nothing else can happen during a while loop.

Similarly, you can use a `repeat` loop, which is the same functionally – runs until a condition is met – except a `repeat` loop will always run AT LEAST once, whereas a `while` loop won’t run at all if the condition isn’t met. Let’s spy another CA example, this time in wh2_dlc11_treasure_maps.lua:

```    ```repeat
random_number = cm:random_number(#level)
ancillary = level[random_number]
until(context:faction():ancillary_exists(ancillary) == false)```
```

Which is loud-person talk for “go through random numbers until we find an ancillary in this array which doesn’t exist in this faction”.

Again, repeat is pretty performance-heavy, as it holds up basically everything else. Don’t do big repeat loops, please. Please. PLEASE.

Or, do. I don’t really care.

#### CA Loops and Timing

There are some CA-defined methods to do a repeated function, or to delay a function, which do not hold up the entire environment like the above two loops. These callbacks are super helpful for repeated constant operation; for instance, I used a repeat_callback recently to print out the camera coordinates every half a second, so I could work on a custom cutscene. There was absolutely no performance drop, because Lua is beautiful.

The two types are callback and, spoiler alert, repeat_callback. The former simply delays a function by a time; the latter delays a function by that time, and repeats that same delay and function over and over again.

```    ```cm:callback(function()
-- run this chunk ONCE after five seconds
end,
5)

cm:repeat_callback(function()
-- run this chunk every five seconds
end,
5)```
```

For the campaign manager, these two functions are wrapped and the final parameter is in seconds. However, for battle and frontend, these would be milliseconds.

```    ```-- BATTLE
bm:callback(function()
-- run this chunk ONCE after five seconds
end,
5000)

bm:repeat_callback(function()
-- run this chunk every five seconds
end,
5000)

-- FRONTEND
local timer_obj = get_tm()
timer_obj:callback(function()
-- run this chunk ONCE after five seconds
end,
5000)

timer_obj:repeat_callback(function()
-- run this chunk every five seconds
end,
5000)```
```

There are lots of uses for these; namely, waiting for some UI to load, putting a timer on a quest battle for deployments, disabling/reenabling event feeds of a certain type, cutscene timing, and much else!