Battle Documentation

Scripting Homepage

Search

Search battle only




Game Areas

• Campaign Index
• > Battle Index
• Frontend Index

On this page

Key

Loaded in Campaign
Loaded in Battle
Loaded in Frontend

• Lua Language
•   More Information
•   Lua Data Types
•   Local and Global Variables
•   if statements
•   Conditional Operators
•   Standard Functions
•     print
•     type
•     tostring
•     tonumber
•     loadstring
• Nil
• Booleans
• Numbers
• Strings
•   String Patterns
•   String Library
•     byte
•     byte_compare
•     byte_greater_than
•     byte_less_than
•     char
•     dump
•     ends_with
•     find
•     find_lua
•     find_utf8
•     format
•     gmatch
•     gsub
•     len
•     len_utf8
•     lower
•     match
•     rep
•     reverse
•     starts_with
•     sub
•     sub_utf8
•     split
•     upper
• Functions
•   Varargs
• Tables
•   Table Construction
•   Tables and Memory
•   Indexed Tables
•   Lookup Tables
•   Standard Traversal
•   Table Iterators
•     ipairs
•     pairs
•     ipairs_reverse
•     dpairs
•   Table Library
•     concat
•     insert
•     maxn
•     remove
•     sort
•     tostring
•     contains
•     binary_search
•     binary_search_interval
•     is_empty
•     copy
•     mem_address
•     indexed_to_lookup
•     compile_tables
•     merge_tables
• Userdata
• Math
•   Values
•   Functions
•     abs
•     acos
•     asin
•     atan
•     atan2
•     ceil
•     ceil_to
•     clamp
•     cos
•     cosh
•     deg
•     exp
•     floor
•     floor_to
•     fmod
•     frexp
•     ldexp
•     log
•     log10
•     map_range
•     max
•     min
•     modf
•     normalize
•     pow
•     rad
•     random
•     randomseed
•     round
•     sin
•     sinh
•     sqrt
•     tan
•     tanh
•     to_bool

Battle Topics

• Battle Index
• Battle Hierarchy
• Battle Reinforcements
• > Lua Language
• Scripted Events

Game Code Interfaces

• Battle
• Alliances
• Alliance
• Armies
• Army
• Units
• Unit
• Unitcontroller
• AI Planners
• Assault Equipment
• Building
• Buildings
• Camera
• Capture Location
• Debug Drawing
• Sound Effects
• Subtitles
• Vector
• Common
• ScriptedValueRegistry
• UIComponents

Script Interfaces

• Battle Manager
• Core
• Advice Manager
• Battle UI Manager
• Convex Areas
• Custom Context
• Battle Cutscenes
• Generated Battle
• Global
• Infotext Manager
• Key Steal Manager
• Movie Overlays
• Navigable Tours
• Objectives Manager
• Script AI Planner
• Script Messager
• Script Unit
• Scripted Tours
• Text Pointers
• Timer Manager
• Topic Leader

Data Interfaces

• Scripted Tour Helpers

Lua Language

Lua is an interpreted language that is used for scripting in Total War. It's lightweight, fast, and easy to use.

Lua instructions are written in a text file, which is generally given a .lua file extension. The game looks to load certain script files when loading, and may be configured to load specific scripts when loading a particular campaign or battle.

Version 5.1 of lua is used in Total War scripting - the latest at time of writing is version 5.3.5.

Whitespace in lua is ignored, so scripts can be spaced out according to the scripters preference. Lua statements may optionally be terminated with a semicolon. Individual lines may be commented with -- - this causes the rest of the line to be ignored. Blocks of script of any size may be commented with --[[ script ]]. These blocks may not be nested, however.

Lua is case-sensitive, so variables named value, Value and VALUE are all different. This is a common source of bugs.

Example:

Relevant in Campaign
Relevant in Battle
Relevant in Frontend

More information about lua can be found on the following sites:

https://www.lua.org	Lua homepage.
https://www.lua.org/demo.html	Lua demo site - allows snippets of script to be tested outside of the game (very useful).
https://www.lua.org/manual/5.1/	The lua manual.
http://lua-users.org/wiki/	Lua wiki - contains useful information about supplied libraries.
https://www.tutorialspoint.com/lua/	Lua tutorial - others are available.

Lua supports only eight data types, six of which are documented further down this page:

Data Type	Description
nil	The absence of a value.
boolean	true/false values.
number	Floating-point numeric values.
string	Text values.
function	Executable chunks of script.
table	Dynamically-sized key/value lists, may be used to build complex data structures.
userdata	Objects provided by the host program to lua, with an interface on which script may make function calls.
thread	Represents independent threads of execution - not supported in Total War scripting.

Variables created in lua are global by default, which means they are accessible across the entire scope of the script. Variables can optionally be declared with local scope, whereby they only persist for the lifetime of the block in which they are declared. It is strongly encouraged to declare variables with local scope unless there is a compelling reason to do otherwise, as it lessens the risk of them being accessed or overwritten by accident.

Example:

An if statement may be used to perform a logical test and, based on the boolean result of that test, execute different blocks of instruction. An if statement will execute a block of script specified by a mandatory then operator if the logical test evaluates to true, or a second optional block specified by an else operator if it doesn't. Each if statement must be terminated by the keyword end.

An else operator following another if statement may be combined into an elseif operator. Converting nested if statements to elseif operators in this way saves on having to terminate each if statement with end - see the example below.

Example:

Conditional tests may be performed by structures such as if statements, while loops and repeat loops to make decisions about what scripts to execute. Any values can be evaluated in a conditional test - non-boolean values may be evaluated in a boolean manner as follows:

• false boolean values, and nil values, evaluate to false.
• Any other value evaluates to true (including the number 0, which evaluates to false in C).

The logical operator not may be used to negate the result of a boolean - if passed a true value it returns false, and if passed a false value it returns true. The value returned by the not operator is always boolean, even if the value supplied was not. The statement x = not not x converts x to a boolean value, therefore.

The logical operators and and or may be used to assess multiple boolean conditions together. The and operator returns true if both of the expressions passed to it evaluate to true themselves. The or operator returns the second value passed to it if the first evaluates to false, otherwise the first value is returned. Unlike and, not and other comparison operators, therefore, or can return something other than a boolean value. This can be useful for setting default values for a variable - see the example below.

The lua interpreter reads forward when performing conditional tests, and will not evaluate expressions that it doesn't need to. For example, if the first expression passed to an and operator evaluates to false then the second is never evaluated. Likewise, if the first expression passed to an or operator evaluates to true then the second expression is never evaluated (and the first is returned). These constructs can both be useful in different ways - see the examples below.

The not operator has precedence (meaning it gets evaluated first), followed by the and operator and finally the or operator. Parenthesis () can be used to override the natural order of precedence.

Example - Relying on conversion to boolean to test existence of value:

Example - Using 'not' to convert to boolean:

Example - and/or operator examples:

Example - Compound logical test of greater length, with parenthesis:

Example - Using 'or' to set a default value during an assignment operation:

Example - Using 'and' to test existence or type before value of variable, to prevent errors :

This example shows how the 'and' operator can be used in a serial to guard operations on values that might otherwise fail and cause script errors. Performing a numeric comparison such as > on a non-numeric value is illegal and would cause a script failure. This is prevented by the first expression which tests whether value is a number. If value is not a number, and the type check returns false, lua will not proceed on to evaluate the second expression (containing the numeric comparison) as the interpreter is smart enough to realise that it can't affect the final result.

Lua provides a number of standard functions for various puposes, some of which are documented below.

---

Nil

The data type nil represents the absence of a value in lua. nil is both the name of the type and also the only value that a variable of that type can take. All variables contain the value nil, and are of type nil, before they are declared. Assigning nil to a variable is the same as deleting it.

nil values resolve to false when considered in a logical expression.

Example:

---

Booleans

Boolean values may be either true or false. Boolean values are of most use when evaluated by language structures such as if statements and while loops that perform logical tests and take action based on the result. The logical operators and, or and not can be used to evaluate booleans.

See the section on Conditional Operators for more information.

Example:

---

Numbers

Numeric values in lua are real, so they may contain decimal places. There is no integer numeric type. The default lua language specification sets numbers to be stored as double-precision floats. At time of writing, however, numbers in Total War's implementation of lua are stored as single-precision floats, which offer only about 7 digits of precision. Scripters should be aware of this limitation when planning scripts that may potentially have to deal with very large or precise numbers.

Number values can be added, subtracted, multiplied and divided with the +, -, * and / operators respectively. Exponents may be expressed with the ^ operator.

Example:

---

Strings

Strings are variables containing representations of text. A string may be specified by enclosing a value in matching single or double quotes. A string can be zero, one or more characters long, with no upper limit beyond the amount of memory available.

Strings may be joined together using the concatenation operator, ...

Example:

Some of the string functions described in the next section make use of string patterns, a method of matching sequences of characters akin to regular expressions. More information about lua string patterns may be found on lua-users.org here.

Lua provides a number of operations that can be performed on strings, listed below. More detailed information about these functions may be found on the dedicated page on lua-users.org here.

The functions may be called in the form string.<function>(<string>, <arguments>), or <string>:<function>(<arguments>) where appropriate.

---

Functions

Functions are chunks of script that, when executed, perform one or more operations and then return control to the script that called them. Function declarations begin with the function keyword, and end with a corresponding end keyword. They are useful for encapsulating tasks that need to be performed repeatedly.

Functions can optionally take one or more argument values from the calling script. This allows a single function to produce different results when run repeatedly, based on its input values. Functions may also optionally return one or more values to the script that called them.

Functions in lua are first-class values, which means that they may be assigned and re-assigned to variables in exactly the same manner as number values, string values and so on. As with other variables types in lua it's possible for functions to be anonymous, where they are created without a name.

Once declared, a function can be called and executed in script by appending open and close parenthesis characters to its name in the form <function_name>(arg1, arg2). See the examples below.

Example - Simple function declaration and execution:

Example - Alternative form of function declaration:

This alternative form of function declaration is identical to the previous example. It better illustrates the nature of functions as just another type of variable, created by assignment like a string or number.

Example - Function taking two arguments:

Arguments can be specified in the function specification as follows. The arguments will be accessible as local variables throughout the lifetime of the function.

Example - Function returning two values:

Example - Example of passing functions as arguments to another function:

This includes an example of an anonymous function.

A function can also take a variable number of arguments in a vararg structure. Using varargs, an unlimited number of arguments can be supplied to a function, which accesses them as elements in a table created within the function block called arg. The number of arguments can be accessed at the special element n within the arg table. See the examples below.

Example:

---

Tables

Tables are the only data type in lua that can be used to contain other data. As such, they are the only mechanism available for building complex data structures.

Lua tables are associative arrays, which means they store sets of key/value pairs. A value in a table is stored in a record corresponding to a key, and that value may later accessed or modified using that same key.

An example representation of a table:

Key	Value
1	"first"
2	"second place"
3	"third place"
4	"also ran"
5	"also ran"

If a value is written to a table at a key which is already associated with a value, then that previous value is overwritten, just like normal variables.

Table keys are most commonly or usefully number or string values, but may be of any data type other than nil. Values stored at keys within a table can be of any type, including function or table (allowing tables to be nested). If a value of nil is stored at a particular key, then that is equivalent to deleting that key/value combination. If a key is looked up in a table at which no value has been stored, then nil is returned.

Values in a table may be accessed using [] square brackets, or by using the . accessor if the key is a string that contains no spaces, and where the first character of that string is not a numeric character. See the examples below:

Example:

Example:

Before a table can be used it must be created with a table constructor, which is a pair of {} braces. Values, or key/value pairs, can be included within the constructor so that they are stored in the table from creation.

Within the {} braces which denote the new table, key/value combinations that specify data to add to the table on construction can be given in a variety of formats:

1. Keys can be explictly given by enclosing them in square brackets [].
2. If a key name is given but not enclosed within square brackets, it is assumed to be a string.
3. If the key is omitted altogether, then the first ascending free integer is used as the key. This shorthand is useful for creating Indexed Tables.

Example - Create an empty table:

Example - Create an indexed table with data values by omitting the keys:

If data values are supplied without keys, separated by commas, then each value is inserted into the table at the first available integer key, starting at 1. See the section on Indexed Tables below.

Example - Create a table with explicit key/values:

Example - Shorthand way of creating string keys during construction:

Example - Create a table with key/values, but where the key is evaluated:

Tables are always assigned by reference, and passed by reference if supplied as function arguments. Multiple references to the same table can exist at the same time. When no more references to a table exist, the lua garbage collector will eventually delete it and reclaim the memory it uses.

Example:

Tables are commonly used in one of two manners. Our internal nomenclature for these is Indexed vs Lookup Tables. There is no difference in the manner of creation between the two, and indeed one table can work in both modes at once, although this is rarely done.

Indexed tables, as we call them, contain elements stored at keys in an ascending numerical sequence, starting from 1. Tables arranged in this manner are easy to create, easy to iterate over in sequence, and many functions within the table library and elsewhere require tables to be arranged in an indexed manner in order to work. Additionally, the sizeof operator # will only produce accurate results for an indexed table.

Indexed tables can be iterated-over with a manual for-loop (see the section on Standard Traversal), or with the ipairs iterator. The pairs iterator can also be used, but the order of iteration will not be predictable or deterministic.

It is advantageous to create an indexed table when the problem being solved would benefit from storing and working with data in a listed, fixed order. If the relative order in which elements are stored in the table is important, especially if iterating over the table, or if the table's use case demands that the data within it will be accessed via iteration more than directly by key, then chances are it should be set up as an indexed table. Examples include stacks, queues, trees or other data structure where the order of elements needs to be preserved.

Example - Indexed table creation:

If no keys are given during table creation, then the table is indexed by default.

Tables containing keys that are not defined in an ascending integer sequence tend to be used as lookup tables. Data in a lookup table is more commonly looked up directly by key, rather than by iteration. If data within the table is accessed more commonly by iteration, or if it's important to maintain an order between the records stored in the table, then consider creating an indexed table with ascending numeric keys instead.

Lookup tables are most useful for flat data sets with no order of precedence or operation between the data records. Data sets akin to database tables are ideal for storing in lookup tables.

Lookup tables cannot be iterated over with the ipairs iterator - instead, the pairs iterator may be used. The downside to pairs is that order of iteration cannot be relied on to be the same on different machines running the same script, or even on the same machine running the same script multiple times.

Example - Lookup table example, showing nested tables:

Tables are commonly traversed/iterated over with a for-loop with manually-defined limits and steps. This is possible if the table keys are arranged in a suitable numeric order - usually an ascending integer sequence (see the section on Indexed Tables).

The size of a table where values are assigned at ascending numeric integer keys can be accessed with the # operator. This reports the first integer key n for which no value is stored at key n + 1.

Example - Examples of #t:

Example - Traversal by numeric sequence:

The lua language provides the iterator functions ipairs and pairs for iterating over tables where Standard Traversal may not be possible or desirable.

The ipairs iterator behaves much the same as traversing over a table in ascending numeric sequence. Like other iterator functions, ipairs automatically creates local variables for the key and (optionally) the value for each table element it traverses. The ipairs iterator starts at the table element corresponding to a numeric key value of 1, increments the key by 1 for each loop iteration, and stops at the first integer key it finds for which a value is not assigned.

Unlike ipairs and numeric traversal, the pairs iterator allows traversal over all elements in a table, regardless of key type or any 'gaps' in the data. The main caveat to usage is that the order of traversal is not deterministic, either between machines or on the same machine making multiple passes over the same table. As such, the pairs iterator is unsafe to use in multiplayer scripts as two different machines will traverse the same table in different orders.

Also provided within the scripting libraries are:

• dpairs, which is a deterministic version of pairs. This eliminates the problem of not being able to use pairs in multiplayer, but is written in lua and is quite computationally slow, so use this sparingly.
• ipairs_reverse is an equivalent to ipairs which iterates in reverse order.

See also the section on Game Object Iterators, for iterators that work on non-table game objects.

ipairs(table subject table)

Iterates over a numerically indexed table. An indexed table is one containing keys in an ascending numeric sequence, starting from 1. The iterator will query the key/value pair where the key is 1, and then 2, 3 and so on, until it finds a key/pair that doesn't exist, at which point the iterator will terminate.
The ipairs function returns three values - an iterator function, the table to iterate over, and the control variable. When used with a for loop the iterator can be used to get the key/value of each element in the table in sequence. See the examples below for more information on usage.
Unlike the pairs iterator, ipairs disregards values stored at non-numeric keys, but the order in which values are returned is deterministic, meaning ipairs is safe to use in multiplayer mode.
The ipairs iterator is interchangeable with using the size of table operator # to manually control the loop iteration.

Parameters:

1

table

subject table

Returns:

1. function iterator function
2. table subject table
3. number control variable

Example - Standard ipairs example:

t = {"january", "february", "march", "april", "may" }         -- table created with ascending numeric keys
for key, value in ipairs(t) do
    -- local variables called 'key' and 'value' are automatically created each loop cycle
    print("key: " .. key .. ", value: " .. value);
end


key: 1, value: january
key: 2, value: febraury
key: 3, value: march
key: 4, value: april
key: 5, value: may


Example - Ipairs example with gap in numeric sequence:

t = { [1] = "first", [2] = "second", [3] = "third", [5] = "fifth" }         -- gap at 4
for key, value in ipairs(t) do
    -- local variables called 'key' and 'value' are automatically created each loop cycle
    print("key: " .. key .. ", value: " .. value);
end


key: 1, value: first
key: 2, value: second
key: 3, value: third


Example - Ipairs example with table containing non-numeric keys:

t = {
    ["fruit"] = "apples",
    [4] = "fourth",
    ["animal"] = "cat",
    [2] = "second",
    [1] = "first",
    ["month"] = "september"
}

for key, value in ipairs(t) do
    -- loop will continue until it fails to find a value corresponding to key 3, and then stop
    print("key: " .. key .. ", value: " .. value);
end


key: 1, value: first
key: 2, value: second


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 1208

pairs(table subject table)

Iterates over any table returning key/value pairs in a non-deterministic order. The pairs iterator function is the main way to query each record in a table that is not numerically indexed. However, the order of iteration is not guaranteed, so the pairs iterator should be used with caution in multiplayer games where a different order of modifications to the model between clients can cause the game to desync.
The pairs function returns three values - an iterator function, the table to iterate over, and the control variable. When used with a for loop the iterator can be used to get the key/value of each element in the table in sequence. See the examples below for more information on usage.

Parameters:

1

table

subject table

Returns:

1. function iterator function
2. table subject table
3. number control variable

Example - pairs example:

Note how the order of the output is arbitrary.

-- table with keys of lots of different types - impossible to traverse with #t or ipairs
t = {
    [1] = "first",
["greeting"] = "hello",
[5] = "fifth",
[10] = "tenth",
[true] = "this has a boolean key",
    [function() print("hello") end] = "This has a function key! Weird but possible"
}
for key, value in pairs(t) do
    print("key: " .. tostring(key) .. ", value: " .. tostring(value));
end


key: 1, value: first
key: greeting, value: hello
key: function: 0x2194d10, value: This has a function key! Weird but possible
key: 5, value: fifth
key: true, value: this has a boolean key
key: 10, value: tenth


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 1259

ipairs_reverse(table table)

Iterator function that allows Indexed Tables to be iterated over in reverse order. This function can be used effectively with a for-loop to traverse backwards over an indexed table - see the example below.

Parameters:

1

table

table

Returns:

1. function iterator function
2. table table
3. number initial search key

Example:

local t = {"monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"}
for index, day in ipairs_reverse(t) do
    print("Day " .. index .. " is " .. day);
end;


Day 7 is sunday
Day 6 is saturday
Day 5 is friday
Day 4 is thursday
Day 3 is wednesday
Day 2 is tuesday
Day 1 is monday


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 1300

dpairs(table subject table)

An iterator function, a deterministic equivalent of pairs. It is used in the same way, but it iterates over the table in a deterministic way, which makes it safe for use in multiplayer.
Note that iteration using this function would be slower, so don't use it with large tables in performance-critical code! However, for the general usage in gameplay model or UI code with not many entries, it should be fine. Still, be mindful of the perfomance.
It works by first iterating over all keys of the given table (using pairs), compiling the keys of the same type in separate tables. Then it sorts those tables and finally going through their contents (keys), table by table.
dpairs requires that all keys within the table are number or string values.

Parameters:

1

table

subject table

Returns:

1. function iterator function
2. table subject table
3. nil starting index value

Example - dpairs example:

Note how the order of the output is not arbitrary, numerical keys before string keys.

t = { 3, 2, 1, colour = "black", monster = "dragons", {}, "dragons", index = 5 }
t[11] = 6
t[12] = 7
for k, v in dpairs(t) do
    print(tostring(k) .. " " .. tostring(v))
end


1 3
2 2
3 1
4 table: 0x85bc50
5 dragons
11 6
12 7
colour black
index 5
monster dragons


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 1324

Back to top

Table Library

Lua provides a library of operations that can be performed on tables, listed below. More detailed information about these functions may be found on the dedicated page on lua-users.org here.

The functions may be called in the form table.<function>(<t>, <arguments>).

table.concat(table table, [string separator], [number start element], [number end element])

Concatenates the values in the supplied table into a string, with optional separator characters, and returns that string. This can be a memory-efficient way of concatenating large amounts of strings together.

Parameters:

1	table	Table to concatenate.
2	string	optional, default value="" Separator string to insert between elements from the table.
3	number	optional, default value=1 Table element at which to start concatenating.
4	number	optional, default value=<table_size> Table element at which to finish concatenating.

Returns:

1. nil

Example:

t = {"first", "second", "third", "fourth", "fifth"}
print(table.concat(t))
print(table.concat(t, " ", 2, 4))


firstsecondthirdfourthfifth
second third fourth


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 1415

table.insert(table table, [number position], obj value)

Inserts a value into the supplied table. The index at which to insert the value may optionally be specified - note that this can change the sequence of arguments.
If no position argument is specified then the first available integer key in ascending order is chosen, starting from 1.

Parameters:

1	table	Table to insert element in to.
2	number	optional, default value=<table_size> Position at which to insert value. Note that this may be omitted, in which case the value to insert should be specified as the second argument. In this case the first available integer key is chosen, ascending from 1.
3	obj	Value to insert. If a third argument is omitted, the second is taken as the value to insert.

Returns:

1. nil

Example:

t = {1, 2, 3}
table.insert(t, "hello")            -- insert "hello" as the last element in the table
table.insert(t, 3, "goodbye")        -- insert "goodbye" as the third element in the table
print(table.concat(t, " "))


1 2 goodbye 3 hello


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 1428

table.maxn(table table)

Returns the largest positive numeric index within the supplied table at which a value is assigned. Unlike the # operator, this will not stop counting if a gap in the integer sequence is found.

Parameters:

1

table

table

Returns:

1. number highest index

Example:

t = {}
t[1] = "goodbye"
t[2] = "adios"
t[4] = "auf"
-- no t[5]
t[6] = "la revedere"
t["8"] = "au revoir"        -- not counted as the key is a string
print("table.maxn(t) is " .. table.maxn(t))
print("#t is " .. #t)


table.maxn(t) is 6
#t is 4


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 1441

table.remove(table table, [number position])

Removes the element from the supplied table at the supplied numeric index.

Parameters:

1	table	Table.
2	number	optional, default value=<table_size> Position within table of element to remove.

Returns:

1. nil

Example:

t = {1, 2, 3, 4, 5}
table.remove(t)        -- remove element at the end of the table
table.remove(t, 2)        -- remove second element from the table
print(table.concat(t))


134


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 1458

table.sort(table table, [function comparison])

Sorts the elements in the supplied table into a new order. A comparison function may be supplied, which should take two table elements as arguments and return true if the first of these elements should appear in the final sorted order before the second, or false if the opposite is desired. The table is sorted into ascending numerical order by default, which is the equivalent of supplying the sort function function(a, b) return a < b end.

Parameters:

1	table	Table to sort.
2	function	optional, default value=<ascending_sort_order> Comparison function.

Returns:

1. nil

Example - Default ascending sort order:

t = {4, 5, 3, 1, 8, 10}
table.sort(t)
print(table.concat(t, " "))


1 3 4 5 8 10


Example - Reverse sort order:

t = {4, 5, 3, 1, 8, 10}
table.sort(t, function(a, b) return a > b end)
print(table.concat(t, " "))


10 8 5 4 3 1


Example - Sorting a table of strings into length order:

t = {"very_long", "short", "longer", "really_really_long"}
table.sort(t, function(a, b) return string.len(a) < string.len(b) end)
print(table.concat(t, "..."))


short...longer...very_long...really_really_long


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 1469

table.tostring(table table, boolean for campaign savegame, [number max depth], [number tab level])

Converts a table into a string representation of that table for debug output. Note that this function is not provided with lua but is provided by Total War's script libraries.

Parameters:

1	table	Subject table.
2	boolean	Set to true if the string is intended for saving into a campaign savegame. This discards values that are not boolean, number, strings or tables.
3	number	optional, default value=3 Maximum depth. This is the maximum depth of tables-within-tables to which the function will descend. Supply -1 to set no maximum depth, which makes an infinite loop a possibility.
4	number	optional, default value=0 Starting tab level. This number of tabs will be prepended to the start of each new line in the output.

Returns:

1. string table to string

defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 1493

table.contains(table table, value value)

Reports if the supplied table contains the supplied value. If the table does contain the supplied value, the corresponding key at which it may be found is returned, otherwise false is returned.

Parameters:

1	table	table
2	value	value

Returns:

1. value key corresponding to value

defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 1600

table.binary_search(table table, value value, [function comparison function])

Searches for a given value in the supplied sorted indexed table using binary search (which has log2 complexity).

Parameters:

1	table	The table to search the value in. It must be indexed table already sorted using the comparison function.
2	value	The value to search the table for.
3	function	optional, default value=less-than-comparison Comparison function used also for the sorting. If not provided operator less-than is used.

Returns:

1. boolean is the given value present in the table
2. number index of an occurence of the value if it is present (not necessary the first one, if more than one are present), or where the value should be inserted in order to keep the table sorted

defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 1619

table.binary_search_interval(
  table table,
  number first subinterval index,
  number last subinterval index,
  value value,
  function comparison function
)

Searches for a given value in a subinterval of the supplied sorted indexed table using binary search (which has log2 complexity).

Parameters:

1	table	table
2	number	first subinterval index
3	number	last subinterval index
4	value	value
5	function	Comparison function used also for the sorting.

Returns:

1. boolean is the given value present in the table
2. number index of an occurence of the value if it is present in the given interval (not necessary the first one, if more than one are present), or where the value should be inserted in order to keep the table sorted

defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 1637

table.is_empty(table table)

Returns whether the supplied table is empty.

Parameters:

1

table

Subject table.

Returns:

1. boolean is empty

defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 1668

table.copy(table table)

Returns a deep copy of the supplied table. All subtables are copied. Metatables are not copied. Cyclical references are preserved.

Parameters:

1

table

Subject table

Returns:

1. table copy

Example - Loading faction script:

This script snippet requires the path to the campaign faction folder, then loads the "faction_script_loader" script file, when the game is created.

my_table = { fruit = "apple", topping = { flavour = "cinnamon" } }
copied_table = table.copy(my_table)
copied_table.fruit = "banana"
copied_table.topping.flavour = "chocolate"
print(my_table.fruit .. " topped with " .. my_table.topping.flavour)
print(copied_table.fruit .. " topped with " .. copied_table.topping.flavour)


apple topped with cinnamon
banana topped with chocolate


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 1681

table.mem_address(table object, [boolean leave punctuation])

Returns the memory address portion of the result of calling tostring() with a table argument. The function will fail if the supplied table has a metatable that's write-protected.
If the leave punctuation flag is set then the memory address is supplied back still with its leading colon and space characters.

Parameters:

1	table	object
2	boolean	optional, default value=false leave punctuation

Returns:

1. string address string

defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 1727

table.indexed_to_lookup(table indexed table)

Returns another table containing all records in the supplied indexed table, except with the values set to keys. The values in the returned table will be true for all records.

Parameters:

1

table

indexed table

Returns:

1. table lookup table

Example:

indexed_t = {"oranges", "apples", "strawberries"}
lookup_t = table.indexed_to_lookup(indexed_t)
for key, value in pairs(lookup_t) do
print(key, value)
end


strawberries    true
oranges            true
apples            true


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 1768

table.compile_tables(table table_list, [table merge_rules])

Given a list of tables, sorts all tables by an optional load_order and then merges each one onto the previous successively. Can be used to merge and override data tables for mod compatibility.

Parameters:

1	table	The list of tables to be merged, indexed numerically.
2	table	optional, default value=default rules (fully recursive, allow overrides) A table describing the rules for merging, including recursion_levels and allow_overrides.

Returns:

1. table Returns the fully compiled table (a new table reference).

defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 1833

table.merge_tables(table merge_to, table merge_from, table merge_rules, [number recursion_level])

Merge two tables given a set of merge rules, implanting the data from merge_from into merge_to.

Parameters:

1	table	The table to which data will be merged. The return value is this table, following the merge.
2	table	The table from which data will be merged.
3	table	A table describing the rules for merging, including recursion_levels and allow_overrides.
4	number	optional, default value=1 The number of recursions this function call is at, i.e. the number of table layers into the original table that the merge has reached. If unspecified, this begins at 1.

Returns:

1. table Returns the original merge_to table, but with the contents of merge_from incoorporated into it.

defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 1862

---

Userdata

Userdata is an area of memory accessible to lua but created by the host program. In our case, the host program is the game executable. It allows the host program to package up code functionality in a black box that can be used in fixed ways script.

The interface objects supplied to script by the game in campaign and battle are typically userdata. It's not possible for script to meaningfully modify or query userdata objects in ways that weren't specifically set up by the creating code.

---

Math

The math library provides mathematical functions and values in a table that be called from within lua.

Back to top

Values

The math libraries provides the following constants that can be looked up:

Back to top

Functions

math.abs(number value)

Returns the absolute of the supplied value, converting it to a positive value if negative.

Parameters:

1

number

value

Returns:

1. number absolute value

Example:

print(math.abs(-4))


4


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 1944

math.acos(number value)

Returns the arc cosine of the supplied value, in radians. The supplied value should be between -1 and 1.

Parameters:

1

number

value

Returns:

1. number acos value in radians

Example:

print(math.acos(0.5))


1.0471975511966


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 1952

math.asin(number value)

Returns the arc sine of the supplied value, in radians. The supplied value should be between -1 and 1.

Parameters:

1

number

value

Returns:

1. number asin value in radians

Example:

print(math.asin(0.5))


0.5235987755983


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 1960

math.atan(number value)

Returns the arc tangent of the supplied value, in radians.

Parameters:

1

number

value

Returns:

1. number atan value in radians

Example:

print(math.atan2(1))


0.64350110879328


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 1968

math.atan2(number opposite, number adjacent)

Returns the arc tangent of the supplied opposite value divided by the supplied adjacent value, in radians. The sign of both arguments is used to find the quadrant of the result.

Parameters:

1	number	opposite
2	number	adjacent

Returns:

1. number atan value in radians

Example:

print(math.atan2(5, 5))
print(math.atan2(-5, 5))


0.78539816339745
-0.78539816339745


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 1976

math.ceil(number value)

Returns the smallest integer that is larger than or equal to the supplied value.

Parameters:

1

number

value

Returns:

1. number ceil value

Example:

print(math.ceil(2.2))


3


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 1987

math.ceil_to(number subject value, [number multiple value])

Returns the smallest multiple of the supplied multiple value, which is larger than the supplied subject value.

Parameters:

1	number	subject value
2	number	optional, default value=10 multiple value

Returns:

1. number ceiling value

Example:

-- print the smallest multiple of 50 that is larger than 128
print(math.ceil_to(128, 50))


150


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 1995

math.clamp(number value, number min, number max)

Clamps the supplied numeric value to be between the supplied min and max values. The clamped value is returned.

Parameters:

1	number	value
2	number	min
3	number	max

Returns:

1. number clamped value

defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 2009

math.cos(number value)

Returns the cosine of the supplied radian value.

Parameters:

1

number

value

Returns:

1. number cosine value

Example:

print(math.cos(1.0471975511966))


0.5


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 2026

math.cosh(number value)

Returns the hyperbolic cosine of the supplied value.

Parameters:

1

number

value

Returns:

1. number hyperbolic cosine value

Example:

print(math.cosh(1))


1.5430806348152


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 2034

math.deg(number radian value)

Converts the supplied radian value into an angle in degrees. See also math.rad.

Parameters:

1

number

radian value

Returns:

1. number value in degrees

Example:

print(math.deg(math.pi))


180.0


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 2042

math.exp(number exponent)

Returns the numerical constant e to the power of the supplied value. Supply a value of 1 to just return e.

Parameters:

1

number

exponent

Returns:

1. number e ^ exponent

Example:

print(math.exp(1))


2.718281828459


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 2050

math.floor(number value)

Returns the largest integer that is smaller than or equal to the supplied value.

Parameters:

1

number

value

Returns:

1. number floor value

Example:

print(math.floor(2.2))


2


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 2058

math.floor_to(number subject value, [number multiple value])

Returns the largest multiple of the supplied multiple value, which is smaller than the supplied subject value.

Parameters:

1	number	subject value
2	number	optional, default value=10 multiple value

Returns:

1. number ceiling value

Example:

-- print the largest multiple of 50 that is smaller than 128
print(math.floor_to(128, 50))


100


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 2066

math.fmod(number dividend, number divisor)

Returns remainder of the division of the first supplied value by the second supplied value.

Parameters:

1	number	dividend
2	number	divisor

Returns:

1. number floor value

Example:

-- 5 * 4 is 20, leaving a remainder of 3 to reach 23
print(math.fmod(23, 5))


3


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 2080

math.frexp(number x value)

Returns the values of m and exp in the expression x = m * 2 ^ exp, where x is the value supplied to the function. exp is an integer and the absolute value of the mantissa m is in the range 0.5 - 1 (or zero when x is zero).

Parameters:

1

number

x value

Returns:

1. number mantissa m value
2. number exponent e value

Example:

print(math.frexp(10)))


0.625    4


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 2090

math.ldexp(number m, number exp)

Returns m * 2 ^ exp, where the mantissa m and exponent exp are values supplied to the function. exp should be an integer value.

Parameters:

1	number	m
2	number	exp

Returns:

1. number m * 2 ^ exp

Example:

print(math.ldexp(2, 4))


32.0


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 2099

math.log(number value)

Returns the natural logarithm of the supplied value.

Parameters:

1

number

value

Returns:

1. number log value

Example:

print(math.log(10))


2.302585092994


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 2108

math.log10(number value)

Returns the base-10 logarithm of the supplied value.

Parameters:

1

number

value

Returns:

1. number log value

Example:

print(math.log(10))


1.0


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 2116

math.map_range(
  number input value,
  number input range start,
  number input range end,
  number output range start,
  number output range end
)

Map a numeric value from one given range of numbers to another. The returned value will be the same relative to the output range, as the input number is to the specified input range. Negative numbers, input values outside of the input range, and ranges that run backwards are all supported.

Parameters:

1	number	input value
2	number	input range start
3	number	input range end
4	number	output range start
5	number	output range end

Returns:

1. number output value

Example - Simple map_range example:

For an input range between 0 to 10, and an input value of 1 (i.e. 10% of the difference between 0 and 10), show the value mapped on to the output range 50 to 60

print(math.map_range(1, 0, 10, 50, 60))


51.0


Example - Further map_range example:

For an input range between 20 to 30, and an input value of 25 (50% of the difference between 20 and 30), show the value mapped on to the output range 50 to 100

print(math.map_range(25, 20, 30, 50, 100))


75.0


Example - Negative numbers:

For an input range between -100 to -50, and an input value of -25, show the value mapped on to the output range 50 to 100

print(math.map_range(-25, -100, -50, 50, 100))


125.0


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 2124

math.max(... values)

Returns the maximum numeric value amongst the arguments given.

Parameters:

1

...

Varargs of number values

Returns:

1. number max value

Example:

print(math.max(12, 10, 14, 3, 8, 13))


14


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 2150

math.min(... values)

Returns the minimum numeric value amongst the arguments given.

Parameters:

1

...

Varargs of number values

Returns:

1. number min value

Example:

print(math.min(12, 10, 14, 3, 8, 13))


3


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 2158

math.modf(number input value)

Returns the integral part of the supplied value and the fractional part of the supplied value.

Parameters:

1

number

input value

Returns:

1. number integral value
2. number fractional value

Example:

print(math.modf(5))
print(math.modf(5.4))


5    0.0
5    0.4


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 2166

math.normalize(number value, [number minimum], [number maximum])

Scales a supplied value to between supplied minimum and maximum values.

Parameters:

1	number	value
2	number	optional, default value=0 minimum
3	number	optional, default value=1 maximum

Returns:

1. number normalized value

defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 2177

math.pow(number x, number y)

Returns the first supplied number value to the power of the second supplied number value.

Parameters:

1	number	x
2	number	y

Returns:

1. number x ^ y

Example:

print(math.pow(2, 4))


16.0


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 2190

math.rad(number degree value)

Converts the supplied angle in degrees into an angle in radians. See also math.deg.

Parameters:

1

number

degree value

Returns:

1. number value in radians

Example:

print(math.rad(180))


3.1415926535898


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 2199

math.random([number first limit], [number second limit])

Provides an interface to the pseudo-random number generator provided by ANSI C. This function returns a random number between two optionally-supplied limits. If no arguments are supplied, those limits are 0 and 1. If one argument a is supplied, those limits are 1 and a. If two arguments a and b are supplied then those limits are a and b.
If no arguments are supplied the returned value is real, whereas if any arguments are supplied the returned value is an integer.
Note that use of this function is discouraged, as it will generate different results on different clients in a multiplayer game. Acting upon the result of this function in multiplayer scripts will likely cause desyncs.

Parameters:

1	number	optional, default value=nil first limit
2	number	optional, default value=nil second limit

Returns:

1. number random number

Example:

print(math.random())        -- returned value will be 0..1
print(math.random(10))        -- returned value will be 1..10
print(math.random(5, 10))        -- returned value will be 5..10


0.84018771676347
4
9


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 2207

math.randomseed(number seed)

Sets the supplied value as the seed for the random number system.

Parameters:

1

number

seed

Returns:

1. nil

Example:

math.randomseed(os.clock()))        -- use os clock as random seed


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 2222

math.round(number input)

Returns the nearest integer value to the supplied number.

Parameters:

1

number

input

Returns:

1. number rounded output

Example:

print(math.round(10.49))
print(math.round(10.51))
print(math.round(-10.49))
print(math.round(-10.51))


10
11
-10
-11


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 2228

math.sin(number value)

Returns the sine of the supplied radian value.

Parameters:

1

number

value

Returns:

1. number sine value

Example:

print(math.sin(0.5235987755983))


0.5


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 2245

math.sinh(number value)

Returns the hyperbolic sine of the supplied value.

Parameters:

1

number

value

Returns:

1. number hyperbolic sine value

Example:

print(math.sinh(0.5235987755983))


0.54785347388804


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 2253

math.sqrt(number value)

Returns the square root of the supplied value.

Parameters:

1

number

value

Returns:

1. number square root value

Example:

print(math.sqrt(4))


2.0


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 2261

math.tan(number value)

Returns the tangent of the supplied radian value.

Parameters:

1

number

value

Returns:

1. number tan value

Example:

print(math.tan(0.64350110879328))


0.74999999999999


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 2269

math.tanh(number value)

Returns the hyperbolic tangent of the supplied value.

Parameters:

1

number

value

Returns:

1. number hyperbolic tan value

Example:

print(math.tanh(0.64350110879328))


0.56727870240097


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 2277

math.to_bool(value data)

Converts the given data to a boolean. Only "nil" and "false" will return false.

Parameters:

1

value

data

Returns:

1. boolean true or false

Example:

to_bool(nil)
to_bool(false)
to_bool(1)
to_bool(0)
to_bool({5})
to_bool({})
to_bool("string")
to_bool("")


false
false
true
true
true
true
true
true


defined in ../../Warhammer/working_data/script/_lib/lib_lua_extensions.lua, line 2284

Back to top

Other Functionality

Variables in this section:

These variables may be accessed via <interface>.<variable_name>:

pi	number	Value of Pi.
huge	number	The value HUGE_VAL, a value equal to or larger than any other numerical value.