Civilization Modding Wiki - User contributions [en]

Template:Civ5 API Beta Banner

2012-12-25T18:58:36Z

DonQuich:

<noinclude>Now obsolete, we're no longer in beta version.</noinclude>

Template:Civ5 API Beta Banner

2012-12-25T18:58:05Z

DonQuich: Beta period is over. See http://forums.civfanatics.com/showthread.php?p=12096993#post12096993

<noinclude>
==Demonstration==
{|
|-
!Code
!Result
|-
|<pre style="border:none; margin:0px; padding:0px;">{{Civ5 API Beta Banner}}</pre>
|{{Civ5 API Beta Banner}}
|}

==Usage==
<pre>{{Civ5 API Beta Banner}}</pre>

[[Category:Civ5 API Templates]]</noinclude>

Template:Civ5 API Beta Banner

2012-10-14T23:51:44Z

DonQuich:

<includeonly><div style="background-color: #FAEBD7; border: 2px solid #FF8C00; clear:both;">
{| width="100%"
|-
|valign="top" |<div style="width:64px; text-align:center">[[Image:lock-128.png|64px]]</div>
|<div style="font-size:110%; font-weight:bold; align:center; width:100%; text-align:center;">
Beta version. Do not edit this page, all modifications will be lost at the end of the beta period!
</div><div style="align:center; width:100%; text-align:center;">This page was automatically generated by the Civ5 API Bot (see the [[Civ5 API Reference FAQ]]). This bot is currently in beta version until '''October 31''' and all pages will be regenerated at this date. <br/>You can join us to provide feedback and report bugs on [http://forums.civfanatics.com/showthread.php?p=11843283 the bot's thread] at CivFanatics.</div>
|}</div></includeonly><noinclude>
==Demonstration==
{|
|-
!Code
!Result
|-
|<pre style="border:none; margin:0px; padding:0px;">{{Civ5 API Beta Banner}}</pre>
|{{Civ5 API Beta Banner}}
|}

==Usage==
<pre>{{Civ5 API Beta Banner}}</pre>

[[Category:Civ5 API Templates]]</noinclude>

Civ5 Modding Tutorials

2012-10-01T19:55:12Z

DonQuich:

= Getting started =
'''Get a tour.'''
:If you have no idea about modding and what are Lua and Xml, you should give a look at [http://www.weplayciv.com/forums/entry.php?15-Dale-s-Mod-Blog-Civ5-Modding-Explained Civ5 Modding Explained].
'''Read the guide.'''
:The best introduction to civ5 modding is still the '''[http://forums.civfanatics.com/showthread.php?t=385009 Kael's Guide]'''. However it was written a long time ago and some informations are obsolete or missing.
'''Import your files into VFS.'''
:The main change since Kael wrote his guide is about the [[VFS (Civ5)|VFS]] (Virtual File System). Forgetting to import files into the VFS is the common source of problems for beginners.
'''Get the right tools for the job.'''
:See [[Civ5 Useful Programs]]. You should have installed the SDK of course, but it is also strongly recommended that you get a tool to search in all civ5 files at once, to compensate for the lack of documentation. You may also need additional softwares to extract and read the textures, test and debug your mod, etc.
'''Modify your ini files.'''
:See [[Debugging (Civ5)#Configuration|Debugging#Configuration]].

= Tutorials =
See also the [http://forums.civfanatics.com/forumdisplay.php?f=394&order=desc&page=2 Modding tutorials section] on the forums.<br/>
Also note that the [[Civ5 XML Reference|XML]] and [[Lua and UI Reference|Lua]] sections each contain specific tutorials, articles and extensive documentation.

=== General ===
* [[Modding Limits and Issues (Civ5)|Modding Limits and Issues]]
* [http://forums.civfanatics.com/showthread.php?t=459392 Create and use DDS textures]
* [http://forums.civfanatics.com/showthread.php?t=449431 Adding custom data and using them in Lua]
* [http://wiki.2kgames.com/civ5/index.php/Mods:LocalizationSyntax Localization Syntax]
* [[Debugging (Civ5)|Debugging]]

=== Common tasks ===
* [http://forums.civfanatics.com/showthread.php?t=391823 New Leaders (2D images)]
* [http://forums.civfanatics.com/showthread.php?t=389782 New Resources]
* [http://forums.civfanatics.com/showthread.php?t=474309 New Resources (with 3D textures)]
* [http://forums.civfanatics.com/showthread.php?t=470290 New Buildings]
* [http://forums.civfanatics.com/showthread.php?t=406877 New Specialists]
* [http://forums.civfanatics.com/showthread.php?t=392985 New Units]

=== Specific topics ===
* [http://forums.civfanatics.com/showthread.php?t=394056 Converting civ4 units for civ5: 1. importing the mesh and creating the unit]
* [http://forums.civfanatics.com/showthread.php?t=396911 Converting civ4 units for civ5: 2. using civ5 animations]
* [http://forums.civfanatics.com/showthread.php?t=444883 Importing civ5 units into Blender]
* [http://forums.civfanatics.com/showthread.php?t=405148 Civilization-specific techs]
* [http://forums.civfanatics.com/showthread.php?t=468374 Culture buildings - vanilla and G&K cross compatibility]
* [[Text icons and markups (Civ5)|Text icons and markups]]
* [[VFS (Civ5)|VFS]]

[[Category:Civ5 Tutorials]]

Lua introduction for confirmed developers

2012-09-30T14:13:16Z

DonQuich:

''This page is a part of the [[Lua and UI Reference (Civ5)|Lua and UI Reference]].''

= About Lua =
===Lua, not LUA===
This is a Portuguese word meaning "moon", not an acronym.

===Presentation===
Lua is an interpreted, dynamically typed, multi-paradigm language. It was designed in 1993 with the following objectives in mind:
* Extensible semantics. A small set of features allows the support of multiple paradigms, from functional programming to object programming. For example, while inheritance is not natively supported, it can be easily set up through metatables. The same features allow events in civ5 to behave both as functions and objects with Add and Remove methods.
* Highly portable. The con is a lightweight and somewhat lacking API.
* Easy to embed and to interface from other languages.
* Well suited for data description (''à la'' JSON).
* A beginners-friendly syntax.

===Performances===
As usual with interpreted and dynamically typed languages (hereby abusively named "scripting languages"), expect a 10 to 100 order of magnitude in performances decrease when compared to compiled and statically typed languages like C, C++ or C#. While it is possible for scripting languages to drastically improve the performances through more or less sophisticated means (expression trees/opcodes caching, JIT compiler, type inference to perform static resolutions), no such solution has been used in Civ5 (aside, probably, of the caching). And while an external JIT library exists, it causes compatibility problems with most mods using Lua.

That being said, Lua is still pretty good for a scripting language, better than the Python implementation from Civ4 for example. And all in all, it is fast enough for most of what modders want to achieve without the need to compromise code elegance, readability and maintainability for performances. So keep in mind that "premature optimization is the root of all evil" (Donald Knuth).

=Syntax cheatsheet=
=== Basics ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Literals
local x = 5
local x = 5.0
local x = nil -- A nil value is the same as an undefined value
local x = true
local x = false

-- Strings (single and double quotes can be used indifferently, there is no difference)
local x = "five"
local x = 'five'
local x = "five\n" -- Escape characters with "\".
local x = [[Five is a number.
Did you know?]] -- Multi-line string: equivalent to "Five is number.\nDid you know?"

-- Globals versus locals
x = 5 -- For globals, assigning is declaring.
local x = 5
</syntaxhighlight></div>

=== Operators ===
<div class="civ5-example"><syntaxhighlight lang="lua">
local x = a or b
local x = a and b

local x = "hello ".."world" .. "!" -- concatenation: two dots
local x = 4..5 -- Result is "45". On concatenation, conversions occur.

local x = (a + b - d) * f ^ g % h -- ^ is exponentiation, % is modulo
local x = "4" + "5" -- Result is 9. On arithmetic operations, conversions occur.

local x = a == b -- equality -- True only if a and b have the same values and types.
local x = a ~= b -- inequality

local x = ((a <= b) == not (a > b)) == ((a >= b) == not (a < b))
local x = "abc" < "def" -- Byte-wise comparison, not Unicode-compliant. Use Locale's methods instead.

local x = #"abc" -- Returns 3, the number of bytes in the string (3 characters, 1 byte each).
local x = #"您好世界" -- Returns 8, the number of bytes in the string (4 characters, 2 bytes each).
local x = #SomeTable -- Returns the biggest integer key in the table, or nil if there is no integer key.

-- No increment operator (++ --), no binary-assign operator (+= *=), no ternary operator (? :), no coalescence operator (??)
</syntaxhighlight></div>

=== Tables and multiple assignments ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Table declaration
SomeTable = {}

SomeArray = { "abc", "def" }
-- 1 => "abc", 2 => "def"

SomeComplexTable = { name = "John", surname = "Doe", age = 25, 43, [7] = 8 }
-- "name" => "John", "surname" => "Doe", "age" => 25, 1 => 43, 7 => 8.

-- Member access (all equivalent)
SomeTable.SomeMember = 5
SomeTable["SomeMember"] = 5

-- Multiple assignment
-- Both statements are equivalent since SomeArray contains "abc" and "def".
local x, y = "abc", "def"
local x, y = unpack(SomeArray)
</syntaxhighlight></div>

=== Functions ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Functions declarations (all equivalent)
function HelloWorld(a, b) print("Hello world") end
HelloWorld = function(a, b) print("Hello world") end
-- Functions are first-class objects and can be assigned like any other value!

-- Methods declarations (all equivalent)
SomeTable.HelloWorld(a, b) print("Hello world") end
SomeTable.HelloWorld = function(a, b) print("Hello world") end

-- Instanced methods declarations (all equivalent)
SomeTable.HelloWorldInstanced(self, a, b) print(self.SomeMember) end
SomeTable:HelloWorldInstanced(a, b) print(self.SomeMember) end

-- Functions and methods calls
HelloWorld(a) -- b will be nil in the function
HelloWorld(a, b)
SomeTable.HelloWorld(a, b)

-- Instanced methods calls (all equivalent)
SomeTable:HelloWorldInstanced(a, b)
SomeTable.HelloWorldInstanced(SomeTable, a, b)

-- Multiple return values
function func(a, b) return a, b end
local x, y, z = func(5, 6) -- Assigns 5 to x and 6 to y, z will be nil

-- Variable arguments
function SomeFunc(a, b, ...)
print(a)
print(b)
for i, v in ipairs(arg) do -- arg is a keyword for a table containing the variable arguments
print(v)
end
end
SomeFunc(1, 2, 3, 4, 5) -- prints 1, 2, 3, 4, 5
SomeFunc(1, 2) -- prints 1, 2
</syntaxhighlight></div>

=== Control flow ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- If
if name == "Wu Zetian" then
print("Hello China")
elseif name == "Napoleon" then -- "elseif", not "else if". Beware C developers!
print("Hello France")
else -- no "then" after "else"!
print("Hello unknown")
end

-- For loop (with counter)
for i = 1, 8 do print(i) end -- Prints 1, 2, 3, 4, 5, 6, 7, 8
for i = 1, 8, 2 do print(i) end -- Prints 1, 3, 5, 7

-- For loop (with iterator)
for playerID, pPlayer in pairs(Players) do -- Prints 1 Wu Zetian, 2 Napoleon, ...
print(playerID, pPlayer:GetName())
end
for plot in Plots() do -- Prints 0 0, 0 1, 0 2, ...
print(plot:GetX(), plot:GetY())
end

-- While (i will be 5 in the end)
while i < 5 do
i = i + 1
end

-- Repeat until (i will be 5 in the end)
repeat
i = i + 1
until i == 5

-- Infinite loops
-- Lua supports "break" for all loops but not "continue" instruction does not exist!
do
i = i + 1
if i > 5 then break end
end

</syntaxhighlight></div>

= Basics =
=== Type system ===
You can get a variable's type by using the '''type''' function. It takes any value and returns a string. Here are all the possible results:
* The following are [http://en.wikipedia.org/wiki/Value_type value types].
** '''nil''': Lua makes do distinction between an undefined variable and a variable with a nil value. Assigning nil to a variable or table member is equivalent to undefining it.
** '''number''': a 64 bits floating-point number. Lua has no support for integers and only use floating-points. See also [[#No integer type]].
** '''boolean''': true or false obviously.
* The following are [http://en.wikipedia.org/wiki/Reference_type reference types]
** '''table''': any table.
** '''string''': your usual string of characters. In Lua all strings are interned and immutable (see [#String Interning]).
** '''userdata''': objects defined in C for use in Lua. They may not be enumerated through pairs and are often read-only.
** '''function''': remember that functions are first-class objects in Lua.
** '''thread''': coroutines actually. Lua does not support threads.

Note: Many objects in the Civ5 API are actually regular tables which either have userdata methods as members, or a userdata metatable index.

=== Implicit conversions ===
* Whenever you concatenate two values (and possibly when you invoke a standard function that takes a string), an automatic conversion to string occurs, as if you had used the '''tostring''' function. The expression <code>4..5</code> returns "45".
* Whenever you perform an arithmetic operation, the operands are both converted to numbers, as if you had used the '''tonumber''' function. The expression <code>"4" + "5"</code> returns 9.
* The Civ5 API may or may not implicitly convert the values you pass to its methods and functions. Considers it does not.
* Aside of those, no implicit conversion is ever performed.

=== Equality comparisons ===
'''Two values are equal only if their types are the same.'''<br/>
This is far stricter than most dynamic languages for example and somehow stricter than C.
* 4 is not equal to "4". (number type and string type). In PHP they would be equal.
* 0 is not equal to false (number type and bool type). In C they would be equal (false is typically defined as a number).
* 0 is not equal to nil. (number type and nil type). In C they would be equal (nil is typically defined as a number).

'''Numbers and booleans are compared by value. Everything else by reference. Strings are interned.'''
* Numbers and booleans are compared by value.
* Tables, userdata, functions and threads are compared by reference.
* Strings are interned (see [#String Interning]), which means that two identical strings are always the same reference. So comparisons are made by reference but are equivalent to by-value comparisons.
* All nil values are always equal.
<div class="civ5-example"><syntaxhighlight lang="lua">
local a = 5
assert(a == 5)
-- true, comparison by value

local a = {}
assert(a == {})
-- false, comparison by reference: those two tables are distinct objects.

local a = "Hello ".."world"
assert(a == "Hello world")
-- true, both strings are the same reference thanks to string interning.
</syntaxhighlight></div>

=== String interning ===
'''All strings are interned in Lua, without any exception.'''<br/>
[http://en.wikipedia.org/wiki/String_interning String interning] is a process through which all identical strings ends up being the same reference to a unique string instance. Typically, the interpreter maintains a string dictionary in the memory and whenever a string needs to be built (from a literal, from a concatenation, from a native call, etc), it first searches in this dictionary whether there is already a reference for this sequence of characters and uses it when it exists. This process usually reduces memory consumptions and speeds up equality comparisons, but it makes other operations slower because of the lookup cost. Some platforms such as Dotnet or Java automatically interns literals only. Lua, on the other hand, systematically interns every string.

=== Boolean logic ===
'''Anything that is neither false nor nil is evaluated to true.'''<br/>
This is pretty simple. Especially, an empty string or the zero number are evaluated to true.
<div class="civ5-example"><syntaxhighlight lang="lua">
if 0 then print("hello world") end -- prints hello world
</syntaxhighlight></div>

Now regarding the and/or operators, two rules to remember:
* '''The right operand is only evaluated when needed.'''
** <code>false and x()</code> does not call x() since the result will be false anyway.
** <code>true or x()</code> does not call x() since the result will be true anyway.
* '''The result is the last operand to have been evaluated.'''
** <code>x() and y()</code> returns x() if it was false, y() otherwise.
** <code>x() or y()</code> returns x() if it was true, y() otherwise.

=== Ternary and coalescence statements ===
We can exploit the and/or operators behavior:
* '''Coalescence:''' <code>x or y</code>. It returns x if x is neither nil nor false, y otherwise.
:In other words <code>result = x or y</code> is equivalent to: <code>if x then result = x else result = y end</code>.
* '''Ternary:''' <code>condition and x or y</code> (as long as x is not nil or false). It returns x if condition was true, y if it was false.
:Indeed the expression becomes: <code>(condition and x) or y</code>. If condition is true the '''and''' operator returns x, and since x is true, y is not evaluated and '''or''' returns x.
:In other words <code>result = condition and x or y</code> is equivalent to: <code>if condition then result = x else result = y end</code>.

=== Method calls: dot versus colon ===
'''The colon (<code>:</code>) operator implicitly passes the caller as the first argument.''' <br/>
As opposed to the dot (<code>.</code>) operator that performs a regular call without implicitly passing anything. The colon operator behavior is obviously designed for instance methods.<br/>
<div class="civ5-example"><syntaxhighlight lang="lua">
local myTable = { msg = "Hello world" }
myTable.Print = function(self) print(self.msg)

-- Three different ways to call this method
myTable:Print()
myTable.Print(myTable)

local func = myTable.Print
func(myTable)
</syntaxhighlight></div>

Note: in the civ5 API you will often encounter static methods that do not take any argument but that are called through a dot. This results from a misunderstanding of Lua from one of the Firaxis developers. While this work when the method does not take any argument (the one provided by the colon operator will be ignored), this is slower and can be considered as an error without any consequence.

=== Arrays versus tables ===
'''In Lua, an array is a table whose keys are integers.'''

Since this is a common programming pattern, a number of things are designed for arrays:
* <code>{"abc", "def", "ghi"}</code> starts at index 1, up to index 3. Arrays typically start at 1.
* <code>table.insert({}, "abc")</code> will transform the provided empty table to <code>{"abc"}</code>
* <code>table.insert({"abc", "def"}, "ghi")</code> will transform the provided table to <code>{"abc", "def", "ghi"}</code>
* <code>table.insert({"abc", "ghi"}, 2, "def")</code> will transform the provided table to <code>{"abc", "def", "ghi"}</code>
* <code>table.remove({"abc", "def", "ghi"}, 2)</code> will transform the provided table to <code>{"abc", ""ghi"}</code>
* <code>#{"abc", "def", "ghi"}</code> returns 3, the biggest integer key.

=== Ipairs versus pairs ===
You could say that '''pairs''' is for table and '''ipairs''' for arrays.
* '''Pairs''' enumerate all the key/value pairs in an unordered matter.
* '''Ipairs''' only enumerates the key/value pairs for consecutive integer keys, in an ascending order, starting from 1 up to the largest key. If at some point a key is missing, the enumeration stops.
::It does not matter whether the table was created with table.insert or directly by inserting the values through, for example <code>table[i] = value</code>.

<div class="civ5-example"><syntaxhighlight lang="lua">
-- Produces: { 1 => "one", 2 => "two", 4 => "four", "name" => "John", "age" => 25 }
local t = { "one", "two", name = "John", age = 25, [4] = "four" }

-- Will print (for example, the order is undetermined): "name", 2, 4, "age", 1
for k in pairs(t) do print(k) end

-- Will print 1, 2
for k in ipairs(t) do print(k) end

-- Both ipairs and pairs return a key and a value, so you could also use:
for k, v in pairs(t) do print(k, v) end
</syntaxhighlight></div>

=== Indices start at 1 ===
'''All indices in the API, not just for arrays, start at 1.'''<br/>
When you declare an array with implicit keys, when you use ipairs, when you retrieve the n-th character of a string, when you query the n-th call informations in the stack call, etcetera. This is a consistent pattern in Lua.

{{Warning}} The Civ5 API, however, uses 0-based indices, as it is the standard in C and most programming languages.

=== Semicolons and line breaks ===
'''Statements need to be separated either by a line break or a semicolon.'''
* You can use both a semicolon and a line break but then the semicolon is redundant and not required, although it does not cause any problem.
* Line breaks can also be freely added about everywhere and behave as whitespaces most of the time (you can add them after most keywords for example, so you can keep if...then...end structures on one line or split them across multiple lines).

=== Local variables visibility ===
'''Local variables are only visible after the point where they have been declared.'''<br/>
This is different from global variables that are always visible. An example is worth thousand of words.
<div class="civ5-example"><syntaxhighlight lang="lua">
function Func1()
print(someLocal or "nil") -- Will NOT see someLocal.
print(someGlobal or "nil") -- Will see someGlobal.
end

local someLocal = "foo" -- The "foo" value will never be used.
function Func2()
print(someLocal or "nil") -- Will see someLocal.
print(someGlobal or "nil") -- Will see someGlobal.
end

someGlobal = "global"
someLocal = "local"
Func1() -- prints "nil", then "global": someLocal is assigned but not visible from Func1
Func2() -- prints "local", then "global": someLocal is assigned and visible from Func2
</syntaxhighlight></div>

Performances-wise, Lua first searches a variable name in the current scope, then in the parent scope, etcetera until it reaches the highest scope, and finally it searches the global scope. So the deeper a local is declared, the faster it is accessed. On the contrary, globals are the slowest to retrieve.

=== Files structure ===
* The include statement allows you to include a lua file into another one (see [[Specificities of the Lua implementation in Civ5]]). When you do so, the globals defined in the included file are imported in the parent file. However the local variables are only visible from within the file that declared them.
* If you're not familiar with scripting languages, consider that whenever Lua reads a file, it executes it. Practically, a Lua chunk (the root scope of a file) is no different from any other scope. It can contains ordinary statements as the ones found in a function scope, and you can use the <code>include</code> statement from any scope (although the globals defined in this included file will still be globals and won't be contained in the current scope).

= Semi-advanced topics =
=== Closures ===
'''Closures are functions that embed variables that are persisted across calls.'''<br/>
This is typically achieved through a "parent" function that declares a local "closed" variable and returns another child "closure" function using this local. The "closed" variable is then unreachable for anyone but the "closure". And since it the "closed" variable is not in the "closure"'s scope, it is not reinitialized on every call of "closure".
<div class="civ5-example"><syntaxhighlight lang="lua">
function GiveMeAFunc() -- the parent function
local x = 0 -- the closed variable
return function() -- the closure function embedding "closed"
x = x + 1
return closure
end
end

local func = GiveMeAFunc()
print(func()) -- Prints 1
print(func()) -- Prints 2
print(func()) -- Prints 3
</syntaxhighlight></div>

=== Iterators ===
'''Iterators are functions for use in <code>for...in</code> loops.'''<br/>
Let's consider the following code: <code>for var1, var2, var3 in iterable() do</code>.
* iterable has the following signature: <code>iterator, state, var1 iterable()</code>. It returns a function, a state, and the initial value of var1.
* iterator has the following signature: <code>var1, var2, var3 iterator(state, var1)</code>. It takes the state and the last value of var1 and returns var1, var2 and var3.
* The loop stops when var1 is nil.
* The for...in loop is equivalent to:
<div class="civ5-example"><syntaxhighlight lang="lua">
local iterator, state, var1, var2, var3
iterator, state, var1 = iterable()
do
var1, var2, var3 = iterator(state, var1)
if var1 == nil then break end

-- Inserts here the user code defined in the for..in loop
end
</syntaxhighlight></div>
* Note that we used var1, var2 and var3 for the example but there is no restriction to the number of variables. You could have one or hundred.

Let's write the "ipairs" function.
<div class="civ5-example"><syntaxhighlight lang="lua">
local function ipairs(table) -- The iterable function
local iterator = function(table, key) -- The iterator function
key = key + 1
return key, table[key]
end
return iterator, table, 0
end
</syntaxhighlight></div>

The same with closures: it's easier.
<div class="civ5-example"><syntaxhighlight lang="lua">
local function ipairs(table) -- The iterable function
local key = 0 -- Both "table" and "key" are closed variables.
local iterator = function() -- The iterator function, a closure: it ignores the arguments provided to it
key = key + 1
return key, table[key]
end
return iterator -- No need to return anything since we do not require any argument.
end
</syntaxhighlight></div>

=== No integer type ===
'''Lua offers no support for integers and only has a 64-bits floating point number type.'''<br/>
Actually, this is only troublesome for a few algorithms that use very large integers (>2^52) or require fast integer arithmetics. But many developers misunderstand floating points and believe the problem is broader than it is. For example, does the following assertion surprise you at least a bit: "any integer smaller than 2^52 can be accurately represented with a 64-bits floating point without any error"? If it did, you suffer from some misconceptions and you should better read carefully what's coming.

Many developers are confusing rounding errors with representation errors.
* '''Rounding errors''' actually only happen if you need a very high number of digits to represent a number. For example if you are adding a very large number with a small number. Rounding errors are very rarely encountered in day to day to applications. Actually most developers work their whole career without ever encountering them.
* '''Representation errors''' are the real problem: 0.1 is expressed in a decimal basis, but it has no finite representation in binary: it requires an infinite number of binary digits. This means that if you write 0.1 in your code it will be translated to a binary number close enough from 0.1 bot not exactly equal to it. So if you sum ten times 0.1, you sill sum ten times something close from 0.1 and the result will not be 1.

'''So the real problem for most developers only lies in the decimal-binary conversion that arises when you manipulate numbers in your code that do not have a finite representation in binary. As long as you do not use such numbers, there will be no problem. And here are the good news: integers do not suffer from any representation problem!''' Indeed, any integer can be represented with a finite number of binary digits. This is why the absence of an integer type typically does not cause problems, minus the performance penalty.

Here are a few examples to illustrate that point.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- This loop works as intended: no representation error and the upper bound is far below 2^52.
local sum = 0
for i = 0, 10000000000, 1 do sum = sum + 1 end
assert(sum == 10000000001)

-- This loop works as intended: 1/16 is a floating-point with an exact representation in binary
local sum = 0
for i = 0, 1, 1/16 do sum = sum + 1 end
assert(sum == 17/16)

-- This loop does NOT work as intended: 0.1 does not have an exact representation in binary.
-- It's the same for Lua, C and almost every programming language.
local sum = 0
for i = 0, 1, 0.1 do sum = sum + 1 end
assert(sum == 1.1) -- throws an error
</syntaxhighlight></div>

=== Errors management ===
Lua offers a error handling mechanism similar to exception handling but unfortunately not very convenient.
* Errors are thrown using the '''error''' function. It takes a string and it immediately aborts Lua execution until the game handles the error and prints it in Firetuner (when enabled).
* Errors are caught before that point using '''pcall''' or '''xpcall''', in order to let you resume execution by managing the error. "pcall" stands for "protected call".

Here are the syntaxes for pcall and xpcall:
* <code>bool, ... pcall(func, ...)</code>
** The function is called with the specified arguments.
** Pcall returns either true followed by the values returned by func, or false followed by the error text.
* <code>bool, ... xpcall(func, errorHandler)</code>:
** The function is called without any argument. If an error occurs the specified errorHandler is invoked with the error text as the only argument.
** Xpcall returns either true followed by the values returned by func, or false followed by the returned values from errorHandler.

Examples to invoke "someFunc" with "someArg" as the only argument. In both examples we want to display the error on the console, or the result if it was a success. A complete errors management example with a reporting mechanism for the end-user is presented in [[Debugging (Civ5)]].
<div class="civ5-example"><syntaxhighlight lang="lua">
-- pcall
local status, result = pcall(someFunc, someArg)
if not status then
print("error was: "..(result or "?"))
else
print("success: "..result)
end

-- xpcall
local status, result = xpcall(
function() someFunc(someArg) end,
function(err) print("error was: "..(result or "?")) end)

if status then
print("success: "..result)
end
</syntaxhighlight></div>

= Advanced topics=
=== Metatables and metamethods ===
* Every value in Lua, from a number to a userdata, has a metatable.
** Many objects can share the same metatable.
** Tables and userdata each have their own metatables by default. Numbers, bools, nils and strings all share the same metatable.
* A metatable may contain a few metamethods and index tables.
** Metamethods are methods stored under special fields names. They implement operators overloads.
** Index tables behave as "base classes": if a field name is not defined on an table, then Lua looks for this field on the index.
** In a way, metatables are analogous to virtual tables in object languages, but they are not just for methods, but also for fields and operators.
* You can get an object's metatable through '''getmetatable''' and assign it with '''setmetatable'''.
* See also the [http://www.lua.org/manual/5.1/manual.html#2.8 official metatables reference]

One example.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Define two tables A and B, and set "meta" their metatable
local a, b, meta = {}, {}, {}
setmetatable(a, meta)
setmetatable(b, meta)

-- Define an __index table on the metatable. It contains one key/value pair.
meta.__index = { "hello world" };

-- Print "hello world" twice
print(a[1])
print(b[1])

-- Now make our tables read-only
meta.__newindex = function(table, key, value) error("this table is read-only!") end
a[1] = "foo" -- throws an error
</syntaxhighlight></div>

Here are the most important fields a metatable can have:
* '''__index''': used when you read a member from an object. On tables, Lua will first search for a regular field on the table itself (not its index) before it looks at the index. The index may be a table or a function: <code>value func(object, key)</code>
* '''__newindex''': used when you assign a value to an object's member. On tables, newindex is only called if the table itself (not its index) does not already contains the specified key. May be a table or a function: <code>func(object, key, value)</code>
* '''__call''': used when you invoke the object as a function. Must be a function: <code>func(object, <args>)</code>
* '''__tostring''': used when you invoke the '''tostring''' function with this object in argument. Must be a function: <code>string func(object)</code>

Besides of that it can have fields for binary operators. When each of the two operands defined overloads, the left one is used. They must be functions: <code>result func(object)</code>
* '''__add''': addition
* '''__sub''': subtraction
* '''__mul''': multiplication
* '''__div''': division
* '''__mod''': module
* '''__pow''': exponentiation
* '''__eq''': equality comparison. Prior to calling this overload, Lua checks that types are equal.
* '''__neq''': inequality comparison. Prior to calling this overload, Lua checks whether types are different.
* '''__lt''': lesser than comparison. (b >= a) is considered equivalent to (a < b)
* '''__le''': lesser than or equal to comparison. (b > a) is considered equivalent to (a <= b). If __le is not defined, lua will use __lt, considering that (a <= b) is equivalent to not (b < a).
* '''__concat''': concatenation

Finally it can have the following fields for unary operators. They must be functions: <code>result func(object)</code>
* '''__unm''': unary minus
* '''__len''': the sharp operator (#). Can only be used on userdata ; on tables the default operator will always be called.

=== Implementing inheritance ===
The most common use of metatables is to mimic the behavior of object languages' types hierarchy. Here is how to do it:
<div class="civ5-example"><syntaxhighlight lang="lua">
local Dog = {}
function Dog:specie()
return "dog"
end
function Dog:race()
return "unknown"
end
function Dog:description()
return self.specie().." - "..self.race()
end
function Dog:new()
local instance = {}
setmetatable(instance, { __index = self})
return instance
end

local Pitbull = dog:new()
function Pitbull:race()
return "pitbull"
end

pitbull = Pitbull:new()
print(pitbull:description()) -- prints "dog - pitbull"
</syntaxhighlight></div>

This implementation is very elegant: the "new" method both creates a new instance and subtypes the creator, since "pitbull"'s index is now "Pitbull". However, should you define an operator overload on Dog's metatable, Pitbull would not inherit it. This is the limit of inheritance in Lua: operator overloads must be defined on the metatable itself, they cannot be defined on the metatable's index. As a result, there is no way to inherit those overloads while subtyping.

=== Coroutines ===
Coroutines provide a way to slice a function in many shorter calls and optionally return intermediate results. On each call, the function execution is resumed to the point where it stopped previously, with all locals being properly restored with the value they had at this time.
* Coroutines are often compared to threads. Indeed, when there are more threads than CPU cores, the operating system slices threads' execution into many little time frames and sequentially runs them in order to achieve multitasking.
* However while coroutines allows you to implement cooperative multitasking (the coroutines need to explicitly give the hand back), they cannot be used for preemptive multitasking or to use more than one system thread or CPU Core.
* As a result, coroutines are rather used as syntactic sugar (mostly to write iterators), or as a way to split a long function execution across many frames (through Context.{{Func5|UIElement|SetUpdate}}).

The following methods are mainly used:
* <code>'''coroutine''' coroutine.create('''function''' func)</code> creates a coroutine for the specified function. The function signature can be anything.
* <code>'''bool''', '''...''' coroutine.resume('''coroutine''' co, '''...''')</code> resumes the coroutine with the specified arguments. Then it returns either '''true''' followed by the returned results (either though '''return''' or '''yield'''), or '''false''' followed by an error message.
* <code>'''string''' coroutine.status('''coroutine''' co)</code> returns either "running" (the active coroutine), "normal" (a parent of the active coroutine), "suspended" (not started or waiting to be resumed) or "dead" (finished or threw an error).
* <code>coroutine.yield('''...''')</code> suspends the execution of the running coroutine and gives the hand back to the caller of coroutine.resume. The arguments will be returned by coroutine.resume.

Here is a base example:
<div class="civ5-example"><syntaxhighlight lang="lua">
function neighborsCoroutine(plot)
for i = 0, 5 do
coroutine.yield(Map.PlotDirection(plot:GetX(), plot:GetY(), i))
end
end

local co = coroutine.create(neighborsCoroutine)
while coroutine.status(co) == "suspended"
local _, neighbor = co.resume(plot)
-- Do something with plot
end
</syntaxhighlight></div>

Here is how to transform it into an iterator:
<div class="civ5-example"><syntaxhighlight lang="lua">
function neighbors(plot)
local co = coroutine.create(neighbors)
return function()
if coroutine.status(co) ~= "suspended" then return end
return select(2, coroutine.resume(plot))
end
end

for neighbor in neighbors(plot) do
-- Do something with plot
end
</syntaxhighlight></div>

Here is an example that spreads a long function call across many frames:
<div class="civ5-example"><syntaxhighlight lang="lua">
function SpreadAcrossFrames(longFunctionCall, ...)
local co = coroutine.create(longFunctionCall)
ContextPtr.SetUpdate(function()
coroutine.resume(unpack(arg))
if coroutine.status(co) ~= "suspended" then
ContextPtr:ClearUpdate()
end
end)
end

SpreadAcrossFrames(SomeLongFunction, arg1, arg2)
</syntaxhighlight></div>

=== Design philosophy for Lua ===
Do not use a butter knife as you would use a chainsaw (the opposite is even more true and usually ends up badly). When designing your code, remember that:
* Lua is not an object language. While you can use objects and inheritance in some extent, you do not have to and there may be better alternatives sometimes.
* Lua is not a functional language. While you can use lambdas and similar concepts, you do not have to and there may be better alternatives sometimes.
* Lua is a multi-paradigm and dynamic language, take advantage of those.
* Lua is very suited for prototyping and small programs, and this is perfect for mods. Try to adjust your mindset: you're not writing a framework that a whole team will still use and maintain in twenty years.

[[Category:Civ5 API]]
[[Category:Civ5 Tutorials]]

Lua introduction for confirmed developers

2012-09-30T14:10:51Z

DonQuich:

''This page is a part of the [[Lua and UI Reference (Civ5)|Lua and UI Reference]].''

= About Lua =
===Lua, not LUA===
This is a Portuguese word meaning "moon", not an acronym.

===Presentation===
Lua is an interpreted, dynamically typed, multi-paradigm language. It was designed in 1993 with the following objectives in mind:
* Extensible semantics. A small set of features allows the support of multiple paradigms, from functional programming to object programming. For example, while inheritance is not natively supported, it can be easily set up through metatables. The same features allow events in civ5 to behave both as functions and objects with Add and Remove methods.
* Highly portable. The con is a lightweight and somewhat lacking API.
* Easy to embed and to interface from other languages.
* Well suited for data description (''à la'' JSON).
* A beginners-friendly syntax.

===Performances===
As usual with interpreted and dynamically typed languages (hereby abusively named "scripting languages"), expect a 10 to 100 order of magnitude in performances decrease when compared to compiled and statically typed languages like C, C++ or C#. While it is possible for scripting languages to drastically improve the performances through more or less sophisticated means (expression trees/opcodes caching, JIT compiler, type inference to perform static resolutions), no such solution has been used in Civ5 (aside, probably, of the caching). And while an external JIT library exists, it causes compatibility problems with most mods using Lua.

That being said, Lua is still pretty good for a scripting language, better than the Python implementation from Civ4 for example. And all in all, it is fast enough for most of what modders want to achieve without the need to compromise code elegance, readability and maintainability for performances. So keep in mind that "premature optimization is the root of all evil" (Donald Knuth).

=Syntax cheatsheet=
=== Basics ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Literals
local x = 5
local x = 5.0
local x = nil -- A nil value is the same as an undefined value
local x = true
local x = false

-- Strings (single and double quotes can be used indifferently, there is no difference)
local x = "five"
local x = 'five'
local x = "five\n" -- Escape characters with "\".
local x = [[Five is a number.
Did you know?]] -- Multi-line string: equivalent to "Five is number.\nDid you know?"

-- Globals versus locals
x = 5 -- For globals, assigning is declaring.
local x = 5
</syntaxhighlight></div>

=== Operators ===
<div class="civ5-example"><syntaxhighlight lang="lua">
local x = a or b
local x = a and b

local x = "hello ".."world" .. "!" -- concatenation: two dots
local x = 4..5 -- Result is "45". On concatenation, conversions occur.

local x = (a + b - d) * f ^ g % h -- ^ is exponentiation, % is modulo
local x = "4" + "5" -- Result is 9. On arithmetic operations, conversions occur.

local x = a == b -- equality -- True only if a and b have the same values and types.
local x = a ~= b -- inequality

local x = ((a <= b) == not (a > b)) == ((a >= b) == not (a < b))
local x = "abc" < "def" -- Byte-wise comparison, not Unicode-compliant. Use Locale's methods instead.

local x = #"abc" -- Returns 3, the number of bytes in the string (3 characters, 1 byte each).
local x = #"您好世界" -- Returns 8, the number of bytes in the string (4 characters, 2 bytes each).
local x = #SomeTable -- Returns the biggest integer key in the table, or nil if there is no integer key.

-- No increment operator (++ --), no binary-assign operator (+= *=), no ternary operator (? :), no coalescence operator (??)
</syntaxhighlight></div>

=== Tables and multiple assignments ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Table declaration
SomeTable = {}

SomeArray = { "abc", "def" }
-- 1 => "abc", 2 => "def"

SomeComplexTable = { name = "John", surname = "Doe", age = 25, 43, [7] = 8 }
-- "name" => "John", "surname" => "Doe", "age" => 25, 1 => 43, 7 => 8.

-- Member access (all equivalent)
SomeTable.SomeMember = 5
SomeTable["SomeMember"] = 5

-- Multiple assignment
-- Both statements are equivalent since SomeArray contains "abc" and "def".
local x, y = "abc", "def"
local x, y = unpack(SomeArray)
</syntaxhighlight></div>

=== Functions ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Functions declarations (all equivalent)
function HelloWorld(a, b) print("Hello world") end
HelloWorld = function(a, b) print("Hello world") end
-- Functions are first-class objects and can be assigned like any other value!

-- Methods declarations (all equivalent)
SomeTable.HelloWorld(a, b) print("Hello world") end
SomeTable.HelloWorld = function(a, b) print("Hello world") end

-- Instanced methods declarations (all equivalent)
SomeTable.HelloWorldInstanced(self, a, b) print(self.SomeMember) end
SomeTable:HelloWorldInstanced(a, b) print(self.SomeMember) end

-- Functions and methods calls
HelloWorld(a) -- b will be nil in the function
HelloWorld(a, b)
SomeTable.HelloWorld(a, b)

-- Instanced methods calls (all equivalent)
SomeTable:HelloWorldInstanced(a, b)
SomeTable.HelloWorldInstanced(SomeTable, a, b)

-- Multiple return values
function func(a, b) return a, b end
local x, y, z = func(5, 6) -- Assigns 5 to x and 6 to y, z will be nil

-- Variable arguments
function SomeFunc(a, b, ...)
print(a)
print(b)
for i, v in ipairs(arg) do -- arg is a keyword for a table containing the variable arguments
print(v)
end
end
SomeFunc(1, 2, 3, 4, 5) -- prints 1, 2, 3, 4, 5
SomeFunc(1, 2) -- prints 1, 2
</syntaxhighlight></div>

=== Control flow ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- If
if name == "Wu Zetian" then
print("Hello China")
elseif name == "Napoleon" then -- "elseif", not "else if". Beware C developers!
print("Hello France")
else -- no "then" after "else"!
print("Hello unknown")
end

-- For loop (with counter)
for i = 1, 8 do print(i) end -- Prints 1, 2, 3, 4, 5, 6, 7, 8
for i = 1, 8, 2 do print(i) end -- Prints 1, 3, 5, 7

-- For loop (with iterator)
for playerID, pPlayer in pairs(Players) do -- Prints 1 Wu Zetian, 2 Napoleon, ...
print(playerID, pPlayer:GetName())
end
for plot in Plots() do -- Prints 0 0, 0 1, 0 2, ...
print(plot:GetX(), plot:GetY())
end

-- While (i will be 5 in the end)
while i < 5 do
i = i + 1
end

-- Repeat until (i will be 5 in the end)
repeat
i = i + 1
until i == 5

-- Infinite loops
-- Lua supports "break" for all loops but not "continue" instruction does not exist!
do
i = i + 1
if i > 5 then break end
end

</syntaxhighlight></div>

= Basics =
=== Type system ===
You can get a variable's type by using the '''type''' function. It takes any value and returns a string. Here are the possible results:
* The following are [http://en.wikipedia.org/wiki/Value_type value types].
** '''nil''': Lua makes do distinction between an undefined variable and a variable with a nil value. Assigning nil to a variable or table member is equivalent to undefining it.
** '''number''': a 64 bits floating-point number. Lua has no support for integers and only use floating-points. See also [[#No integer type]].
** '''boolean''': true or false obviously.
* The following are [http://en.wikipedia.org/wiki/Reference_type reference types]
** '''table''': any table.
** '''string''': your usual string of characters. In Lua all strings are interned and immutable (see [#String Interning]).
** '''userdata''': objects defined in C for use in Lua. They may not be enumerated through pairs and are often read-only.
** '''function''': remember that functions are first-class objects in Lua.
** '''thread''': coroutines actually. Lua does not support threads.

Note: Many objects in the Civ5 API are actually regular tables which either have userdata methods as members, or a userdata metatable index.

=== Implicit conversions ===
* Whenever you concatenate two values (and possibly when you invoke a standard function that takes a string), an automatic conversion to string occurs, as if you had used the '''tostring''' function. The expression <code>4..5</code> returns "45".
* Whenever you perform an arithmetic operation, the operands are both converted to numbers, as if you had used the '''tonumber''' function. The expression <code>"4" + "5"</code> returns 9.

=== Equality comparisons ===
'''Two values are equal only if their types are the same.'''<br/>
This is far stricter than most dynamic languages for example and somehow stricter than C.
* 4 is not equal to "4". (number type and string type). In PHP they would be equal.
* 0 is not equal to false (number type and bool type). In C they would be equal (false is typically defined as a number).
* 0 is not equal to nil. (number type and nil type). In C they would be equal (nil is typically defined as a number).

'''Numbers and booleans are compared by value. Everything else by reference. Strings are interned.'''
* Numbers and booleans are compared by value.
* Tables, userdata, functions and threads are compared by reference.
* Strings are interned (see [#String Interning]), which means that two identical strings are always the same reference. So comparisons are made by reference but are equivalent to by-value comparisons.
* All nil values are always equal.
<div class="civ5-example"><syntaxhighlight lang="lua">
local a = 5
assert(a == 5)
-- true, comparison by value

local a = {}
assert(a == {})
-- false, comparison by reference: those two tables are distinct objects.

local a = "Hello ".."world"
assert(a == "Hello world")
-- true, both strings are the same reference thanks to string interning.
</syntaxhighlight></div>

=== String interning ===
'''All strings are interned in Lua, without any exception.'''<br/>
[http://en.wikipedia.org/wiki/String_interning String interning] is a process through which all identical strings ends up being the same reference to a unique string instance. Typically, the interpreter maintains a string dictionary in the memory and whenever a string needs to be built (from a literal, from a concatenation, from a native call, etc), it first searches in this dictionary whether there is already a reference for this sequence of characters and uses it when it exists. This process usually reduces memory consumptions and speeds up equality comparisons, but it makes other operations slower because of the lookup cost. Some platforms such as Dotnet or Java automatically interns literals only. Lua, on the other hand, systematically interns every string.

=== Boolean logic ===
'''Anything that is neither false nor nil is evaluated to true.'''<br/>
This is pretty simple. Especially, an empty string or the zero number are evaluated to true.
<div class="civ5-example"><syntaxhighlight lang="lua">
if 0 then print("hello world") end -- prints hello world
</syntaxhighlight></div>

Now regarding the and/or operators, two rules to remember:
* '''The right operand is only evaluated when needed.'''
** <code>false and x()</code> does not call x() since the result will be false anyway.
** <code>true or x()</code> does not call x() since the result will be true anyway.
* '''The result is the last operand to have been evaluated.'''
** <code>x() and y()</code> returns x() if it was false, y() otherwise.
** <code>x() or y()</code> returns x() if it was true, y() otherwise.

=== Ternary and coalescence statements ===
We can exploit the and/or operators behavior:
* '''Coalescence:''' <code>x or y</code>. It returns x if x is neither nil nor false, y otherwise.
:In other words <code>result = x or y</code> is equivalent to: <code>if x then result = x else result = y end</code>.
* '''Ternary:''' <code>condition and x or y</code> (as long as x is not nil or false). It returns x if condition was true, y if it was false.
:Indeed the expression becomes: <code>(condition and x) or y</code>. If condition is true the '''and''' operator returns x, and since x is true, y is not evaluated and '''or''' returns x.
:In other words <code>result = condition and x or y</code> is equivalent to: <code>if condition then result = x else result = y end</code>.

=== Method calls: dot versus colon ===
'''The colon (<code>:</code>) operator implicitly passes the caller as the first argument.''' <br/>
As opposed to the dot (<code>.</code>) operator that performs a regular call without implicitly passing anything. The colon operator behavior is obviously designed for instance methods.<br/>
<div class="civ5-example"><syntaxhighlight lang="lua">
local myTable = { msg = "Hello world" }
myTable.Print = function(self) print(self.msg)

-- Three different ways to call this method
myTable:Print()
myTable.Print(myTable)

local func = myTable.Print
func(myTable)
</syntaxhighlight></div>

Note: in the civ5 API you will often encounter static methods that do not take any argument but that are called through a dot. This results from a misunderstanding of Lua from one of the Firaxis developers. While this work when the method does not take any argument (the one provided by the colon operator will be ignored), this is slower and can be considered as an error without any consequence.

=== Arrays versus tables ===
'''In Lua, an array is a table whose keys are integers.'''

Since this is a common programming pattern, a number of things are designed for arrays:
* <code>{"abc", "def", "ghi"}</code> starts at index 1, up to index 3. Arrays typically start at 1.
* <code>table.insert({}, "abc")</code> will transform the provided empty table to <code>{"abc"}</code>
* <code>table.insert({"abc", "def"}, "ghi")</code> will transform the provided table to <code>{"abc", "def", "ghi"}</code>
* <code>table.insert({"abc", "ghi"}, 2, "def")</code> will transform the provided table to <code>{"abc", "def", "ghi"}</code>
* <code>table.remove({"abc", "def", "ghi"}, 2)</code> will transform the provided table to <code>{"abc", ""ghi"}</code>
* <code>#{"abc", "def", "ghi"}</code> returns 3, the biggest integer key.

=== Ipairs versus pairs ===
You could say that '''pairs''' is for table and '''ipairs''' for arrays.
* '''Pairs''' enumerate all the key/value pairs in an unordered matter.
* '''Ipairs''' only enumerates the key/value pairs for consecutive integer keys, in an ascending order, starting from 1 up to the largest key. If at some point a key is missing, the enumeration stops.
::It does not matter whether the table was created with table.insert or directly by inserting the values through, for example <code>table[i] = value</code>.

<div class="civ5-example"><syntaxhighlight lang="lua">
-- Produces: { 1 => "one", 2 => "two", 4 => "four", "name" => "John", "age" => 25 }
local t = { "one", "two", name = "John", age = 25, [4] = "four" }

-- Will print (for example, the order is undetermined): "name", 2, 4, "age", 1
for k in pairs(t) do print(k) end

-- Will print 1, 2
for k in ipairs(t) do print(k) end

-- Both ipairs and pairs return a key and a value, so you could also use:
for k, v in pairs(t) do print(k, v) end
</syntaxhighlight></div>

=== Indices start at 1 ===
'''All indices in the API, not just for arrays, start at 1.'''<br/>
When you declare an array with implicit keys, when you use ipairs, when you retrieve the n-th character of a string, when you query the n-th call informations in the stack call, etcetera. This is a consistent pattern in Lua.

{{Warning}} The Civ5 API, however, uses 0-based indices, as it is the standard in C and most programming languages.

=== Semicolons and line breaks ===
'''Statements need to be separated either by a line break or a semicolon.'''
* You can use both a semicolon and a line break but then the semicolon is redundant and not required, although it does not cause any problem.
* Line breaks can also be freely added about everywhere and behave as whitespaces most of the time (you can add them after most keywords for example, so you can keep if...then...end structures on one line or split them across multiple lines).

=== Local variables visibility ===
'''Local variables are only visible after the point where they have been declared.'''<br/>
This is different from global variables that are always visible. An example is worth thousand of words.
<div class="civ5-example"><syntaxhighlight lang="lua">
function Func1()
print(someLocal or "nil") -- Will NOT see someLocal.
print(someGlobal or "nil") -- Will see someGlobal.
end

local someLocal = "foo" -- The "foo" value will never be used.
function Func2()
print(someLocal or "nil") -- Will see someLocal.
print(someGlobal or "nil") -- Will see someGlobal.
end

someGlobal = "global"
someLocal = "local"
Func1() -- prints "nil", then "global": someLocal is assigned but not visible from Func1
Func2() -- prints "local", then "global": someLocal is assigned and visible from Func2
</syntaxhighlight></div>

Performances-wise, Lua first searches a variable name in the current scope, then in the parent scope, etcetera until it reaches the highest scope, and finally it searches the global scope. So the deeper a local is declared, the faster it is accessed. On the contrary, globals are the slowest to retrieve.

=== Files structure ===
* The include statement allows you to include a lua file into another one (see [[Specificities of the Lua implementation in Civ5]]). When you do so, the globals defined in the included file are imported in the parent file. However the local variables are only visible from within the file that declared them.
* If you're not familiar with scripting languages, consider that whenever Lua reads a file, it executes it. Practically, a Lua chunk (the root scope of a file) is no different from any other scope. It can contains ordinary statements as the ones found in a function scope, and you can use the <code>include</code> statement from any scope (although the globals defined in this included file will still be globals and won't be contained in the current scope).

= Semi-advanced topics =
=== Closures ===
'''Closures are functions that embed variables that are persisted across calls.'''<br/>
This is typically achieved through a "parent" function that declares a local "closed" variable and returns another child "closure" function using this local. The "closed" variable is then unreachable for anyone but the "closure". And since it the "closed" variable is not in the "closure"'s scope, it is not reinitialized on every call of "closure".
<div class="civ5-example"><syntaxhighlight lang="lua">
function GiveMeAFunc() -- the parent function
local x = 0 -- the closed variable
return function() -- the closure function embedding "closed"
x = x + 1
return closure
end
end

local func = GiveMeAFunc()
print(func()) -- Prints 1
print(func()) -- Prints 2
print(func()) -- Prints 3
</syntaxhighlight></div>

=== Iterators ===
'''Iterators are functions for use in <code>for...in</code> loops.'''<br/>
Let's consider the following code: <code>for var1, var2, var3 in iterable() do</code>.
* iterable has the following signature: <code>iterator, state, var1 iterable()</code>. It returns a function, a state, and the initial value of var1.
* iterator has the following signature: <code>var1, var2, var3 iterator(state, var1)</code>. It takes the state and the last value of var1 and returns var1, var2 and var3.
* The loop stops when var1 is nil.
* The for...in loop is equivalent to:
<div class="civ5-example"><syntaxhighlight lang="lua">
local iterator, state, var1, var2, var3
iterator, state, var1 = iterable()
do
var1, var2, var3 = iterator(state, var1)
if var1 == nil then break end

-- Inserts here the user code defined in the for..in loop
end
</syntaxhighlight></div>
* Note that we used var1, var2 and var3 for the example but there is no restriction to the number of variables. You could have one or hundred.

Let's write the "ipairs" function.
<div class="civ5-example"><syntaxhighlight lang="lua">
local function ipairs(table) -- The iterable function
local iterator = function(table, key) -- The iterator function
key = key + 1
return key, table[key]
end
return iterator, table, 0
end
</syntaxhighlight></div>

The same with closures: it's easier.
<div class="civ5-example"><syntaxhighlight lang="lua">
local function ipairs(table) -- The iterable function
local key = 0 -- Both "table" and "key" are closed variables.
local iterator = function() -- The iterator function, a closure: it ignores the arguments provided to it
key = key + 1
return key, table[key]
end
return iterator -- No need to return anything since we do not require any argument.
end
</syntaxhighlight></div>

=== No integer type ===
'''Lua offers no support for integers and only has a 64-bits floating point number type.'''<br/>
Actually, this is only troublesome for a few algorithms that use very large integers (>2^52) or require fast integer arithmetics. But many developers misunderstand floating points and believe the problem is broader than it is. For example, does the following assertion surprise you at least a bit: "any integer smaller than 2^52 can be accurately represented with a 64-bits floating point without any error"? If it did, you suffer from some misconceptions and you should better read carefully what's coming.

Many developers are confusing rounding errors with representation errors.
* '''Rounding errors''' actually only happen if you need a very high number of digits to represent a number. For example if you are adding a very large number with a small number. Rounding errors are very rarely encountered in day to day to applications. Actually most developers work their whole career without ever encountering them.
* '''Representation errors''' are the real problem: 0.1 is expressed in a decimal basis, but it has no finite representation in binary: it requires an infinite number of binary digits. This means that if you write 0.1 in your code it will be translated to a binary number close enough from 0.1 bot not exactly equal to it. So if you sum ten times 0.1, you sill sum ten times something close from 0.1 and the result will not be 1.

'''So the real problem for most developers only lies in the decimal-binary conversion that arises when you manipulate numbers in your code that do not have a finite representation in binary. As long as you do not use such numbers, there will be no problem. And here are the good news: integers do not suffer from any representation problem!''' Indeed, any integer can be represented with a finite number of binary digits. This is why the absence of an integer type typically does not cause problems, minus the performance penalty.

Here are a few examples to illustrate that point.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- This loop works as intended: no representation error and the upper bound is far below 2^52.
local sum = 0
for i = 0, 10000000000, 1 do sum = sum + 1 end
assert(sum == 10000000001)

-- This loop works as intended: 1/16 is a floating-point with an exact representation in binary
local sum = 0
for i = 0, 1, 1/16 do sum = sum + 1 end
assert(sum == 17/16)

-- This loop does NOT work as intended: 0.1 does not have an exact representation in binary.
-- It's the same for Lua, C and almost every programming language.
local sum = 0
for i = 0, 1, 0.1 do sum = sum + 1 end
assert(sum == 1.1) -- throws an error
</syntaxhighlight></div>

=== Errors management ===
Lua offers a error handling mechanism similar to exception handling but unfortunately not very convenient.
* Errors are thrown using the '''error''' function. It takes a string and it immediately aborts Lua execution until the game handles the error and prints it in Firetuner (when enabled).
* Errors are caught before that point using '''pcall''' or '''xpcall''', in order to let you resume execution by managing the error. "pcall" stands for "protected call".

Here are the syntaxes for pcall and xpcall:
* <code>bool, ... pcall(func, ...)</code>
** The function is called with the specified arguments.
** Pcall returns either true followed by the values returned by func, or false followed by the error text.
* <code>bool, ... xpcall(func, errorHandler)</code>:
** The function is called without any argument. If an error occurs the specified errorHandler is invoked with the error text as the only argument.
** Xpcall returns either true followed by the values returned by func, or false followed by the returned values from errorHandler.

Examples to invoke "someFunc" with "someArg" as the only argument. In both examples we want to display the error on the console, or the result if it was a success. A complete errors management example with a reporting mechanism for the end-user is presented in [[Debugging (Civ5)]].
<div class="civ5-example"><syntaxhighlight lang="lua">
-- pcall
local status, result = pcall(someFunc, someArg)
if not status then
print("error was: "..(result or "?"))
else
print("success: "..result)
end

-- xpcall
local status, result = xpcall(
function() someFunc(someArg) end,
function(err) print("error was: "..(result or "?")) end)

if status then
print("success: "..result)
end
</syntaxhighlight></div>

= Advanced topics=
=== Metatables and metamethods ===
* Every value in Lua, from a number to a userdata, has a metatable.
** Many objects can share the same metatable.
** Tables and userdata each have their own metatables by default. Numbers, bools, nils and strings all share the same metatable.
* A metatable may contain a few metamethods and index tables.
** Metamethods are methods stored under special fields names. They implement operators overloads.
** Index tables behave as "base classes": if a field name is not defined on an table, then Lua looks for this field on the index.
** In a way, metatables are analogous to virtual tables in object languages, but they are not just for methods, but also for fields and operators.
* You can get an object's metatable through '''getmetatable''' and assign it with '''setmetatable'''.
* See also the [http://www.lua.org/manual/5.1/manual.html#2.8 official metatables reference]

One example.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Define two tables A and B, and set "meta" their metatable
local a, b, meta = {}, {}, {}
setmetatable(a, meta)
setmetatable(b, meta)

-- Define an __index table on the metatable. It contains one key/value pair.
meta.__index = { "hello world" };

-- Print "hello world" twice
print(a[1])
print(b[1])

-- Now make our tables read-only
meta.__newindex = function(table, key, value) error("this table is read-only!") end
a[1] = "foo" -- throws an error
</syntaxhighlight></div>

Here are the most important fields a metatable can have:
* '''__index''': used when you read a member from an object. On tables, Lua will first search for a regular field on the table itself (not its index) before it looks at the index. The index may be a table or a function: <code>value func(object, key)</code>
* '''__newindex''': used when you assign a value to an object's member. On tables, newindex is only called if the table itself (not its index) does not already contains the specified key. May be a table or a function: <code>func(object, key, value)</code>
* '''__call''': used when you invoke the object as a function. Must be a function: <code>func(object, <args>)</code>
* '''__tostring''': used when you invoke the '''tostring''' function with this object in argument. Must be a function: <code>string func(object)</code>

Besides of that it can have fields for binary operators. When each of the two operands defined overloads, the left one is used. They must be functions: <code>result func(object)</code>
* '''__add''': addition
* '''__sub''': subtraction
* '''__mul''': multiplication
* '''__div''': division
* '''__mod''': module
* '''__pow''': exponentiation
* '''__eq''': equality comparison. Prior to calling this overload, Lua checks that types are equal.
* '''__neq''': inequality comparison. Prior to calling this overload, Lua checks whether types are different.
* '''__lt''': lesser than comparison. (b >= a) is considered equivalent to (a < b)
* '''__le''': lesser than or equal to comparison. (b > a) is considered equivalent to (a <= b). If __le is not defined, lua will use __lt, considering that (a <= b) is equivalent to not (b < a).
* '''__concat''': concatenation

Finally it can have the following fields for unary operators. They must be functions: <code>result func(object)</code>
* '''__unm''': unary minus
* '''__len''': the sharp operator (#). Can only be used on userdata ; on tables the default operator will always be called.

=== Implementing inheritance ===
The most common use of metatables is to mimic the behavior of object languages' types hierarchy. Here is how to do it:
<div class="civ5-example"><syntaxhighlight lang="lua">
local Dog = {}
function Dog:specie()
return "dog"
end
function Dog:race()
return "unknown"
end
function Dog:description()
return self.specie().." - "..self.race()
end
function Dog:new()
local instance = {}
setmetatable(instance, { __index = self})
return instance
end

local Pitbull = dog:new()
function Pitbull:race()
return "pitbull"
end

pitbull = Pitbull:new()
print(pitbull:description()) -- prints "dog - pitbull"
</syntaxhighlight></div>

This implementation is very elegant: the "new" method both creates a new instance and subtypes the creator, since "pitbull"'s index is now "Pitbull". However, should you define an operator overload on Dog's metatable, Pitbull would not inherit it. This is the limit of inheritance in Lua: operator overloads must be defined on the metatable itself, they cannot be defined on the metatable's index. As a result, there is no way to inherit those overloads while subtyping.

=== Coroutines ===
Coroutines provide a way to slice a function in many shorter calls and optionally return intermediate results. On each call, the function execution is resumed to the point where it stopped previously, with all locals being properly restored with the value they had at this time.
* Coroutines are often compared to threads. Indeed, when there are more threads than CPU cores, the operating system slices threads' execution into many little time frames and sequentially runs them in order to achieve multitasking.
* However while coroutines allows you to implement cooperative multitasking (the coroutines need to explicitly give the hand back), they cannot be used for preemptive multitasking or to use more than one system thread or CPU Core.
* As a result, coroutines are rather used as syntactic sugar (mostly to write iterators), or as a way to split a long function execution across many frames (through Context.{{Func5|UIElement|SetUpdate}}).

The following methods are mainly used:
* <code>'''coroutine''' coroutine.create('''function''' func)</code> creates a coroutine for the specified function. The function signature can be anything.
* <code>'''bool''', '''...''' coroutine.resume('''coroutine''' co, '''...''')</code> resumes the coroutine with the specified arguments. Then it returns either '''true''' followed by the returned results (either though '''return''' or '''yield'''), or '''false''' followed by an error message.
* <code>'''string''' coroutine.status('''coroutine''' co)</code> returns either "running" (the active coroutine), "normal" (a parent of the active coroutine), "suspended" (not started or waiting to be resumed) or "dead" (finished or threw an error).
* <code>coroutine.yield('''...''')</code> suspends the execution of the running coroutine and gives the hand back to the caller of coroutine.resume. The arguments will be returned by coroutine.resume.

Here is a base example:
<div class="civ5-example"><syntaxhighlight lang="lua">
function neighborsCoroutine(plot)
for i = 0, 5 do
coroutine.yield(Map.PlotDirection(plot:GetX(), plot:GetY(), i))
end
end

local co = coroutine.create(neighborsCoroutine)
while coroutine.status(co) == "suspended"
local _, neighbor = co.resume(plot)
-- Do something with plot
end
</syntaxhighlight></div>

Here is how to transform it into an iterator:
<div class="civ5-example"><syntaxhighlight lang="lua">
function neighbors(plot)
local co = coroutine.create(neighbors)
return function()
if coroutine.status(co) ~= "suspended" then return end
return select(2, coroutine.resume(plot))
end
end

for neighbor in neighbors(plot) do
-- Do something with plot
end
</syntaxhighlight></div>

Here is an example that spreads a long function call across many frames:
<div class="civ5-example"><syntaxhighlight lang="lua">
function SpreadAcrossFrames(longFunctionCall, ...)
local co = coroutine.create(longFunctionCall)
ContextPtr.SetUpdate(function()
coroutine.resume(unpack(arg))
if coroutine.status(co) ~= "suspended" then
ContextPtr:ClearUpdate()
end
end)
end

SpreadAcrossFrames(SomeLongFunction, arg1, arg2)
</syntaxhighlight></div>

=== Design philosophy for Lua ===
Do not use a butter knife as you would use a chainsaw (the opposite is even more true and usually ends up badly). When designing your code, remember that:
* Lua is not an object language. While you can use objects and inheritance in some extent, you do not have to and there may be better alternatives sometimes.
* Lua is not a functional language. While you can use lambdas and similar concepts, you do not have to and there may be better alternatives sometimes.
* Lua is a multi-paradigm and dynamic language, take advantage of those.
* Lua is very suited for prototyping and small programs, and this is perfect for mods. Try to adjust your mindset: you're not writing a framework that a whole team will still use and maintain in twenty years.

[[Category:Civ5 API]]
[[Category:Civ5 Tutorials]]

Lua introduction for confirmed developers

2012-09-30T14:09:23Z

DonQuich:

''This page is a part of the [[Lua and UI Reference (Civ5)|Lua and UI Reference]].''

= About Lua =
===Lua, not LUA===
This is a Portuguese word meaning "moon", not an acronym.

===Presentation===
Lua is an interpreted, dynamically typed, multi-paradigm language. It was designed in 1993 with the following objectives in mind:
* Extensible semantics. A small set of features allows the support of multiple paradigms, from functional programming to object programming. For example, while inheritance is not natively supported, it can be easily set up through metatables. The same features allow events in civ5 to behave both as functions and objects with Add and Remove methods.
* Highly portable. The con is a lightweight and somewhat lacking API.
* Easy to embed and to interface from other languages.
* Well suited for data description (''à la'' JSON).
* A beginners-friendly syntax.

===Performances===
As usual with interpreted and dynamically typed languages (hereby abusively named "scripting languages"), expect a 10 to 100 order of magnitude in performances decrease when compared to compiled and statically typed languages like C, C++ or C#. While it is possible for scripting languages to drastically improve the performances through more or less sophisticated means (expression trees/opcodes caching, JIT compiler, type inference to perform static resolutions), no such solution has been used in Civ5 (aside, probably, of the caching). And while an external JIT library exists, it causes compatibility problems with most mods using Lua.

That being said, Lua is still pretty good for a scripting language, better than the Python implementation from Civ4 for example. And all in all, it is fast enough for most of what modders want to achieve without the need to compromise code elegance, readability and maintainability for performances. So keep in mind that "premature optimization is the root of all evil" (Donald Knuth).

=Syntax cheatsheet=
=== Basics ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Literals
local x = 5
local x = 5.0
local x = nil -- A nil value is the same as an undefined value
local x = true
local x = false

-- Strings (single and double quotes can be used indifferently, there is no difference)
local x = "five"
local x = 'five'
local x = "five\n" -- Escape characters with "\".
local x = [[Five is a number.
Did you know?]] -- Multi-line string: equivalent to "Five is number.\nDid you know?"

-- Globals versus locals
x = 5 -- For globals, assigning is declaring.
local x = 5
</syntaxhighlight></div>

=== Operators ===
<div class="civ5-example"><syntaxhighlight lang="lua">
local x = a or b
local x = a and b

local x = "hello ".."world" .. "!" -- concatenation: two dots
local x = 4..5 -- Result is "45". On concatenation, conversions occur.

local x = (a + b - d) * f ^ g % h -- ^ is exponentiation, % is modulo
local x = "4" + "5" -- Result is 9. On arithmetic operations, conversions occur.

local x = a == b -- equality -- True only if a and b have the same values and types.
local x = a ~= b -- inequality

local x = ((a <= b) == not (a > b)) == ((a >= b) == not (a < b))
local x = "abc" < "def" -- Byte-wise comparison, not Unicode-compliant. Use Locale's methods instead.

local x = #"abc" -- Returns 3, the number of bytes in the string (3 characters, 1 byte each).
local x = #"您好世界" -- Returns 8, the number of bytes in the string (4 characters, 2 bytes each).
local x = #SomeTable -- Returns the biggest integer key in the table, or nil if there is no integer key.

-- No increment operator (++ --), no binary-assign operator (+= *=), no ternary operator (? :), no coalescence operator (??)
</syntaxhighlight></div>

=== Tables and multiple assignments ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Table declaration
SomeTable = {}

SomeArray = { "abc", "def" }
-- 1 => "abc", 2 => "def"

SomeComplexTable = { name = "John", surname = "Doe", age = 25, 43, [7] = 8 }
-- "name" => "John", "surname" => "Doe", "age" => 25, 1 => 43, 7 => 8.

-- Member access (all equivalent)
SomeTable.SomeMember = 5
SomeTable["SomeMember"] = 5

-- Multiple assignment
-- Both statements are equivalent since SomeArray contains "abc" and "def".
local x, y = "abc", "def"
local x, y = unpack(SomeArray)
</syntaxhighlight></div>

=== Functions ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Functions declarations (all equivalent)
function HelloWorld(a, b) print("Hello world") end
HelloWorld = function(a, b) print("Hello world") end
-- Functions are first-class objects and can be assigned like any other value!

-- Methods declarations (all equivalent)
SomeTable.HelloWorld(a, b) print("Hello world") end
SomeTable.HelloWorld = function(a, b) print("Hello world") end

-- Instanced methods declarations (all equivalent)
SomeTable.HelloWorldInstanced(self, a, b) print(self.SomeMember) end
SomeTable:HelloWorldInstanced(a, b) print(self.SomeMember) end

-- Functions and methods calls
HelloWorld(a) -- b will be nil in the function
HelloWorld(a, b)
SomeTable.HelloWorld(a, b)

-- Instanced methods calls (all equivalent)
SomeTable:HelloWorldInstanced(a, b)
SomeTable.HelloWorldInstanced(SomeTable, a, b)

-- Multiple return values
function func(a, b) return a, b end
local x, y, z = func(5, 6) -- Assigns 5 to x and 6 to y, z will be nil

-- Variable arguments
function SomeFunc(a, b, ...)
print(a)
print(b)
for i, v in ipairs(arg) do -- arg is a keyword for a table containing the variable arguments
print(v)
end
end
SomeFunc(1, 2, 3, 4, 5) -- prints 1, 2, 3, 4, 5
SomeFunc(1, 2) -- prints 1, 2
</syntaxhighlight></div>

=== Control flow ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- If
if name == "Wu Zetian" then
print("Hello China")
elseif name == "Napoleon" then -- "elseif", not "else if". Beware C developers!
print("Hello France")
else -- no "then" after "else"!
print("Hello unknown")
end

-- For loop (with counter)
for i = 1, 8 do print(i) end -- Prints 1, 2, 3, 4, 5, 6, 7, 8
for i = 1, 8, 2 do print(i) end -- Prints 1, 3, 5, 7

-- For loop (with iterator)
for playerID, pPlayer in pairs(Players) do -- Prints 1 Wu Zetian, 2 Napoleon, ...
print(playerID, pPlayer:GetName())
end
for plot in Plots() do -- Prints 0 0, 0 1, 0 2, ...
print(plot:GetX(), plot:GetY())
end

-- While (i will be 5 in the end)
while i < 5 do
i = i + 1
end

-- Repeat until (i will be 5 in the end)
repeat
i = i + 1
until i == 5

-- Infinite loops
-- Lua supports "break" for all loops but not "continue" instruction does not exist!
do
i = i + 1
if i > 5 then break end
end

</syntaxhighlight></div>

= Basics =
=== Type system ===
You can get a variable's type by using the '''type''' function. It takes any value and returns a string. Here are the possible results:
* The following are [http://en.wikipedia.org/wiki/Value_type value types].
** '''nil''': Lua makes do distinction between an undefined variable and a variable with a nil value. Assigning nil to a variable or table member is equivalent to undefining it.
** '''number''': a 64 bits floating-point number. Lua has no support for integers and only use floating-points. See also [[#No integer type]].
** '''boolean''': true or false obviously.
* The following are [http://en.wikipedia.org/wiki/Reference_type reference types]
** '''table''': any table.
** '''string''': your usual string of characters. In Lua all strings are interned and immutable (see [#String Interning]).
** '''userdata''': objects defined in C for use in Lua. They may not be enumerated through pairs and are often read-only.
** '''function''': remember that functions are first-class objects in Lua.
** '''thread''': coroutines actually. Lua does not support threads.

Note: Many objects in the Civ5 API are actually regular tables which either have userdata methods as members, or a userdata metatable index.

=== Implicit conversions ===
* Whenever you concatenate two values (and possibly when you invoke a standard function that takes a string), an automatic conversion to string occurs, as if you had used the '''tostring''' function. The expression <code>4..5</code> returns "45".
* Whenever you perform an arithmetic operation, the operands are both converted to numbers, as if you had used the '''tonumber''' function. The expression <code>"4" + "5"</code> returns 9.

=== Equality comparisons ===
'''Two values are equal only if their types are the same.'''<br/>
This is far stricter than most dynamic languages for example and somehow stricter than C.
* 4 is not equal to "4". (number type and string type). In PHP they would be equal.
* 0 is not equal to false (number type and bool type). In C they would be equal (false is typically defined as a number).
* 0 is not equal to nil. (number type and nil type). In C they would be equal (nil is typically defined as a number).

'''Numbers and booleans are compared by value. Everything else by reference. Strings are interned.'''
* Numbers and booleans are compared by value.
* Tables, userdata, functions and threads are compared by reference.
* Strings are interned (see [#String Interning]), which means that two identical strings are always the same reference. So comparisons are made by reference but are equivalent to by-value comparisons.
* All nil values are always equal.
<div class="civ5-example"><syntaxhighlight lang="lua">
local a = 5
assert(a == 5)
-- true, comparison by value

local a = {}
assert(a == {})
-- false, comparison by reference: those two tables are distinct objects.

local a = "Hello ".."world"
assert(a == "Hello world")
-- true, both strings are the same reference thanks to string interning.
</syntaxhighlight></div>

=== String interning ===
'''All strings are interned in Lua, without any exception.'''<br/>
[http://en.wikipedia.org/wiki/String_interning String interning] is a process through which all identical strings ends up being the same reference to a unique string instance. Typically, the interpreter maintains a string dictionary in the memory and whenever a string needs to be built (from a literal, from a concatenation, from a native call, etc), it first searches in this dictionary whether there is already a reference for this sequence of characters and uses it when it exists. This process usually reduces memory consumptions and speeds up equality comparisons, but it makes other operations slower because of the lookup cost. Some platforms such as Dotnet or Java automatically interns literals only. Lua, on the other hand, systematically interns every string.

=== Boolean logic ===
'''Anything that is neither false nor nil is evaluated to true.'''<br/>
This is pretty simple. Especially, an empty string or the zero number are evaluated to true.
<div class="civ5-example"><syntaxhighlight lang="lua">
if 0 then print("hello world") end -- prints hello world
</syntaxhighlight></div>

Now regarding the and/or operators, two rules to remember:
* '''The right operand is only evaluated when needed.'''
** <code>false and x()</code> does not call x() since the result will be false anyway.
** <code>true or x()</code> does not call x() since the result will be true anyway.
* '''The result is the last operand to have been evaluated.'''
** <code>x() and y()</code> returns x() if it was false, y() otherwise.
** <code>x() or y()</code> returns x() if it was true, y() otherwise.

=== Ternary and coalescence statements ===
We can exploit the and/or operators behavior:
* '''Coalescence:''' <code>x or y</code>. It returns x if x is neither nil nor false, y otherwise.
:In other words <code>result = x or y</code> is equivalent to: <code>if x then result = x else result = y end</code>.
* '''Ternary:''' <code>condition and x or y</code> (as long as x is not nil or false). It returns x if condition was true, y if it was false.
:Indeed the expression becomes: <code>(condition and x) or y</code>. If condition is true the '''and''' operator returns x, and since x is true, y is not evaluated and '''or''' returns x.
:In other words <code>result = condition and x or y</code> is equivalent to: <code>if condition then result = x else result = y end</code>.

=== Method calls: dot versus colon ===
'''The colon (<code>:</code>) operator implicitly passes the caller as the first argument.''' <br/>
As opposed to the dot (<code>.</code>) operator that performs a regular call without implicitly passing anything. The colon operator behavior is obviously designed for instance methods.<br/>
<div class="civ5-example"><syntaxhighlight lang="lua">
local myTable = { msg = "Hello world" }
myTable.Print = function(self) print(self.msg)

-- Three different ways to call this method
myTable:Print()
myTable.Print(myTable)

local func = myTable.Print
func(myTable)
</syntaxhighlight></div>

Note: in the civ5 API you will often encounter static methods that do not take any argument but that are called through a dot. This results from a misunderstanding of Lua from one of the Firaxis developers. While this work when the method does not take any argument (the one provided by the colon operator will be ignored), this is slower and can be considered as an error without any consequence.

=== Arrays versus tables ===
'''In Lua, an array is a table whose keys are integers.'''

Since this is a common programming pattern, a number of things are designed for arrays:
* <code>{"abc", "def", "ghi"}</code> starts at index 1, up to index 3. Arrays typically start at 1.
* <code>table.insert({}, "abc")</code> will transform the provided empty table to <code>{"abc"}</code>
* <code>table.insert({"abc", "def"}, "ghi")</code> will transform the provided table to <code>{"abc", "def", "ghi"}</code>
* <code>table.insert({"abc", "ghi"}, 2, "def")</code> will transform the provided table to <code>{"abc", "def", "ghi"}</code>
* <code>table.remove({"abc", "def", "ghi"}, 2)</code> will transform the provided table to <code>{"abc", ""ghi"}</code>
* <code>#{"abc", "def", "ghi"}</code> returns 3, the biggest integer key.

=== Ipairs versus pairs ===
You could say that '''pairs''' is for table and '''ipairs''' for arrays.
* '''Pairs''' enumerate all the key/value pairs in an unordered matter.
* '''Ipairs''' only enumerates the key/value pairs for consecutive integer keys, in an ascending order, starting from 1 up to the largest key. If at some point a key is missing, the enumeration stops.
::It does not matter whether the table was created with table.insert or directly by inserting the values through, for example <code>table[i] = value</code>.

<div class="civ5-example"><syntaxhighlight lang="lua">
-- Produces: { 1 => "one", 2 => "two", 4 => "four", "name" => "John", "age" => 25 }
local t = { "one", "two", name = "John", age = 25, [4] = "four" }

-- Will print (for example, the order is undetermined): "name", 2, 4, "age", 1
for k in pairs(t) do print(k) end

-- Will print 1, 2
for k in ipairs(t) do print(k) end

-- Both ipairs and pairs return a key and a value, so you could also use:
for k, v in pairs(t) do print(k, v) end
</syntaxhighlight></div>

=== Indices start at 1 ===
'''All indices in the API, not just for arrays, start at 1.'''<br/>
When you declare an array with implicit keys, when you use ipairs, when you retrieve the n-th character of a string, when you query the n-th call informations in the stack call, etcetera. This is a consistent pattern in Lua.

{{Warning}} The Civ5 API, however, uses 0-based indices, as it is the standard in C and most programming languages.

=== Semicolons and line breaks ===
'''Statements need to be separated either by a line break or a semicolon.'''
* You can use both a semicolon and a line break but then the semicolon is redundant and not required, although it does not cause any problem.
* Line breaks can also be freely added about everywhere and behave as whitespaces most of the time (you can add them after most keywords for example, so you can keep if...then...end structures on one line or split them across multiple lines).

=== Locals declaration order does matter ===
'''Local variables are only visible after the point where they have been declared.'''<br/>
This is different from global variables that are always visible. An example is worth thousand of words.
<div class="civ5-example"><syntaxhighlight lang="lua">
function Func1()
print(someLocal or "nil") -- Will NOT see someLocal.
print(someGlobal or "nil") -- Will see someGlobal.
end

local someLocal = "foo" -- The "foo" value will never be used.
function Func2()
print(someLocal or "nil") -- Will see someLocal.
print(someGlobal or "nil") -- Will see someGlobal.
end

someGlobal = "global"
someLocal = "local"
Func1() -- prints "nil", then "global": someLocal is assigned but not visible from Func1
Func2() -- prints "local", then "global": someLocal is assigned and visible from Func2
</syntaxhighlight></div>

Performances-wise, Lua first searches a variable name in the current scope, then in the parent scope, etcetera until it reaches the highest scope, and finally it searches the global scope. So the deeper a local is declared, the faster it is accessed. On the contrary, globals are the slowest to retrieve.

=== Files structure ===
* The include statement allows you to include a lua file into another one (see [[Specificities of the Lua implementation in Civ5]]). When you do so, the globals defined in the included file are imported in the parent file. However the local variables are only visible from within the file that declared them.
* If you're not familiar with scripting languages, consider that whenever Lua reads a file, it executes it. Practically, a Lua chunk (the root scope of a file) is no different from any other scope. It can contains ordinary statements as the ones found in a function scope, and you can use the <code>include</code> statement from any scope (although the globals defined in this included file will still be globals and won't be contained in the current scope).

= Semi-advanced topics =
=== Closures ===
'''Closures are functions that embed variables that are persisted across calls.'''<br/>
This is typically achieved through a "parent" function that declares a local "closed" variable and returns another child "closure" function using this local. The "closed" variable is then unreachable for anyone but the "closure". And since it the "closed" variable is not in the "closure"'s scope, it is not reinitialized on every call of "closure".
<div class="civ5-example"><syntaxhighlight lang="lua">
function GiveMeAFunc() -- the parent function
local x = 0 -- the closed variable
return function() -- the closure function embedding "closed"
x = x + 1
return closure
end
end

local func = GiveMeAFunc()
print(func()) -- Prints 1
print(func()) -- Prints 2
print(func()) -- Prints 3
</syntaxhighlight></div>

=== Iterators ===
'''Iterators are functions for use in <code>for...in</code> loops.'''<br/>
Let's consider the following code: <code>for var1, var2, var3 in iterable() do</code>.
* iterable has the following signature: <code>iterator, state, var1 iterable()</code>. It returns a function, a state, and the initial value of var1.
* iterator has the following signature: <code>var1, var2, var3 iterator(state, var1)</code>. It takes the state and the last value of var1 and returns var1, var2 and var3.
* The loop stops when var1 is nil.
* The for...in loop is equivalent to:
<div class="civ5-example"><syntaxhighlight lang="lua">
local iterator, state, var1, var2, var3
iterator, state, var1 = iterable()
do
var1, var2, var3 = iterator(state, var1)
if var1 == nil then break end

-- Inserts here the user code defined in the for..in loop
end
</syntaxhighlight></div>
* Note that we used var1, var2 and var3 for the example but there is no restriction to the number of variables. You could have one or hundred.

Let's write the "ipairs" function.
<div class="civ5-example"><syntaxhighlight lang="lua">
local function ipairs(table) -- The iterable function
local iterator = function(table, key) -- The iterator function
key = key + 1
return key, table[key]
end
return iterator, table, 0
end
</syntaxhighlight></div>

The same with closures: it's easier.
<div class="civ5-example"><syntaxhighlight lang="lua">
local function ipairs(table) -- The iterable function
local key = 0 -- Both "table" and "key" are closed variables.
local iterator = function() -- The iterator function, a closure: it ignores the arguments provided to it
key = key + 1
return key, table[key]
end
return iterator -- No need to return anything since we do not require any argument.
end
</syntaxhighlight></div>

=== No integer type ===
'''Lua offers no support for integers and only has a 64-bits floating point number type.'''<br/>
Actually, this is only troublesome for a few algorithms that use very large integers (>2^52) or require fast integer arithmetics. But many developers misunderstand floating points and believe the problem is broader than it is. For example, does the following assertion surprise you at least a bit: "any integer smaller than 2^52 can be accurately represented with a 64-bits floating point without any error"? If it did, you suffer from some misconceptions and you should better read carefully what's coming.

Many developers are confusing rounding errors with representation errors.
* '''Rounding errors''' actually only happen if you need a very high number of digits to represent a number. For example if you are adding a very large number with a small number. Rounding errors are very rarely encountered in day to day to applications. Actually most developers work their whole career without ever encountering them.
* '''Representation errors''' are the real problem: 0.1 is expressed in a decimal basis, but it has no finite representation in binary: it requires an infinite number of binary digits. This means that if you write 0.1 in your code it will be translated to a binary number close enough from 0.1 bot not exactly equal to it. So if you sum ten times 0.1, you sill sum ten times something close from 0.1 and the result will not be 1.

'''So the real problem for most developers only lies in the decimal-binary conversion that arises when you manipulate numbers in your code that do not have a finite representation in binary. As long as you do not use such numbers, there will be no problem. And here are the good news: integers do not suffer from any representation problem!''' Indeed, any integer can be represented with a finite number of binary digits. This is why the absence of an integer type typically does not cause problems, minus the performance penalty.

Here are a few examples to illustrate that point.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- This loop works as intended: no representation error and the upper bound is far below 2^52.
local sum = 0
for i = 0, 10000000000, 1 do sum = sum + 1 end
assert(sum == 10000000001)

-- This loop works as intended: 1/16 is a floating-point with an exact representation in binary
local sum = 0
for i = 0, 1, 1/16 do sum = sum + 1 end
assert(sum == 17/16)

-- This loop does NOT work as intended: 0.1 does not have an exact representation in binary.
-- It's the same for Lua, C and almost every programming language.
local sum = 0
for i = 0, 1, 0.1 do sum = sum + 1 end
assert(sum == 1.1) -- throws an error
</syntaxhighlight></div>

=== Errors management ===
Lua offers a error handling mechanism similar to exception handling but unfortunately not very convenient.
* Errors are thrown using the '''error''' function. It takes a string and it immediately aborts Lua execution until the game handles the error and prints it in Firetuner (when enabled).
* Errors are caught before that point using '''pcall''' or '''xpcall''', in order to let you resume execution by managing the error. "pcall" stands for "protected call".

Here are the syntaxes for pcall and xpcall:
* <code>bool, ... pcall(func, ...)</code>
** The function is called with the specified arguments.
** Pcall returns either true followed by the values returned by func, or false followed by the error text.
* <code>bool, ... xpcall(func, errorHandler)</code>:
** The function is called without any argument. If an error occurs the specified errorHandler is invoked with the error text as the only argument.
** Xpcall returns either true followed by the values returned by func, or false followed by the returned values from errorHandler.

Examples to invoke "someFunc" with "someArg" as the only argument. In both examples we want to display the error on the console, or the result if it was a success. A complete errors management example with a reporting mechanism for the end-user is presented in [[Debugging (Civ5)]].
<div class="civ5-example"><syntaxhighlight lang="lua">
-- pcall
local status, result = pcall(someFunc, someArg)
if not status then
print("error was: "..(result or "?"))
else
print("success: "..result)
end

-- xpcall
local status, result = xpcall(
function() someFunc(someArg) end,
function(err) print("error was: "..(result or "?")) end)

if status then
print("success: "..result)
end
</syntaxhighlight></div>

= Advanced topics=
=== Metatables and metamethods ===
* Every value in Lua, from a number to a userdata, has a metatable.
** Many objects can share the same metatable.
** Tables and userdata each have their own metatables by default. Numbers, bools, nils and strings all share the same metatable.
* A metatable may contain a few metamethods and index tables.
** Metamethods are methods stored under special fields names. They implement operators overloads.
** Index tables behave as "base classes": if a field name is not defined on an table, then Lua looks for this field on the index.
** In a way, metatables are analogous to virtual tables in object languages, but they are not just for methods, but also for fields and operators.
* You can get an object's metatable through '''getmetatable''' and assign it with '''setmetatable'''.
* See also the [http://www.lua.org/manual/5.1/manual.html#2.8 official metatables reference]

One example.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Define two tables A and B, and set "meta" their metatable
local a, b, meta = {}, {}, {}
setmetatable(a, meta)
setmetatable(b, meta)

-- Define an __index table on the metatable. It contains one key/value pair.
meta.__index = { "hello world" };

-- Print "hello world" twice
print(a[1])
print(b[1])

-- Now make our tables read-only
meta.__newindex = function(table, key, value) error("this table is read-only!") end
a[1] = "foo" -- throws an error
</syntaxhighlight></div>

Here are the most important fields a metatable can have:
* '''__index''': used when you read a member from an object. On tables, Lua will first search for a regular field on the table itself (not its index) before it looks at the index. The index may be a table or a function: <code>value func(object, key)</code>
* '''__newindex''': used when you assign a value to an object's member. On tables, newindex is only called if the table itself (not its index) does not already contains the specified key. May be a table or a function: <code>func(object, key, value)</code>
* '''__call''': used when you invoke the object as a function. Must be a function: <code>func(object, <args>)</code>
* '''__tostring''': used when you invoke the '''tostring''' function with this object in argument. Must be a function: <code>string func(object)</code>

Besides of that it can have fields for binary operators. When each of the two operands defined overloads, the left one is used. They must be functions: <code>result func(object)</code>
* '''__add''': addition
* '''__sub''': subtraction
* '''__mul''': multiplication
* '''__div''': division
* '''__mod''': module
* '''__pow''': exponentiation
* '''__eq''': equality comparison. Prior to calling this overload, Lua checks that types are equal.
* '''__neq''': inequality comparison. Prior to calling this overload, Lua checks whether types are different.
* '''__lt''': lesser than comparison. (b >= a) is considered equivalent to (a < b)
* '''__le''': lesser than or equal to comparison. (b > a) is considered equivalent to (a <= b). If __le is not defined, lua will use __lt, considering that (a <= b) is equivalent to not (b < a).
* '''__concat''': concatenation

Finally it can have the following fields for unary operators. They must be functions: <code>result func(object)</code>
* '''__unm''': unary minus
* '''__len''': the sharp operator (#). Can only be used on userdata ; on tables the default operator will always be called.

=== Implementing inheritance ===
The most common use of metatables is to mimic the behavior of object languages' types hierarchy. Here is how to do it:
<div class="civ5-example"><syntaxhighlight lang="lua">
local Dog = {}
function Dog:specie()
return "dog"
end
function Dog:race()
return "unknown"
end
function Dog:description()
return self.specie().." - "..self.race()
end
function Dog:new()
local instance = {}
setmetatable(instance, { __index = self})
return instance
end

local Pitbull = dog:new()
function Pitbull:race()
return "pitbull"
end

pitbull = Pitbull:new()
print(pitbull:description()) -- prints "dog - pitbull"
</syntaxhighlight></div>

This implementation is very elegant: the "new" method both creates a new instance and subtypes the creator, since "pitbull"'s index is now "Pitbull". However, should you define an operator overload on Dog's metatable, Pitbull would not inherit it. This is the limit of inheritance in Lua: operator overloads must be defined on the metatable itself, they cannot be defined on the metatable's index. As a result, there is no way to inherit those overloads while subtyping.

=== Coroutines ===
Coroutines provide a way to slice a function in many shorter calls and optionally return intermediate results. On each call, the function execution is resumed to the point where it stopped previously, with all locals being properly restored with the value they had at this time.
* Coroutines are often compared to threads. Indeed, when there are more threads than CPU cores, the operating system slices threads' execution into many little time frames and sequentially runs them in order to achieve multitasking.
* However while coroutines allows you to implement cooperative multitasking (the coroutines need to explicitly give the hand back), they cannot be used for preemptive multitasking or to use more than one system thread or CPU Core.
* As a result, coroutines are rather used as syntactic sugar (mostly to write iterators), or as a way to split a long function execution across many frames (through Context.{{Func5|UIElement|SetUpdate}}).

The following methods are mainly used:
* <code>'''coroutine''' coroutine.create('''function''' func)</code> creates a coroutine for the specified function. The function signature can be anything.
* <code>'''bool''', '''...''' coroutine.resume('''coroutine''' co, '''...''')</code> resumes the coroutine with the specified arguments. Then it returns either '''true''' followed by the returned results (either though '''return''' or '''yield'''), or '''false''' followed by an error message.
* <code>'''string''' coroutine.status('''coroutine''' co)</code> returns either "running" (the active coroutine), "normal" (a parent of the active coroutine), "suspended" (not started or waiting to be resumed) or "dead" (finished or threw an error).
* <code>coroutine.yield('''...''')</code> suspends the execution of the running coroutine and gives the hand back to the caller of coroutine.resume. The arguments will be returned by coroutine.resume.

Here is a base example:
<div class="civ5-example"><syntaxhighlight lang="lua">
function neighborsCoroutine(plot)
for i = 0, 5 do
coroutine.yield(Map.PlotDirection(plot:GetX(), plot:GetY(), i))
end
end

local co = coroutine.create(neighborsCoroutine)
while coroutine.status(co) == "suspended"
local _, neighbor = co.resume(plot)
-- Do something with plot
end
</syntaxhighlight></div>

Here is how to transform it into an iterator:
<div class="civ5-example"><syntaxhighlight lang="lua">
function neighbors(plot)
local co = coroutine.create(neighbors)
return function()
if coroutine.status(co) ~= "suspended" then return end
return select(2, coroutine.resume(plot))
end
end

for neighbor in neighbors(plot) do
-- Do something with plot
end
</syntaxhighlight></div>

Here is an example that spreads a long function call across many frames:
<div class="civ5-example"><syntaxhighlight lang="lua">
function SpreadAcrossFrames(longFunctionCall, ...)
local co = coroutine.create(longFunctionCall)
ContextPtr.SetUpdate(function()
coroutine.resume(unpack(arg))
if coroutine.status(co) ~= "suspended" then
ContextPtr:ClearUpdate()
end
end)
end

SpreadAcrossFrames(SomeLongFunction, arg1, arg2)
</syntaxhighlight></div>

=== Design philosophy for Lua ===
Do not use a butter knife as you would use a chainsaw (the opposite is even more true and usually ends up badly). When designing your code, remember that:
* Lua is not an object language. While you can use objects and inheritance in some extent, you do not have to and there may be better alternatives sometimes.
* Lua is not a functional language. While you can use lambdas and similar concepts, you do not have to and there may be better alternatives sometimes.
* Lua is a multi-paradigm and dynamic language, take advantage of those.
* Lua is very suited for prototyping and small programs, and this is perfect for mods. Try to adjust your mindset: you're not writing a framework that a whole team will still use and maintain in twenty years.

[[Category:Civ5 API]]
[[Category:Civ5 Tutorials]]

Lua introduction for confirmed developers

2012-09-30T14:09:06Z

DonQuich:

''This page is a part of the [[Lua and UI Reference (Civ5)|Lua and UI Reference]].''

= About Lua =
===Lua, not LUA===
This is a Portuguese word meaning "moon", not an acronym.

===Presentation===
Lua is an interpreted, dynamically typed, multi-paradigm language. It was designed in 1993 with the following objectives in mind:
* Extensible semantics. A small set of features allows the support of multiple paradigms, from functional programming to object programming. For example, while inheritance is not natively supported, it can be easily set up through metatables. The same features allow events in civ5 to behave both as functions and objects with Add and Remove methods.
* Highly portable. The con is a lightweight and somewhat lacking API.
* Easy to embed and to interface from other languages.
* Well suited for data description (''à la'' JSON).
* A beginners-friendly syntax.

===Performances===
As usual with interpreted and dynamically typed languages (hereby abusively named "scripting languages"), expect a 10 to 100 order of magnitude in performances decrease when compared to compiled and statically typed languages like C, C++ or C#. While it is possible for scripting languages to drastically improve the performances through more or less sophisticated means (expression trees/opcodes caching, JIT compiler, type inference to perform static resolutions), no such solution has been used in Civ5 (aside, probably, of the caching). And while an external JIT library exists, it causes compatibility problems with most mods using Lua.

That being said, Lua is still pretty good for a scripting language, better than the Python implementation from Civ4 for example. And all in all, it is fast enough for most of what modders want to achieve without the need to compromise code elegance, readability and maintainability for performances. So keep in mind that "premature optimization is the root of all evil" (Donald Knuth).

=Syntax cheatsheet=
=== Basics ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Literals
local x = 5
local x = 5.0
local x = nil -- A nil value is the same as an undefined value
local x = true
local x = false

-- Strings (single and double quotes can be used indifferently, there is no difference)
local x = "five"
local x = 'five'
local x = "five\n" -- Escape characters with "\".
local x = [[Five is a number.
Did you know?]] -- Multi-line string: equivalent to "Five is number.\nDid you know?"

-- Globals versus locals
x = 5 -- For globals, assigning is declaring.
local x = 5
</syntaxhighlight></div>

=== Operators ===
<div class="civ5-example"><syntaxhighlight lang="lua">
local x = a or b
local x = a and b

local x = "hello ".."world" .. "!" -- concatenation: two dots
local x = 4..5 -- Result is "45". On concatenation, conversions occur.

local x = (a + b - d) * f ^ g % h -- ^ is exponentiation, % is modulo
local x = "4" + "5" -- Result is 9. On arithmetic operations, conversions occur.

local x = a == b -- equality -- True only if a and b have the same values and types.
local x = a ~= b -- inequality

local x = ((a <= b) == not (a > b)) == ((a >= b) == not (a < b))
local x = "abc" < "def" -- Byte-wise comparison, not Unicode-compliant. Use Locale's methods instead.

local x = #"abc" -- Returns 3, the number of bytes in the string (3 characters, 1 byte each).
local x = #"您好世界" -- Returns 8, the number of bytes in the string (4 characters, 2 bytes each).
local x = #SomeTable -- Returns the biggest integer key in the table, or nil if there is no integer key.

-- No increment operator (++ --), no binary-assign operator (+= *=), no ternary operator (? :), no coalescence operator (??)
</syntaxhighlight></div>

=== Tables and multiple assignments ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Table declaration
SomeTable = {}

SomeArray = { "abc", "def" }
-- 1 => "abc", 2 => "def"

SomeComplexTable = { name = "John", surname = "Doe", age = 25, 43, [7] = 8 }
-- "name" => "John", "surname" => "Doe", "age" => 25, 1 => 43, 7 => 8.

-- Member access (all equivalent)
SomeTable.SomeMember = 5
SomeTable["SomeMember"] = 5

-- Multiple assignment
-- Both statements are equivalent since SomeArray contains "abc" and "def".
local x, y = "abc", "def"
local x, y = unpack(SomeArray)
</syntaxhighlight></div>

=== Functions ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Functions declarations (all equivalent)
function HelloWorld(a, b) print("Hello world") end
HelloWorld = function(a, b) print("Hello world") end
-- Functions are first-class objects and can be assigned like any other value!

-- Methods declarations (all equivalent)
SomeTable.HelloWorld(a, b) print("Hello world") end
SomeTable.HelloWorld = function(a, b) print("Hello world") end

-- Instanced methods declarations (all equivalent)
SomeTable.HelloWorldInstanced(self, a, b) print(self.SomeMember) end
SomeTable:HelloWorldInstanced(a, b) print(self.SomeMember) end

-- Functions and methods calls
HelloWorld(a) -- b will be nil in the function
HelloWorld(a, b)
SomeTable.HelloWorld(a, b)

-- Instanced methods calls (all equivalent)
SomeTable:HelloWorldInstanced(a, b)
SomeTable.HelloWorldInstanced(SomeTable, a, b)

-- Multiple return values
function func(a, b) return a, b end
local x, y, z = func(5, 6) -- Assigns 5 to x and 6 to y, z will be nil

-- Variable arguments
function SomeFunc(a, b, ...)
print(a)
print(b)
for i, v in ipairs(arg) do -- arg is a keyword for a table containing the variable arguments
print(v)
end
end
SomeFunc(1, 2, 3, 4, 5) -- prints 1, 2, 3, 4, 5
SomeFunc(1, 2) -- prints 1, 2
</syntaxhighlight></div>

=== Control flow ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- If
if name == "Wu Zetian" then
print("Hello China")
elseif name == "Napoleon" then -- "elseif", not "else if". Beware C developers!
print("Hello France")
else -- no "then" after "else"!
print("Hello unknown")
end

-- For loop (with counter)
for i = 1, 8 do print(i) end -- Prints 1, 2, 3, 4, 5, 6, 7, 8
for i = 1, 8, 2 do print(i) end -- Prints 1, 3, 5, 7

-- For loop (with iterator)
for playerID, pPlayer in pairs(Players) do -- Prints 1 Wu Zetian, 2 Napoleon, ...
print(playerID, pPlayer:GetName())
end
for plot in Plots() do -- Prints 0 0, 0 1, 0 2, ...
print(plot:GetX(), plot:GetY())
end

-- While (i will be 5 in the end)
while i < 5 do
i = i + 1
end

-- Repeat until (i will be 5 in the end)
repeat
i = i + 1
until i == 5

-- Infinite loops
-- Lua supports "break" for all loops but not "continue" instruction does not exist!
do
i = i + 1
if i > 5 then break end
end

</syntaxhighlight></div>

= Basics =
=== Type system ===
You can get a variable's type by using the '''type''' function. It takes any value and returns a string. Here are the possible results:
* The following are [http://en.wikipedia.org/wiki/Value_type value types].
** '''nil''': Lua makes do distinction between an undefined variable and a variable with a nil value. Assigning nil to a variable or table member is equivalent to undefining it.
** '''number''': a 64 bits floating-point number. Lua has no support for integers and only use floating-points. See also [[#No integer type]].
** '''boolean''': true or false obviously.
* The following are [http://en.wikipedia.org/wiki/Reference_type reference types]
** '''table''': any table.
** '''string''': your usual string of characters. In Lua all strings are interned and immutable (see [#String Interning]).
** '''userdata''': objects defined in C for use in Lua. They may not be enumerated through pairs and are often read-only.
** '''function''': remember that functions are first-class objects in Lua.
** '''thread''': coroutines actually. Lua does not support threads.

Note: Many objects in the Civ5 API are actually regular tables which either have userdata methods as members, or a userdata metatable index.

=== Implicit conversions ===
* Whenever you concatenate two values (and possibly when you invoke a standard function that takes a string), an automatic conversion to string occurs, as if you had used the '''tostring''' function. The expression <code>4..5</code> returns "45".
* Whenever you perform an arithmetic operation, the operands are both converted to numbers, as if you had used the '''tonumber''' function. The expression <code>"4" + "5"</code> returns 9.

=== Equality comparisons ===
'''Two values are equal only if their types are the same.'''<br/>
This is far stricter than most dynamic languages for example and somehow stricter than C.
* 4 is not equal to "4". (number type and string type). In PHP they would be equal.
* 0 is not equal to false (number type and bool type). In C they would be equal (false is typically defined as a number).
* 0 is not equal to nil. (number type and nil type). In C they would be equal (nil is typically defined as a number).

'''Numbers and booleans are compared by value. Everything else by reference. Strings are interned.'''
* Numbers and booleans are compared by value.
* Tables, userdata, functions and threads are compared by reference.
* Strings are interned (see [#String Interning]), which means that two identical strings are always the same reference. So comparisons are made by reference but are equivalent to by-value comparisons.
* All nil values are always equal.
<div class="civ5-example"><syntaxhighlight lang="lua">
local a = 5
assert(a == 5)
-- true, comparison by value

local a = {}
assert(a == {})
-- false, comparison by reference: those two tables are distinct objects.

local a = "Hello ".."world"
assert(a == "Hello world")
-- true, both strings are the same reference thanks to string interning.
</syntaxhighlight></div>

=== String interning ===
'''All strings are interned in Lua, without any exception.'''<br/>
[http://en.wikipedia.org/wiki/String_interning String interning] is a process through which all identical strings ends up being the same reference to a unique string instance. Typically, the interpreter maintains a string dictionary in the memory and whenever a string needs to be built (from a literal, from a concatenation, from a native call, etc), it first searches in this dictionary whether there is already a reference for this sequence of characters and uses it when it exists. This process usually reduces memory consumptions and speeds up equality comparisons, but it makes other operations slower because of the lookup cost. Some platforms such as Dotnet or Java automatically interns literals only. Lua, on the other hand, systematically interns every string.

=== Boolean logic ===
'''Anything that is neither false nor nil is evaluated to true.'''<br/>
This is pretty simple. Especially, an empty string or the zero number are evaluated to true.
<div class="civ5-example"><syntaxhighlight lang="lua">
if 0 then print("hello world") end -- prints hello world
</syntaxhighlight></div>

Now regarding the and/or operators, two rules to remember:
* '''The right operand is only evaluated when needed.'''
** <code>false and x()</code> does not call x() since the result will be false anyway.
** <code>true or x()</code> does not call x() since the result will be true anyway.
* '''The result is the last operand to have been evaluated.'''
** <code>x() and y()</code> returns x() if it was false, y() otherwise.
** <code>x() or y()</code> returns x() if it was true, y() otherwise.

=== Ternary and coalescence statements ===
We can exploit the and/or operators behavior:
* '''Coalescence:''' <code>x or y</code>. It returns x if x is neither nil nor false, y otherwise.
:In other words <code>result = x or y</code> is equivalent to: <code>if x then result = x else result = y end</code>.
* '''Ternary:''' <code>condition and x or y</code> (as long as x is not nil or false). It returns x if condition was true, y if it was false.
:Indeed the expression becomes: <code>(condition and x) or y</code>. If condition is true the '''and''' operator returns x, and since x is true, y is not evaluated and '''or''' returns x.
:In other words <code>result = condition and x or y</code> is equivalent to: <code>if condition then result = x else result = y end</code>.

=== Method calls: dot versus colon ===
'''The colon (<code>:</code>) operator implicitly passes the caller as the first argument.''' <br/>
As opposed to the dot (<code>.</code>) operator that performs a regular call without implicitly passing anything. The colon operator behavior is obviously designed for instance methods.<br/>
<div class="civ5-example"><syntaxhighlight lang="lua">
local myTable = { msg = "Hello world" }
myTable.Print = function(self) print(self.msg)

-- Three different ways to call this method
myTable:Print()
myTable.Print(myTable)

local func = myTable.Print
func(myTable)
</syntaxhighlight></div>

Note: in the civ5 API you will often encounter static methods that do not take any argument but that are called through a dot. This results from a misunderstanding of Lua from one of the Firaxis developers. While this work when the method does not take any argument (the one provided by the colon operator will be ignored), this is slower and can be considered as an error without any consequence.

=== Arrays versus tables ===
'''In Lua, an array is a table whose keys are integers.'''

Since this is a common programming pattern, a number of things are designed for arrays:
* <code>{"abc", "def", "ghi"}</code> starts at index 1, up to index 3. Arrays typically start at 1.
* <code>table.insert({}, "abc")</code> will transform the provided empty table to <code>{"abc"}</code>
* <code>table.insert({"abc", "def"}, "ghi")</code> will transform the provided table to <code>{"abc", "def", "ghi"}</code>
* <code>table.insert({"abc", "ghi"}, 2, "def")</code> will transform the provided table to <code>{"abc", "def", "ghi"}</code>
* <code>table.remove({"abc", "def", "ghi"}, 2)</code> will transform the provided table to <code>{"abc", ""ghi"}</code>
* <code>#{"abc", "def", "ghi"}</code> returns 3, the biggest integer key.

=== Ipairs versus pairs ===
You could say that '''pairs''' is for table and '''ipairs''' for arrays.
* '''Pairs''' enumerate all the key/value pairs in an unordered matter.
* '''Ipairs''' only enumerates the key/value pairs for consecutive integer keys, in an ascending order, starting from 1 up to the largest key. If at some point a key is missing, the enumeration stops.
::It does not matter whether the table was crated with table.insert or directly by inserting the values through, for example <code>table[i] = value</code>.

<div class="civ5-example"><syntaxhighlight lang="lua">
-- Produces: { 1 => "one", 2 => "two", 4 => "four", "name" => "John", "age" => 25 }
local t = { "one", "two", name = "John", age = 25, [4] = "four" }

-- Will print (for example, the order is undetermined): "name", 2, 4, "age", 1
for k in pairs(t) do print(k) end

-- Will print 1, 2
for k in ipairs(t) do print(k) end

-- Both ipairs and pairs return a key and a value, so you could also use:
for k, v in pairs(t) do print(k, v) end
</syntaxhighlight></div>

=== Indices start at 1 ===
'''All indices in the API, not just for arrays, start at 1.'''<br/>
When you declare an array with implicit keys, when you use ipairs, when you retrieve the n-th character of a string, when you query the n-th call informations in the stack call, etcetera. This is a consistent pattern in Lua.

{{Warning}} The Civ5 API, however, uses 0-based indices, as it is the standard in C and most programming languages.

=== Semicolons and line breaks ===
'''Statements need to be separated either by a line break or a semicolon.'''
* You can use both a semicolon and a line break but then the semicolon is redundant and not required, although it does not cause any problem.
* Line breaks can also be freely added about everywhere and behave as whitespaces most of the time (you can add them after most keywords for example, so you can keep if...then...end structures on one line or split them across multiple lines).

=== Locals declaration order does matter ===
'''Local variables are only visible after the point where they have been declared.'''<br/>
This is different from global variables that are always visible. An example is worth thousand of words.
<div class="civ5-example"><syntaxhighlight lang="lua">
function Func1()
print(someLocal or "nil") -- Will NOT see someLocal.
print(someGlobal or "nil") -- Will see someGlobal.
end

local someLocal = "foo" -- The "foo" value will never be used.
function Func2()
print(someLocal or "nil") -- Will see someLocal.
print(someGlobal or "nil") -- Will see someGlobal.
end

someGlobal = "global"
someLocal = "local"
Func1() -- prints "nil", then "global": someLocal is assigned but not visible from Func1
Func2() -- prints "local", then "global": someLocal is assigned and visible from Func2
</syntaxhighlight></div>

Performances-wise, Lua first searches a variable name in the current scope, then in the parent scope, etcetera until it reaches the highest scope, and finally it searches the global scope. So the deeper a local is declared, the faster it is accessed. On the contrary, globals are the slowest to retrieve.

=== Files structure ===
* The include statement allows you to include a lua file into another one (see [[Specificities of the Lua implementation in Civ5]]). When you do so, the globals defined in the included file are imported in the parent file. However the local variables are only visible from within the file that declared them.
* If you're not familiar with scripting languages, consider that whenever Lua reads a file, it executes it. Practically, a Lua chunk (the root scope of a file) is no different from any other scope. It can contains ordinary statements as the ones found in a function scope, and you can use the <code>include</code> statement from any scope (although the globals defined in this included file will still be globals and won't be contained in the current scope).

= Semi-advanced topics =
=== Closures ===
'''Closures are functions that embed variables that are persisted across calls.'''<br/>
This is typically achieved through a "parent" function that declares a local "closed" variable and returns another child "closure" function using this local. The "closed" variable is then unreachable for anyone but the "closure". And since it the "closed" variable is not in the "closure"'s scope, it is not reinitialized on every call of "closure".
<div class="civ5-example"><syntaxhighlight lang="lua">
function GiveMeAFunc() -- the parent function
local x = 0 -- the closed variable
return function() -- the closure function embedding "closed"
x = x + 1
return closure
end
end

local func = GiveMeAFunc()
print(func()) -- Prints 1
print(func()) -- Prints 2
print(func()) -- Prints 3
</syntaxhighlight></div>

=== Iterators ===
'''Iterators are functions for use in <code>for...in</code> loops.'''<br/>
Let's consider the following code: <code>for var1, var2, var3 in iterable() do</code>.
* iterable has the following signature: <code>iterator, state, var1 iterable()</code>. It returns a function, a state, and the initial value of var1.
* iterator has the following signature: <code>var1, var2, var3 iterator(state, var1)</code>. It takes the state and the last value of var1 and returns var1, var2 and var3.
* The loop stops when var1 is nil.
* The for...in loop is equivalent to:
<div class="civ5-example"><syntaxhighlight lang="lua">
local iterator, state, var1, var2, var3
iterator, state, var1 = iterable()
do
var1, var2, var3 = iterator(state, var1)
if var1 == nil then break end

-- Inserts here the user code defined in the for..in loop
end
</syntaxhighlight></div>
* Note that we used var1, var2 and var3 for the example but there is no restriction to the number of variables. You could have one or hundred.

Let's write the "ipairs" function.
<div class="civ5-example"><syntaxhighlight lang="lua">
local function ipairs(table) -- The iterable function
local iterator = function(table, key) -- The iterator function
key = key + 1
return key, table[key]
end
return iterator, table, 0
end
</syntaxhighlight></div>

The same with closures: it's easier.
<div class="civ5-example"><syntaxhighlight lang="lua">
local function ipairs(table) -- The iterable function
local key = 0 -- Both "table" and "key" are closed variables.
local iterator = function() -- The iterator function, a closure: it ignores the arguments provided to it
key = key + 1
return key, table[key]
end
return iterator -- No need to return anything since we do not require any argument.
end
</syntaxhighlight></div>

=== No integer type ===
'''Lua offers no support for integers and only has a 64-bits floating point number type.'''<br/>
Actually, this is only troublesome for a few algorithms that use very large integers (>2^52) or require fast integer arithmetics. But many developers misunderstand floating points and believe the problem is broader than it is. For example, does the following assertion surprise you at least a bit: "any integer smaller than 2^52 can be accurately represented with a 64-bits floating point without any error"? If it did, you suffer from some misconceptions and you should better read carefully what's coming.

Many developers are confusing rounding errors with representation errors.
* '''Rounding errors''' actually only happen if you need a very high number of digits to represent a number. For example if you are adding a very large number with a small number. Rounding errors are very rarely encountered in day to day to applications. Actually most developers work their whole career without ever encountering them.
* '''Representation errors''' are the real problem: 0.1 is expressed in a decimal basis, but it has no finite representation in binary: it requires an infinite number of binary digits. This means that if you write 0.1 in your code it will be translated to a binary number close enough from 0.1 bot not exactly equal to it. So if you sum ten times 0.1, you sill sum ten times something close from 0.1 and the result will not be 1.

'''So the real problem for most developers only lies in the decimal-binary conversion that arises when you manipulate numbers in your code that do not have a finite representation in binary. As long as you do not use such numbers, there will be no problem. And here are the good news: integers do not suffer from any representation problem!''' Indeed, any integer can be represented with a finite number of binary digits. This is why the absence of an integer type typically does not cause problems, minus the performance penalty.

Here are a few examples to illustrate that point.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- This loop works as intended: no representation error and the upper bound is far below 2^52.
local sum = 0
for i = 0, 10000000000, 1 do sum = sum + 1 end
assert(sum == 10000000001)

-- This loop works as intended: 1/16 is a floating-point with an exact representation in binary
local sum = 0
for i = 0, 1, 1/16 do sum = sum + 1 end
assert(sum == 17/16)

-- This loop does NOT work as intended: 0.1 does not have an exact representation in binary.
-- It's the same for Lua, C and almost every programming language.
local sum = 0
for i = 0, 1, 0.1 do sum = sum + 1 end
assert(sum == 1.1) -- throws an error
</syntaxhighlight></div>

=== Errors management ===
Lua offers a error handling mechanism similar to exception handling but unfortunately not very convenient.
* Errors are thrown using the '''error''' function. It takes a string and it immediately aborts Lua execution until the game handles the error and prints it in Firetuner (when enabled).
* Errors are caught before that point using '''pcall''' or '''xpcall''', in order to let you resume execution by managing the error. "pcall" stands for "protected call".

Here are the syntaxes for pcall and xpcall:
* <code>bool, ... pcall(func, ...)</code>
** The function is called with the specified arguments.
** Pcall returns either true followed by the values returned by func, or false followed by the error text.
* <code>bool, ... xpcall(func, errorHandler)</code>:
** The function is called without any argument. If an error occurs the specified errorHandler is invoked with the error text as the only argument.
** Xpcall returns either true followed by the values returned by func, or false followed by the returned values from errorHandler.

Examples to invoke "someFunc" with "someArg" as the only argument. In both examples we want to display the error on the console, or the result if it was a success. A complete errors management example with a reporting mechanism for the end-user is presented in [[Debugging (Civ5)]].
<div class="civ5-example"><syntaxhighlight lang="lua">
-- pcall
local status, result = pcall(someFunc, someArg)
if not status then
print("error was: "..(result or "?"))
else
print("success: "..result)
end

-- xpcall
local status, result = xpcall(
function() someFunc(someArg) end,
function(err) print("error was: "..(result or "?")) end)

if status then
print("success: "..result)
end
</syntaxhighlight></div>

= Advanced topics=
=== Metatables and metamethods ===
* Every value in Lua, from a number to a userdata, has a metatable.
** Many objects can share the same metatable.
** Tables and userdata each have their own metatables by default. Numbers, bools, nils and strings all share the same metatable.
* A metatable may contain a few metamethods and index tables.
** Metamethods are methods stored under special fields names. They implement operators overloads.
** Index tables behave as "base classes": if a field name is not defined on an table, then Lua looks for this field on the index.
** In a way, metatables are analogous to virtual tables in object languages, but they are not just for methods, but also for fields and operators.
* You can get an object's metatable through '''getmetatable''' and assign it with '''setmetatable'''.
* See also the [http://www.lua.org/manual/5.1/manual.html#2.8 official metatables reference]

One example.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Define two tables A and B, and set "meta" their metatable
local a, b, meta = {}, {}, {}
setmetatable(a, meta)
setmetatable(b, meta)

-- Define an __index table on the metatable. It contains one key/value pair.
meta.__index = { "hello world" };

-- Print "hello world" twice
print(a[1])
print(b[1])

-- Now make our tables read-only
meta.__newindex = function(table, key, value) error("this table is read-only!") end
a[1] = "foo" -- throws an error
</syntaxhighlight></div>

Here are the most important fields a metatable can have:
* '''__index''': used when you read a member from an object. On tables, Lua will first search for a regular field on the table itself (not its index) before it looks at the index. The index may be a table or a function: <code>value func(object, key)</code>
* '''__newindex''': used when you assign a value to an object's member. On tables, newindex is only called if the table itself (not its index) does not already contains the specified key. May be a table or a function: <code>func(object, key, value)</code>
* '''__call''': used when you invoke the object as a function. Must be a function: <code>func(object, <args>)</code>
* '''__tostring''': used when you invoke the '''tostring''' function with this object in argument. Must be a function: <code>string func(object)</code>

Besides of that it can have fields for binary operators. When each of the two operands defined overloads, the left one is used. They must be functions: <code>result func(object)</code>
* '''__add''': addition
* '''__sub''': subtraction
* '''__mul''': multiplication
* '''__div''': division
* '''__mod''': module
* '''__pow''': exponentiation
* '''__eq''': equality comparison. Prior to calling this overload, Lua checks that types are equal.
* '''__neq''': inequality comparison. Prior to calling this overload, Lua checks whether types are different.
* '''__lt''': lesser than comparison. (b >= a) is considered equivalent to (a < b)
* '''__le''': lesser than or equal to comparison. (b > a) is considered equivalent to (a <= b). If __le is not defined, lua will use __lt, considering that (a <= b) is equivalent to not (b < a).
* '''__concat''': concatenation

Finally it can have the following fields for unary operators. They must be functions: <code>result func(object)</code>
* '''__unm''': unary minus
* '''__len''': the sharp operator (#). Can only be used on userdata ; on tables the default operator will always be called.

=== Implementing inheritance ===
The most common use of metatables is to mimic the behavior of object languages' types hierarchy. Here is how to do it:
<div class="civ5-example"><syntaxhighlight lang="lua">
local Dog = {}
function Dog:specie()
return "dog"
end
function Dog:race()
return "unknown"
end
function Dog:description()
return self.specie().." - "..self.race()
end
function Dog:new()
local instance = {}
setmetatable(instance, { __index = self})
return instance
end

local Pitbull = dog:new()
function Pitbull:race()
return "pitbull"
end

pitbull = Pitbull:new()
print(pitbull:description()) -- prints "dog - pitbull"
</syntaxhighlight></div>

This implementation is very elegant: the "new" method both creates a new instance and subtypes the creator, since "pitbull"'s index is now "Pitbull". However, should you define an operator overload on Dog's metatable, Pitbull would not inherit it. This is the limit of inheritance in Lua: operator overloads must be defined on the metatable itself, they cannot be defined on the metatable's index. As a result, there is no way to inherit those overloads while subtyping.

=== Coroutines ===
Coroutines provide a way to slice a function in many shorter calls and optionally return intermediate results. On each call, the function execution is resumed to the point where it stopped previously, with all locals being properly restored with the value they had at this time.
* Coroutines are often compared to threads. Indeed, when there are more threads than CPU cores, the operating system slices threads' execution into many little time frames and sequentially runs them in order to achieve multitasking.
* However while coroutines allows you to implement cooperative multitasking (the coroutines need to explicitly give the hand back), they cannot be used for preemptive multitasking or to use more than one system thread or CPU Core.
* As a result, coroutines are rather used as syntactic sugar (mostly to write iterators), or as a way to split a long function execution across many frames (through Context.{{Func5|UIElement|SetUpdate}}).

The following methods are mainly used:
* <code>'''coroutine''' coroutine.create('''function''' func)</code> creates a coroutine for the specified function. The function signature can be anything.
* <code>'''bool''', '''...''' coroutine.resume('''coroutine''' co, '''...''')</code> resumes the coroutine with the specified arguments. Then it returns either '''true''' followed by the returned results (either though '''return''' or '''yield'''), or '''false''' followed by an error message.
* <code>'''string''' coroutine.status('''coroutine''' co)</code> returns either "running" (the active coroutine), "normal" (a parent of the active coroutine), "suspended" (not started or waiting to be resumed) or "dead" (finished or threw an error).
* <code>coroutine.yield('''...''')</code> suspends the execution of the running coroutine and gives the hand back to the caller of coroutine.resume. The arguments will be returned by coroutine.resume.

Here is a base example:
<div class="civ5-example"><syntaxhighlight lang="lua">
function neighborsCoroutine(plot)
for i = 0, 5 do
coroutine.yield(Map.PlotDirection(plot:GetX(), plot:GetY(), i))
end
end

local co = coroutine.create(neighborsCoroutine)
while coroutine.status(co) == "suspended"
local _, neighbor = co.resume(plot)
-- Do something with plot
end
</syntaxhighlight></div>

Here is how to transform it into an iterator:
<div class="civ5-example"><syntaxhighlight lang="lua">
function neighbors(plot)
local co = coroutine.create(neighbors)
return function()
if coroutine.status(co) ~= "suspended" then return end
return select(2, coroutine.resume(plot))
end
end

for neighbor in neighbors(plot) do
-- Do something with plot
end
</syntaxhighlight></div>

Here is an example that spreads a long function call across many frames:
<div class="civ5-example"><syntaxhighlight lang="lua">
function SpreadAcrossFrames(longFunctionCall, ...)
local co = coroutine.create(longFunctionCall)
ContextPtr.SetUpdate(function()
coroutine.resume(unpack(arg))
if coroutine.status(co) ~= "suspended" then
ContextPtr:ClearUpdate()
end
end)
end

SpreadAcrossFrames(SomeLongFunction, arg1, arg2)
</syntaxhighlight></div>

=== Design philosophy for Lua ===
Do not use a butter knife as you would use a chainsaw (the opposite is even more true and usually ends up badly). When designing your code, remember that:
* Lua is not an object language. While you can use objects and inheritance in some extent, you do not have to and there may be better alternatives sometimes.
* Lua is not a functional language. While you can use lambdas and similar concepts, you do not have to and there may be better alternatives sometimes.
* Lua is a multi-paradigm and dynamic language, take advantage of those.
* Lua is very suited for prototyping and small programs, and this is perfect for mods. Try to adjust your mindset: you're not writing a framework that a whole team will still use and maintain in twenty years.

[[Category:Civ5 API]]
[[Category:Civ5 Tutorials]]

Lua introduction for confirmed developers

2012-09-30T14:06:45Z

DonQuich:

''This page is a part of the [[Lua and UI Reference (Civ5)|Lua and UI Reference]].''

= About Lua =
===Lua, not LUA===
This is a Portuguese word meaning "moon", not an acronym.

===Presentation===
Lua is an interpreted, dynamically typed, multi-paradigm language. It was designed in 1993 with the following objectives in mind:
* Extensible semantics. A small set of features allows the support of multiple paradigms, from functional programming to object programming. For example, while inheritance is not natively supported, it can be easily set up through metatables. The same features allow events in civ5 to behave both as functions and objects with Add and Remove methods.
* Highly portable. The con is a lightweight and somewhat lacking API.
* Easy to embed and to interface from other languages.
* Well suited for data description (''à la'' JSON).
* A beginners-friendly syntax.

===Performances===
As usual with interpreted and dynamically typed languages (hereby abusively named "scripting languages"), expect a 10 to 100 order of magnitude in performances decrease when compared to compiled and statically typed languages like C, C++ or C#. While it is possible for scripting languages to drastically improve the performances through more or less sophisticated means (expression trees/opcodes caching, JIT compiler, type inference to perform static resolutions), no such solution has been used in Civ5 (aside, probably, of the caching). And while an external JIT library exists, it causes compatibility problems with most mods using Lua.

That being said, Lua is still pretty good for a scripting language, better than the Python implementation from Civ4 for example. And all in all, it is fast enough for most of what modders want to achieve without the need to compromise code elegance, readability and maintainability for performances. So keep in mind that "premature optimization is the root of all evil" (Donald Knuth).

=Syntax cheatsheet=
=== Basics ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Literals
local x = 5
local x = 5.0
local x = nil -- A nil value is the same as an undefined value
local x = true
local x = false

-- Strings (single and double quotes can be used indifferently, there is no difference)
local x = "five"
local x = 'five'
local x = "five\n" -- Escape characters with "\".
local x = [[Five is a number.
Did you know?]] -- Multi-line string: equivalent to "Five is number.\nDid you know?"

-- Globals versus locals
x = 5 -- For globals, assigning is declaring.
local x = 5
</syntaxhighlight></div>

=== Operators ===
<div class="civ5-example"><syntaxhighlight lang="lua">
local x = a or b
local x = a and b

local x = "hello ".."world" .. "!" -- concatenation: two dots
local x = 4..5 -- Result is "45". On concatenation, conversions occur.

local x = (a + b - d) * f ^ g % h -- ^ is exponentiation, % is modulo
local x = "4" + "5" -- Result is 9. On arithmetic operations, conversions occur.

local x = a == b -- equality -- True only if a and b have the same values and types.
local x = a ~= b -- inequality

local x = ((a <= b) == not (a > b)) == ((a >= b) == not (a < b))
local x = "abc" < "def" -- Byte-wise comparison, not Unicode-compliant. Use Locale's methods instead.

local x = #"abc" -- Returns 3, the number of bytes in the string (3 characters, 1 byte each).
local x = #"您好世界" -- Returns 8, the number of bytes in the string (4 characters, 2 bytes each).
local x = #SomeTable -- Returns the biggest integer key in the table, or nil if there is no integer key.

-- No increment operator (++ --), no binary-assign operator (+= *=), no ternary operator (? :), no coalescence operator (??)
</syntaxhighlight></div>

=== Tables and multiple assignments ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Table declaration
SomeTable = {}

SomeArray = { "abc", "def" }
-- 1 => "abc", 2 => "def"

SomeComplexTable = { name = "John", surname = "Doe", age = 25, 43, [7] = 8 }
-- "name" => "John", "surname" => "Doe", "age" => 25, 1 => 43, 7 => 8.

-- Member access (all equivalent)
SomeTable.SomeMember = 5
SomeTable["SomeMember"] = 5

-- Multiple assignment
-- Both statements are equivalent since SomeArray contains "abc" and "def".
local x, y = "abc", "def"
local x, y = unpack(SomeArray)
</syntaxhighlight></div>

=== Functions ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Functions declarations (all equivalent)
function HelloWorld(a, b) print("Hello world") end
HelloWorld = function(a, b) print("Hello world") end
-- Functions are first-class objects and can be assigned like any other value!

-- Methods declarations (all equivalent)
SomeTable.HelloWorld(a, b) print("Hello world") end
SomeTable.HelloWorld = function(a, b) print("Hello world") end

-- Instanced methods declarations (all equivalent)
SomeTable.HelloWorldInstanced(self, a, b) print(self.SomeMember) end
SomeTable:HelloWorldInstanced(a, b) print(self.SomeMember) end

-- Functions and methods calls
HelloWorld(a) -- b will be nil in the function
HelloWorld(a, b)
SomeTable.HelloWorld(a, b)

-- Instanced methods calls (all equivalent)
SomeTable:HelloWorldInstanced(a, b)
SomeTable.HelloWorldInstanced(SomeTable, a, b)

-- Multiple return values
function func(a, b) return a, b end
local x, y, z = func(5, 6) -- Assigns 5 to x and 6 to y, z will be nil

-- Variable arguments
function SomeFunc(a, b, ...)
print(a)
print(b)
for i, v in ipairs(arg) do -- arg is a keyword for a table containing the variable arguments
print(v)
end
end
SomeFunc(1, 2, 3, 4, 5) -- prints 1, 2, 3, 4, 5
SomeFunc(1, 2) -- prints 1, 2
</syntaxhighlight></div>

=== Control flow ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- If
if name == "Wu Zetian" then
print("Hello China")
elseif name == "Napoleon" then -- "elseif", not "else if". Beware C developers!
print("Hello France")
else -- no "then" after "else"!
print("Hello unknown")
end

-- For loop (with counter)
for i = 1, 8 do print(i) end -- Prints 1, 2, 3, 4, 5, 6, 7, 8
for i = 1, 8, 2 do print(i) end -- Prints 1, 3, 5, 7

-- For loop (with iterator)
for playerID, pPlayer in pairs(Players) do -- Prints 1 Wu Zetian, 2 Napoleon, ...
print(playerID, pPlayer:GetName())
end
for plot in Plots() do -- Prints 0 0, 0 1, 0 2, ...
print(plot:GetX(), plot:GetY())
end

-- While (i will be 5 in the end)
while i < 5 do
i = i + 1
end

-- Repeat until (i will be 5 in the end)
repeat
i = i + 1
until i == 5

-- Infinite loops
-- Lua supports "break" for all loops but not "continue" instruction does not exist!
do
i = i + 1
if i > 5 then break end
end

</syntaxhighlight></div>

= Basics =
=== Type system ===
You can get a variable's type by using the '''type''' function. It takes any value and returns a string. Here are the possible results:
* The following are [http://en.wikipedia.org/wiki/Value_type value types].
** '''nil''': Lua makes do distinction between an undefined variable and a variable with a nil value. Assigning nil to a variable or table member is equivalent to undefining it.
** '''number''': a 64 bits floating-point number. Lua has no support for integers and only use floating-points. See also [[#No integer type]].
** '''boolean''': true or false obviously.
* The following are [http://en.wikipedia.org/wiki/Reference_type reference types]
** '''table''': any table.
** '''string''': your usual string of characters. In Lua all strings are interned and immutable (see [#String Interning]).
** '''userdata''': objects defined in C for use in Lua. They may not be enumerated through pairs and are often read-only.
** '''function''': remember that functions are first-class objects in Lua.
** '''thread''': coroutines actually. Lua does not support threads.

Note: Many objects in the Civ5 API are actually regular tables which either have userdata methods as members, or a userdata metatable index.

=== Implicit conversions ===
* Whenever you concatenate two values (and possibly when you invoke a standard function that takes a string), an automatic conversion to string occurs, as if you had used the '''tostring''' function. The expression <code>4..5</code> returns "45".
* Whenever you perform an arithmetic operation, the operands are both converted to numbers, as if you had used the '''tonumber''' function. The expression <code>"4" + "5"</code> returns 9.

=== Equality comparisons ===
'''Two values are equal only if their types are the same.'''<br/>
This is far stricter than most dynamic languages for example and somehow stricter than C.
* 4 is not equal to "4". (number type and string type). In PHP they would be equal.
* 0 is not equal to false (number type and bool type). In C they would be equal (false is typically defined as a number).
* 0 is not equal to nil. (number type and nil type). In C they would be equal (nil is typically defined as a number).

'''Numbers and booleans are compared by value. Everything else by reference. Strings are interned.'''
* Numbers and booleans are compared by value.
* Tables, userdata, functions and threads are compared by reference.
* Strings are interned (see [#String Interning]), which means that two identical strings are always the same reference. So comparisons are made by reference but are equivalent to by-value comparisons.
* All nil values are always equal.
<div class="civ5-example"><syntaxhighlight lang="lua">
local a = 5
assert(a == 5)
-- true, comparison by value

local a = {}
assert(a == {})
-- false, comparison by reference: those two tables are distinct objects.

local a = "Hello ".."world"
assert(a == "Hello world")
-- true, both strings are the same reference thanks to string interning.
</syntaxhighlight></div>

=== String interning ===
'''All strings are interned in Lua, without any exception.'''<br/>
[http://en.wikipedia.org/wiki/String_interning String interning] is a process through which all identical strings ends up being the same reference to a unique string instance. Typically, the interpreter maintains a string dictionary in the memory and whenever a string needs to be built (from a literal, from a concatenation, from a native call, etc), it first searches in this dictionary whether there is already a reference for this sequence of characters and uses it when it exists. This process usually reduces memory consumptions and speeds up equality comparisons, but it makes other operations slower because of the lookup cost. Some platforms such as Dotnet or Java automatically interns literals only. Lua, on the other hand, systematically interns every string.

=== Boolean logic ===
'''Anything that is neither false nor nil is evaluated to true.'''<br/>
This is pretty simple. Especially, an empty string or the zero number are evaluated to true.
<div class="civ5-example"><syntaxhighlight lang="lua">
if 0 then print("hello world") end -- prints hello world
</syntaxhighlight></div>

Now regarding the and/or operators, two rules to remember:
* '''The right operand is only evaluated when needed.'''
** <code>false and x()</code> does not call x() since the result will be false anyway.
** <code>true or x()</code> does not call x() since the result will be true anyway.
* '''The result is the last operand to have been evaluated.'''
** <code>x() and y()</code> returns x() if it was false, y() otherwise.
** <code>x() or y()</code> returns x() if it was true, y() otherwise.

=== Ternary and coalescence statements ===
We can exploit the and/or operators behavior:
* '''Coalescence:''' <code>x or y</code>. It returns x if x is neither nil nor false, y otherwise.
:In other words <code>result = x or y</code> is equivalent to: <code>if x then result = x else result = y end</code>.
* '''Ternary:''' <code>condition and x or y</code> (as long as x is not nil or false). It returns x if condition was true, y if it was false.
:Indeed the expression becomes: <code>(condition and x) or y</code>. If condition is true the '''and''' operator returns x, and since x is true, y is not evaluated and '''or''' returns x.
:In other words <code>result = condition and x or y</code> is equivalent to: <code>if condition then result = x else result = y end</code>.

=== Method calls: dot versus colon ===
'''The colon (<code>:</code>) operator implicitly passes the caller as the first argument.''' <br/>
As opposed to the dot (<code>.</code>) operator that performs a regular call without implicitly passing anything. The colon operator behavior is obviously designed for instance methods.<br/>
<div class="civ5-example"><syntaxhighlight lang="lua">
local myTable = { msg = "Hello world" }
myTable.Print = function(self) print(self.msg)

-- Three different ways to call this method
myTable:Print()
myTable.Print(myTable)

local func = myTable.Print
func(myTable)
</syntaxhighlight></div>

Note: in the civ5 API you will often encounter static methods that do not take any argument but that are called through a dot. This results from a misunderstanding of Lua from one of the Firaxis developers. While this work when the method does not take any argument (the one provided by the colon operator will be ignored), this is slower and can be considered as an error without any consequence.

=== Arrays versus tables ===
'''In Lua, an array is a table whose keys are integers.'''

Since this is a common programming pattern, a number of things are designed for arrays:
* <code>{"abc", "def", "ghi"}</code> starts at index 1, up to index 3. Arrays typically start at 1.
* <code>table.insert({}, "abc")</code> will transform the provided empty table to <code>{"abc"}</code>
* <code>table.insert({"abc", "def"}, "ghi")</code> will transform the provided table to <code>{"abc", "def", "ghi"}</code>
* <code>table.insert({"abc", "ghi"}, 2, "def")</code> will transform the provided table to <code>{"abc", "def", "ghi"}</code>
* <code>table.remove({"abc", "def", "ghi"}, 2)</code> will transform the provided table to <code>{"abc", ""ghi"}</code>
* <code>#{"abc", "def", "ghi"}</code> returns 3, the biggest integer key.

=== Ipairs versus pairs ===
You could say that '''pairs''' is for table and '''ipairs''' for arrays.
* '''Pairs''' enumerate all the key/value pairs in an unordered matter.
* '''Ipairs''' only enumerates the key/value pairs for consecutive integer keys, in an ascending order, starting from 1 up to the largest key. If at some point a key is missing, the enumeration stops.
::It does not matter whether the table was crated with table.insert or directly by inserting the values through, for example <code>table[i] = value</code>.

<div class="civ5-example"><syntaxhighlight lang="lua">
-- Produces: { 1 => "one", 2 => "two", 4 => "four", "name" => "John", "age" => 25 }
local t = { "one", "two", name = "John", age = 25, [4] = "four" }

-- Will print (for example, the order is undetermined): "name", 2, 4, "age", 1
for k in pairs(t) do print(k) end

-- Will print 1, 2
for k in ipairs(t) do print(k) end

-- Both ipairs and pairs return a key and a value, so you could also use:
for k, v in pairs(t) do print(k, v) end
</syntaxhighlight></div>

=== Indices start at 1 ===
'''All indices in the API, not just for arrays, start at 1.'''<br/>
When you declare an array with implicit keys, when you use ipairs, when you retrieve the n-th character of a string, when you query the n-th call informations in the stack call, etcetera. This is a consistent pattern in Lua.

{{Warning}} The Civ5 API, however, uses 0-based indices, as it is the standard in C and most programming languages.

=== Semicolons and line breaks ===
'''Statements need to be separated either by a line break or a semicolon.'''
* You can use both a semicolon and a line break but then the semicolon is redundant and not required, although it does not cause any problem.
* Line breaks can also be freely added about everywhere and behave as whitespaces most of the time (you can add them after most keywords for example, so you can keep if...then...end structures on one line or split them across multiple lines).

=== Locals declaration order does matter ===
'''Local variables are only visible after the point where they have been declared.'''
This is different from global variables that are always visible. An example is worth thousand of words.
<div class="civ5-example"><syntaxhighlight lang="lua">
function Func1()
print(someLocal or "nil") -- Will NOT see someLocal
print(someGlobal or "nil") -- Will see someGlobal
end

local someLocal = "foo"
function Func2()
print(someLocal or "nil") -- Will see someLocal
print(someGlobal or "nil") -- Will see someGlobal
end

someGlobal = "global"
someLocal = "local"
Func1() -- prints "nil", then "global": someLocal is assigned but not visible from Func1
Func2() -- prints "local", then "global": someLocal is assigned and visible from Func2
</syntaxhighlight></div>

Performances-wise, Lua first searches a variable name in the current scope, then in the parent scope, etcetera until it reaches the highest scope, and finally it searches the global scope. So the deeper a local is declared, the faster it is accessed. On the contrary, globals are the slowest to retrieve.

=== File structure ===
* The include statement allows you to include a lua file into another one (see [[Specificities of the Lua implementation in Civ5]]). When you do so, the globals defined in the included file are imported in the parent file. However the local variables are only visible from within the file that declared them.
* If you're not familiar with scripting languages, consider that whenever Lua reads a file, it executes it. Practically, a Lua chunk (the root scope of a file) is no different from any other scope. It can contains ordinary statements as the ones found in a function scope, and you can use the <code>include</code> statement from any scope (although the globals defined in this included file will still be globals and won't be contained in the current scope).

= Semi-advanced topics =
=== Closures ===
'''Closures are functions that embed variables that are persisted across calls.'''<br/>
This is typically achieved through a "parent" function that declares a local "closed" variable and returns another child "closure" function using this local. The "closed" variable is then unreachable for anyone but the "closure". And since it the "closed" variable is not in the "closure"'s scope, it is not reinitialized on every call of "closure".
<div class="civ5-example"><syntaxhighlight lang="lua">
function GiveMeAFunc() -- the parent function
local x = 0 -- the closed variable
return function() -- the closure function embedding "closed"
x = x + 1
return closure
end
end

local func = GiveMeAFunc()
print(func()) -- Prints 1
print(func()) -- Prints 2
print(func()) -- Prints 3
</syntaxhighlight></div>

=== Iterators ===
'''Iterators are functions for use in <code>for...in</code> loops.'''<br/>
Let's consider the following code: <code>for var1, var2, var3 in iterable() do</code>.
* iterable has the following signature: <code>iterator, state, var1 iterable()</code>. It returns a function, a state, and the initial value of var1.
* iterator has the following signature: <code>var1, var2, var3 iterator(state, var1)</code>. It takes the state and the last value of var1 and returns var1, var2 and var3.
* The loop stops when var1 is nil.
* The for...in loop is equivalent to:
<div class="civ5-example"><syntaxhighlight lang="lua">
local iterator, state, var1, var2, var3
iterator, state, var1 = iterable()
do
var1, var2, var3 = iterator(state, var1)
if var1 == nil then break end

-- Inserts here the user code defined in the for..in loop
end
</syntaxhighlight></div>
* Note that we used var1, var2 and var3 for the example but there is no restriction to the number of variables. You could have one or hundred.

Let's write the "ipairs" function.
<div class="civ5-example"><syntaxhighlight lang="lua">
local function ipairs(table) -- The iterable function
local iterator = function(table, key) -- The iterator function
key = key + 1
return key, table[key]
end
return iterator, table, 0
end
</syntaxhighlight></div>

The same with closures: it's easier.
<div class="civ5-example"><syntaxhighlight lang="lua">
local function ipairs(table) -- The iterable function
local key = 0 -- Both "table" and "key" are closed variables.
local iterator = function() -- The iterator function, a closure: it ignores the arguments provided to it
key = key + 1
return key, table[key]
end
return iterator -- No need to return anything since we do not require any argument.
end
</syntaxhighlight></div>

=== No integer type ===
'''Lua offers no support for integers and only has a 64-bits floating point number type.'''<br/>
Actually, this is only troublesome for a few algorithms that use very large integers (>2^52) or require fast integer arithmetics. But many developers misunderstand floating points and believe the problem is broader than it is. For example, does the following assertion surprise you at least a bit: "any integer smaller than 2^52 can be accurately represented with a 64-bits floating point without any error"? If it did, you suffer from some misconceptions and you should better read carefully what's coming.

Many developers are confusing rounding errors with representation errors.
* '''Rounding errors''' actually only happen if you need a very high number of digits to represent a number. For example if you are adding a very large number with a small number. Rounding errors are very rarely encountered in day to day to applications. Actually most developers work their whole career without ever encountering them.
* '''Representation errors''' are the real problem: 0.1 is expressed in a decimal basis, but it has no finite representation in binary: it requires an infinite number of binary digits. This means that if you write 0.1 in your code it will be translated to a binary number close enough from 0.1 bot not exactly equal to it. So if you sum ten times 0.1, you sill sum ten times something close from 0.1 and the result will not be 1.

'''So the real problem for most developers only lies in the decimal-binary conversion that arises when you manipulate numbers in your code that do not have a finite representation in binary. As long as you do not use such numbers, there will be no problem. And here are the good news: integers do not suffer from any representation problem!''' Indeed, any integer can be represented with a finite number of binary digits. This is why the absence of an integer type typically does not cause problems, minus the performance penalty.

Here are a few examples to illustrate that point.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- This loop works as intended: no representation error and the upper bound is far below 2^52.
local sum = 0
for i = 0, 10000000000, 1 do sum = sum + 1 end
assert(sum == 10000000001)

-- This loop works as intended: 1/16 is a floating-point with an exact representation in binary
local sum = 0
for i = 0, 1, 1/16 do sum = sum + 1 end
assert(sum == 17/16)

-- This loop does NOT work as intended: 0.1 does not have an exact representation in binary.
-- It's the same for Lua, C and almost every programming language.
local sum = 0
for i = 0, 1, 0.1 do sum = sum + 1 end
assert(sum == 1.1) -- throws an error
</syntaxhighlight></div>

=== Errors management ===
Lua offers a error handling mechanism similar to exception handling but unfortunately not very convenient.
* Errors are thrown using the '''error''' function. It takes a string and it immediately aborts Lua execution until the game handles the error and prints it in Firetuner (when enabled).
* Errors are caught before that point using '''pcall''' or '''xpcall''', in order to let you resume execution by managing the error. "pcall" stands for "protected call".

Here are the syntaxes for pcall and xpcall:
* <code>bool, ... pcall(func, ...)</code>
** The function is called with the specified arguments.
** Pcall returns either true followed by the values returned by func, or false followed by the error text.
* <code>bool, ... xpcall(func, errorHandler)</code>:
** The function is called without any argument. If an error occurs the specified errorHandler is invoked with the error text as the only argument.
** Xpcall returns either true followed by the values returned by func, or false followed by the returned values from errorHandler.

Examples to invoke "someFunc" with "someArg" as the only argument. In both examples we want to display the error on the console, or the result if it was a success. A complete errors management example with a reporting mechanism for the end-user is presented in [[Debugging (Civ5)]].
<div class="civ5-example"><syntaxhighlight lang="lua">
-- pcall
local status, result = pcall(someFunc, someArg)
if not status then
print("error was: "..(result or "?"))
else
print("success: "..result)
end

-- xpcall
local status, result = xpcall(
function() someFunc(someArg) end,
function(err) print("error was: "..(result or "?")) end)

if status then
print("success: "..result)
end
</syntaxhighlight></div>

= Advanced topics=
=== Metatables and metamethods ===
* Every value in Lua, from a number to a userdata, has a metatable.
** Many objects can share the same metatable.
** Tables and userdata each have their own metatables by default. Numbers, bools, nils and strings all share the same metatable.
* A metatable may contain a few metamethods and index tables.
** Metamethods are methods stored under special fields names. They implement operators overloads.
** Index tables behave as "base classes": if a field name is not defined on an table, then Lua looks for this field on the index.
** In a way, metatables are analogous to virtual tables in object languages, but they are not just for methods, but also for fields and operators.
* You can get an object's metatable through '''getmetatable''' and assign it with '''setmetatable'''.
* See also the [http://www.lua.org/manual/5.1/manual.html#2.8 official metatables reference]

One example.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Define two tables A and B, and set "meta" their metatable
local a, b, meta = {}, {}, {}
setmetatable(a, meta)
setmetatable(b, meta)

-- Define an __index table on the metatable. It contains one key/value pair.
meta.__index = { "hello world" };

-- Print "hello world" twice
print(a[1])
print(b[1])

-- Now make our tables read-only
meta.__newindex = function(table, key, value) error("this table is read-only!") end
a[1] = "foo" -- throws an error
</syntaxhighlight></div>

Here are the most important fields a metatable can have:
* '''__index''': used when you read a member from an object. On tables, Lua will first search for a regular field on the table itself (not its index) before it looks at the index. The index may be a table or a function: <code>value func(object, key)</code>
* '''__newindex''': used when you assign a value to an object's member. On tables, newindex is only called if the table itself (not its index) does not already contains the specified key. May be a table or a function: <code>func(object, key, value)</code>
* '''__call''': used when you invoke the object as a function. Must be a function: <code>func(object, <args>)</code>
* '''__tostring''': used when you invoke the '''tostring''' function with this object in argument. Must be a function: <code>string func(object)</code>

Besides of that it can have fields for binary operators. When each of the two operands defined overloads, the left one is used. They must be functions: <code>result func(object)</code>
* '''__add''': addition
* '''__sub''': subtraction
* '''__mul''': multiplication
* '''__div''': division
* '''__mod''': module
* '''__pow''': exponentiation
* '''__eq''': equality comparison. Prior to calling this overload, Lua checks that types are equal.
* '''__neq''': inequality comparison. Prior to calling this overload, Lua checks whether types are different.
* '''__lt''': lesser than comparison. (b >= a) is considered equivalent to (a < b)
* '''__le''': lesser than or equal to comparison. (b > a) is considered equivalent to (a <= b). If __le is not defined, lua will use __lt, considering that (a <= b) is equivalent to not (b < a).
* '''__concat''': concatenation

Finally it can have the following fields for unary operators. They must be functions: <code>result func(object)</code>
* '''__unm''': unary minus
* '''__len''': the sharp operator (#). Can only be used on userdata ; on tables the default operator will always be called.

=== Implementing inheritance ===
The most common use of metatables is to mimic the behavior of object languages' types hierarchy. Here is how to do it:
<div class="civ5-example"><syntaxhighlight lang="lua">
local Dog = {}
function Dog:specie()
return "dog"
end
function Dog:race()
return "unknown"
end
function Dog:description()
return self.specie().." - "..self.race()
end
function Dog:new()
local instance = {}
setmetatable(instance, { __index = self})
return instance
end

local Pitbull = dog:new()
function Pitbull:race()
return "pitbull"
end

pitbull = Pitbull:new()
print(pitbull:description()) -- prints "dog - pitbull"
</syntaxhighlight></div>

This implementation is very elegant: the "new" method both creates a new instance and subtypes the creator, since "pitbull"'s index is now "Pitbull". However, should you define an operator overload on Dog's metatable, Pitbull would not inherit it. This is the limit of inheritance in Lua: operator overloads must be defined on the metatable itself, they cannot be defined on the metatable's index. As a result, there is no way to inherit those overloads while subtyping.

=== Coroutines ===
Coroutines provide a way to slice a function in many shorter calls and optionally return intermediate results. On each call, the function execution is resumed to the point where it stopped previously, with all locals being properly restored with the value they had at this time.
* Coroutines are often compared to threads. Indeed, when there are more threads than CPU cores, the operating system slices threads' execution into many little time frames and sequentially runs them in order to achieve multitasking.
* However while coroutines allows you to implement cooperative multitasking (the coroutines need to explicitly give the hand back), they cannot be used for preemptive multitasking or to use more than one system thread or CPU Core.
* As a result, coroutines are rather used as syntactic sugar (mostly to write iterators), or as a way to split a long function execution across many frames (through Context.{{Func5|UIElement|SetUpdate}}).

The following methods are mainly used:
* <code>'''coroutine''' coroutine.create('''function''' func)</code> creates a coroutine for the specified function. The function signature can be anything.
* <code>'''bool''', '''...''' coroutine.resume('''coroutine''' co, '''...''')</code> resumes the coroutine with the specified arguments. Then it returns either '''true''' followed by the returned results (either though '''return''' or '''yield'''), or '''false''' followed by an error message.
* <code>'''string''' coroutine.status('''coroutine''' co)</code> returns either "running" (the active coroutine), "normal" (a parent of the active coroutine), "suspended" (not started or waiting to be resumed) or "dead" (finished or threw an error).
* <code>coroutine.yield('''...''')</code> suspends the execution of the running coroutine and gives the hand back to the caller of coroutine.resume. The arguments will be returned by coroutine.resume.

Here is a base example:
<div class="civ5-example"><syntaxhighlight lang="lua">
function neighborsCoroutine(plot)
for i = 0, 5 do
coroutine.yield(Map.PlotDirection(plot:GetX(), plot:GetY(), i))
end
end

local co = coroutine.create(neighborsCoroutine)
while coroutine.status(co) == "suspended"
local _, neighbor = co.resume(plot)
-- Do something with plot
end
</syntaxhighlight></div>

Here is how to transform it into an iterator:
<div class="civ5-example"><syntaxhighlight lang="lua">
function neighbors(plot)
local co = coroutine.create(neighbors)
return function()
if coroutine.status(co) ~= "suspended" then return end
return select(2, coroutine.resume(plot))
end
end

for neighbor in neighbors(plot) do
-- Do something with plot
end
</syntaxhighlight></div>

Here is an example that spreads a long function call across many frames:
<div class="civ5-example"><syntaxhighlight lang="lua">
function SpreadAcrossFrames(longFunctionCall, ...)
local co = coroutine.create(longFunctionCall)
ContextPtr.SetUpdate(function()
coroutine.resume(unpack(arg))
if coroutine.status(co) ~= "suspended" then
ContextPtr:ClearUpdate()
end
end)
end

SpreadAcrossFrames(SomeLongFunction, arg1, arg2)
</syntaxhighlight></div>

=== Design philosophy for Lua ===
Do not use a butter knife as you would use a chainsaw (the opposite is even more true and usually ends up badly). When designing your code, remember that:
* Lua is not an object language. While you can use objects and inheritance in some extent, you do not have to and there may be better alternatives sometimes.
* Lua is not a functional language. While you can use lambdas and similar concepts, you do not have to and there may be better alternatives sometimes.
* Lua is a multi-paradigm and dynamic language, take advantage of those.
* Lua is very suited for prototyping and small programs, and this is perfect for mods. Try to adjust your mindset: you're not writing a framework that a whole team will still use and maintain in twenty years.

[[Category:Civ5 API]]
[[Category:Civ5 Tutorials]]

Lua introduction for confirmed developers

2012-09-30T13:48:55Z

DonQuich:

''This page is a part of the [[Lua and UI Reference (Civ5)|Lua and UI Reference]].''

= About Lua =
===Lua, not LUA===
This is a Portuguese word meaning "moon", not an acronym.

===Presentation===
Lua is an interpreted, dynamically typed, multi-paradigm language. It was designed in 1993 with the following objectives in mind:
* Extensible semantics. A small set of features allows the support of multiple paradigms, from functional programming to object programming. For example, while inheritance is not natively supported, it can be easily set up through metatables. The same features allow events in civ5 to behave both as functions and objects with Add and Remove methods.
* Highly portable. The con is a lightweight and somewhat lacking API.
* Easy to embed and to interface from other languages.
* Well suited for data description (''à la'' JSON).
* A beginners-friendly syntax.

===Performances===
As usual with interpreted and dynamically typed languages (hereby abusively named "scripting languages"), expect a 10 to 100 order of magnitude in performances decrease when compared to compiled and statically typed languages like C, C++ or C#. While it is possible for scripting languages to drastically improve the performances through more or less sophisticated means (expression trees/opcodes caching, JIT compiler, type inference to perform static resolutions), no such solution has been used in Civ5 (aside, probably, of the caching). And while an external JIT library exists, it causes compatibility problems with most mods using Lua.

That being said, Lua is still pretty good for a scripting language, better than the Python implementation from Civ4 for example. And all in all, it is fast enough for most of what modders want to achieve without the need to compromise code elegance, readability and maintainability for performances. So keep in mind that "premature optimization is the root of all evil" (Donald Knuth).

=Syntax cheatsheet=
=== Basics ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Literals
local x = 5
local x = 5.0
local x = nil -- A nil value is the same as an undefined value
local x = true
local x = false

-- Strings (single and double quotes can be used indifferently, there is no difference)
local x = "five"
local x = 'five'
local x = "five\n" -- Escape characters with "\".
local x = [[Five is a number.
Did you know?]] -- Multi-line string: equivalent to "Five is number.\nDid you know?"

-- Globals versus locals
x = 5 -- For globals, assigning is declaring.
local x = 5
</syntaxhighlight></div>

=== Operators ===
<div class="civ5-example"><syntaxhighlight lang="lua">
local x = a or b
local x = a and b

local x = "hello ".."world" .. "!" -- concatenation: two dots
local x = 4..5 -- Result is "45". On concatenation, conversions occur.

local x = (a + b - d) * f ^ g % h -- ^ is exponentiation, % is modulo
local x = "4" + "5" -- Result is 9. On arithmetic operations, conversions occur.

local x = a == b -- equality -- True only if a and b have the same values and types.
local x = a ~= b -- inequality

local x = ((a <= b) == not (a > b)) == ((a >= b) == not (a < b))
local x = "abc" < "def" -- Byte-wise comparison, not Unicode-compliant. Use Locale's methods instead.

local x = #"abc" -- Returns 3, the number of bytes in the string (3 characters, 1 byte each).
local x = #"您好世界" -- Returns 8, the number of bytes in the string (4 characters, 2 bytes each).
local x = #SomeTable -- Returns the biggest integer key in the table, or nil if there is no integer key.

-- No increment operator (++ --), no binary-assign operator (+= *=), no ternary operator (? :), no coalescence operator (??)
</syntaxhighlight></div>

=== Tables and multiple assignments ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Table declaration
SomeTable = {}

SomeArray = { "abc", "def" }
-- 1 => "abc", 2 => "def"

SomeComplexTable = { name = "John", surname = "Doe", age = 25, 43, [7] = 8 }
-- "name" => "John", "surname" => "Doe", "age" => 25, 1 => 43, 7 => 8.

-- Member access (all equivalent)
SomeTable.SomeMember = 5
SomeTable["SomeMember"] = 5

-- Multiple assignment
-- Both statements are equivalent since SomeArray contains "abc" and "def".
local x, y = "abc", "def"
local x, y = unpack(SomeArray)
</syntaxhighlight></div>

=== Functions ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Functions declarations (all equivalent)
function HelloWorld(a, b) print("Hello world") end
HelloWorld = function(a, b) print("Hello world") end
-- Functions are first-class objects and can be assigned like any other value!

-- Methods declarations (all equivalent)
SomeTable.HelloWorld(a, b) print("Hello world") end
SomeTable.HelloWorld = function(a, b) print("Hello world") end

-- Instanced methods declarations (all equivalent)
SomeTable.HelloWorldInstanced(self, a, b) print(self.SomeMember) end
SomeTable:HelloWorldInstanced(a, b) print(self.SomeMember) end

-- Functions and methods calls
HelloWorld(a) -- b will be nil in the function
HelloWorld(a, b)
SomeTable.HelloWorld(a, b)

-- Instanced methods calls (all equivalent)
SomeTable:HelloWorldInstanced(a, b)
SomeTable.HelloWorldInstanced(SomeTable, a, b)

-- Multiple return values
function func(a, b) return a, b end
local x, y, z = func(5, 6) -- Assigns 5 to x and 6 to y, z will be nil

-- Variable arguments
function SomeFunc(a, b, ...)
print(a)
print(b)
for i, v in ipairs(arg) do -- arg is a keyword for a table containing the variable arguments
print(v)
end
end
SomeFunc(1, 2, 3, 4, 5) -- prints 1, 2, 3, 4, 5
SomeFunc(1, 2) -- prints 1, 2
</syntaxhighlight></div>

=== Control flow ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- If
if name == "Wu Zetian" then
print("Hello China")
elseif name == "Napoleon" then -- "elseif", not "else if". Beware C developers!
print("Hello France")
else -- no "then" after "else"!
print("Hello unknown")
end

-- For loop (with counter)
for i = 1, 8 do print(i) end -- Prints 1, 2, 3, 4, 5, 6, 7, 8
for i = 1, 8, 2 do print(i) end -- Prints 1, 3, 5, 7

-- For loop (with iterator)
for playerID, pPlayer in pairs(Players) do -- Prints 1 Wu Zetian, 2 Napoleon, ...
print(playerID, pPlayer:GetName())
end
for plot in Plots() do -- Prints 0 0, 0 1, 0 2, ...
print(plot:GetX(), plot:GetY())
end

-- While (i will be 5 in the end)
while i < 5 do
i = i + 1
end

-- Repeat until (i will be 5 in the end)
repeat
i = i + 1
until i == 5

-- Infinite loops
-- Lua supports "break" for all loops but not "continue" instruction does not exist!
do
i = i + 1
if i > 5 then break end
end

</syntaxhighlight></div>

= Basics =
=== Type system ===
You can get a variable's type by using the '''type''' function. It takes any value and returns a string. Here are the possible results:
* The following are [http://en.wikipedia.org/wiki/Value_type value types].
** '''nil''': Lua makes do distinction between an undefined variable and a variable with a nil value. Assigning nil to a variable or table member is equivalent to undefining it.
** '''number''': a 64 bits floating-point number. Lua has no support for integers and only use floating-points. See also [[#No integer type]].
** '''boolean''': true or false obviously.
* The following are [http://en.wikipedia.org/wiki/Reference_type reference types]
** '''table''': any table.
** '''string''': your usual string of characters. In Lua all strings are interned and immutable (see [#String Interning]).
** '''userdata''': objects defined in C for use in Lua. They may not be enumerated through pairs and are often read-only.
** '''function''': remember that functions are first-class objects in Lua.
** '''thread''': coroutines actually. Lua does not support threads.

Note: Many objects in the Civ5 API are actually regular tables which either have userdata methods as members, or a userdata metatable index.

=== Implicit conversions ===
* Whenever you concatenate two values (and possibly when you invoke a standard function that takes a string), an automatic conversion to string occurs, as if you had used the '''tostring''' function. The expression <code>4..5</code> returns "45".
* Whenever you perform an arithmetic operation, the operands are both converted to numbers, as if you had used the '''tonumber''' function. The expression <code>"4" + "5"</code> returns 9.

=== Equality comparisons ===
'''Two values are equal only if their types are the same.'''<br/>
This is far stricter than most dynamic languages for example and somehow stricter than C.
* 4 is not equal to "4". (number type and string type). In PHP they would be equal.
* 0 is not equal to false (number type and bool type). In C they would be equal (false is typically defined as a number).
* 0 is not equal to nil. (number type and nil type). In C they would be equal (nil is typically defined as a number).

'''Numbers and booleans are compared by value. Everything else by reference. Strings are interned.'''
* Numbers and booleans are compared by value.
* Tables, userdata, functions and threads are compared by reference.
* Strings are interned (see [#String Interning]), which means that two identical strings are always the same reference. So comparisons are made by reference but are equivalent to by-value comparisons.
* All nil values are always equal.
<div class="civ5-example"><syntaxhighlight lang="lua">
local a = 5
assert(a == 5)
-- true, comparison by value

local a = {}
assert(a == {})
-- false, comparison by reference: those two tables are distinct objects.

local a = "Hello ".."world"
assert(a == "Hello world")
-- true, both strings are the same reference thanks to string interning.
</syntaxhighlight></div>

=== String interning ===
'''All strings are interned in Lua, without any exception.'''<br/>
[http://en.wikipedia.org/wiki/String_interning String interning] is a process through which all identical strings ends up being the same reference to a unique string instance. Typically, the interpreter maintains a string dictionary in the memory and whenever a string needs to be built (from a literal, from a concatenation, from a native call, etc), it first searches in this dictionary whether there is already a reference for this sequence of characters and uses it when it exists. This process usually reduces memory consumptions and speeds up equality comparisons, but it makes other operations slower because of the lookup cost. Some platforms such as Dotnet or Java automatically interns literals only. Lua, on the other hand, systematically interns every string.

=== Boolean logic ===
'''Anything that is neither false nor nil is evaluated to true.'''<br/>
This is pretty simple. Especially, an empty string or the zero number are evaluated to true.
<div class="civ5-example"><syntaxhighlight lang="lua">
if 0 then print("hello world") end -- prints hello world
</syntaxhighlight></div>

Now regarding the and/or operators, two rules to remember:
* '''The right operand is only evaluated when needed.'''
** <code>false and x()</code> does not call x() since the result will be false anyway.
** <code>true or x()</code> does not call x() since the result will be true anyway.
* '''The result is the last operand to have been evaluated.'''
** <code>x() and y()</code> returns x() if it was false, y() otherwise.
** <code>x() or y()</code> returns x() if it was true, y() otherwise.

=== Ternary and coalescence statements ===
We can exploit the and/or operators behavior:
* '''Coalescence:''' <code>x or y</code>. It returns x if x is neither nil nor false, y otherwise.
:In other words <code>result = x or y</code> is equivalent to: <code>if x then result = x else result = y end</code>.
* '''Ternary:''' <code>condition and x or y</code> (as long as x is not nil or false). It returns x if condition was true, y if it was false.
:Indeed the expression becomes: <code>(condition and x) or y</code>. If condition is true the '''and''' operator returns x, and since x is true, y is not evaluated and '''or''' returns x.
:In other words <code>result = condition and x or y</code> is equivalent to: <code>if condition then result = x else result = y end</code>.

=== Method calls: dot versus colon ===
'''The colon (<code>:</code>) operator implicitly passes the caller as the first argument.''' <br/>
As opposed to the dot (<code>.</code>) operator that performs a regular call without implicitly passing anything. The colon operator behavior is obviously designed for instance methods.<br/>
<div class="civ5-example"><syntaxhighlight lang="lua">
local myTable = { msg = "Hello world" }
myTable.Print = function(self) print(self.msg)

-- Three different ways to call this method
myTable:Print()
myTable.Print(myTable)

local func = myTable.Print
func(myTable)
</syntaxhighlight></div>

Note: in the civ5 API you will often encounter static methods that do not take any argument but that are called through a dot. This results from a misunderstanding of Lua from one of the Firaxis developers. While this work when the method does not take any argument (the one provided by the colon operator will be ignored), this is slower and can be considered as an error without any consequence.

=== Arrays versus tables ===
'''In Lua, an array is a table whose keys are integers.'''

Since this is a common programming pattern, a number of things are designed for arrays:
* <code>{"abc", "def", "ghi"}</code> starts at index 1, up to index 3. Arrays typically start at 1.
* <code>table.insert({}, "abc")</code> will transform the provided empty table to <code>{"abc"}</code>
* <code>table.insert({"abc", "def"}, "ghi")</code> will transform the provided table to <code>{"abc", "def", "ghi"}</code>
* <code>table.insert({"abc", "ghi"}, 2, "def")</code> will transform the provided table to <code>{"abc", "def", "ghi"}</code>
* <code>table.remove({"abc", "def", "ghi"}, 2)</code> will transform the provided table to <code>{"abc", ""ghi"}</code>
* <code>#{"abc", "def", "ghi"}</code> returns 3, the biggest integer key.

=== Ipairs versus pairs ===
You could say that '''pairs''' is for table and '''ipairs''' for arrays.
* '''Pairs''' enumerate all the key/value pairs in an unordered matter.
* '''Ipairs''' only enumerates the key/value pairs for consecutive integer keys, in an ascending order, starting from 1 up to the largest key. If at some point a key is missing, the enumeration stops.
::It does not matter whether the table was crated with table.insert or directly by inserting the values through, for example <code>table[i] = value</code>.

<div class="civ5-example"><syntaxhighlight lang="lua">
-- Produces: { 1 => "one", 2 => "two", 4 => "four", "name" => "John", "age" => 25 }
local t = { "one", "two", name = "John", age = 25, [4] = "four" }

-- Will print (for example, the order is undetermined): "name", 2, 4, "age", 1
for k in pairs(t) do print(k) end

-- Will print 1, 2
for k in ipairs(t) do print(k) end

-- Both ipairs and pairs return a key and a value, so you could also use:
for k, v in pairs(t) do print(k, v) end
</syntaxhighlight></div>

=== Semicolons and line breaks ===
'''Statements need to be separated either by a line break or a semicolon.'''
* You can use both a semicolon and a line break but then the semicolon is redundant and not required, although it does not cause any problem.
* Line breaks can also be freely added about everywhere and behave as whitespaces most of the time (you can add them after most keywords for example, so you can keep if...then...end structures on one line or split them across multiple lines).

=== Locals, globals and includes ===
* The include statement allows you to include a lua file into another one (see [[Specificities of the Lua implementation in Civ5]]). When you do so, the globals defined in the included file are imported in the parent file. However the local variables are only visible from within the file that declared them.
* Another specificities of locals: they're only visible after the point they have been declared in the file, while globals are always visible. An example is worth thousand of words.
<div class="civ5-example"><syntaxhighlight lang="lua">
function Func1()
print(someLocal or "nil")
print(someGlobal or "nil")
end

local someLocal = "foo"
function Func2()
print(someLocal or "nil")
print(someGlobal or "nil")
end

someGlobal = "global"
someLocal = "local"
Func1() -- prints "nil", then "global": someLocal is assigned but not visible from Func1
Func2() -- prints "local", then "global": someLocal is assigned and visible from Func2
</syntaxhighlight></div>
* Performances-wise, Lua first searches a variable name in the current scope, then in the parent scope, etcetera until it reaches the highest scope, and finally it searches the global scope. So the deeper a local is declared, the faster it is accessed. On the contrary, globals are the slowest to retrieve.

= Semi-advanced topics =
=== Closures ===
'''Closures are functions that embed variables that are persisted across calls.'''<br/>
This is typically achieved through a "parent" function that declares a local "closed" variable and returns another child "closure" function using this local. The "closed" variable is then unreachable for anyone but the "closure". And since it the "closed" variable is not in the "closure"'s scope, it is not reinitialized on every call of "closure".
<div class="civ5-example"><syntaxhighlight lang="lua">
function GiveMeAFunc() -- the parent function
local x = 0 -- the closed variable
return function() -- the closure function embedding "closed"
x = x + 1
return closure
end
end

local func = GiveMeAFunc()
print(func()) -- Prints 1
print(func()) -- Prints 2
print(func()) -- Prints 3
</syntaxhighlight></div>

=== Iterators ===
'''Iterators are functions for use in <code>for...in</code> loops.'''<br/>
Let's consider the following code: <code>for var1, var2, var3 in iterable() do</code>.
* iterable has the following signature: <code>iterator, state, var1 iterable()</code>. It returns a function, a state, and the initial value of var1.
* iterator has the following signature: <code>var1, var2, var3 iterator(state, var1)</code>. It takes the state and the last value of var1 and returns var1, var2 and var3.
* The loop stops when var1 is nil.
* The for...in loop is equivalent to:
<div class="civ5-example"><syntaxhighlight lang="lua">
local iterator, state, var1, var2, var3
iterator, state, var1 = iterable()
do
var1, var2, var3 = iterator(state, var1)
if var1 == nil then break end

-- Inserts here the user code defined in the for..in loop
end
</syntaxhighlight></div>
* Note that we used var1, var2 and var3 for the example but there is no restriction to the number of variables. You could have one or hundred.

Let's write the "ipairs" function.
<div class="civ5-example"><syntaxhighlight lang="lua">
local function ipairs(table) -- The iterable function
local iterator = function(table, key) -- The iterator function
key = key + 1
return key, table[key]
end
return iterator, table, 0
end
</syntaxhighlight></div>

The same with closures: it's easier.
<div class="civ5-example"><syntaxhighlight lang="lua">
local function ipairs(table) -- The iterable function
local key = 0 -- Both "table" and "key" are closed variables.
local iterator = function() -- The iterator function, a closure: it ignores the arguments provided to it
key = key + 1
return key, table[key]
end
return iterator -- No need to return anything since we do not require any argument.
end
</syntaxhighlight></div>

=== No integer type ===
'''Lua offers no support for integers and only has a 64-bits floating point number type.'''<br/>
Actually, this is only troublesome for a few algorithms that use very large integers (>2^52) or require fast integer arithmetics. But many developers misunderstand floating points and believe the problem is broader than it is. For example, does the following assertion surprise you at least a bit: "any integer smaller than 2^52 can be accurately represented with a 64-bits floating point without any error"? If it did, you suffer from some misconceptions and you should better read carefully what's coming.

Many developers are confusing rounding errors with representation errors.
* '''Rounding errors''' actually only happen if you need a very high number of digits to represent a number. For example if you are adding a very large number with a small number. Rounding errors are very rarely encountered in day to day to applications. Actually most developers work their whole career without ever encountering them.
* '''Representation errors''' are the real problem: 0.1 is expressed in a decimal basis, but it has no finite representation in binary: it requires an infinite number of binary digits. This means that if you write 0.1 in your code it will be translated to a binary number close enough from 0.1 bot not exactly equal to it. So if you sum ten times 0.1, you sill sum ten times something close from 0.1 and the result will not be 1.

'''So the real problem for most developers only lies in the decimal-binary conversion that arises when you manipulate numbers in your code that do not have a finite representation in binary. As long as you do not use such numbers, there will be no problem. And here are the good news: integers do not suffer from any representation problem!''' Indeed, any integer can be represented with a finite number of binary digits. This is why the absence of an integer type typically does not cause problems, minus the performance penalty.

Here are a few examples to illustrate that point.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- This loop works as intended: no representation error and the upper bound is far below 2^52.
local sum = 0
for i = 0, 10000000000, 1 do sum = sum + 1 end
assert(sum == 10000000001)

-- This loop works as intended: 1/16 is a floating-point with an exact representation in binary
local sum = 0
for i = 0, 1, 1/16 do sum = sum + 1 end
assert(sum == 17/16)

-- This loop does NOT work as intended: 0.1 does not have an exact representation in binary.
-- It's the same for Lua, C and almost every programming language.
local sum = 0
for i = 0, 1, 0.1 do sum = sum + 1 end
assert(sum == 1.1) -- throws an error
</syntaxhighlight></div>

=== Errors management ===
Lua offers a error handling mechanism similar to exception handling but unfortunately not very convenient.
* Errors are thrown using the '''error''' function. It takes a string and it immediately aborts Lua execution until the game handles the error and prints it in Firetuner (when enabled).
* Errors are caught before that point using '''pcall''' or '''xpcall''', in order to let you resume execution by managing the error. "pcall" stands for "protected call".

Here are the syntaxes for pcall and xpcall:
* <code>bool, ... pcall(func, ...)</code>
** The function is called with the specified arguments.
** Pcall returns either true followed by the values returned by func, or false followed by the error text.
* <code>bool, ... xpcall(func, errorHandler)</code>:
** The function is called without any argument. If an error occurs the specified errorHandler is invoked with the error text as the only argument.
** Xpcall returns either true followed by the values returned by func, or false followed by the returned values from errorHandler.

Examples to invoke "someFunc" with "someArg" as the only argument. In both examples we want to display the error on the console, or the result if it was a success. A complete errors management example with a reporting mechanism for the end-user is presented in [[Debugging (Civ5)]].
<div class="civ5-example"><syntaxhighlight lang="lua">
-- pcall
local status, result = pcall(someFunc, someArg)
if not status then
print("error was: "..(result or "?"))
else
print("success: "..result)
end

-- xpcall
local status, result = xpcall(
function() someFunc(someArg) end,
function(err) print("error was: "..(result or "?")) end)

if status then
print("success: "..result)
end
</syntaxhighlight></div>

= Advanced topics=
=== Metatables and metamethods ===
* Every value in Lua, from a number to a userdata, has a metatable.
** Many objects can share the same metatable.
** Tables and userdata each have their own metatables by default. Numbers, bools, nils and strings all share the same metatable.
* A metatable may contain a few metamethods and index tables.
** Metamethods are methods stored under special fields names. They implement operators overloads.
** Index tables behave as "base classes": if a field name is not defined on an table, then Lua looks for this field on the index.
** In a way, metatables are analogous to virtual tables in object languages, but they are not just for methods, but also for fields and operators.
* You can get an object's metatable through '''getmetatable''' and assign it with '''setmetatable'''.
* See also the [http://www.lua.org/manual/5.1/manual.html#2.8 official metatables reference]

One example.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Define two tables A and B, and set "meta" their metatable
local a, b, meta = {}, {}, {}
setmetatable(a, meta)
setmetatable(b, meta)

-- Define an __index table on the metatable. It contains one key/value pair.
meta.__index = { "hello world" };

-- Print "hello world" twice
print(a[1])
print(b[1])

-- Now make our tables read-only
meta.__newindex = function(table, key, value) error("this table is read-only!") end
a[1] = "foo" -- throws an error
</syntaxhighlight></div>

Here are the most important fields a metatable can have:
* '''__index''': used when you read a member from an object. On tables, Lua will first search for a regular field on the table itself (not its index) before it looks at the index. The index may be a table or a function: <code>value func(object, key)</code>
* '''__newindex''': used when you assign a value to an object's member. On tables, newindex is only called if the table itself (not its index) does not already contains the specified key. May be a table or a function: <code>func(object, key, value)</code>
* '''__call''': used when you invoke the object as a function. Must be a function: <code>func(object, <args>)</code>
* '''__tostring''': used when you invoke the '''tostring''' function with this object in argument. Must be a function: <code>string func(object)</code>

Besides of that it can have fields for binary operators. When each of the two operands defined overloads, the left one is used. They must be functions: <code>result func(object)</code>
* '''__add''': addition
* '''__sub''': subtraction
* '''__mul''': multiplication
* '''__div''': division
* '''__mod''': module
* '''__pow''': exponentiation
* '''__eq''': equality comparison. Prior to calling this overload, Lua checks that types are equal.
* '''__neq''': inequality comparison. Prior to calling this overload, Lua checks whether types are different.
* '''__lt''': lesser than comparison. (b >= a) is considered equivalent to (a < b)
* '''__le''': lesser than or equal to comparison. (b > a) is considered equivalent to (a <= b). If __le is not defined, lua will use __lt, considering that (a <= b) is equivalent to not (b < a).
* '''__concat''': concatenation

Finally it can have the following fields for unary operators. They must be functions: <code>result func(object)</code>
* '''__unm''': unary minus
* '''__len''': the sharp operator (#). Can only be used on userdata ; on tables the default operator will always be called.

=== Implementing inheritance ===
The most common use of metatables is to mimic the behavior of object languages' types hierarchy. Here is how to do it:
<div class="civ5-example"><syntaxhighlight lang="lua">
local Dog = {}
function Dog:specie()
return "dog"
end
function Dog:race()
return "unknown"
end
function Dog:description()
return self.specie().." - "..self.race()
end
function Dog:new()
local instance = {}
setmetatable(instance, { __index = self})
return instance
end

local Pitbull = dog:new()
function Pitbull:race()
return "pitbull"
end

pitbull = Pitbull:new()
print(pitbull:description()) -- prints "dog - pitbull"
</syntaxhighlight></div>

This implementation is very elegant: the "new" method both creates a new instance and subtypes the creator, since "pitbull"'s index is now "Pitbull". However, should you define an operator overload on Dog's metatable, Pitbull would not inherit it. This is the limit of inheritance in Lua: operator overloads must be defined on the metatable itself, they cannot be defined on the metatable's index. As a result, there is no way to inherit those overloads while subtyping.

=== Coroutines ===
Coroutines provide a way to slice a function in many shorter calls and optionally return intermediate results. On each call, the function execution is resumed to the point where it stopped previously, with all locals being properly restored with the value they had at this time.
* Coroutines are often compared to threads. Indeed, when there are more threads than CPU cores, the operating system slices threads' execution into many little time frames and sequentially runs them in order to achieve multitasking.
* However while coroutines allows you to implement cooperative multitasking (the coroutines need to explicitly give the hand back), they cannot be used for preemptive multitasking or to use more than one system thread or CPU Core.
* As a result, coroutines are rather used as syntactic sugar (mostly to write iterators), or as a way to split a long function execution across many frames (through Context.{{Func5|UIElement|SetUpdate}}).

The following methods are mainly used:
* <code>'''coroutine''' coroutine.create('''function''' func)</code> creates a coroutine for the specified function. The function signature can be anything.
* <code>'''bool''', '''...''' coroutine.resume('''coroutine''' co, '''...''')</code> resumes the coroutine with the specified arguments. Then it returns either '''true''' followed by the returned results (either though '''return''' or '''yield'''), or '''false''' followed by an error message.
* <code>'''string''' coroutine.status('''coroutine''' co)</code> returns either "running" (the active coroutine), "normal" (a parent of the active coroutine), "suspended" (not started or waiting to be resumed) or "dead" (finished or threw an error).
* <code>coroutine.yield('''...''')</code> suspends the execution of the running coroutine and gives the hand back to the caller of coroutine.resume. The arguments will be returned by coroutine.resume.

Here is a base example:
<div class="civ5-example"><syntaxhighlight lang="lua">
function neighborsCoroutine(plot)
for i = 0, 5 do
coroutine.yield(Map.PlotDirection(plot:GetX(), plot:GetY(), i))
end
end

local co = coroutine.create(neighborsCoroutine)
while coroutine.status(co) == "suspended"
local _, neighbor = co.resume(plot)
-- Do something with plot
end
</syntaxhighlight></div>

Here is how to transform it into an iterator:
<div class="civ5-example"><syntaxhighlight lang="lua">
function neighbors(plot)
local co = coroutine.create(neighbors)
return function()
if coroutine.status(co) ~= "suspended" then return end
return select(2, coroutine.resume(plot))
end
end

for neighbor in neighbors(plot) do
-- Do something with plot
end
</syntaxhighlight></div>

Here is an example that spreads a long function call across many frames:
<div class="civ5-example"><syntaxhighlight lang="lua">
function SpreadAcrossFrames(longFunctionCall, ...)
local co = coroutine.create(longFunctionCall)
ContextPtr.SetUpdate(function()
coroutine.resume(unpack(arg))
if coroutine.status(co) ~= "suspended" then
ContextPtr:ClearUpdate()
end
end)
end

SpreadAcrossFrames(SomeLongFunction, arg1, arg2)
</syntaxhighlight></div>

=== Design philosophy for Lua ===
Do not use a butter knife as you would use a chainsaw (the opposite is even more true and usually ends up badly). When designing your code, remember that:
* Lua is not an object language. While you can use objects and inheritance in some extent, you do not have to and there may be better alternatives sometimes.
* Lua is not a functional language. While you can use lambdas and similar concepts, you do not have to and there may be better alternatives sometimes.
* Lua is a multi-paradigm and dynamic language, take advantage of those.
* Lua is very suited for prototyping and small programs, and this is perfect for mods. Try to adjust your mindset: you're not writing a framework that a whole team will still use and maintain in twenty years.

[[Category:Civ5 API]]
[[Category:Civ5 Tutorials]]

Lua introduction for confirmed developers

2012-09-30T13:47:21Z

DonQuich:

''This page is a part of the [[Lua and UI Reference (Civ5)|Lua and UI Reference]].''

= About Lua =
===Lua, not LUA===
This is a Portuguese word meaning "moon", not an acronym.

===Presentation===
Lua is an interpreted, dynamically typed, multi-paradigm language. It was designed in 1993 with the following objectives in mind:
* Extensible semantics. A small set of features allows the support of multiple paradigms, from functional programming to object programming. For example, while inheritance is not natively supported, it can be easily set up through metatables. The same features allow events in civ5 to behave both as functions and objects with Add and Remove methods.
* Highly portable. The con is a lightweight and somewhat lacking API.
* Easy to embed and to interface from other languages.
* Well suited for data description (''à la'' JSON).
* A beginners-friendly syntax.

===Performances===
As usual with interpreted and dynamically typed languages (hereby abusively named "scripting languages"), expect a 10 to 100 order of magnitude in performances decrease when compared to compiled and statically typed languages like C, C++ or C#. While it is possible for scripting languages to drastically improve the performances through more or less sophisticated means (expression trees/opcodes caching, JIT compiler, type inference to perform static resolutions), no such solution has been used in Civ5 (aside, probably, of the caching). And while an external JIT library exists, it causes compatibility problems with most mods using Lua.

That being said, Lua is still pretty good for a scripting language, better than the Python implementation from Civ4 for example. And all in all, it is fast enough for most of what modders want to achieve without the need to compromise code elegance, readability and maintainability for performances. So keep in mind that "premature optimization is the root of all evil" (Donald Knuth).

=Syntax cheatsheet=
=== Basics ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Literals
local x = 5
local x = 5.0
local x = nil -- A nil value is the same as an undefined value
local x = true
local x = false

-- Strings (single and double quotes can be used indifferently, there is no difference)
local x = "five"
local x = 'five'
local x = "five\n" -- Escape characters with "\".
local x = [[Five is a number.
Did you know?]] -- Multi-line string: equivalent to "Five is number.\nDid you know?"

-- Globals versus locals
x = 5 -- For globals, assigning is declaring.
local x = 5
</syntaxhighlight></div>

=== Operators ===
<div class="civ5-example"><syntaxhighlight lang="lua">
local x = a or b
local x = a and b

local x = "hello ".."world" .. "!" -- concatenation: two dots
local x = 4..5 -- Result is "45". On concatenation, conversions occur.

local x = (a + b - d) * f ^ g % h -- ^ is exponentiation, % is modulo
local x = "4" + "5" -- Result is 9. On arithmetic operations, conversions occur.

local x = a == b -- equality -- True only if a and b have the same values and types.
local x = a ~= b -- inequality

local x = ((a <= b) == not (a > b)) == ((a >= b) == not (a < b))
local x = "abc" < "def" -- Byte-wise comparison, not Unicode-compliant. Use Locale's methods instead.

local x = #"abc" -- Returns 3, the number of bytes in the string (3 characters, 1 byte each).
local x = #"您好世界" -- Returns 8, the number of bytes in the string (4 characters, 2 bytes each).
local x = #SomeTable -- Returns the biggest integer key in the table, or nil if there is no integer key.

-- No increment operator (++ --), no binary-assign operator (+= *=), no ternary operator (? :), no coalescence operator (??)
</syntaxhighlight></div>

=== Tables and multiple assignments ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Table declaration
SomeTable = {}

SomeArray = { "abc", "def" }
-- 1 => "abc", 2 => "def"

SomeComplexTable = { name = "John", surname = "Doe", age = 25, 43, [7] = 8 }
-- "name" => "John", "surname" => "Doe", "age" => 25, 1 => 43, 7 => 8.

-- Member access (all equivalent)
SomeTable.SomeMember = 5
SomeTable["SomeMember"] = 5

-- Multiple assignment
-- Both statements are equivalent since SomeArray contains "abc" and "def".
local x, y = "abc", "def"
local x, y = unpack(SomeArray)
</syntaxhighlight></div>

=== Functions ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Functions declarations (all equivalent)
function HelloWorld(a, b) print("Hello world") end
HelloWorld = function(a, b) print("Hello world") end
-- Functions are first-class objects and can be assigned like any other value!

-- Methods declarations (all equivalent)
SomeTable.HelloWorld(a, b) print("Hello world") end
SomeTable.HelloWorld = function(a, b) print("Hello world") end

-- Instanced methods declarations (all equivalent)
SomeTable.HelloWorldInstanced(self, a, b) print(self.SomeMember) end
SomeTable:HelloWorldInstanced(a, b) print(self.SomeMember) end

-- Functions and methods calls
HelloWorld(a) -- b will be nil in the function
HelloWorld(a, b)
SomeTable.HelloWorld(a, b)

-- Instanced methods calls (all equivalent)
SomeTable:HelloWorldInstanced(a, b)
SomeTable.HelloWorldInstanced(SomeTable, a, b)

-- Multiple return values
function func(a, b) return a, b end
local x, y, z = func(5, 6) -- Assigns 5 to x and 6 to y, z will be nil

-- Variable arguments
function SomeFunc(a, b, ...)
print(a)
print(b)
for i, v in ipairs(arg) do -- arg is a keyword for a table containing the variable arguments
print(v)
end
end
SomeFunc(1, 2, 3, 4, 5) -- prints 1, 2, 3, 4, 5
SomeFunc(1, 2) -- prints 1, 2
</syntaxhighlight></div>

=== Control flow ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- If
if name == "Wu Zetian" then
print("Hello China")
elseif name == "Napoleon" then -- "elseif", not "else if". Beware C developers!
print("Hello France")
else -- no "then" after "else"!
print("Hello unknown")
end

-- For loop (with counter)
for i = 1, 8 do print(i) end -- Prints 1, 2, 3, 4, 5, 6, 7, 8
for i = 1, 8, 2 do print(i) end -- Prints 1, 3, 5, 7

-- For loop (with iterator)
for playerID, pPlayer in pairs(Players) do -- Prints 1 Wu Zetian, 2 Napoleon, ...
print(playerID, pPlayer:GetName())
end
for plot in Plots() do -- Prints 0 0, 0 1, 0 2, ...
print(plot:GetX(), plot:GetY())
end

-- While (i will be 5 in the end)
while i < 5 do
i = i + 1
end

-- Repeat until (i will be 5 in the end)
repeat
i = i + 1
until i == 5

-- Infinite loops
-- Lua supports "break" for all loops but not "continue" instruction does not exist!
do
i = i + 1
if i > 5 then break end
end

</syntaxhighlight></div>

= Basics =
=== Type system ===
You can get a variable's type by using the '''type''' function. It takes any value and returns a string. Here are the possible results:
* The following are [http://en.wikipedia.org/wiki/Value_type value types].
** '''nil''': Lua makes do distinction between an undefined variable and a variable with a nil value. Assigning nil to a variable or table member is equivalent to undefining it.
** '''number''': a 64 bits floating-point number. Lua has no support for integers and only use floating-points. See also [[#No integer type]].
** '''boolean''': true or false obviously.
* The following are [http://en.wikipedia.org/wiki/Reference_type reference types]
** '''table''': any table.
** '''string''': your usual string of characters. In Lua all strings are [http://en.wikipedia.org/wiki/String_interning interned] and immutable.
** '''userdata''': objects defined in C for use in Lua. They may not be enumerated through pairs and are often read-only.
** '''function''': remember that functions are first-class objects in Lua.
** '''thread''': coroutines actually. Lua does not support threads.

Note: Many objects in the Civ5 API are actually regular tables which either have userdata methods as members, or a userdata metatable index.

=== Implicit conversions ===
* Whenever you concatenate two values (and possibly when you invoke a standard function that takes a string), an automatic conversion to string occurs, as if you had used the '''tostring''' function. The expression <code>4..5</code> returns "45".
* Whenever you perform an arithmetic operation, the operands are both converted to numbers, as if you had used the '''tonumber''' function. The expression <code>"4" + "5"</code> returns 9.

=== Equality comparisons ===
'''Two values are equal only if their types are the same.'''<br/>
This is far stricter than most dynamic languages for example and somehow stricter than C.
* 4 is not equal to "4". (number type and string type). In PHP they would be equal.
* 0 is not equal to false (number type and bool type). In C they would be equal (false is typically defined as a number).
* 0 is not equal to nil. (number type and nil type). In C they would be equal (nil is typically defined as a number).

'''Numbers and booleans are compared by value. Everything else by reference. Strings are interned.'''
* Numbers and booleans are compared by value.
* Tables, userdata, functions and threads are compared by reference.
* Strings are [http://en.wikipedia.org/wiki/String_interning interned], which means that two identical strings are always the same reference. So comparisons are made by reference but are equivalent to by-value comparisons.
* All nil values are always equal.
<div class="civ5-example"><syntaxhighlight lang="lua">
local a = 5
assert(a == 5)
-- true, comparison by value

local a = {}
assert(a == {})
-- false, comparison by reference: those two tables are distinct objects.

local a = "Hello ".."world"
assert(a == "Hello world")
-- true, both strings are the same reference thanks to string interning.
</syntaxhighlight></div>

=== String interning ===
'''All strings are interned in Lua, without any exception.'''<br/>
[http://en.wikipedia.org/wiki/String_interning String interning] is a process through which all identical strings ends up being the same reference to a unique string instance. Typically, the interpreter maintains a string dictionary in the memory and whenever a string needs to be built (from a literal, from a concatenation, from a native call, etc), it first searches in this dictionary whether there is already a reference for this sequence of characters and uses it when it exists. This process usually reduces memory consumptions and speeds up equality comparisons, but it makes other operations slower because of the lookup cost. Some platforms such as Dotnet or Java automatically interns literals only. Lua, on the other hand, systematically interns every string.

=== Boolean logic ===
'''Anything that is neither false nor nil is evaluated to true.'''<br/>
This is pretty simple. Especially, an empty string or the zero number are evaluated to true.
<div class="civ5-example"><syntaxhighlight lang="lua">
if 0 then print("hello world") end -- prints hello world
</syntaxhighlight></div>

Now regarding the and/or operators, two rules to remember:
* '''The right operand is only evaluated when needed.'''
** <code>false and x()</code> does not call x() since the result will be false anyway.
** <code>true or x()</code> does not call x() since the result will be true anyway.
* '''The result is the last operand to have been evaluated.'''
** <code>x() and y()</code> returns x() if it was false, y() otherwise.
** <code>x() or y()</code> returns x() if it was true, y() otherwise.

=== Ternary and coalescence statements ===
We can exploit the and/or operators behavior:
* '''Coalescence:''' <code>x or y</code>. It returns x if x is neither nil nor false, y otherwise.
:In other words <code>result = x or y</code> is equivalent to: <code>if x then result = x else result = y end</code>.
* '''Ternary:''' <code>condition and x or y</code> (as long as x is not nil or false). It returns x if condition was true, y if it was false.
:Indeed the expression becomes: <code>(condition and x) or y</code>. If condition is true the '''and''' operator returns x, and since x is true, y is not evaluated and '''or''' returns x.
:In other words <code>result = condition and x or y</code> is equivalent to: <code>if condition then result = x else result = y end</code>.

=== Method calls: dot versus colon ===
'''The colon (<code>:</code>) operator implicitly passes the caller as the first argument.''' <br/>
As opposed to the dot (<code>.</code>) operator that performs a regular call without implicitly passing anything. The colon operator behavior is obviously designed for instance methods.<br/>
<div class="civ5-example"><syntaxhighlight lang="lua">
local myTable = { msg = "Hello world" }
myTable.Print = function(self) print(self.msg)

-- Three different ways to call this method
myTable:Print()
myTable.Print(myTable)

local func = myTable.Print
func(myTable)
</syntaxhighlight></div>

Note: in the civ5 API you will often encounter static methods that do not take any argument but that are called through a dot. This results from a misunderstanding of Lua from one of the Firaxis developers. While this work when the method does not take any argument (the one provided by the colon operator will be ignored), this is slower and can be considered as an error without any consequence.

=== Arrays versus tables ===
'''In Lua, an array is a table whose keys are integers.'''

Since this is a common programming pattern, a number of things are designed for arrays:
* <code>{"abc", "def", "ghi"}</code> starts at index 1, up to index 3. Arrays typically start at 1.
* <code>table.insert({}, "abc")</code> will transform the provided empty table to <code>{"abc"}</code>
* <code>table.insert({"abc", "def"}, "ghi")</code> will transform the provided table to <code>{"abc", "def", "ghi"}</code>
* <code>table.insert({"abc", "ghi"}, 2, "def")</code> will transform the provided table to <code>{"abc", "def", "ghi"}</code>
* <code>table.remove({"abc", "def", "ghi"}, 2)</code> will transform the provided table to <code>{"abc", ""ghi"}</code>
* <code>#{"abc", "def", "ghi"}</code> returns 3, the biggest integer key.

=== Ipairs versus pairs ===
You could say that '''pairs''' is for table and '''ipairs''' for arrays.
* '''Pairs''' enumerate all the key/value pairs in an unordered matter.
* '''Ipairs''' only enumerates the key/value pairs for consecutive integer keys, in an ascending order, starting from 1 up to the largest key. If at some point a key is missing, the enumeration stops.
::It does not matter whether the table was crated with table.insert or directly by inserting the values through, for example <code>table[i] = value</code>.

<div class="civ5-example"><syntaxhighlight lang="lua">
-- Produces: { 1 => "one", 2 => "two", 4 => "four", "name" => "John", "age" => 25 }
local t = { "one", "two", name = "John", age = 25, [4] = "four" }

-- Will print (for example, the order is undetermined): "name", 2, 4, "age", 1
for k in pairs(t) do print(k) end

-- Will print 1, 2
for k in ipairs(t) do print(k) end

-- Both ipairs and pairs return a key and a value, so you could also use:
for k, v in pairs(t) do print(k, v) end
</syntaxhighlight></div>

=== Semicolons and line breaks ===
'''Statements need to be separated either by a line break or a semicolon.'''
* You can use both a semicolon and a line break but then the semicolon is redundant and not required, although it does not cause any problem.
* Line breaks can also be freely added about everywhere and behave as whitespaces most of the time (you can add them after most keywords for example, so you can keep if...then...end structures on one line or split them across multiple lines).

=== Locals, globals and includes ===
* The include statement allows you to include a lua file into another one (see [[Specificities of the Lua implementation in Civ5]]). When you do so, the globals defined in the included file are imported in the parent file. However the local variables are only visible from within the file that declared them.
* Another specificities of locals: they're only visible after the point they have been declared in the file, while globals are always visible. An example is worth thousand of words.
<div class="civ5-example"><syntaxhighlight lang="lua">
function Func1()
print(someLocal or "nil")
print(someGlobal or "nil")
end

local someLocal = "foo"
function Func2()
print(someLocal or "nil")
print(someGlobal or "nil")
end

someGlobal = "global"
someLocal = "local"
Func1() -- prints "nil", then "global": someLocal is assigned but not visible from Func1
Func2() -- prints "local", then "global": someLocal is assigned and visible from Func2
</syntaxhighlight></div>
* Performances-wise, Lua first searches a variable name in the current scope, then in the parent scope, etcetera until it reaches the highest scope, and finally it searches the global scope. So the deeper a local is declared, the faster it is accessed. On the contrary, globals are the slowest to retrieve.

= Semi-advanced topics =
=== Closures ===
'''Closures are functions that embed variables that are persisted across calls.'''<br/>
This is typically achieved through a "parent" function that declares a local "closed" variable and returns another child "closure" function using this local. The "closed" variable is then unreachable for anyone but the "closure". And since it the "closed" variable is not in the "closure"'s scope, it is not reinitialized on every call of "closure".
<div class="civ5-example"><syntaxhighlight lang="lua">
function GiveMeAFunc() -- the parent function
local x = 0 -- the closed variable
return function() -- the closure function embedding "closed"
x = x + 1
return closure
end
end

local func = GiveMeAFunc()
print(func()) -- Prints 1
print(func()) -- Prints 2
print(func()) -- Prints 3
</syntaxhighlight></div>

=== Iterators ===
'''Iterators are functions for use in <code>for...in</code> loops.'''<br/>
Let's consider the following code: <code>for var1, var2, var3 in iterable() do</code>.
* iterable has the following signature: <code>iterator, state, var1 iterable()</code>. It returns a function, a state, and the initial value of var1.
* iterator has the following signature: <code>var1, var2, var3 iterator(state, var1)</code>. It takes the state and the last value of var1 and returns var1, var2 and var3.
* The loop stops when var1 is nil.
* The for...in loop is equivalent to:
<div class="civ5-example"><syntaxhighlight lang="lua">
local iterator, state, var1, var2, var3
iterator, state, var1 = iterable()
do
var1, var2, var3 = iterator(state, var1)
if var1 == nil then break end

-- Inserts here the user code defined in the for..in loop
end
</syntaxhighlight></div>
* Note that we used var1, var2 and var3 for the example but there is no restriction to the number of variables. You could have one or hundred.

Let's write the "ipairs" function.
<div class="civ5-example"><syntaxhighlight lang="lua">
local function ipairs(table) -- The iterable function
local iterator = function(table, key) -- The iterator function
key = key + 1
return key, table[key]
end
return iterator, table, 0
end
</syntaxhighlight></div>

The same with closures: it's easier.
<div class="civ5-example"><syntaxhighlight lang="lua">
local function ipairs(table) -- The iterable function
local key = 0 -- Both "table" and "key" are closed variables.
local iterator = function() -- The iterator function, a closure: it ignores the arguments provided to it
key = key + 1
return key, table[key]
end
return iterator -- No need to return anything since we do not require any argument.
end
</syntaxhighlight></div>

=== No integer type ===
'''Lua offers no support for integers and only has a 64-bits floating point number type.'''<br/>
Actually, this is only troublesome for a few algorithms that use very large integers (>2^52) or require fast integer arithmetics. But many developers misunderstand floating points and believe the problem is broader than it is. For example, does the following assertion surprise you at least a bit: "any integer smaller than 2^52 can be accurately represented with a 64-bits floating point without any error"? If it did, you suffer from some misconceptions and you should better read carefully what's coming.

Many developers are confusing rounding errors with representation errors.
* '''Rounding errors''' actually only happen if you need a very high number of digits to represent a number. For example if you are adding a very large number with a small number. Rounding errors are very rarely encountered in day to day to applications. Actually most developers work their whole career without ever encountering them.
* '''Representation errors''' are the real problem: 0.1 is expressed in a decimal basis, but it has no finite representation in binary: it requires an infinite number of binary digits. This means that if you write 0.1 in your code it will be translated to a binary number close enough from 0.1 bot not exactly equal to it. So if you sum ten times 0.1, you sill sum ten times something close from 0.1 and the result will not be 1.

'''So the real problem for most developers only lies in the decimal-binary conversion that arises when you manipulate numbers in your code that do not have a finite representation in binary. As long as you do not use such numbers, there will be no problem. And here are the good news: integers do not suffer from any representation problem!''' Indeed, any integer can be represented with a finite number of binary digits. This is why the absence of an integer type typically does not cause problems, minus the performance penalty.

Here are a few examples to illustrate that point.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- This loop works as intended: no representation error and the upper bound is far below 2^52.
local sum = 0
for i = 0, 10000000000, 1 do sum = sum + 1 end
assert(sum == 10000000001)

-- This loop works as intended: 1/16 is a floating-point with an exact representation in binary
local sum = 0
for i = 0, 1, 1/16 do sum = sum + 1 end
assert(sum == 17/16)

-- This loop does NOT work as intended: 0.1 does not have an exact representation in binary.
-- It's the same for Lua, C and almost every programming language.
local sum = 0
for i = 0, 1, 0.1 do sum = sum + 1 end
assert(sum == 1.1) -- throws an error
</syntaxhighlight></div>

=== Errors management ===
Lua offers a error handling mechanism similar to exception handling but unfortunately not very convenient.
* Errors are thrown using the '''error''' function. It takes a string and it immediately aborts Lua execution until the game handles the error and prints it in Firetuner (when enabled).
* Errors are caught before that point using '''pcall''' or '''xpcall''', in order to let you resume execution by managing the error. "pcall" stands for "protected call".

Here are the syntaxes for pcall and xpcall:
* <code>bool, ... pcall(func, ...)</code>
** The function is called with the specified arguments.
** Pcall returns either true followed by the values returned by func, or false followed by the error text.
* <code>bool, ... xpcall(func, errorHandler)</code>:
** The function is called without any argument. If an error occurs the specified errorHandler is invoked with the error text as the only argument.
** Xpcall returns either true followed by the values returned by func, or false followed by the returned values from errorHandler.

Examples to invoke "someFunc" with "someArg" as the only argument. In both examples we want to display the error on the console, or the result if it was a success. A complete errors management example with a reporting mechanism for the end-user is presented in [[Debugging (Civ5)]].
<div class="civ5-example"><syntaxhighlight lang="lua">
-- pcall
local status, result = pcall(someFunc, someArg)
if not status then
print("error was: "..(result or "?"))
else
print("success: "..result)
end

-- xpcall
local status, result = xpcall(
function() someFunc(someArg) end,
function(err) print("error was: "..(result or "?")) end)

if status then
print("success: "..result)
end
</syntaxhighlight></div>

= Advanced topics=
=== Metatables and metamethods ===
* Every value in Lua, from a number to a userdata, has a metatable.
** Many objects can share the same metatable.
** Tables and userdata each have their own metatables by default. Numbers, bools, nils and strings all share the same metatable.
* A metatable may contain a few metamethods and index tables.
** Metamethods are methods stored under special fields names. They implement operators overloads.
** Index tables behave as "base classes": if a field name is not defined on an table, then Lua looks for this field on the index.
** In a way, metatables are analogous to virtual tables in object languages, but they are not just for methods, but also for fields and operators.
* You can get an object's metatable through '''getmetatable''' and assign it with '''setmetatable'''.
* See also the [http://www.lua.org/manual/5.1/manual.html#2.8 official metatables reference]

One example.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Define two tables A and B, and set "meta" their metatable
local a, b, meta = {}, {}, {}
setmetatable(a, meta)
setmetatable(b, meta)

-- Define an __index table on the metatable. It contains one key/value pair.
meta.__index = { "hello world" };

-- Print "hello world" twice
print(a[1])
print(b[1])

-- Now make our tables read-only
meta.__newindex = function(table, key, value) error("this table is read-only!") end
a[1] = "foo" -- throws an error
</syntaxhighlight></div>

Here are the most important fields a metatable can have:
* '''__index''': used when you read a member from an object. On tables, Lua will first search for a regular field on the table itself (not its index) before it looks at the index. The index may be a table or a function: <code>value func(object, key)</code>
* '''__newindex''': used when you assign a value to an object's member. On tables, newindex is only called if the table itself (not its index) does not already contains the specified key. May be a table or a function: <code>func(object, key, value)</code>
* '''__call''': used when you invoke the object as a function. Must be a function: <code>func(object, <args>)</code>
* '''__tostring''': used when you invoke the '''tostring''' function with this object in argument. Must be a function: <code>string func(object)</code>

Besides of that it can have fields for binary operators. When each of the two operands defined overloads, the left one is used. They must be functions: <code>result func(object)</code>
* '''__add''': addition
* '''__sub''': subtraction
* '''__mul''': multiplication
* '''__div''': division
* '''__mod''': module
* '''__pow''': exponentiation
* '''__eq''': equality comparison. Prior to calling this overload, Lua checks that types are equal.
* '''__neq''': inequality comparison. Prior to calling this overload, Lua checks whether types are different.
* '''__lt''': lesser than comparison. (b >= a) is considered equivalent to (a < b)
* '''__le''': lesser than or equal to comparison. (b > a) is considered equivalent to (a <= b). If __le is not defined, lua will use __lt, considering that (a <= b) is equivalent to not (b < a).
* '''__concat''': concatenation

Finally it can have the following fields for unary operators. They must be functions: <code>result func(object)</code>
* '''__unm''': unary minus
* '''__len''': the sharp operator (#). Can only be used on userdata ; on tables the default operator will always be called.

=== Implementing inheritance ===
The most common use of metatables is to mimic the behavior of object languages' types hierarchy. Here is how to do it:
<div class="civ5-example"><syntaxhighlight lang="lua">
local Dog = {}
function Dog:specie()
return "dog"
end
function Dog:race()
return "unknown"
end
function Dog:description()
return self.specie().." - "..self.race()
end
function Dog:new()
local instance = {}
setmetatable(instance, { __index = self})
return instance
end

local Pitbull = dog:new()
function Pitbull:race()
return "pitbull"
end

pitbull = Pitbull:new()
print(pitbull:description()) -- prints "dog - pitbull"
</syntaxhighlight></div>

This implementation is very elegant: the "new" method both creates a new instance and subtypes the creator, since "pitbull"'s index is now "Pitbull". However, should you define an operator overload on Dog's metatable, Pitbull would not inherit it. This is the limit of inheritance in Lua: operator overloads must be defined on the metatable itself, they cannot be defined on the metatable's index. As a result, there is no way to inherit those overloads while subtyping.

=== Coroutines ===
Coroutines provide a way to slice a function in many shorter calls and optionally return intermediate results. On each call, the function execution is resumed to the point where it stopped previously, with all locals being properly restored with the value they had at this time.
* Coroutines are often compared to threads. Indeed, when there are more threads than CPU cores, the operating system slices threads' execution into many little time frames and sequentially runs them in order to achieve multitasking.
* However while coroutines allows you to implement cooperative multitasking (the coroutines need to explicitly give the hand back), they cannot be used for preemptive multitasking or to use more than one system thread or CPU Core.
* As a result, coroutines are rather used as syntactic sugar (mostly to write iterators), or as a way to split a long function execution across many frames (through Context.{{Func5|UIElement|SetUpdate}}).

The following methods are mainly used:
* <code>'''coroutine''' coroutine.create('''function''' func)</code> creates a coroutine for the specified function. The function signature can be anything.
* <code>'''bool''', '''...''' coroutine.resume('''coroutine''' co, '''...''')</code> resumes the coroutine with the specified arguments. Then it returns either '''true''' followed by the returned results (either though '''return''' or '''yield'''), or '''false''' followed by an error message.
* <code>'''string''' coroutine.status('''coroutine''' co)</code> returns either "running" (the active coroutine), "normal" (a parent of the active coroutine), "suspended" (not started or waiting to be resumed) or "dead" (finished or threw an error).
* <code>coroutine.yield('''...''')</code> suspends the execution of the running coroutine and gives the hand back to the caller of coroutine.resume. The arguments will be returned by coroutine.resume.

Here is a base example:
<div class="civ5-example"><syntaxhighlight lang="lua">
function neighborsCoroutine(plot)
for i = 0, 5 do
coroutine.yield(Map.PlotDirection(plot:GetX(), plot:GetY(), i))
end
end

local co = coroutine.create(neighborsCoroutine)
while coroutine.status(co) == "suspended"
local _, neighbor = co.resume(plot)
-- Do something with plot
end
</syntaxhighlight></div>

Here is how to transform it into an iterator:
<div class="civ5-example"><syntaxhighlight lang="lua">
function neighbors(plot)
local co = coroutine.create(neighbors)
return function()
if coroutine.status(co) ~= "suspended" then return end
return select(2, coroutine.resume(plot))
end
end

for neighbor in neighbors(plot) do
-- Do something with plot
end
</syntaxhighlight></div>

Here is an example that spreads a long function call across many frames:
<div class="civ5-example"><syntaxhighlight lang="lua">
function SpreadAcrossFrames(longFunctionCall, ...)
local co = coroutine.create(longFunctionCall)
ContextPtr.SetUpdate(function()
coroutine.resume(unpack(arg))
if coroutine.status(co) ~= "suspended" then
ContextPtr:ClearUpdate()
end
end)
end

SpreadAcrossFrames(SomeLongFunction, arg1, arg2)
</syntaxhighlight></div>

=== Design philosophy for Lua ===
Do not use a butter knife as you would use a chainsaw (the opposite is even more true and usually ends up badly). When designing your code, remember that:
* Lua is not an object language. While you can use objects and inheritance in some extent, you do not have to and there may be better alternatives sometimes.
* Lua is not a functional language. While you can use lambdas and similar concepts, you do not have to and there may be better alternatives sometimes.
* Lua is a multi-paradigm and dynamic language, take advantage of those.
* Lua is very suited for prototyping and small programs, and this is perfect for mods. Try to adjust your mindset: you're not writing a framework that a whole team will still use and maintain in twenty years.

[[Category:Civ5 API]]
[[Category:Civ5 Tutorials]]

Lua introduction for confirmed developers

2012-09-30T13:44:17Z

DonQuich:

''This page is a part of the [[Lua and UI Reference (Civ5)|Lua and UI Reference]].''

= About Lua =
===Lua, not LUA===
This is a Portuguese word meaning "moon", not an acronym.

===Presentation===
Lua is an interpreted, dynamically typed, multi-paradigm language. It was designed in 1993 with the following objectives in mind:
* Extensible semantics. A small set of features allows the support of multiple paradigms, from functional programming to object programming. For example, while inheritance is not natively supported, it can be easily set up through metatables. The same features allow events in civ5 to behave both as functions and objects with Add and Remove methods.
* Highly portable. The con is a lightweight and somewhat lacking API.
* Easy to embed and to interface from other languages.
* Well suited for data description (''à la'' JSON).
* A beginners-friendly syntax.

===Performances===
As usual with interpreted and dynamically typed languages (hereby abusively named "scripting languages"), expect a 10 to 100 order of magnitude in performances decrease when compared to compiled and statically typed languages like C, C++ or C#. While it is possible for scripting languages to drastically improve the performances through more or less sophisticated means (expression trees/opcodes caching, JIT compiler, type inference to perform static resolutions), no such solution has been used in Civ5 (aside, probably, of the caching). And while an external JIT library exists, it causes compatibility problems with most mods using Lua.

That being said, Lua is still pretty good for a scripting language, better than the Python implementation from Civ4 for example. And all in all, it is fast enough for most of what modders want to achieve without the need to compromise code elegance, readability and maintainability for performances. So keep in mind that "premature optimization is the root of all evil" (Donald Knuth).

=Syntax cheatsheet=
=== Basics ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Literals
local x = 5
local x = 5.0
local x = nil -- A nil value is the same as an undefined value
local x = true
local x = false

-- Strings (single and double quotes can be used indifferently, there is no difference)
local x = "five"
local x = 'five'
local x = "five\n" -- Escape characters with "\".
local x = [[Five is a number.
Did you know?]] -- Multi-line string: equivalent to "Five is number.\nDid you know?"

-- Globals versus locals
x = 5 -- For globals, assigning is declaring.
local x = 5
</syntaxhighlight></div>

=== Operators ===
<div class="civ5-example"><syntaxhighlight lang="lua">
local x = a or b
local x = a and b

local x = "hello ".."world" .. "!" -- concatenation: two dots
local x = 4..5 -- Result is "45". On concatenation, conversions occur.

local x = (a + b - d) * f ^ g % h -- ^ is exponentiation, % is modulo
local x = "4" + "5" -- Result is 9. On arithmetic operations, conversions occur.

local x = a == b -- equality -- True only if a and b have the same values and types.
local x = a ~= b -- inequality

local x = ((a <= b) == not (a > b)) == ((a >= b) == not (a < b))
local x = "abc" < "def" -- Byte-wise comparison, not Unicode-compliant. Use Locale's methods instead.

local x = #"abc" -- Returns 3, the number of bytes in the string (3 characters, 1 byte each).
local x = #"您好世界" -- Returns 8, the number of bytes in the string (4 characters, 2 bytes each).
local x = #SomeTable -- Returns the biggest integer key in the table, or nil if there is no integer key.

-- No increment operator (++ --), no binary-assign operator (+= *=), no ternary operator (? :), no coalescence operator (??)
</syntaxhighlight></div>

=== Tables and multiple assignments ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Table declaration
SomeTable = {}

SomeArray = { "abc", "def" }
-- 1 => "abc", 2 => "def"

SomeComplexTable = { name = "John", surname = "Doe", age = 25, 43, [7] = 8 }
-- "name" => "John", "surname" => "Doe", "age" => 25, 1 => 43, 7 => 8.

-- Member access (all equivalent)
SomeTable.SomeMember = 5
SomeTable["SomeMember"] = 5

-- Multiple assignment
-- Both statements are equivalent since SomeArray contains "abc" and "def".
local x, y = "abc", "def"
local x, y = unpack(SomeArray)
</syntaxhighlight></div>

=== Functions ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Functions declarations (all equivalent)
function HelloWorld(a, b) print("Hello world") end
HelloWorld = function(a, b) print("Hello world") end
-- Functions are first-class objects and can be assigned like any other value!

-- Methods declarations (all equivalent)
SomeTable.HelloWorld(a, b) print("Hello world") end
SomeTable.HelloWorld = function(a, b) print("Hello world") end

-- Instanced methods declarations (all equivalent)
SomeTable.HelloWorldInstanced(self, a, b) print(self.SomeMember) end
SomeTable:HelloWorldInstanced(a, b) print(self.SomeMember) end

-- Functions and methods calls
HelloWorld(a) -- b will be nil in the function
HelloWorld(a, b)
SomeTable.HelloWorld(a, b)

-- Instanced methods calls (all equivalent)
SomeTable:HelloWorldInstanced(a, b)
SomeTable.HelloWorldInstanced(SomeTable, a, b)

-- Multiple return values
function func(a, b) return a, b end
local x, y, z = func(5, 6) -- Assigns 5 to x and 6 to y, z will be nil

-- Variable arguments
function SomeFunc(a, b, ...)
print(a)
print(b)
for i, v in ipairs(arg) do -- arg is a keyword for a table containing the variable arguments
print(v)
end
end
SomeFunc(1, 2, 3, 4, 5) -- prints 1, 2, 3, 4, 5
SomeFunc(1, 2) -- prints 1, 2
</syntaxhighlight></div>

=== Control flow ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- If
if name == "Wu Zetian" then
print("Hello China")
elseif name == "Napoleon" then -- "elseif", not "else if". Beware C developers!
print("Hello France")
else -- no "then" after "else"!
print("Hello unknown")
end

-- For loop (with counter)
for i = 1, 8 do print(i) end -- Prints 1, 2, 3, 4, 5, 6, 7, 8
for i = 1, 8, 2 do print(i) end -- Prints 1, 3, 5, 7

-- For loop (with iterator)
for playerID, pPlayer in pairs(Players) do -- Prints 1 Wu Zetian, 2 Napoleon, ...
print(playerID, pPlayer:GetName())
end
for plot in Plots() do -- Prints 0 0, 0 1, 0 2, ...
print(plot:GetX(), plot:GetY())
end

-- While (i will be 5 in the end)
while i < 5 do
i = i + 1
end

-- Repeat until (i will be 5 in the end)
repeat
i = i + 1
until i == 5

-- Infinite loops
-- Lua supports "break" for all loops but not "continue" instruction does not exist!
do
i = i + 1
if i > 5 then break end
end

</syntaxhighlight></div>

= Basics =
=== Type system ===
You can get a variable's type by using the '''type''' function. It takes any value and returns a string. Here are the possible results:
* The following are [http://en.wikipedia.org/wiki/Value_type value types].
** '''nil''': Lua makes do distinction between an undefined variable and a variable with a nil value. Assigning nil to a variable or table member is equivalent to undefining it.
** '''number''': a 64 bits floating-point number. Lua has no support for integers and only use floating-points. See also [[#No integer type]].
** '''boolean''': true or false obviously.
* The following are [http://en.wikipedia.org/wiki/Reference_type reference types]
** '''table''': any table.
** '''string''': your usual string of characters. In Lua all strings are [http://en.wikipedia.org/wiki/String_interning interned] and immutable.
** '''userdata''': objects defined in C for use in Lua. They may not be enumerated through pairs and are often read-only.
** '''function''': remember that functions are first-class objects in Lua.
** '''thread''': coroutines actually. Lua does not support threads.

Note: Many objects in the Civ5 API are actually regular tables which either have userdata methods as members, or a userdata metatable index.

=== Implicit conversions ===
* Whenever you concatenate two values (and possibly when you invoke a standard function that takes a string), an automatic conversion to string occurs, as if you had used the '''tostring''' function. The expression <code>4..5</code> returns "45".
* Whenever you perform an arithmetic operation, the operands are both converted to numbers, as if you had used the '''tonumber''' function. The expression <code>"4" + "5"</code> returns 9.

=== Equality comparisons ===
'''Two values are equal only if their types are the same.'''<br/>
This is far stricter than most dynamic languages for example and somehow stricter than C.
* 4 is not equal to "4". (number type and string type). In PHP they would be equal.
* 0 is not equal to false (number type and bool type). In C they would be equal (false is typically defined as a number).
* 0 is not equal to nil. (number type and nil type). In C they would be equal (nil is typically defined as a number).

'''Numbers and booleans are compared by value. Everything else by reference. Strings are interned.'''
* Numbers and booleans are compared by value.
* Tables, userdata, functions and threads are compared by reference.
* Strings are [http://en.wikipedia.org/wiki/String_interning interned], which means that two identical strings are always the same reference. So comparison is made by reference but it is equivalent to a by-value comparison.
* All nil values are always equal.
<div class="civ5-example"><syntaxhighlight lang="lua">
local a = 5
assert(a == 5)
-- true, comparison by value

local a = {}
assert(a == {})
-- false, comparison by reference: those two tables are distinct objects.

local a = "Hello ".."world"
assert(a == "Hello world")
-- true, both strings are the same reference thanks to string interning.
</syntaxhighlight></div>

=== String interning ===
'''All strings are interned in Lua, without any exception.'''<br/>
[http://en.wikipedia.org/wiki/String_interning String interning] is a process through which all identical strings ends up being the same reference to a unique string instance. Typically, the interpreter maintains a string dictionary in the memory and whenever a string needs to be built (from a literal, from a concatenation, from a native call, etc), it first searches in this dictionary whether there is already a reference for this sequence of characters and uses it when it exists. This process usually reduces memory consumptions and speeds up equality comparisons, but it makes other operations slower because of the lookup cost. Some platforms such as Dotnet or Java automatically interns literals only. Lua, on the other hand, systematically interns every string.

=== Boolean logic ===
'''Anything that is neither false nor nil is evaluated to true.'''<br/>
This is pretty simple. Especially, an empty string or the zero number are evaluated to true.
<div class="civ5-example"><syntaxhighlight lang="lua">
if 0 then print("hello world") end -- prints hello world
</syntaxhighlight></div>

Now regarding the and/or operators, two rules to remember:
* '''The right operand is only evaluated when needed.'''
** <code>false and x()</code> does not call x() since the result will be false anyway.
** <code>true or x()</code> does not call x() since the result will be true anyway.
* '''The result is the last operand to have been evaluated.'''
** <code>x() and y()</code> returns x() if it was false, y() otherwise.
** <code>x() or y()</code> returns x() if it was true, y() otherwise.

=== Ternary and coalescence statements ===
We can exploit the and/or operators behavior:
* '''Coalescence:''' <code>x or y</code>. It returns x if x is neither nil nor false, y otherwise.
:In other words <code>result = x or y</code> is equivalent to: <code>if x then result = x else result = y end</code>.
* '''Ternary:''' <code>condition and x or y</code> (as long as x is not nil or false). It returns x if condition was true, y if it was false.
:Indeed the expression becomes: <code>(condition and x) or y</code>. If condition is true the '''and''' operator returns x, and since x is true, y is not evaluated and '''or''' returns x.
:In other words <code>result = condition and x or y</code> is equivalent to: <code>if condition then result = x else result = y end</code>.

=== Method calls: dot versus colon ===
'''The colon (<code>:</code>) operator implicitly passes the caller as the first argument.''' <br/>
As opposed to the dot (<code>.</code>) operator that performs a regular call without implicitly passing anything. The colon operator behavior is obviously designed for instance methods.<br/>
<div class="civ5-example"><syntaxhighlight lang="lua">
local myTable = { msg = "Hello world" }
myTable.Print = function(self) print(self.msg)

-- Three different ways to call this method
myTable:Print()
myTable.Print(myTable)

local func = myTable.Print
func(myTable)
</syntaxhighlight></div>

Note: in the civ5 API you will often encounter static methods that do not take any argument but that are called through a dot. This results from a misunderstanding of Lua from one of the Firaxis developers. While this work when the method does not take any argument (the one provided by the colon operator will be ignored), this is slower and can be considered as an error without any consequence.

=== Arrays versus tables ===
'''In Lua, an array is a table whose keys are integers.'''

Since this is a common programming pattern, a number of things are designed for arrays:
* <code>{"abc", "def", "ghi"}</code> starts at index 1, up to index 3. Arrays typically start at 1.
* <code>table.insert({}, "abc")</code> will transform the provided empty table to <code>{"abc"}</code>
* <code>table.insert({"abc", "def"}, "ghi")</code> will transform the provided table to <code>{"abc", "def", "ghi"}</code>
* <code>table.insert({"abc", "ghi"}, 2, "def")</code> will transform the provided table to <code>{"abc", "def", "ghi"}</code>
* <code>table.remove({"abc", "def", "ghi"}, 2)</code> will transform the provided table to <code>{"abc", ""ghi"}</code>
* <code>#{"abc", "def", "ghi"}</code> returns 3, the biggest integer key.

=== Ipairs versus pairs ===
You could say that '''pairs''' is for table and '''ipairs''' for arrays.
* '''Pairs''' enumerate all the key/value pairs in an unordered matter.
* '''Ipairs''' only enumerates the key/value pairs for consecutive integer keys, in an ascending order, starting from 1 up to the largest key. If at some point a key is missing, the enumeration stops.
::It does not matter whether the table was crated with table.insert or directly by inserting the values through, for example <code>table[i] = value</code>.

<div class="civ5-example"><syntaxhighlight lang="lua">
-- Produces: { 1 => "one", 2 => "two", 4 => "four", "name" => "John", "age" => 25 }
local t = { "one", "two", name = "John", age = 25, [4] = "four" }

-- Will print (for example, the order is undetermined): "name", 2, 4, "age", 1
for k in pairs(t) do print(k) end

-- Will print 1, 2
for k in ipairs(t) do print(k) end

-- Both ipairs and pairs return a key and a value, so you could also use:
for k, v in pairs(t) do print(k, v) end
</syntaxhighlight></div>

=== Semicolons and line breaks ===
'''Statements need to be separated either by a line break or a semicolon.'''
* You can use both a semicolon and a line break but then the semicolon is redundant and not required, although it does not cause any problem.
* Line breaks can also be freely added about everywhere and behave as whitespaces most of the time (you can add them after most keywords for example, so you can keep if...then...end structures on one line or split them across multiple lines).

=== Locals, globals and includes ===
* The include statement allows you to include a lua file into another one (see [[Specificities of the Lua implementation in Civ5]]). When you do so, the globals defined in the included file are imported in the parent file. However the local variables are only visible from within the file that declared them.
* Another specificities of locals: they're only visible after the point they have been declared in the file, while globals are always visible. An example is worth thousand of words.
<div class="civ5-example"><syntaxhighlight lang="lua">
function Func1()
print(someLocal or "nil")
print(someGlobal or "nil")
end

local someLocal = "foo"
function Func2()
print(someLocal or "nil")
print(someGlobal or "nil")
end

someGlobal = "global"
someLocal = "local"
Func1() -- prints "nil", then "global": someLocal is assigned but not visible from Func1
Func2() -- prints "local", then "global": someLocal is assigned and visible from Func2
</syntaxhighlight></div>
* Performances-wise, Lua first searches a variable name in the current scope, then in the parent scope, etcetera until it reaches the highest scope, and finally it searches the global scope. So the deeper a local is declared, the faster it is accessed. On the contrary, globals are the slowest to retrieve.

= Semi-advanced topics =
=== Closures ===
'''Closures are functions that embed variables that are persisted across calls.'''<br/>
This is typically achieved through a "parent" function that declares a local "closed" variable and returns another child "closure" function using this local. The "closed" variable is then unreachable for anyone but the "closure". And since it the "closed" variable is not in the "closure"'s scope, it is not reinitialized on every call of "closure".
<div class="civ5-example"><syntaxhighlight lang="lua">
function GiveMeAFunc() -- the parent function
local x = 0 -- the closed variable
return function() -- the closure function embedding "closed"
x = x + 1
return closure
end
end

local func = GiveMeAFunc()
print(func()) -- Prints 1
print(func()) -- Prints 2
print(func()) -- Prints 3
</syntaxhighlight></div>

=== Iterators ===
'''Iterators are functions for use in <code>for...in</code> loops.'''<br/>
Let's consider the following code: <code>for var1, var2, var3 in iterable() do</code>.
* iterable has the following signature: <code>iterator, state, var1 iterable()</code>. It returns a function, a state, and the initial value of var1.
* iterator has the following signature: <code>var1, var2, var3 iterator(state, var1)</code>. It takes the state and the last value of var1 and returns var1, var2 and var3.
* The loop stops when var1 is nil.
* The for...in loop is equivalent to:
<div class="civ5-example"><syntaxhighlight lang="lua">
local iterator, state, var1, var2, var3
iterator, state, var1 = iterable()
do
var1, var2, var3 = iterator(state, var1)
if var1 == nil then break end

-- Inserts here the user code defined in the for..in loop
end
</syntaxhighlight></div>
* Note that we used var1, var2 and var3 for the example but there is no restriction to the number of variables. You could have one or hundred.

Let's write the "ipairs" function.
<div class="civ5-example"><syntaxhighlight lang="lua">
local function ipairs(table) -- The iterable function
local iterator = function(table, key) -- The iterator function
key = key + 1
return key, table[key]
end
return iterator, table, 0
end
</syntaxhighlight></div>

The same with closures: it's easier.
<div class="civ5-example"><syntaxhighlight lang="lua">
local function ipairs(table) -- The iterable function
local key = 0 -- Both "table" and "key" are closed variables.
local iterator = function() -- The iterator function, a closure: it ignores the arguments provided to it
key = key + 1
return key, table[key]
end
return iterator -- No need to return anything since we do not require any argument.
end
</syntaxhighlight></div>

=== No integer type ===
'''Lua offers no support for integers and only has a 64-bits floating point number type.'''<br/>
Actually, this is only troublesome for a few algorithms that use very large integers (>2^52) or require fast integer arithmetics. But many developers misunderstand floating points and believe the problem is broader than it is. For example, does the following assertion surprise you at least a bit: "any integer smaller than 2^52 can be accurately represented with a 64-bits floating point without any error"? If it did, you suffer from some misconceptions and you should better read carefully what's coming.

Many developers are confusing rounding errors with representation errors.
* '''Rounding errors''' actually only happen if you need a very high number of digits to represent a number. For example if you are adding a very large number with a small number. Rounding errors are very rarely encountered in day to day to applications. Actually most developers work their whole career without ever encountering them.
* '''Representation errors''' are the real problem: 0.1 is expressed in a decimal basis, but it has no finite representation in binary: it requires an infinite number of binary digits. This means that if you write 0.1 in your code it will be translated to a binary number close enough from 0.1 bot not exactly equal to it. So if you sum ten times 0.1, you sill sum ten times something close from 0.1 and the result will not be 1.

'''So the real problem for most developers only lies in the decimal-binary conversion that arises when you manipulate numbers in your code that do not have a finite representation in binary. As long as you do not use such numbers, there will be no problem. And here are the good news: integers do not suffer from any representation problem!''' Indeed, any integer can be represented with a finite number of binary digits. This is why the absence of an integer type typically does not cause problems, minus the performance penalty.

Here are a few examples to illustrate that point.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- This loop works as intended: no representation error and the upper bound is far below 2^52.
local sum = 0
for i = 0, 10000000000, 1 do sum = sum + 1 end
assert(sum == 10000000001)

-- This loop works as intended: 1/16 is a floating-point with an exact representation in binary
local sum = 0
for i = 0, 1, 1/16 do sum = sum + 1 end
assert(sum == 17/16)

-- This loop does NOT work as intended: 0.1 does not have an exact representation in binary.
-- It's the same for Lua, C and almost every programming language.
local sum = 0
for i = 0, 1, 0.1 do sum = sum + 1 end
assert(sum == 1.1) -- throws an error
</syntaxhighlight></div>

=== Errors management ===
Lua offers a error handling mechanism similar to exception handling but unfortunately not very convenient.
* Errors are thrown using the '''error''' function. It takes a string and it immediately aborts Lua execution until the game handles the error and prints it in Firetuner (when enabled).
* Errors are caught before that point using '''pcall''' or '''xpcall''', in order to let you resume execution by managing the error. "pcall" stands for "protected call".

Here are the syntaxes for pcall and xpcall:
* <code>bool, ... pcall(func, ...)</code>
** The function is called with the specified arguments.
** Pcall returns either true followed by the values returned by func, or false followed by the error text.
* <code>bool, ... xpcall(func, errorHandler)</code>:
** The function is called without any argument. If an error occurs the specified errorHandler is invoked with the error text as the only argument.
** Xpcall returns either true followed by the values returned by func, or false followed by the returned values from errorHandler.

Examples to invoke "someFunc" with "someArg" as the only argument. In both examples we want to display the error on the console, or the result if it was a success. A complete errors management example with a reporting mechanism for the end-user is presented in [[Debugging (Civ5)]].
<div class="civ5-example"><syntaxhighlight lang="lua">
-- pcall
local status, result = pcall(someFunc, someArg)
if not status then
print("error was: "..(result or "?"))
else
print("success: "..result)
end

-- xpcall
local status, result = xpcall(
function() someFunc(someArg) end,
function(err) print("error was: "..(result or "?")) end)

if status then
print("success: "..result)
end
</syntaxhighlight></div>

= Advanced topics=
=== Metatables and metamethods ===
* Every value in Lua, from a number to a userdata, has a metatable.
** Many objects can share the same metatable.
** Tables and userdata each have their own metatables by default. Numbers, bools, nils and strings all share the same metatable.
* A metatable may contain a few metamethods and index tables.
** Metamethods are methods stored under special fields names. They implement operators overloads.
** Index tables behave as "base classes": if a field name is not defined on an table, then Lua looks for this field on the index.
** In a way, metatables are analogous to virtual tables in object languages, but they are not just for methods, but also for fields and operators.
* You can get an object's metatable through '''getmetatable''' and assign it with '''setmetatable'''.
* See also the [http://www.lua.org/manual/5.1/manual.html#2.8 official metatables reference]

One example.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Define two tables A and B, and set "meta" their metatable
local a, b, meta = {}, {}, {}
setmetatable(a, meta)
setmetatable(b, meta)

-- Define an __index table on the metatable. It contains one key/value pair.
meta.__index = { "hello world" };

-- Print "hello world" twice
print(a[1])
print(b[1])

-- Now make our tables read-only
meta.__newindex = function(table, key, value) error("this table is read-only!") end
a[1] = "foo" -- throws an error
</syntaxhighlight></div>

Here are the most important fields a metatable can have:
* '''__index''': used when you read a member from an object. On tables, Lua will first search for a regular field on the table itself (not its index) before it looks at the index. The index may be a table or a function: <code>value func(object, key)</code>
* '''__newindex''': used when you assign a value to an object's member. On tables, newindex is only called if the table itself (not its index) does not already contains the specified key. May be a table or a function: <code>func(object, key, value)</code>
* '''__call''': used when you invoke the object as a function. Must be a function: <code>func(object, <args>)</code>
* '''__tostring''': used when you invoke the '''tostring''' function with this object in argument. Must be a function: <code>string func(object)</code>

Besides of that it can have fields for binary operators. When each of the two operands defined overloads, the left one is used. They must be functions: <code>result func(object)</code>
* '''__add''': addition
* '''__sub''': subtraction
* '''__mul''': multiplication
* '''__div''': division
* '''__mod''': module
* '''__pow''': exponentiation
* '''__eq''': equality comparison. Prior to calling this overload, Lua checks that types are equal.
* '''__neq''': inequality comparison. Prior to calling this overload, Lua checks whether types are different.
* '''__lt''': lesser than comparison. (b >= a) is considered equivalent to (a < b)
* '''__le''': lesser than or equal to comparison. (b > a) is considered equivalent to (a <= b). If __le is not defined, lua will use __lt, considering that (a <= b) is equivalent to not (b < a).
* '''__concat''': concatenation

Finally it can have the following fields for unary operators. They must be functions: <code>result func(object)</code>
* '''__unm''': unary minus
* '''__len''': the sharp operator (#). Can only be used on userdata ; on tables the default operator will always be called.

=== Implementing inheritance ===
The most common use of metatables is to mimic the behavior of object languages' types hierarchy. Here is how to do it:
<div class="civ5-example"><syntaxhighlight lang="lua">
local Dog = {}
function Dog:specie()
return "dog"
end
function Dog:race()
return "unknown"
end
function Dog:description()
return self.specie().." - "..self.race()
end
function Dog:new()
local instance = {}
setmetatable(instance, { __index = self})
return instance
end

local Pitbull = dog:new()
function Pitbull:race()
return "pitbull"
end

pitbull = Pitbull:new()
print(pitbull:description()) -- prints "dog - pitbull"
</syntaxhighlight></div>

This implementation is very elegant: the "new" method both creates a new instance and subtypes the creator, since "pitbull"'s index is now "Pitbull". However, should you define an operator overload on Dog's metatable, Pitbull would not inherit it. This is the limit of inheritance in Lua: operator overloads must be defined on the metatable itself, they cannot be defined on the metatable's index. As a result, there is no way to inherit those overloads while subtyping.

=== Coroutines ===
Coroutines provide a way to slice a function in many shorter calls and optionally return intermediate results. On each call, the function execution is resumed to the point where it stopped previously, with all locals being properly restored with the value they had at this time.
* Coroutines are often compared to threads. Indeed, when there are more threads than CPU cores, the operating system slices threads' execution into many little time frames and sequentially runs them in order to achieve multitasking.
* However while coroutines allows you to implement cooperative multitasking (the coroutines need to explicitly give the hand back), they cannot be used for preemptive multitasking or to use more than one system thread or CPU Core.
* As a result, coroutines are rather used as syntactic sugar (mostly to write iterators), or as a way to split a long function execution across many frames (through Context.{{Func5|UIElement|SetUpdate}}).

The following methods are mainly used:
* <code>'''coroutine''' coroutine.create('''function''' func)</code> creates a coroutine for the specified function. The function signature can be anything.
* <code>'''bool''', '''...''' coroutine.resume('''coroutine''' co, '''...''')</code> resumes the coroutine with the specified arguments. Then it returns either '''true''' followed by the returned results (either though '''return''' or '''yield'''), or '''false''' followed by an error message.
* <code>'''string''' coroutine.status('''coroutine''' co)</code> returns either "running" (the active coroutine), "normal" (a parent of the active coroutine), "suspended" (not started or waiting to be resumed) or "dead" (finished or threw an error).
* <code>coroutine.yield('''...''')</code> suspends the execution of the running coroutine and gives the hand back to the caller of coroutine.resume. The arguments will be returned by coroutine.resume.

Here is a base example:
<div class="civ5-example"><syntaxhighlight lang="lua">
function neighborsCoroutine(plot)
for i = 0, 5 do
coroutine.yield(Map.PlotDirection(plot:GetX(), plot:GetY(), i))
end
end

local co = coroutine.create(neighborsCoroutine)
while coroutine.status(co) == "suspended"
local _, neighbor = co.resume(plot)
-- Do something with plot
end
</syntaxhighlight></div>

Here is how to transform it into an iterator:
<div class="civ5-example"><syntaxhighlight lang="lua">
function neighbors(plot)
local co = coroutine.create(neighbors)
return function()
if coroutine.status(co) ~= "suspended" then return end
return select(2, coroutine.resume(plot))
end
end

for neighbor in neighbors(plot) do
-- Do something with plot
end
</syntaxhighlight></div>

Here is an example that spreads a long function call across many frames:
<div class="civ5-example"><syntaxhighlight lang="lua">
function SpreadAcrossFrames(longFunctionCall, ...)
local co = coroutine.create(longFunctionCall)
ContextPtr.SetUpdate(function()
coroutine.resume(unpack(arg))
if coroutine.status(co) ~= "suspended" then
ContextPtr:ClearUpdate()
end
end)
end

SpreadAcrossFrames(SomeLongFunction, arg1, arg2)
</syntaxhighlight></div>

=== Design philosophy for Lua ===
Do not use a butter knife as you would use a chainsaw (the opposite is even more true and usually ends up badly). When designing your code, remember that:
* Lua is not an object language. While you can use objects and inheritance in some extent, you do not have to and there may be better alternatives sometimes.
* Lua is not a functional language. While you can use lambdas and similar concepts, you do not have to and there may be better alternatives sometimes.
* Lua is a multi-paradigm and dynamic language, take advantage of those.
* Lua is very suited for prototyping and small programs, and this is perfect for mods. Try to adjust your mindset: you're not writing a framework that a whole team will still use and maintain in twenty years.

[[Category:Civ5 API]]
[[Category:Civ5 Tutorials]]

Civ5 Modding Tutorials

2012-09-28T20:05:18Z

DonQuich:

= Getting started =
'''Get a tour.'''
:If you have no idea about modding and what are Lua and Xml, you should give a look at [http://www.weplayciv.com/forums/entry.php?15-Dale-s-Mod-Blog-Civ5-Modding-Explained Civ5 Modding Explained].
'''Read the guide.'''
:The best introduction to civ5 modding is still the '''[http://forums.civfanatics.com/showthread.php?t=385009 Kael's Guide]'''. However it was written a long time ago and some informations are obsolete or missing.
'''Import your files into VFS.'''
:The main change since Kael wrote his guide is about the [[VFS (Civ5)|VFS]] (Virtual File System). Forgetting to import files into the VFS is the common source of problems for beginners.
'''Get the right tools for the job.'''
:See [[Civ5 Useful Programs]]. You should have installed the SDK of course, but it is also strongly recommended that you get a tool to search in all civ5 files at once, to compensate for the lack of documentation. You may also need additional softwares to extract and read the textures, test and debug your mod, etc.
'''Modify your ini files.'''
:See [[Debugging (Civ5)#Configuration|Debugging#Configuration]].

= Tutorials =
See also the [http://forums.civfanatics.com/forumdisplay.php?f=394&order=desc&page=2 Modding tutorials section] on the forums.<br/>
Also note that the [[Civ5 XML Reference|XML]] and [[Lua and UI Reference|Lua]] sections each contain specific tutorials, articles and extensive documentation.

=== General ===
* [[Modding Limits and Issues (Civ5)|Modding Limits and Issues]]
* [http://forums.civfanatics.com/showthread.php?t=459392 Create and use DDS textures]
* [http://forums.civfanatics.com/showthread.php?t=449431 Adding custom data and using them in Lua]
* [http://wiki.2kgames.com/civ5/index.php/Mods:LocalizationSyntax Localization Syntax]
* [[Debugging (Civ5)|Debugging]]

=== Common tasks ===
* [http://forums.civfanatics.com/showthread.php?t=391823 New Leaders (2D images)]
* [http://forums.civfanatics.com/showthread.php?t=389782 New Resources]
* [http://forums.civfanatics.com/showthread.php?t=474309 New Resources (with 3D textures)]
* [http://forums.civfanatics.com/showthread.php?t=470290 New Buildings]
* [http://forums.civfanatics.com/showthread.php?t=406877 New Specialists]
* [http://forums.civfanatics.com/showthread.php?t=392985 New Units]

=== Specific topics ===
* [http://forums.civfanatics.com/showthread.php?t=394056 Importing civ4 units into civ5]
* [http://forums.civfanatics.com/showthread.php?t=396911 Making units that use Civ5 animations]
* [http://forums.civfanatics.com/showthread.php?t=405148 Locking techs on a civilization basis]
* [http://forums.civfanatics.com/showthread.php?t=468374 Culture buildings - vanilla and G&K cross compatibility]
* [[Text icons and markups (Civ5)|Text icons and markups]]
* [[VFS (Civ5)|VFS]]

[[Category:Civ5 Tutorials]]

Modding Limits and Issues (Civ5)

2012-09-25T12:23:54Z

DonQuich:

''This page is a part of the [[Civ5 Modding Tutorials]].''

= Hard limits =
Limits you won't be able to circumvent.
* '''Audio'''
:A mod cannot add its own audio files
* '''3D leader scenes'''
:They use a proprietary format. Although a paper has been published that explains how the algorithm works, the details of the implementation are unknown and as of August 2012 there is not tool to read or write them.
* '''Combat mechanics'''
:Since the pre-G&K patch the combat is no longer moddable.
* '''AI'''
:Most of it is processed on the C++ side and the API exposes almost no hooks to replace, trigger or prevent the standard behaviors. Now the diplomacy UI may be slightly modded though bonuses, and the fact that a mod can give orders to units opens a theoritical way to override the tactical and strategical UI although the daunting amount of work required and the involved CPU cost when comparing to Lua to C++ probably just makes this an illusion.
* '''Terrain modifications'''
:When they require an update of the 3D mesh (changing the TerrainType or the PlotType, and removing a feature), this one is not dynamically updated, the game needs to be reloaded. No terraforming mod.
* '''No more than 200 promotions'''
:Any promotion after that is added to every unit in the game. The base game with all DLC and expansion have about 165 promotions, so mods are restricted to less than 35 promotions in total. '''Will be removed in the 2012 Fall patch.'''
* '''No more than 22 major civilizations and 41 city states'''
:More hard-coded values.
* '''Espionage'''
:There is about no API to control it (no way to add/remove spies for example).
* '''Religious units'''
:There is no API to set a unit's religion.
* '''Civilizations without overrides'''
:A civilization that doesn't have at least two overrides (unique units/buildings) will not appear in the civilization selection screen.

= Soft limits =
Limits that can be overcame.
* '''Some assets cannot be deleted'''
:Deleting them causes the game to crash. Try to disable them instead.
* '''No more than one leader per civilization'''
:The Lua code for the setup screen only keeps the first leader for every civilization. You would need to use a modified version of the setup screen.

= Modularity problems =
Things that only one mod can do at the same time because it requires the full replacement of some resources. The community could theoretically issue solutions in some cases but in practice there is rarely a solution available.
* '''Units arts'''
:UnitMemberArtInfos and UnitArtInfos must be replaced altogether.
* '''UI'''
:Most of the UI mods need to replace some parts of the UI with their custom versions.
* '''Resources placement'''
:It requires the replacement of some of the AssignStartingPlots functions
* '''Natural wonders placement'''
:For the same reasons than resources.

[[Category:Civ5 Tutorials]]

Modding Limits and Issues (Civ5)

2012-09-25T12:23:41Z

DonQuich:

VFS (Civ5)

2012-09-25T12:21:49Z

DonQuich:

''This page is a part of the [[Civ5 Modding Tutorials]].''

This article explains the Virtual File System (VFS) in Civ5. Lua developers looking for informations on the '''include''' function should look at [[Specificities of the Lua implementation in Civ5]].

= What is it? =
[[File:ModBuddy.ImportIntoVFS.png|frame|The ''import into VFS'' option.]]
VFS stands for Virtual File System. Rather than locating the files directly in the file system, Civ5 looks for them in its virtual file system. This system provides the following benefits:
* '''Modularity:''' each mod, expansion or DLC can provide its own version of a given file without overwriting the original one. At run-time the game sequentially loads those files into the VFS, performing virtual overwrites as needed. This contrasts with the mods hell in the Elders Scrolls series for example.
* '''Packaging:''' The files in the VFS can be either independent files or parts of packages (archives). The VFS behaves as a unified resource loader.
* '''Sandboxing:''' whenever a mod requests a file, civ5 only looks in the VFS. This prevents mods to be allowed to look at the physical file system since this could open a security breach.

= Determining whether a file must be imported or not =
In doubt, import your files into the VFS. But you should better stick to what is written here.

'''Must be imported''' the files that are requested during the game.
* The XML UI files.
* The XML files for animations, scenes, etc.
* The Lua files (minus the exception detailed below).
* The art assets such as textures or models.

'''Should not be imported''' the files that are loaded through the project's content and actions tab (except the XML UI files, those ones should always be imported). While this is harmless most of the time, this can sometimes result in unexpected side-effects.
* The Lua files that are directly loaded through the project's content tab. This does not apply if the Lua file is associated with a XML file and you load this XML file instead. Note that if you want a Lua file to be included by other Lua or XML UI files, you will still have to import it into the VFS but you may see it loaded more times than necessary.
* The XML data and text files. Those ones are only ran at start up to modify the data tables.
* The SQL files. For the same reasons.

= Importing a file into the VFS =
* In ModBuddy, select a file in the solution explorer.
* Hit F4 (or click View > Properties Window) to open its properties.
* At the bottom of this new window, look for '''Import into VFS''' and set it to true.
* If Civ5 is opened, you will need to exit to the main menu for this change to be applied.

= Final warning =
{{Warning}} In some circumstances (notable the include statement in Lua, see [[Specificities of the Lua implementation in Civ5]]) only the first eight characters of the file matter. Tow files starting with the same first eight characters could then be confused by the game.

[[Category:Civ5 Tutorials]]

VFS (Civ5)

2012-09-25T12:21:21Z

DonQuich:

''This page is a part of the [[Civ5 Modding Tutorials]].''

This article explains the Virtual File System (VFS) in Civ5. Lua developers looking for informations on the '''include''' function should look at [[Specificities of the Lua implementation in Civ5]].

= What is it? =
[[File:ModBuddy.ImportIntoVFS.png|frame|The ''import into VFS'' option.]]
VFS stands for Virtual File System. Rather than locating the files directly in the file system, Civ5 looks for them in its virtual file system. This system provides the following benefits:
* '''Modularity:''' each mod, expansion or DLC can provide its own version of a given file without overwriting the original one. At run-time the game sequentially loads those files into the VFS, performing virtual overwrites as needed. This contrasts with the mods hell in the Elders Scrolls series for example.
* '''Packaging:''' The files in the VFS can be either independent files or parts of packages (archives). The VFS behaves as a unified resource loader.
* '''Sandboxing:''' whenever a mod requests a file, civ5 only looks in the VFS. This prevents mods to be allowed to look at the physical file system since this could open a security breach.

= Determining whether a file must be imported or not =
In doubt, import your files into the VFS. But you should better stick to what is written here.

'''Must be imported''' the files that are requested during the game.
* The XML UI files.
* The XML files for animations, scenes, etc.
* The Lua files (minus the exception detailed below).
* The art assets such as textures or models.

'''Should not be imported''' the files that are loaded through the project's content and actions tab (except the XML UI files, those ones should always be imported). While this is harmless most of the time, this can sometimes result in unexpected side-effects.
* The Lua files that are directly loaded through the project's content tab. This does not apply if the Lua file is associated with a XML file and you load this XML file instead. Note that if you want a Lua file to be included by other Lua or XML UI files, you will still have to import it into the VFS but you may see it loaded more times than necessary.
* The XML data and text files. Those ones are only ran at start up to modify the data tables.
* The SQL files. For the same reasons.

= Importing a file into the VFS =
* In ModBuddy, select a file in the solution explorer.
* Hit F4 (or click View > Properties Window) to open its properties.
* At the bottom of this new window, look for '''Import into VFS''' and set it to true.
* If Civ5 is opened, you will need to exit to the main menu for this change to be applied.

= Final warning =
{{Warning}} In some circumstances (notable the include statement in Lua, see [[Specificities of the Lua implementation in Civ5]], only the first eight characters of the file matter. Tow files starting with the same first eight characters could then be confused by the game.

[[Category:Civ5 Tutorials]]

Civ5 Modding Tutorials

2012-09-25T12:18:45Z

DonQuich:

= Getting started =
'''Get a tour.'''
:If you have no idea about modding and what are Lua and Xml, you should give a look at [http://www.weplayciv.com/forums/entry.php?15-Dale-s-Mod-Blog-Civ5-Modding-Explained Civ5 Modding Explained].
'''Read the guide.'''
:The best introduction to civ5 modding is still the '''[http://forums.civfanatics.com/showthread.php?t=385009 Kael's Guide]'''. However it was written a long time ago and some informations are obsolete or missing.
'''Import your files into VFS.'''
:The main change since Kael wrote his guide is about the [[VFS (Civ5)|VFS]] (Virtual File System). Forgetting to import files into the VFS is the common source of problems for beginners.
'''Get the right tools for the job.'''
:See [[Civ5 Useful Programs]]. You should have installed the SDK of course, but it is also strongly recommended that you get a tool to search in all civ5 files at once, to compensate for the lack of documentation. You may also need additional softwares to extract and read the textures, test and debug your mod, etc.
'''Modify your ini files.'''
:See [[Debugging (Civ5)#Configuration|Debugging#Configuration]].

= Tutorials =
See also the [http://forums.civfanatics.com/forumdisplay.php?f=394&order=desc&page=2 Modding tutorials section] on the forums.<br/>
Also note that the [[Civ5 XML Reference|XML]] and [[Lua and UI Reference|Lua]] sections each contain specific tutorials, articles and extensive documentation.

=== General ===
* [[Modding Limits and Issues (Civ5)|Modding Limits and Issues]]
* [http://forums.civfanatics.com/showthread.php?t=459392 Create and use DDS textures]
* [http://forums.civfanatics.com/showthread.php?t=449431 Adding custom data and using them in Lua]
* [http://wiki.2kgames.com/civ5/index.php/Mods:LocalizationSyntax Localization Syntax]
* [[Debugging (Civ5)|Debugging]]

=== Common tasks ===
* [http://forums.civfanatics.com/showthread.php?t=391823 New Leaders (2D images)]
* [http://forums.civfanatics.com/showthread.php?t=389782 New Resources]
* [http://forums.civfanatics.com/showthread.php?t=470290 New Buildings]
* [http://forums.civfanatics.com/showthread.php?t=406877 New Specialists]
* [http://forums.civfanatics.com/showthread.php?t=392985 New Units]

=== Specific topics ===
* [http://forums.civfanatics.com/showthread.php?t=468374 Culture buildings - vanilla and G&K cross compatibility]
* [http://forums.civfanatics.com/showthread.php?t=394056 Import civ4 units into civ5]
* [http://forums.civfanatics.com/showthread.php?t=405148 Locking techs on a civilization basis]
* [http://forums.civfanatics.com/showthread.php?t=396911 Making units that use Civ5 animations]
* [http://forums.civfanatics.com/showthread.php?t=474309 Guide to Adding a new Resource with Custom Reskins]
* [[Text icons and markups (Civ5)|Text icons and markups]]
* [[VFS (Civ5)|VFS]]

[[Category:Civ5 Tutorials]]

Persisting data (Civ5)

2012-09-25T12:12:31Z

DonQuich:

''This page is a part of the [[Lua and UI Reference (Civ5)|Lua and UI Reference]].''

This article explains how to store data that are persisted when the user saves his game, or at anytime for mods settings.

= Opening or creating a storage space =

Mods can store data in the following containers:
* Global storage spaces accessible at any time. To store mods settings for example.
* One local storage space embedded in savegames. A zombie mod could for example use it to store the locations where units died in case they should be resurrected later.

=== Global storage spaces ===
You create/open such a space by using: <code>{{Type5|ModData}} Modding.{{Func5|Modding|OpenUserData}}('''string''' name, '''int''' version)<code>.
* Many modders specify their mod's GUID as a name. However this is not mandatory and it is not necessary the best practice for the end-user since it produces undecipherable files names. We suggest you just make sure to provide a unique name to avoid conflicts between mods.
* This storage space will be stored under a file in <code>My Games/Sid Meier's Civilization V/ModUserData/</code>. The file name will be the name you provided with the ".db" extension.
* Mods can use the same space if they share common settings for example. However it cannot be used as a communication channel it is not possible to listen for changes.
* One mod can create as much spaces as it wants.

=== Savegame's storage space ===
You can create/open the savegame's storage space by using: <code>{{Type5|ModData}} Modding.{{Func5|Modding|OpenSaveData}}()</code>.
* This space is shared by all mods, so beware of keys names conflicts: when saving a property try to prepend its name with a unique prefix for your mod "IGE_" for In-game editor, "RED_" for R.E.D., etc.
* The content of this space is written directly in the savegame file whenever the user saves his game.

= Using the storage space =
=== Get or set value ===
Once you retrieve a {{Type5|ModData}} instance, this one exposes the following methods:
* <code>{{Func5|ModData|SetValue}}('''string''' name, '''variant''' data)</code>
* <code>'''variant''' {{Func5|ModData|GetValue}}('''string''' name)</code>
A few remarks:
* Data can be '''nil''', '''bool''', '''number''' or '''string'''.
* If you query a value never assigned before, it will be nil.

=== Dealing with default values ===
Since it is not possible to know whether the value you just did read already existed before, you need to deal with the default nil values you will encounter. Here are some examples:
<div class="civ5-example"><syntaxhighlight lang="lua">
local db = Modding.OpenSaveData()
local trueByDefault = db.GetValue("trueByDefault") ~= "false" -- False if "false", true otherwise
local falseByDefault = db.GetValue("falseByDefault") == "true" -- True if "true", false otherwise
local oneByDefault = db.GetValue("oneByDefault") or 1 -- 1 if nil or false, the value otherwise
</syntaxhighlight></div>

= Addressing performances problems =
The {{Type5|ModData}} you get is implemented through a database table. This means that every value read/write will generate a request string, this one will have to be parsed, etc. If you frequently read or write values, this can greatly hinder the game's performances.

=== Using a local cache ===
Dealing with the reads is pretty easy, we only need to create a local copy of the properties, as demonstrated in the G&K scenarios. Instead of calling {{Func5|ModData|GetValue}} and {{Func5|ModData|SetValue}} directly, we will use the following wrappers:
<div class="civ5-example"><syntaxhighlight lang="lua">
g_SaveData = Modding.OpenSaveData()
g_Properties = {}

function GetPersistentProperty(name)
if not g_Properties[name] then
g_Properties[name] = g_SaveData.GetValue(name)
end
return g_Properties[name]
end

function SetPersistentProperty(name, value)
if GetPersistentProperty(name) == value then return end
g_SaveData.SetValue(name, value)
g_Properties[name] = value
end
</syntaxhighlight></div>

=== Persisting tables ===
A convenient and fast solution is to save tables, by exploiting the [http://www.lua.org/manual/5.1/manual.html#pdf-loadstring loadstring] table. The following implementation is a simple and naive one with the following limitations:
* Strings cannot contain the "]]" sequence.
* Can only save nils, booleans, numbers, strings, and tables. No functions or API Objects like {{Type5|Player}}.
* No identity preservation: if a sub-table is stored twice in the provided table, it will be deserialized as two different tables.
* It has not been tested, there may be errors.
<div class="civ5-example"><syntaxhighlight lang="lua">
function ToLuaCode(item)
if type(item) == "nil" then return "nil" end
if type(item) == "bool" then return tostring(item) end
if type(item) == "number" then return tostring(item) end
if type(item) == "string" then return "[[" .. item .. "]]" end
if type(item) ~= "table" then error("could not serialize an element") end

local str = "{"
for k, v in pairs(item) do
str = str .. "[" .. ToLuaCode(k) .. "] = " .. ToLuaCode(v) .. ", "
end
return str.."}"
end

function SetPersistentTable(name, t)
g_SaveData.SetValue(name, ToLuaCode(t))
g_Properties[name] = t
end

function GetPersistentTable(name)
if not g_Properties[name] then
local code = g_SaveData.GetValue(name)
g_Properties[name] = loadstring(code)()
end
return g_Properties[name]
end
</syntaxhighlight></div>

=== Just-in-time writes ===
The previous tricks unfortunately do not address the problem entirely if you need frequent writes (for example anytime a unit moves). A good idea in theory would be to detect when the user is going to save his game so that you only write data at this point. Unfortunately there is no event for this circumstance and while it is possible to hijack the "quicksave" hotkey and the "save" menu, '''this creates a whole bunch of incompatibilities with other mods'''. Use it in last resort. If you want to see an implementation example, look at the R.E.D. WWII mod.

Another alternative is to use custom tables, as described in the next section.

= Alternatives =

=== Using the script data (mostly deprecated) ===
Every {{Type5|Player}}, {{Type5|Plot}} and {{Type5|Unit}} can hold one string.
* Strings are set through Player:{{Func5|Player|SetScriptData}}, Plot:{{Func5|Plot|SetScriptData}}, and Unit:{{Func5|Unit|SetScriptData}}
* Strings are retrieved through Player:{{Func5|Player|GetScriptData}}, Plot:{{Func5|Plot|GetScriptData}}, and Unit:{{Func5|Unit|GetScriptData}}
* Those data are shared between mods so this is a frequent cause of conflicts.
* There were more of those "SetScriptData" methods in the past, on other objects, but they have been removed on May 2012 by Firaxis. It is possible that Firaxis also removes the last three ones at a later point.
* Users interested in this solution should give a look at the [http://forums.civfanatics.com/showthread.php?t=392958 SaveUtils] library from Whys.

=== Using a custom table ===
If you want you may use a custom data table, although it has few advantages. It's not very convenient and if you were using it to store one row at once, you would encounter the same performances problems as {{Type5|ModData}}. However writing one or thousands of values at once in a data table makes small difference in the execution time so you could use it for batch updates and get good results. This can be an alternative to the table persistence method explained before. This can be done through <code>DB.{{Func5|DB|Query}}('''variant''' data)</code>. Users interested in this solution should also give a look at the [http://forums.civfanatics.com/showthread.php?t=442249 TableSaverLoader] library from Pazyryk.

Here is an example where we store magic points for some units (untested):
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Create table if not already done on mod loading
if not GetPersistentProperty("MyMod_initialized") then
DB.Query("CREATE TABLE UnitsMagic( id INTEGER PRIMARY KEY UNIQUE, value INTEGER);")
SetPersistentProperty("MyMod_initialized", true)
end

-- SaveAll takes a table[playerID][unitID] = value
function SaveAll(magicPoints)
local query = ""
for playerID, playerTable in ipairs(magicPoints) do
for unitID, magicPoints in ipairs(playerTable) do
-- Units' ID are player-specific only, so we compute a global unique identifier from the player's and unit's identifiers.
local ID = playerID * 10000 + unitID
query = query.."REPLACE INTO UnitsMagic (id, value) VALUES ("..ID..", "..magicPoints..");\n"
end
end
DB.Query(query)
end
</syntaxhighlight></div>

[[Category:Civ5 API]]
[[Category:Civ5 Tutorials]]

Persisting data (Civ5)

2012-09-25T12:12:03Z

DonQuich:

''This page is a part of the [[Lua and UI Reference (Civ5)|Lua and UI Reference]].''

This article explains how to store data that are persisted when the user saves his game, or at anytime for mods settings.

= Opening or creating a storage space =

Mods can store data in the following containers:
* Global storage spaces accessible at any time. To store mods settings for example.
* One local storage space embedded in savegames. A zombie mod could for example use it to store the locations where units died in case they should be resurrected later.

=== Global storage spaces ===
You create/open such a space by using: <code>{{Type5|ModData}} Modding.{{Func5|Modding|OpenUserData}}('''string''' name, '''int''' version)<code>.
* Many modders specify their mod's GUID as a name. However this is not mandatory and it is not necessary the best practice for the end-user since it produces undecipherable files names. We suggest you just make sure to provide a unique name to avoid conflicts between mods.
* This storage space will be stored under a file in <code>My Games/Sid Meier's Civilization V/ModUserData/</code>. The file name will be the name you provided with the ".db" extension.
* Mods can use the same space if they share common settings for example. However it cannot be used as a communication channel it is not possible to listen for changes.
* One mod can create as much spaces as it wants.

=== Savegame's storage space ===
You can create/open the savegame's storage space by using: <code>{{Type5|ModData}} Modding.{{Func5|Modding|OpenSaveData}}()</code>.
* This space is shared by all mods, so beware of keys names conflicts: when saving a property try to prepend its name with a unique prefix for your mod "IGE_" for In-game editor, "RED_" for R.E.D., etc.
* The content of this space is written directly in the savegame file whenever the user saves his game.

= Using the storage space =
=== Get or set value ===
Once you retrieve a {{Type5|ModData}} instance, this one exposes the following methods:
* <code>{{Func5|ModData|SetValue}}('''string''' name, '''variant''' data)</code>
* <code>'''variant''' {{Func5|ModData|GetValue}}('''string''' name)</code>
A few remarks:
* Data can be '''nil''', '''bool''', '''number''' or '''string'''.
* If you query a value never assigned before, it will be nil.

=== Dealing with default values ===
Since it is not possible to know whether the value you just did read already existed before, you need to deal with the default nil values you will encounter. Here are some examples:
<div class="civ5-example"><syntaxhighlight lang="lua">
local db = Modding.OpenSaveData()
local trueByDefault = db.GetValue("trueByDefault") ~= "false" -- False if "false", true otherwise
local falseByDefault = db.GetValue("falseByDefault") == "true" -- True if "true", false otherwise
local oneByDefault = db.GetValue("oneByDefault") or 1 -- 1 if nil or false, the value otherwise
</syntaxhighlight></div>

== Addressing performances problems ==
The {{Type5|ModData}} you get is implemented through a database table. This means that every value read/write will generate a request string, this one will have to be parsed, etc. If you frequently read or write values, this can greatly hinder the game's performances.

=== Using a local cache ===
Dealing with the reads is pretty easy, we only need to create a local copy of the properties, as demonstrated in the G&K scenarios. Instead of calling {{Func5|ModData|GetValue}} and {{Func5|ModData|SetValue}} directly, we will use the following wrappers:
<div class="civ5-example"><syntaxhighlight lang="lua">
g_SaveData = Modding.OpenSaveData()
g_Properties = {}

function GetPersistentProperty(name)
if not g_Properties[name] then
g_Properties[name] = g_SaveData.GetValue(name)
end
return g_Properties[name]
end

function SetPersistentProperty(name, value)
if GetPersistentProperty(name) == value then return end
g_SaveData.SetValue(name, value)
g_Properties[name] = value
end
</syntaxhighlight></div>

=== Persisting tables ===
A convenient and fast solution is to save tables, by exploiting the [http://www.lua.org/manual/5.1/manual.html#pdf-loadstring loadstring] table. The following implementation is a simple and naive one with the following limitations:
* Strings cannot contain the "]]" sequence.
* Can only save nils, booleans, numbers, strings, and tables. No functions or API Objects like {{Type5|Player}}.
* No identity preservation: if a sub-table is stored twice in the provided table, it will be deserialized as two different tables.
* It has not been tested, there may be errors.
<div class="civ5-example"><syntaxhighlight lang="lua">
function ToLuaCode(item)
if type(item) == "nil" then return "nil" end
if type(item) == "bool" then return tostring(item) end
if type(item) == "number" then return tostring(item) end
if type(item) == "string" then return "[[" .. item .. "]]" end
if type(item) ~= "table" then error("could not serialize an element") end

local str = "{"
for k, v in pairs(item) do
str = str .. "[" .. ToLuaCode(k) .. "] = " .. ToLuaCode(v) .. ", "
end
return str.."}"
end

function SetPersistentTable(name, t)
g_SaveData.SetValue(name, ToLuaCode(t))
g_Properties[name] = t
end

function GetPersistentTable(name)
if not g_Properties[name] then
local code = g_SaveData.GetValue(name)
g_Properties[name] = loadstring(code)()
end
return g_Properties[name]
end
</syntaxhighlight></div>

=== Just-in-time writes ===
The previous tricks unfortunately do not address the problem entirely if you need frequent writes (for example anytime a unit moves). A good idea in theory would be to detect when the user is going to save his game so that you only write data at this point. Unfortunately there is no event for this circumstance and while it is possible to hijack the "quicksave" hotkey and the "save" menu, '''this creates a whole bunch of incompatibilities with other mods'''. Use it in last resort. If you want to see an implementation example, look at the R.E.D. WWII mod.

Another alternative is to use custom tables, as described in the next section.

= Alternatives =

=== Using the script data (mostly deprecated) ===
Every {{Type5|Player}}, {{Type5|Plot}} and {{Type5|Unit}} can hold one string.
* Strings are set through Player:{{Func5|Player|SetScriptData}}, Plot:{{Func5|Plot|SetScriptData}}, and Unit:{{Func5|Unit|SetScriptData}}
* Strings are retrieved through Player:{{Func5|Player|GetScriptData}}, Plot:{{Func5|Plot|GetScriptData}}, and Unit:{{Func5|Unit|GetScriptData}}
* Those data are shared between mods so this is a frequent cause of conflicts.
* There were more of those "SetScriptData" methods in the past, on other objects, but they have been removed on May 2012 by Firaxis. It is possible that Firaxis also removes the last three ones at a later point.
* Users interested in this solution should give a look at the [http://forums.civfanatics.com/showthread.php?t=392958 SaveUtils] library from Whys.

=== Using a custom table ===
If you want you may use a custom data table, although it has few advantages. It's not very convenient and if you were using it to store one row at once, you would encounter the same performances problems as {{Type5|ModData}}. However writing one or thousands of values at once in a data table makes small difference in the execution time so you could use it for batch updates and get good results. This can be an alternative to the table persistence method explained before. This can be done through <code>DB.{{Func5|DB|Query}}('''variant''' data)</code>. Users interested in this solution should also give a look at the [http://forums.civfanatics.com/showthread.php?t=442249 TableSaverLoader] library from Pazyryk.

Here is an example where we store magic points for some units (untested):
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Create table if not already done on mod loading
if not GetPersistentProperty("MyMod_initialized") then
DB.Query("CREATE TABLE UnitsMagic( id INTEGER PRIMARY KEY UNIQUE, value INTEGER);")
SetPersistentProperty("MyMod_initialized", true)
end

-- SaveAll takes a table[playerID][unitID] = value
function SaveAll(magicPoints)
local query = ""
for playerID, playerTable in ipairs(magicPoints) do
for unitID, magicPoints in ipairs(playerTable) do
-- Units' ID are player-specific only, so we compute a global unique identifier from the player's and unit's identifiers.
local ID = playerID * 10000 + unitID
query = query.."REPLACE INTO UnitsMagic (id, value) VALUES ("..ID..", "..magicPoints..");\n"
end
end
DB.Query(query)
end
</syntaxhighlight></div>

[[Category:Civ5 API]]
[[Category:Civ5 Tutorials]]

Map and terrain (Civ5)

2012-09-25T12:11:41Z

DonQuich:

''This page is a part of the [[Lua and UI Reference (Civ5)|Lua and UI Reference]].''

= Layout =

=== Coordinates systems ===
Civ5 uses three different coordinates systems for plots:
* The '''world coordinates'''. The coordinates of the plot's graphics in the 3D space where the world is rendered. This system is only used when you want to display an icon over the map, through a {{Type5|WorldAnchor}}.
* The '''grid coordinates'''. The logical coordinates of a plot. This is the system returned by Plot:{{Func5|Plot|GetX}}() and Plot:{{Func5|Plot|GetY}}()
* The '''hex coordinates'''. The logical coordinates of a plot. Some computations are easier to perform in this system.

{|
|-
|valign="top" |[[File:Coords-Grid.png|frame|The grid coordinates: horizontal and vertical axes are orthogonal.]]
|width="20px"|
|valign="top" |[[File:Coords-Hex.png|frame|The hex coordinates: the vertical axis makes a 60° angle with the horizontal axis.]]
|}
The reason behind the coexistence of the grid and hex coordinates is because most computations are easier to perform in the hex system. For example, if you wish to examine the neighbors of a plot...
* In the grid coordinates, you first need to test whether y is odd or even. Depending on the result, the offsets of the top plots will be { (0,1), (1,1) } or { (-1,1), (0,1)}.
* However no such test is required in the hex system: the top offsets are always { (-1,1), (0,1) }.

=== Helpful functions ===
The following global functions will help you:
{|
|-
|align="right"|<code>{{Type5|Vector2}}</code>
|width="6px"|
|<code>{{Func5|Vector2}}(int x, int y)</code> makes a 2D vector.
|-
|align="right"|<code>int, int</code>
|width="6px"|
|<code>{{Func5|ToGridFromHex}}(int x, int y)</code>
|-
|align="right"|<code>int, int, int </code>
|width="6px"|
|<code>{{Func5|GridToWorld}}(int x, int y)</code>
|-
|align="right"|<code>{{Type5|Vector2}}</code>
|width="6px"|
|<code>{{Func5|ToHexFromGrid}}({{Type5|Vector2}} hexPos)</code>
|-
|align="right"|<code>{{Type5|Vector3}}</code>
|width="6px"|
|<code> {{Func5|HexToWorld}}({{Type5|Vector2}} hexPos)</code>
|}

=== Plots indexing ===
The function Map.{{Func5|Map|GetPlotByIndex}}(int index) takes an index and returns a plot. This index can be computed as follow:
<div class="civ5-example"><syntaxhighlight lang="lua">
local w = Map.GetGridSize()
local index = gridX + gridY * w
</syntaxhighlight></div>

=== Enumerating neighbor plots ===
The best way is to use <code>Map.{{Func5|Map|PlotDirection}}('''int''' x, '''int''' y, {{Type5|DirectionType}} direction)</code>.
<div class="civ5-example"><syntaxhighlight lang="lua">
local x, y = ... -- Initialize those
for i = 0, 5 do
local plot = Map.PlotDirection(x, y, i)
-- Do something with plot
end
</syntaxhighlight></div>

=== Enumerating plots in a certain range ===
If you need to enumerate plots in specific orders, you should look at [http://forums.civfanatics.com/showthread.php?t=474634 Border and plots iterator], a great library from Whoward69 who provides nice iterators for different scan orders.<br/>

Otherwise, Map.{{Func5|Map|PlotXYWithRangeCheck}} offers a simple way to scan all plots within a certain range.
<div class="civ5-example"><syntaxhighlight lang="lua">
local x, y = ... -- Initialize those
local range = 5
for dx = -range, range do
for dy = -range, range do
local plot = Map.PlotXYWithRangeCheck(x, y, dx, dy, range)
if plot then
-- Do whatever you want with this plot
end
end
end
</syntaxhighlight></div>

=== The world is not flat ===
Maps can be wrapped along X or Y. You can get those values through Map.{{Func5|Map|IsWrapX}}() and Map.{{Func5|Map|IsWrapY}}().
* When wrapped along X, reaching the west side of the map brings you to the east side.
* When wrapped along Y, reaching the north side brings you to the south side.
* A map can neither be wrapped along X, neither around Y. For example a map that only covers a part of the world.
* A map cannot be both wrapped along X and Y.

= Terrain =
=== Nature ===
The nature, aspect and value of a {{Type5|Plot}} in civ5 are defined by the following data:
* {{Type5|PlotType}}. It can be ocean (includes lakes and coasts), land, hills or mountain.
* {{Type5|TerrainType}}. It can be ocean, coast (lake or coast), grasslands, plains, tundra or snow. A coast is automatically a lake if it belongs to a water area not larger than nine plots (see the [[#Areas|next section]]).
* {{Type5|FeatureType}}. It can be none, forest, jungle, floodplains, marsh, oasis, ice, fallout or any natural wonder.
* {{Type5|ResourceType}} and a quantity value. It can be any resource: gold, gems, horses, fish, etc.
* {{Type5|ImprovementType}} and a "pillaged" boolean flag. It can be any improvement: mines, farm, etc. Goodies, city ruins and barbarian camps are also improvements.
* {{Type5|RouteType}}. It can be none, road or railroad.
* {{Type5|ArtStyleType}}. It can be South America, Asian, European, Middle-East, Polynesian Greco-Roman or Barbarian. It decides which graphics will be used to render the plot.
* Besides of those, a plot also stores its coordinates, references to the city and units it hosts, its owner index, and visibility flags for every player in the game.

=== Areas ===
* The map is divided into different areas: one per landmass and one per watermass. That is, all plots in an island belong to the same area, which is different from the closest continent's area. Every lake or inner sea also has their own areas.
* Areas are represented in the API by the {{Type5|Area}} type.
* Water areas that contains nine plots at most are lakes. Otherwise they are oceans.
* Areas are computed when the map is generated, through Map.{{Func5|Map|RecalculateAreas}}(). You should not recompute them unless you turn some plots from water to land and reciprocally.
* In Civ4 impassable plots had their distinct areas and they could diode a landmass into sub-areas. This is no longer true in civ5.

= Rivers =
=== Methods ===
[[File:RiverSides.png|frame|You can only query or modify three edges per plot: E, SE, SW]]
[[File:RiverFlow.png|frame|Illustration of the {{Type5|FlowDirectionType}} on every edge.]]
Every plot has:
* Three status getters:
** <code>'''bool''' Plot:IsWOfRiver()</code>. Checks the east edge (IsWOfRiver stands for "is at the west of a river")
** <code>'''bool''' Plot:IsNWOfRiver()</code>. SE edge.
** <code>'''bool''' Plot:IsNEOfRiver()</code>. SW edge.
* Three direction getters:
** <code>{{Type5|FlowDirectionType}} Plot:GetRiverEFlowDirection()</code>.
** <code>{{Type5|FlowDirectionType}} Plot:GetRiverSEFlowDirection()</code>.
** <code>{{Type5|FlowDirectionType}} Plot:GetRiverSWFlowDirection()</code>.
* Three setters:
** <code>Plot:SetWOfRiver('''bool''' hasRiver, {{Type5|FlowDirectionType}} flow = -1)</code>.
** <code>Plot:SetNWOfRiver('''bool''' hasRiver, {{Type5|FlowDirectionType}} flow = -1)</code>.
** <code>Plot:SetNEOfRiver('''bool''' hasRiver, {{Type5|FlowDirectionType}} flow = -1)</code>.
* Two generalized getters that return true if there is a river in the specified direction (or towards the specified plot):
** <code>'''bool''' Plot:{{Func5|Plot|IsRiverCrossing}}({{Type5|DirectionType}} direction)</code>
** <code>'''bool''' Plot:{{Func5|Plot|IsRiverCrossingToPlot}}({{Type5|Plot}} toPlot)</code>

=== Generalized functions ===
The fact that you can only query three edges is troublesome. Here are simple functions to circumvent this limitation. Note that the HasRiver function is redundant with the {{Func5|Plot|IsRiverCrossing}} and {{Func5|Plot|IsRiverCrossingToPlot}} methods.
<div class="civ5-example" style="clear:none;"><syntaxhighlight lang="lua">
function HasRiver(plot, direction)
if direction == 1 then return plot:IsWOfRiver() end
if direction == 2 then return plot:IsNWOfRiver() end
if direction == 3 then return plot:IsNEOfRiver() end
local neighbor = Map.PlotDirection(plot:GetX(), plot:GetY(), direction)
return HasRiver(neighbor, direction - 3)
end

function GetRiverFlow(plot, direction)
if direction == 1 then return plot:GetRiverEFlowDirection() end
if direction == 2 then return plot:GetRiverSEFlowDirection() end
if direction == 3 then return plot:GetRiverSWFlowDirection() end
local neighbor = Map.PlotDirection(plot:GetX(), plot:GetY(), direction)
return GetRiverFlow(neighbor, direction - 3)
end

function SetRiver(plot, direction, hasRiver, flowDirection)
if direction == 1 then return plot:SetWOfRiver(hasRiver, flowDirection) end
if direction == 2 then return plot:SetNWOfRiver(hasRiver, flowDirection) end
if direction == 3 then return plot:SetNEOfRiver(hasRiver, flowDirection) end
local neighbor = Map.PlotDirection(plot:GetX(), plot:GetY(), direction)
return SetRiver(neighbor, direction - 3, hasRiver, flowDirection)
end
</syntaxhighlight></div>

[[Category:Civ5 API]]
[[Category:Civ5 Tutorials]]

Lua Libraries for Civ5

2012-09-25T12:11:21Z

DonQuich:

''This page is a part of the [[Lua and UI Reference (Civ5)|Lua and UI Reference]].''

= Improving modularity and mods compatibility =
Sometimes mods needs to modify the standard game files in order to achieve some features. Since only one mod can modify a given file a a time, this creates conflicts. Those libraries address those issues: all mods use the same file replacement and this one exposes a way to register new entries and such.
{| cellpadding="4"
|-
!Name
!Author
!Description
|-
|valign="top" |[http://forums.civfanatics.com/showthread.php?t=411186 Fully Modifyable Custom Notifications]
|valign="top" |''Sneaks''
|Provides a non-conflicting way for mods to add custom notifications.
|-
|valign="top" |[http://forums.civfanatics.com/showthread.php?p=11394279 Modular Diplo Corner]
|valign="top" |''Whoward69''
|Provides a non-conflicting way for mods to add entries to the diplo corner menu. While Civ5 now offers a similar functionality in standard, this mod still offers the benefit to prevent compatibility issues between updated and outdated mods.
|-
|valign="top" |[http://forums.civfanatics.com/showthread.php?t=458740 Modular Minimap Overlays]
|valign="top" |''Whoward69''
|Provides a non-conflicting way for mods to add entries to the minimap overlays menu.
|-
|valign="top" |[http://forums.civfanatics.com/showthread.php?t=459207 Modular Summary Bar]
|valign="top" |''Whoward69''
|Provides a non-conflicting way for mods to add entries to the topmost bar, near the turn number.
|}

= Other libraries =
{| cellpadding="4"
|-
!Name
!Author
!Description
|-
|[http://forums.civfanatics.com/showthread.php?t=474634 Border and Area Plot Iterators]
|''Whoward69''
|Provides iterators to enumerate plots in a given range and in different orders.
|-
|[http://forums.civfanatics.com/showthread.php?t=392958 SaveUtils]
|''Whys''
|Wrappers around the SetScriptData methods (partially deprecated) for conveniency purpose and mods conflicts prevention. See also [[Persisting data (Civ5)]].
|-
|[http://forums.civfanatics.com/showthread.php?t=442249 TableSaverLoader]
|''Pazyryk''
|Saves a Lua table into a custom data table. See also [[Persisting data (Civ5)]].
|}

[[Category:Civ5 API]]

Civ5 API Reference FAQ

2012-09-25T12:10:55Z

DonQuich:

''This page is a part of the [[Lua and UI Reference (Civ5)|Lua and UI Reference]].''

=Types terminology=
{| cellpadding="8"
|-
|valign="top"|
* <code>'''unknown'''</code>
|This parameter's type could not be identified.
|-
|valign="top"|
* <code>'''string'''</code>
|A Lua string.
|-
|valign="top"|
* <code>'''int'''</code>
|Any integer.
|-
|valign="top"|
* <code>'''float'''</code>
|Any number, integer or floating-point.
|-
|valign="top"|
* <code>'''table'''</code>
|An unidentified table. Look at the code samples to figure it out by yourself.
|-
|valign="top"|
* <code>'''table(key => value)'''</code>
|A table whose keys and values have the specified types.
:Example: <code>table({{Type5|PlayerID}} => {{Type5|Player}}) players</code>
::It can be enumerated with: <code>for playerID, player in ipairs(players) do</code>
::The following will return a {{Type5|Player}}: <code>players[0]</code>
|-
|valign="top"|
* <code>'''iterator(type1, type2, type3)'''</code>
|To be used in a <code>for... in...</code> loop.
:Example: <code>iterator({{Type5|Unit}}) Units()</code>
::It can be enumerated with: <code>for pUnit in Units() do</code>.
|-
|valign="top"|
* <code>'''variant'''</code>
|This parameter can be assigned with different types.
:Example: <code>DB.{{Func5|DB|Query}}('''variant''' arg)</code>
::This function can accept a string or a table.
|-
|valign="top"|
* <code>'''...'''</code>
|A variable number of arguments. A good example is Locale.{{Func5|Locale|ConvertTextKey}}.
|}

=Object-oriented concepts in Lua=
The concepts below originate from object-oriented languages. But since Lua is weakly typed, it offers richer possibilities than those languages. As a result those concepts may sometimes lack relevance and may need to be adapted or broaden. However they're still adequate since most of the API reflects the types defined in C++ by Firaxis.

'''Instance versus static types'''
* Instance types can be instanced, such as {{Type5|Player}}.
* Static types exist as a single global variable, such as {{Type5|Game}}.
* Some types can be both, such as {{Type5|InstanceManager}}: a global variable exists with this name and calling its {{Func5|InstanceManager|new}} method creates a new instance of {{Type5|InstanceManager}}.

'''Functions versus methods'''
* We call method any function stored as a type member.
* This is purely aesthetic: a function and a method are both called and used in the same way. We could store a method in a local variable and use it as a function.

'''Instance methods'''
* They are methods that require the caller to be passed as the first argument.
* The colon (''':''') operator implicitly passes the caller as the first argument. Those two expressions are equivalent: <code>caller.somefunc(caller, arg)</code> and <code>caller:somefunc(arg)</code>
* When declaring methods, the caller is referenced as the '''self''' keyword. It can be explicitly defined or not, see [[Lua introduction for confirmed developers]].

'''Events'''
* Events in the civ5 API can be (un-)subscribed this way: <code>Events.SomeEvent.Add(Handler)</code> and <code>Events.SomeEvent.Remove(Handler)</code>
* They can be invoked like regular methods: <code>Events.SomeEvent(arg1, arg2)</code>
* Events typically do not expect any return type. But the ones in {{Type5|GameEvents}} usually expect an integer or a boolean, see their documentations.

=Reliability of the documentation=
'''All listed functions exist.'''
:But some of them may be malfunctioning. Ghost functions have been removed by checking the binaries strings tables.

'''Some functions may not be listed.'''
:Only the methods that can be enumerated by a Lua code, the ones mentioned on the 2k wiki, and the ones used by the Lua source code from Firaxis are listed. A few additional functions found in the binaries have been added but this scan is quite superficial.

'''Some functions could have hidden arguments/return types.'''
:There could be additional arguments not listed because they were never used or documented by Firaxis.

'''Some functions arguments could be actually optional.'''
:Reciprocally, some of the arguments listed could be optional: Firaxis always used them but it does not mean they always need to be used.

'''Arguments' default values are not reliable.'''
:They are mostly here to notify you that an argument is optional. While '''nil''' is always an acceptable value to provide in such a case, a nil for a boolean will probably be interpreted as '''false''' (but it could be '''true''') and an integer as '''0''' (but it could be anything else).

'''The arguments' types and returned types are not always reliable.'''
:While a lot of efforts were done to ensure the typing is reliable, this problem cannot be solved unambiguously. The current compromise between truthfulness and completeness is quite good but it could still be improved and, anyway, it cannot be perfect without human corrections.

'''Most of those types are only here for documentation purpose'''
:The structures and identifiers are never mentioned anywhere in the API, they have been introduced for documentation purposes only. Lua and the API just treat them as tables (for structures) and integers (for identifiers). That being said, the structures obviously have C++ counterparts behind them. There could be additional structures that are not listed.

=Pages generation process=
The initial versions of those pages were automatically generated by a bot written in C# by [[User:DonQuich|DonQuiche]].

Here are the first steps of this bot:
* We manually define the existing type names and their natures (identifier, structure, etc)
* The [http://wiki.2kgames.com/civ5/index.php/Lua_Game_Objects 2kgames wiki] is scanned. It is sparse, the types are rarely mentioned and the informations are sometimes incorrect or obsolete.
* Manual fixes are applied to core functions that will trigger type inference cascades later during the Lua source code analysis.
* Two lua dumps (with and without G&K) are scanned to collect members. They have been generated by a home-brewed mod that outputs the members on all types, enumerations and their metatables.
* The binaries are scanned to detect additional functions for a few types. The process is rudimentary and does not collect many informations.
* The database files are scanned, this will be used to infere types from calls to GameInfos and such during the Lua source code analysis.

Then we parse the Lua and UI source files from the base game, G&K and most DLC. This step produces an inference graph and assembles the code samples. This is the main information source for the bot and the most important step.
* The inference graph is a bastardized version of a minimalist AST (abstract syntax tree), specialized for type equations resolution. It describes relations such as: ''argument 0 in SomeType.SomeFunc is assigned by the third return type of OtherType.OtherFunc, and also by...''.
* The inference graph is solved in order to infer all the arguments and return types. During this process we also update the arguments name, we detect unknown functions and arguments, new events, structures' fields, etc.
* The whole process implements its custom version of the VFS to manage includes. It manages to test all the possible combinations of different file versions to simulate the presence of absence of the expansions and DLC.

Finally, the whole API is known and the type system complete.
* The binaries (dll and exe) are scanned a second time to search for all the strings they contain. If a function's name does not appear in those tables, it means it no longer exists. This is the primary source to detect methods that have been removed (from the base game and/or G&K) and, while simple, it is very reliable.
* We then import manually written texts to be included in some of the generated pages.
* Finally we consolidate everything and we categorize the methods according to the keywords found in their names.
* All pages are generated using T4 templates and we upload the new wiki thanks to the [http://dotnetwikibot.sourceforge.net/ DotNetWikiBot] library.

[[Category:Civ5 API]]

Civ5 API FAQ

2012-09-25T12:10:31Z

DonQuich:

''This page is a part of the [[Lua and UI Reference (Civ5)|Lua and UI Reference]].''

= Firaxis Hungarian notation =
=== What is it? ===
Firaxis used a naming convention categorized as [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian Notation]. The prefixes provide informations regarding the type.
* '''s''', '''sz''' and '''str''' mean a string.
::Example: '''sName''' expects something like "Genghis Khan".
* '''b''' means boolean.
::Example: '''bHide''' expects true or false.
* '''f''' means floating-point, a number.
::Example: '''fScale''' expects a scale factor, may be 0.5, 1.0, 2.0, etc.
* '''i''' means integer, a number. Sometimes it may be one of the identifiers listed on the main page.
::Example: '''iPlayer''' expects a {{Type5|PlayerID}} while '''iWidth''' expects a width in pixels (50, 200, etc).
* '''e''' means an identifier (integer) taken from a Lua enumeration.
::Example: '''eBuilding''' expects a {{Type5|BuildingType}}. You could assign it with 10 or <code>GameInfoTypes.BUILDING_SEAPORT </code>, both are equivalent.
* '''p''' means an API object (p means pointer but pointer is a C term with no relevance in Lua).
::Example: '''pPlayer''' expects a {{Type5|Player}} object.

=== Should you use the same notation? ===
* Pro: it's widely used in the community and your code will harmonize with the one from Firaxis.
* Pro: you always now the type of a variable by looking at its name, which is useful since ModBuddy does not inform us about the type.
* Con: it adds some clutter and it's not really necessary because most of the time a consistent naming is enough to know the type of a variable: for example playerID for a {{Type5|PlayerID}} and player for a {{Type5|Player}}.

[[Category:Civ5 API]]

Lua introduction for confirmed developers

2012-09-25T12:10:25Z

DonQuich:

''This page is a part of the [[Lua and UI Reference (Civ5)|Lua and UI Reference]].''

= About Lua =
===Lua, not LUA===
This is a Portuguese word meaning "moon", not an acronym.

===Presentation===
Lua is an interpreted, dynamically typed, multi-paradigm language. It was designed in 1993 with the following objectives in mind:
* Extensible semantics. A small set of features allows the support of multiple paradigms, from functional programming to object programming. For example, while inheritance is not natively supported, it can be easily set up through metatables. The same features allow events in civ5 to behave both as functions and objects with Add and Remove methods.
* Highly portable. The con is a lightweight and somewhat lacking API.
* Easy to embed and to interface from other languages.
* Well suited for data description (''à la'' JSON).
* A beginners-friendly syntax.

===Performances===
As usual with interpreted and dynamically typed languages (hereby abusively named "scripting languages"), expect a 10 to 100 order of magnitude in performances decrease when compared to compiled and statically typed languages like C, C++ or C#. While it is possible for scripting languages to drastically improve the performances through more or less sophisticated means (expression trees/opcodes caching, JIT compiler, type inference to perform static resolutions), no such solution has been used in Civ5 (aside, probably, of the caching). And while an external JIT library exists, it causes compatibility problems with most mods using Lua.

That being said, Lua is still pretty good for a scripting language, better than the Python implementation from Civ4 for example. And all in all, it is fast enough for most of what modders want to achieve without the need to compromise code elegance, readability and maintainability for performances. So keep in mind that "premature optimization is the root of all evil" (Donald Knuth).

=Syntax cheatsheet=
=== Basics ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Literals
local x = 5
local x = 5.0
local x = nil -- A nil value is the same as an undefined value
local x = true
local x = false

-- Strings (single and double quotes can be used indifferently, there is no difference)
local x = "five"
local x = 'five'
local x = "five\n" -- Escape characters with "\".
local x = [[Five is a number.
Did you know?]] -- Multi-line string: equivalent to "Five is number.\nDid you know?"

-- Globals versus locals
x = 5 -- For globals, assigning is declaring.
local x = 5
</syntaxhighlight></div>

=== Operators ===
<div class="civ5-example"><syntaxhighlight lang="lua">
local x = a or b
local x = a and b

local x = "hello ".."world" .. "!" -- concatenation: two dots
local x = 4..5 -- Result is "45". On concatenation, conversions occur.

local x = (a + b - d) * f ^ g % h -- ^ is exponentiation, % is modulo
local x = "4" + "5" -- Result is 9. On arithmetic operations, conversions occur.

local x = a == b -- equality -- True only if a and b have the same values and types.
local x = a ~= b -- inequality

local x = ((a <= b) == not (a > b)) == ((a >= b) == not (a < b))
local x = "abc" < "def" -- Byte-wise comparison, not Unicode-compliant. Use Locale's methods instead.

local x = #"abc" -- Returns 3, the number of bytes in the string (3 characters, 1 byte each).
local x = #"您好世界" -- Returns 8, the number of bytes in the string (4 characters, 2 bytes each).
local x = #SomeTable -- Returns the biggest integer key in the table, or nil if there is no integer key.

-- No increment operator (++ --), no binary-assign operator (+= *=), no ternary operator (? :), no coalescence operator (??)
</syntaxhighlight></div>

=== Tables and multiple assignments ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Table declaration
SomeTable = {}

SomeArray = { "abc", "def" }
-- 1 => "abc", 2 => "def"

SomeComplexTable = { name = "John", surname = "Doe", age = 25, 43, [7] = 8 }
-- "name" => "John", "surname" => "Doe", "age" => 25, 1 => 43, 7 => 8.

-- Member access (all equivalent)
SomeTable.SomeMember = 5
SomeTable["SomeMember"] = 5

-- Multiple assignment
-- Both statements are equivalent since SomeArray contains "abc" and "def".
local x, y = "abc", "def"
local x, y = unpack(SomeArray)
</syntaxhighlight></div>

=== Functions ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Functions declarations (all equivalent)
function HelloWorld(a, b) print("Hello world") end
HelloWorld = function(a, b) print("Hello world") end
-- Functions are first-class objects and can be assigned like any other value!

-- Methods declarations (all equivalent)
SomeTable.HelloWorld(a, b) print("Hello world") end
SomeTable.HelloWorld = function(a, b) print("Hello world") end

-- Instanced methods declarations (all equivalent)
SomeTable.HelloWorldInstanced(self, a, b) print(self.SomeMember) end
SomeTable:HelloWorldInstanced(a, b) print(self.SomeMember) end

-- Functions and methods calls
HelloWorld(a) -- b will be nil in the function
HelloWorld(a, b)
SomeTable.HelloWorld(a, b)

-- Instanced methods calls (all equivalent)
SomeTable:HelloWorldInstanced(a, b)
SomeTable.HelloWorldInstanced(SomeTable, a, b)

-- Multiple return values
function func(a, b) return a, b end
local x, y, z = func(5, 6) -- Assigns 5 to x and 6 to y, z will be nil

-- Variable arguments
function SomeFunc(a, b, ...)
print(a)
print(b)
for i, v in ipairs(arg) do -- arg is a keyword for a table containing the variable arguments
print(v)
end
end
SomeFunc(1, 2, 3, 4, 5) -- prints 1, 2, 3, 4, 5
SomeFunc(1, 2) -- prints 1, 2
</syntaxhighlight></div>

=== Control flow ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- If
if name == "Wu Zetian" then
print("Hello China")
elseif name == "Napoleon" then -- "elseif", not "else if". Beware C developers!
print("Hello France")
else -- no "then" after "else"!
print("Hello unknown")
end

-- For loop (with counter)
for i = 1, 8 do print(i) end -- Prints 1, 2, 3, 4, 5, 6, 7, 8
for i = 1, 8, 2 do print(i) end -- Prints 1, 3, 5, 7

-- For loop (with iterator)
for playerID, pPlayer in pairs(Players) do -- Prints 1 Wu Zetian, 2 Napoleon, ...
print(playerID, pPlayer:GetName())
end
for plot in Plots() do -- Prints 0 0, 0 1, 0 2, ...
print(plot:GetX(), plot:GetY())
end

-- While (i will be 5 in the end)
while i < 5 do
i = i + 1
end

-- Repeat until (i will be 5 in the end)
repeat
i = i + 1
until i == 5

-- Infinite loops
-- Lua supports "break" for all loops but not "continue" instruction does not exist!
do
i = i + 1
if i > 5 then break end
end

</syntaxhighlight></div>

= Basics =
=== Type system ===
You can get a variable's type by using the '''type''' function. It takes any value and returns a string. Here are the possible results:
* '''nil''': Lua makes do distinction between an undefined variable and a variable with a nil value. Assigning nil to a variable or table member is equivalent to undefining it.
* '''number''': a 64 bits floating-point number. Lua has no support for integers and only use floating-points. See also [[#No integer type]].
* '''string''': your usual string of characters. In Lua all strings are interned. This speeds up comparisons but it makes allocation of new strings slower.
* '''boolean''': true or false obviously.
* '''table''': any table.
* '''userdata''': objects defined in C for use in Lua. They may not be enumerated through pairs and other limitations. Now the Civ5 API tend to return regular tables whose metatable is of type userdata, this allows us to use the provided objects as regular Lua tables.
* '''function''': remember that functions are first-class objects in Lua.
* '''thread''': coroutines actually. Lua does not support threads.

=== Implicit conversions ===
* Whenever you concatenate two values (and possibly when you invoke a standard function that takes a string), an automatic conversion to string occurs, as if you had used the '''tostring''' function. The expression <code>4..5</code> returns "45".
* Whenever you perform an arithmetic operation, the operands are both converted to numbers, as if you had used the '''tonumber''' function. The expression <code>"4" + "5"</code> returns 9.

=== Strict equality comparisons ===
'''Two values are equal only if their types are the same.'''<br/>
This is stricter than C and far stricter than PHP for example.
* 4 is not equal to "4". (number type and string type). In PHP they would be equal.
* 0 is not equal to false (number type and bool type). In C they would be equal.
* 0 is not equal to nil. (number type and nil type). In C they would be equal.

Regarding tables and C-made objects, they are compared by reference.
<div class="civ5-example"><syntaxhighlight lang="lua">
a = { 5 }
b = { 5 }
c = a
assert(a == c) -- OK
assert(a == b) -- ERROR
</syntaxhighlight></div>

=== Boolean logic ===
'''Anything that is neither false nor nil is evaluated to true.'''<br/>
This is pretty simple. Especially, an empty string or the zero number are evaluated to true.
<div class="civ5-example"><syntaxhighlight lang="lua">
if 0 then print("hello world") end -- prints hello world
</syntaxhighlight></div>

Now regarding the and/or operators, two rules to remember:
* '''The right operand is only evaluated when needed.'''
** <code>false and x()</code> does not call x() since the result will be false anyway.
** <code>true or x()</code> does not call x() since the result will be true anyway.
* '''The result is the last operand to have been evaluated.'''
** <code>x() and y()</code> returns x() if it was false, y() otherwise.
** <code>x() or y()</code> returns x() if it was true, y() otherwise.

=== Ternary and coalescence statements ===
We can exploit the and/or operators behavior:
* '''Coalescence:''' <code>x or y</code>. It returns x if x is neither nil nor false, y otherwise.
:In other words <code>result = x or y</code> is equivalent to: <code>if x then result = x else result = y end</code>.
* '''Ternary:''' <code>condition and x or y</code> (as long as x is not nil or false). It returns x if condition was true, y if it was false.
:Indeed the expression becomes: <code>(condition and x) or y</code>. If condition is true the '''and''' operator returns x, and since x is true, y is not evaluated and '''or''' returns x.
:In other words <code>result = condition and x or y</code> is equivalent to: <code>if condition then result = x else result = y end</code>.

=== Arrays versus tables ===
'''In Lua, an array is a table whose keys are integers.'''

Since this is a common programming pattern, a number of things are designed for arrays:
* <code>{"abc", "def", "ghi"}</code> starts at index 1, up to index 3. Arrays typically start at 1.
* <code>table.insert({}, "abc")</code> will transform the provided empty table to <code>{"abc"}</code>
* <code>table.insert({"abc", "def"}, "ghi")</code> will transform the provided table to <code>{"abc", "def", "ghi"}</code>
* <code>table.insert({"abc", "ghi"}, 2, "def")</code> will transform the provided table to <code>{"abc", "def", "ghi"}</code>
* <code>table.remove({"abc", "def", "ghi"}, 2)</code> will transform the provided table to <code>{"abc", ""ghi"}</code>
* <code>#{"abc", "def", "ghi"}</code> returns 3, the biggest integer key.

=== Ipairs versus pairs ===
You could say that '''pairs''' is for table and '''ipairs''' for arrays.
* '''Pairs''' enumerate all the key/value pairs in an unordered matter.
* '''Ipairs''' only enumerates the key/value pairs for consecutive integer keys, in an ascending order, starting from 1 up to the largest key. If at some point a key is missing, the enumeration stops.
::It does not matter whether the table was crated with table.insert or directly by inserting the values through, for example <code>table[i] = value</code>.

<div class="civ5-example"><syntaxhighlight lang="lua">
-- Produces: { 1 => "one", 2 => "two", 4 => "four", "name" => "John", "age" => 25 }
local t = { "one", "two", name = "John", age = 25, [4] = "four" }

-- Will print (for example, the order is undetermined): "name", 2, 4, "age", 1
for k in pairs(t) do print(k) end

-- Will print 1, 2
for k in ipairs(t) do print(k) end

-- Both ipairs and pairs return a key and a value, so you could also use:
for k, v in pairs(t) do print(k, v) end
</syntaxhighlight></div>

=== Semicolons and line breaks ===
'''Statements need to be separated either by a line break or a semicolon.'''
* You can use both a semicolon and a line break but then the semicolon is redundant and not required, although it does not cause any problem.
* Line breaks can also be freely added about everywhere and behave as whitespaces most of the time (you can add them after most keywords for example, so you can keep if...then...end structures on one line or split them across multiple lines).

=== Locals, globals and includes ===
* The include statement allows you to include a lua file into another one (see [[Specificities of the Lua implementation in Civ5]]). When you do so, the globals defined in the included file are imported in the parent file. However the local variables are only visible from within the file that declared them.
* Another specificities of locals: they're only visible after the point they have been declared in the file, while globals are always visible. An example is worth thousand of words.
<div class="civ5-example"><syntaxhighlight lang="lua">
function Func1()
print(someLocal or "nil")
print(someGlobal or "nil")
end

local someLocal = "foo"
function Func2()
print(someLocal or "nil")
print(someGlobal or "nil")
end

someGlobal = "global"
someLocal = "local"
Func1() -- prints "nil", then "global": someLocal is assigned but not visible from Func1
Func2() -- prints "local", then "global": someLocal is assigned and visible from Func2
</syntaxhighlight></div>
* Performances-wise, Lua first searches a variable name in the current scope, then in the parent scope, etcetera until it reaches the highest scope, and finally it searches the global scope. So the deeper a local is declared, the faster it is accessed. On the contrary, globals are the slowest to retrieve.

= Semi-advanced topics =
=== Closures ===
'''Closures are functions that embed variables that are persisted across calls.'''<br/>
This is typically achieved through a "parent" function that declares a local "closed" variable and returns another child "closure" function using this local. The "closed" variable is then unreachable for anyone but the "closure". And since it the "closed" variable is not in the "closure"'s scope, it is not reinitialized on every call of "closure".
<div class="civ5-example"><syntaxhighlight lang="lua">
function GiveMeAFunc() -- the parent function
local x = 0 -- the closed variable
return function() -- the closure function embedding "closed"
x = x + 1
return closure
end
end

local func = GiveMeAFunc()
print(func()) -- Prints 1
print(func()) -- Prints 2
print(func()) -- Prints 3
</syntaxhighlight></div>

=== Iterators ===
'''Iterators are functions for use in <code>for...in</code> loops.'''<br/>
Let's consider the following code: <code>for var1, var2, var3 in iterable() do</code>.
* iterable has the following signature: <code>iterator, state, var1 iterable()</code>. It returns a function, a state, and the initial value of var1.
* iterator has the following signature: <code>var1, var2, var3 iterator(state, var1)</code>. It takes the state and the last value of var1 and returns var1, var2 and var3.
* The loop stops when var1 is nil.
* The for...in loop is equivalent to:
<div class="civ5-example"><syntaxhighlight lang="lua">
local iterator, state, var1, var2, var3
iterator, state, var1 = iterable()
do
var1, var2, var3 = iterator(state, var1)
if var1 == nil then break end

-- Inserts here the user code defined in the for..in loop
end
</syntaxhighlight></div>
* Note that we used var1, var2 and var3 for the example but there is no restriction to the number of variables. You could have one or hundred.

Let's write the "ipairs" function.
<div class="civ5-example"><syntaxhighlight lang="lua">
local function ipairs(table) -- The iterable function
local iterator = function(table, key) -- The iterator function
key = key + 1
return key, table[key]
end
return iterator, table, 0
end
</syntaxhighlight></div>

The same with closures: it's easier.
<div class="civ5-example"><syntaxhighlight lang="lua">
local function ipairs(table) -- The iterable function
local key = 0 -- Both "table" and "key" are closed variables.
local iterator = function() -- The iterator function, a closure: it ignores the arguments provided to it
key = key + 1
return key, table[key]
end
return iterator -- No need to return anything since we do not require any argument.
end
</syntaxhighlight></div>

=== No integer type ===
'''Lua offers no support for integers and only has a 64-bits floating point number type.'''<br/>
Actually, this is only troublesome for a few algorithms that use very large integers (>2^52) or require fast integer arithmetics. But many developers misunderstand floating points and believe the problem is broader than it is. For example, does the following assertion surprise you at least a bit: "any integer smaller than 2^52 can be accurately represented with a 64-bits floating point without any error"? If it did, you suffer from some misconceptions and you should better read carefully what's coming.

Many developers are confusing rounding errors with representation errors.
* '''Rounding errors''' actually only happen if you need a very high number of digits to represent a number. For example if you are adding a very large number with a small number. Rounding errors are very rarely encountered in day to day to applications. Actually most developers work their whole career without ever encountering them.
* '''Representation errors''' are the real problem: 0.1 is expressed in a decimal basis, but it has no finite representation in binary: it requires an infinite number of binary digits. This means that if you write 0.1 in your code it will be translated to a binary number close enough from 0.1 bot not exactly equal to it. So if you sum ten times 0.1, you sill sum ten times something close from 0.1 and the result will not be 1.

'''So the real problem for most developers only lies in the decimal-binary conversion that arises when you manipulate numbers in your code that do not have a finite representation in binary. As long as you do not use such numbers, there will be no problem. And here are the good news: integers do not suffer from any representation problem!''' Indeed, any integer can be represented with a finite number of binary digits. This is why the absence of an integer type typically does not cause problems, minus the performance penalty.

Here are a few examples to illustrate that point.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- This loop works as intended: no representation error and the upper bound is far below 2^52.
local sum = 0
for i = 0, 10000000000, 1 do sum = sum + 1 end
assert(sum == 10000000001)

-- This loop works as intended: 1/16 is a floating-point with an exact representation in binary
local sum = 0
for i = 0, 1, 1/16 do sum = sum + 1 end
assert(sum == 17/16)

-- This loop does NOT work as intended: 0.1 does not have an exact representation in binary.
-- It's the same for Lua, C and almost every programming language.
local sum = 0
for i = 0, 1, 0.1 do sum = sum + 1 end
assert(sum == 1.1) -- throws an error
</syntaxhighlight></div>

=== Errors management ===
Lua offers a error handling mechanism similar to exception handling but unfortunately not very convenient.
* Errors are thrown using the '''error''' function. It takes a string and it immediately aborts Lua execution until the game handles the error and prints it in Firetuner (when enabled).
* Errors are caught before that point using '''pcall''' or '''xpcall''', in order to let you resume execution by managing the error. "pcall" stands for "protected call".

Here are the syntaxes for pcall and xpcall:
* <code>bool, ... pcall(func, ...)</code>
** The function is called with the specified arguments.
** Pcall returns either true followed by the values returned by func, or false followed by the error text.
* <code>bool, ... xpcall(func, errorHandler)</code>:
** The function is called without any argument. If an error occurs the specified errorHandler is invoked with the error text as the only argument.
** Xpcall returns either true followed by the values returned by func, or false followed by the returned values from errorHandler.

Examples to invoke "someFunc" with "someArg" as the only argument. In both examples we want to display the error on the console, or the result if it was a success. A complete errors management example with a reporting mechanism for the end-user is presented in [[Debugging (Civ5)]].
<div class="civ5-example"><syntaxhighlight lang="lua">
-- pcall
local status, result = pcall(someFunc, someArg)
if not status then
print("error was: "..(result or "?"))
else
print("success: "..result)
end

-- xpcall
local status, result = xpcall(
function() someFunc(someArg) end,
function(err) print("error was: "..(result or "?")) end)

if status then
print("success: "..result)
end
</syntaxhighlight></div>

= Advanced topics=
=== Metatables and metamethods ===
* Every value in Lua, from a number to a userdata, has a metatable.
** Many objects can share the same metatable.
** Tables and userdata each have their own metatables by default. Numbers, bools, nils and strings all share the same metatable.
* A metatable may contain a few metamethods and index tables.
** Metamethods are methods stored under special fields names. They implement operators overloads.
** Index tables behave as "base classes": if a field name is not defined on an table, then Lua looks for this field on the index.
** In a way, metatables are analogous to virtual tables in object languages, but they are not just for methods, but also for fields and operators.
* You can get an object's metatable through '''getmetatable''' and assign it with '''setmetatable'''.
* See also the [http://www.lua.org/manual/5.1/manual.html#2.8 official metatables reference]

One example.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Define two tables A and B, and set "meta" their metatable
local a, b, meta = {}, {}, {}
setmetatable(a, meta)
setmetatable(b, meta)

-- Define an __index table on the metatable. It contains one key/value pair.
meta.__index = { "hello world" };

-- Print "hello world" twice
print(a[1])
print(b[1])

-- Now make our tables read-only
meta.__newindex = function(table, key, value) error("this table is read-only!") end
a[1] = "foo" -- throws an error
</syntaxhighlight></div>

Here are the most important fields a metatable can have:
* '''__index''': used when you read a member from an object. On tables, Lua will first search for a regular field on the table itself (not its index) before it looks at the index. The index may be a table or a function: <code>value func(object, key)</code>
* '''__newindex''': used when you assign a value to an object's member. On tables, newindex is only called if the table itself (not its index) does not already contains the specified key. May be a table or a function: <code>func(object, key, value)</code>
* '''__call''': used when you invoke the object as a function. Must be a function: <code>func(object, <args>)</code>
* '''__tostring''': used when you invoke the '''tostring''' function with this object in argument. Must be a function: <code>string func(object)</code>

Besides of that it can have fields for binary operators. When each of the two operands defined overloads, the left one is used. They must be functions: <code>result func(object)</code>
* '''__add''': addition
* '''__sub''': subtraction
* '''__mul''': multiplication
* '''__div''': division
* '''__mod''': module
* '''__pow''': exponentiation
* '''__eq''': equality comparison. Prior to calling this overload, Lua checks that types are equal.
* '''__neq''': inequality comparison. Prior to calling this overload, Lua checks whether types are different.
* '''__lt''': lesser than comparison. (b >= a) is considered equivalent to (a < b)
* '''__le''': lesser than or equal to comparison. (b > a) is considered equivalent to (a <= b). If __le is not defined, lua will use __lt, considering that (a <= b) is equivalent to not (b < a).
* '''__concat''': concatenation

Finally it can have the following fields for unary operators. They must be functions: <code>result func(object)</code>
* '''__unm''': unary minus
* '''__len''': the sharp operator (#). Can only be used on userdata ; on tables the default operator will always be called.

=== Implementing inheritance ===
The most common use of metatables is to mimic the behavior of object languages' types hierarchy. Here is how to do it:
<div class="civ5-example"><syntaxhighlight lang="lua">
local Dog = {}
function Dog:specie()
return "dog"
end
function Dog:race()
return "unknown"
end
function Dog:description()
return self.specie().." - "..self.race()
end
function Dog:new()
local instance = {}
setmetatable(instance, { __index = self})
return instance
end

local Pitbull = dog:new()
function Pitbull:race()
return "pitbull"
end

pitbull = Pitbull:new()
print(pitbull:description()) -- prints "dog - pitbull"
</syntaxhighlight></div>

This implementation is very elegant: the "new" method both creates a new instance and subtypes the creator, since "pitbull"'s index is now "Pitbull". However, should you define an operator overload on Dog's metatable, Pitbull would not inherit it. This is the limit of inheritance in Lua: operator overloads must be defined on the metatable itself, they cannot be defined on the metatable's index. As a result, there is no way to inherit those overloads while subtyping.

=== Coroutines ===
Coroutines provide a way to slice a function in many shorter calls and optionally return intermediate results. On each call, the function execution is resumed to the point where it stopped previously, with all locals being properly restored with the value they had at this time.
* Coroutines are often compared to threads. Indeed, when there are more threads than CPU cores, the operating system slices threads' execution into many little time frames and sequentially runs them in order to achieve multitasking.
* However while coroutines allows you to implement cooperative multitasking (the coroutines need to explicitly give the hand back), they cannot be used for preemptive multitasking or to use more than one system thread or CPU Core.
* As a result, coroutines are rather used as syntactic sugar (mostly to write iterators), or as a way to split a long function execution across many frames (through Context.{{Func5|UIElement|SetUpdate}}).

The following methods are mainly used:
* <code>'''coroutine''' coroutine.create('''function''' func)</code> creates a coroutine for the specified function. The function signature can be anything.
* <code>'''bool''', '''...''' coroutine.resume('''coroutine''' co, '''...''')</code> resumes the coroutine with the specified arguments. Then it returns either '''true''' followed by the returned results (either though '''return''' or '''yield'''), or '''false''' followed by an error message.
* <code>'''string''' coroutine.status('''coroutine''' co)</code> returns either "running" (the active coroutine), "normal" (a parent of the active coroutine), "suspended" (not started or waiting to be resumed) or "dead" (finished or threw an error).
* <code>coroutine.yield('''...''')</code> suspends the execution of the running coroutine and gives the hand back to the caller of coroutine.resume. The arguments will be returned by coroutine.resume.

Here is a base example:
<div class="civ5-example"><syntaxhighlight lang="lua">
function neighborsCoroutine(plot)
for i = 0, 5 do
coroutine.yield(Map.PlotDirection(plot:GetX(), plot:GetY(), i))
end
end

local co = coroutine.create(neighborsCoroutine)
while coroutine.status(co) == "suspended"
local _, neighbor = co.resume(plot)
-- Do something with plot
end
</syntaxhighlight></div>

Here is how to transform it into an iterator:
<div class="civ5-example"><syntaxhighlight lang="lua">
function neighbors(plot)
local co = coroutine.create(neighbors)
return function()
if coroutine.status(co) ~= "suspended" then return end
return select(2, coroutine.resume(plot))
end
end

for neighbor in neighbors(plot) do
-- Do something with plot
end
</syntaxhighlight></div>

Here is an example that spreads a long function call across many frames:
<div class="civ5-example"><syntaxhighlight lang="lua">
function SpreadAcrossFrames(longFunctionCall, ...)
local co = coroutine.create(longFunctionCall)
ContextPtr.SetUpdate(function()
coroutine.resume(unpack(arg))
if coroutine.status(co) ~= "suspended" then
ContextPtr:ClearUpdate()
end
end)
end

SpreadAcrossFrames(SomeLongFunction, arg1, arg2)
</syntaxhighlight></div>

=== Design philosophy for Lua ===
Do not use a butter knife as you would use a chainsaw (the opposite is even more true and usually ends up badly). When designing your code, remember that:
* Lua is not an object language. While you can use objects and inheritance in some extent, you do not have to and there may be better alternatives sometimes.
* Lua is not a functional language. While you can use lambdas and similar concepts, you do not have to and there may be better alternatives sometimes.
* Lua is a multi-paradigm and dynamic language, take advantage of those.
* Lua is very suited for prototyping and small programs, and this is perfect for mods. Try to adjust your mindset: you're not writing a framework that a whole team will still use and maintain in twenty years.

[[Category:Civ5 API]]
[[Category:Civ5 Tutorials]]

Specificities of the Lua implementation in Civ5

2012-09-25T12:09:42Z

DonQuich:

''This page is a part of the [[Lua and UI Reference (Civ5)|Lua and UI Reference]].''

The Civ5 implementation is based on Lua 5.1.4. However it has been modified, mainly for sandboxing purposes.

= Missing elements =
Those items do not exist in the Civ5 implmentation of Lua. See [http://www.lua.org/manual/5.1/#index Lua Reference#Index] if you want to learn what they are for.

====Missing globals====
* '''__G'''

====Missing functions====
Use '''include''' instead of the '''load*''', '''module''' and '''require''' functions. See the next section for more informations.
* '''getfenv'''
* '''load'''
* '''loadfile'''
* '''loadstring'''
* '''module'''
* '''require'''
* '''setfenv'''
* '''setfenv'''

====Missing objects====
For I/O, use the methods from {{Type5|UI}} and {{Type5|Modding}} instead.
* '''file'''
* '''io'''
* '''package'''
* '''os''': it still exists but only contains the '''clock''', '''date''', '''time''' and '''difftime''' functions.
* <s>debug</s>: fortunately it has been added by Firaxis in May 2012. See [[Lua Debugging (Civ5)]]

= Include =
Instead of the usual functions for loading and requiring a Lua file from another, Civ5 provides a custom function to do so: '''include'''.

====Usage====
<code>table('''int''' => '''string''') include('''string''' file, '''bool''' useRegex = false)</code>
* '''file''': the name of the file, with or without extension. It can also be a local path starting from "Assets\UI" (see examples). Finally, if useRegex is true, it can be a regular expression where the '''%''' character is used instead of '''\'''.
* '''useRegex''': when true, the file argument will be treated as a [http://en.wikipedia.org/wiki/Regular_expression regular expression].
* '''returned value:''' an array that contains all the loaded files (a single one usually, many files if you did use a regular expression).

<div class="civ5-example"><syntaxhighlight lang="lua">
include("CityBannerManager")
include("CityBannerManager.lua")
include("Ingame\\CityBannerManager.lua") -- loads Assets/UI/Ingame/CityBannerManager.lua
include("CityBanner%w+.lua", true) -- loads all files starting with "CityBanner" and ending with ".lua".

-- Loads all "*Popup.lua" files in Assets/UI/Ingame/PopupsGeneric.
-- Then we print a statement for each one of the included files.
local files = include("InGame\\PopupsGeneric\\%w+Popup.lua", true);
for i, v in ipairs(files) do
print("Loaded Popup - "..v);
end
</syntaxhighlight></div>

====Restrictions====
* Only the files that have been imported into the [[VFS (Civ5)|VFS]] may be included.
* Usually only the first eight characters are checked. This is likely only true if you do not specify the path. This means that if you registered two files named ''MapScannerA.lua'' and ''MapScannerB.lua'', using <code>include("MapScannerA")</code> could either load the A file or the B file!
* When called in reaction to an UI event, include can silently fail. For example if you use it inside a function and this function is called in reaction to a click on a button, include will report it has been successful but the globals declared in the included file will not be included. This does not happen if you call this function after a Context update or at the time the mod is loaded.

[[Category:Civ5 API]]
[[Category:Civ5 Tutorials]]

XML-SQL Cheat Sheet (Civ5)

2012-09-25T12:09:08Z

DonQuich:

''This page is a part of the [[Civ5 XML Reference]].''

= Things to remember =
* '''Booleans:''' SQLite does not have booleans, it uses integers. So do not use <code>true</code> or <code>false</code>, use <code>1</code> and <code>0</code>.

= Inserting rows =
=== XML ===
<div class="civ5-example"><syntaxhighlight lang="xml" style="left:40px;">
<GameData>
<Colors>

<Row>
<Type>COLOR_CUSTOM</Type>
<Red>0.1</Red>
<Green>0.1</Green>
<Blue>0.1</Blue>
<Alpha>0.45</Alpha>
</Row>
</Colors>
<GameData>
</syntaxhighlight></div>

=== SQL ===
<div class="civ5-example"><syntaxhighlight lang="sql">
/* Inserts a new color */
INSERT INTO Colors (Type, Red, Green, Blue, Alpha)
VALUES ('COLOR_CUSTOM', 0.1, 0.1, 0.1, 0.45);
</syntaxhighlight></div>

= Deleting rows =
{{Warning}} See [http://forums.civfanatics.com/showthread.php?t=463429 Deleting data and issues, and how to avoid them] if you plan to delete rows and are not aware of the troubles that may arise.
=== XML ===
<div class="civ5-example"><syntaxhighlight lang="xml">
<GameData>
<Colors>

<Delete Type="COLOR_CUSTOM" />

<Delete R="1" G="1"/>
</Colors>
<GameData>
</syntaxhighlight></div>

=== SQL ===
<div class="civ5-example"><syntaxhighlight lang="sql">
/* Deletes all colors named TYPE_CUSTOM whose red channel is equal to 1 */
DELETE FROM Colors
WHERE Type = 'COLOR_CUSTOM' AND Red = 1;
</syntaxhighlight></div>

= Updating rows =
=== XML ===
<div class="civ5-example"><syntaxhighlight lang="xml">
<GameData>
<Colors>

<Update>
<Where Type="COLOR_CUSTOM" Red="0"/>
<Set Red="1" Green="0"/>
</Update>

<Update>
<Where>
<Type>COLOR_CUSTOM</Type>
</Where>
<Set>
<Red>1</Red>
<Green>1</Green>
</Set>
</Update>
</Colors>
</GameData>
</syntaxhighlight></div>

=== SQL ===
<div class="civ5-example"><syntaxhighlight lang="sql">
/* Update all colors whose names are COLOR_CUSTOM and red channel is 0 */
UPDATE Colors
SET Red = 1, Green = 0
WHERE Type = 'COLOR_CUSTOM' AND Red = 0;

/* Makes everything brighter */
UPDATE Colors
SET Red = Red + 0.1, Green = Green + 0.1, Blue=Blue + 0.1;
</syntaxhighlight></div>

= New tables =
=== XML ===
<div class="civ5-example"><syntaxhighlight lang="xml">
<GameData>
<Table Name="MyColors">
<Column name="ID" type="integer" primarykey="true" autoincrement="true"/>
<Column name="Type" type="text" notnull="true" unique="true"/>
</Table>
</GameData>
</syntaxhighlight></div>

=== SQL ===
<div class="civ5-example"><syntaxhighlight lang="sql">
/* Create one new table with two columns */
CREATE TABLE MyColors( id INTEGER PRIMARY KEY AUTOINCREMENT, Type TEXT UNIQUE );
</syntaxhighlight></div>

= New columns =
=== SQL ===
<div class="civ5-example"><syntaxhighlight lang="sql">
/* Adds one Description column to Colors. */
ALTER TABLE Colors COLUMN 'Description' TEXT DEFAULT NULL;
</syntaxhighlight></div>

[[Category:Civ5 XML Files]]
[[Category:Civ5 Tutorials]]

Civ5 Useful Programs

2012-09-25T12:08:14Z

DonQuich: Titles harmonization with other articles

This page includes information on the Civ5 Modding Tools as well as links to other useful programs.

= SDK =
'''World Builder'''
:The stand-alone world builder allows users to create and modify maps and scenarios for Civilization V.

'''Mod Buddy'''
:An editor (IDE) for the XML and Lua elements of the game and allows for the creation, packaging, and uploading of mods. To use it, you have to install the [http://www.microsoft.com/downloads/en/details.aspx?FamilyID=DFBA7AC4-5366-456E-ABD6-0E3E6BA83B7C&displaylang=enMicrosoft Visual Studio 2010 Shell (Isolated) Redistributable Package].
:[http://forums.civfanatics.com/showthread.php?t=387554 Installing ModBuddy Extensions]

'''Nexus'''
:A collection of tools to to work with the art in Civilization V.
:[http://forums.civfanatics.com/showthread.php?t=386972 Initial Look at Nexus, 3D Unit Art, and Reskinning]
:Note that Photoshop templates for icons are also bundled in the SDK, under the ''Art'' folder (in ''Programs Files/Steam/...'').

'''FireTuner'''
:An advanced debugging terminal. It displays the lua output, provides an interactive console and can be simply extended with custom controls and tables.
:Do not forget to modify your *.ini files, see [[Debugging (Civ5)#Configuration|Debugging#Configuration]].
:[http://forums.civfanatics.com/showthread.php?t=399821 Simple Tuner Modifications]

= Digging the source code and the data tables =
Since the documentation is sparse, you need a tool to quickly inspect the civ5 source and data files and search in all of them at once. See also [http://forums.civfanatics.com/showthread.php?t=475076 this comparison of search tools].

'''Notepad++'''
:A great and renowned text editor with a "search in all files" feature (hit ctrl + shift + f). Used by many developers around the world. [http://sourceforge.net/projects/notepad-plus/ Download].

= Browsing the art assets =
'''Dragon unpacker'''
:Can extract the Firaxis packages (.fpk files). [http://sourceforge.net/projects/dragonunpacker/ Download].

'''DDS Unpacker'''
:Some DDS files have been compressed even further and look messed up if you open them in an image viewer. This tool rebuilds them. [http://forums.civfanatics.com/showthread.php?t=389316 Download].

'''XnView'''
:An images browser to get a quick look at all the DDS files to spot the one you're looking for. [http://www.xnview.com/en/download.html Download].

'''FireTuner: Textures Viewer'''
:A FireTuner panel to browse most of the game's textures. [http://forums.2kgames.com/showthread.php?118165-MOD-LiveTuner-Texture-Viewer Download].

'''FireTuner: Icons Viewer'''
:A FireTuner panel to browse the game's icons. [http://forums.2kgames.com/showthread.php?118055-MOD-LiveTuner-Icon-Viewer Download].

= Creating textures =
'''NVidia Texture Tools for Photoshop'''
:A Photoshop plugin to save textures under the DDS format. [http://developer.nvidia.com/content/nvidia-texture-tools-adobe-photoshop Download]

'''Paint.net'''
:An easy-to-use and moderately powerful open-source image editor for Windows that natively supports the DDS format. [http://www.getpaint.net/ Download]

= Testing and debugging =

=== SQLite tools ===
Anytime it starts a game, Civilization V saves a SQLite snapshot of the database, including the changes made by mods, under ''Civ5DebugDatabase.db''.

'''SQLite Manager'''
:A Firefox plug-in, slightly more powerful than the previous tool. [https://addons.mozilla.org/en-US/firefox/addon/sqlite-manager/ Download]

'''SQLiteSpy'''
:A Windows software to inspect the SQLite files. [http://www.yunqa.de/delphi/doku.php/products/sqlitespy/index Download]

'''SQLite Browser'''
:A Windows software to inspect the SQLite files. [http://sqlitebrowser.sourceforge.net/screenshots.html Download]

=== Cheating tools and game inspectors ===
'''In-game Editor (IGE)'''
:Add or remove units, cities, resources, change the terrain, trigger wars, etc. Convenient to quickly test your mod. [http://forums.civfanatics.com/showthread.php?t=436912 Download] (also on the Steam Workshop).

'''FireTuner: Techs and policies panel'''
:A FireTuner panel to list, grant and revoke techs and policies. [http://forums.2kgames.com/showthread.php?108533-MOD-LiveTuner-Tech-and-Policy-Panels Download].

[[Category:Civ5]]

VFS (Civ5)

2012-09-25T12:07:47Z

DonQuich:

''This page is a part of the [[Civ5 Modding Tutorials]].''

This article explains the Virtual File System (VFS) in Civ5. Lua developers looking for informations on the '''include''' function should look at [[Specificities of the Lua implementation in Civ5]].

= What is it? =
[[File:ModBuddy.ImportIntoVFS.png|frame|The ''import into VFS'' option.]]
VFS stands for Virtual File System. Rather than locating the files directly in the file system, Civ5 looks for them in its virtual file system. This system provides the following benefits:
* '''Modularity:''' each mod, expansion or DLC can provide its own version of a given file without overwriting the original one. At run-time the game sequentially loads those files into the VFS, performing virtual overwrites as needed. This contrasts with the mods hell in the Elders Scrolls series for example.
* '''Packaging:''' The files in the VFS can be either independent files or parts of packages (archives). The VFS behaves as a unified resource loader.
* '''Sandboxing:''' whenever a mod requests a file, civ5 only looks in the VFS. This prevents mods to be allowed to look at the physical file system since this could open a security breach.

= Determining whether a file must be imported or not =
In doubt, import your files into the VFS. But you should better stick to what is written here.

'''Must be imported''' the files that are requested during the game.
* The XML UI files.
* The XML files for animations, scenes, etc.
* The Lua files (minus the exception detailed below).
* The art assets such as textures or models.

'''Should not be imported''' the files that are loaded through the project's content and actions tab (except the XML UI files, those ones should always be imported). While this is harmless most of the time, this can sometimes result in unexpected side-effects.
* The Lua files that are directly loaded through the project's content tab. This does not apply if the Lua file is associated with a XML file and you load this XML file instead. Note that if you want a Lua file to be included by other Lua or XML UI files, you will still have to import it into the VFS but you may see it loaded more times than necessary.
* The XML data and text files. Those ones are only ran at start up to modify the data tables.
* The SQL files. For the same reasons.

= Importing a file into the VFS =
* In ModBuddy, select a file in the solution exlporer.
* Hit F4 (or click View > Properties Window) to open its properties.
* At the bottom of this new window, look for '''Import into VFS''' and set it to true.
* If Civ5 is opened, you will need to exit to the main menu for this change to be applied.

[[Category:Civ5 Tutorials]]

Civ5 Modding Tutorials

2012-09-25T12:07:23Z

DonQuich: Titles harmonization with other articles

= Getting started =
'''Get a tour.'''
:If you have no idea about modding and what are Lua and Xml, you should give a look at [http://www.weplayciv.com/forums/entry.php?15-Dale-s-Mod-Blog-Civ5-Modding-Explained Civ5 Modding Explained].
'''Read the guide.'''
:The best introduction to civ5 modding is still the '''[http://forums.civfanatics.com/showthread.php?t=385009 Kael's Guide]'''. However it was written a long time ago and some informations are obsolete or missing.
'''Import your files into VFS.'''
:The main change since Kael wrote his guide is about the [[VFS (Civ5)|VFS]] (Virtual File System). Basically you should include your art assets, UI and lua files into the VFS. In ModBuddy, select those files, hit F4 to open the properties window, check "import into VFS". Forgetting this is a common cause of troubles for beginners. The VFS index only takes into account the first eight chars so beware of conflicts.
'''Get the right tools for the job.'''
:See [[Civ5 Useful Programs]]. You should have installed the SDK of course, but it is also strongly recommended that you get a tool to search in all civ5 files at once, to compensate for the lack of documentation. You may also need additional softwares to extract and read the textures, test and debug your mod, etc.
'''Modify your ini files.'''
:See [[Debugging (Civ5)#Configuration|Debugging#Configuration]].

= Tutorials =
See also the [http://forums.civfanatics.com/forumdisplay.php?f=394&order=desc&page=2 Modding tutorials section] on the forums.<br/>
Also note that the [[Civ5 XML Reference|XML]] and [[Lua and UI Reference|Lua]] sections each contain specific tutorials, articles and extensive documentation.

=== General ===
* [[Modding Limits and Issues (Civ5)|Modding Limits and Issues]]
* [http://forums.civfanatics.com/showthread.php?t=459392 Create and use DDS textures]
* [http://forums.civfanatics.com/showthread.php?t=449431 Adding custom data and using them in Lua]
* [http://wiki.2kgames.com/civ5/index.php/Mods:LocalizationSyntax Localization Syntax]
* [[Debugging (Civ5)|Debugging]]

=== Common tasks ===
* [http://forums.civfanatics.com/showthread.php?t=391823 New Leaders (2D images)]
* [http://forums.civfanatics.com/showthread.php?t=389782 New Resources]
* [http://forums.civfanatics.com/showthread.php?t=470290 New Buildings]
* [http://forums.civfanatics.com/showthread.php?t=406877 New Specialists]
* [http://forums.civfanatics.com/showthread.php?t=392985 New Units]

=== Specific topics ===
* [http://forums.civfanatics.com/showthread.php?t=468374 Culture buildings - vanilla and G&K cross compatibility]
* [http://forums.civfanatics.com/showthread.php?t=394056 Import civ4 units into civ5]
* [http://forums.civfanatics.com/showthread.php?t=405148 Locking techs on a civilization basis]
* [http://forums.civfanatics.com/showthread.php?t=396911 Making units that use Civ5 animations]
* [http://forums.civfanatics.com/showthread.php?t=474309 Guide to Adding a new Resource with Custom Reskins]
* [[Text icons and markups (Civ5)|Text icons and markups]]
* [[VFS (Civ5)|VFS]]

[[Category:Civ5 Tutorials]]

Debugging (Civ5)

2012-09-25T12:06:31Z

DonQuich:

''This page is a part of the [[Civ5 Modding Tutorials]].''

= Checklist =
* Did you correctly import to the [[VFS (Civ5)|VFS]] the files that need to be?
* Did you correctly set up the actions and content tab in your project?
* Did you restart civ5 after you added new files?

= XML Debugging =
[[File:SQLiteManager.png|frame|View of the snapshot using SQLiteManager]]
=== Checking the logs ===
If you correctly set up your [[#Configuration]], whenever you start a game, Civ5 saves some logs under <code>My Games/Sid Medier's Civilization V/cache/Civ5DebugDatabase.db</code>.
* If there were errors with the XML formatting of your data files (wrong column names for example), they will logged in XML.log. Some of those errors may be fatal: in such a case no mod is loaded!
:<pre>[6904.323] Tag (TXT_KEYMODDING_SHOWDLCMODS) does not start with 'TXT_KEY_'</pre>
* If there were errors with the data integrity (missing foreign keys for example - types that reference rows from other tables), they will logged in database.log.
:<pre>[6903.917] Invalid Reference on Leader_Flavors.LeaderType - "LEADER_HARALD" does not exist in Leaders</pre>

=== Using the snapshots ===
If you correctly set up your [[#Configuration]], whenever you start a game, Civ5 saves a snapshot of the database under <code>My Games/Sid Medier's Civilization V/cache/Civ5DebugDatabase.db</code>
* This allows you to check how your XML and SQL files have been merged with the standard game data.

= Lua Debugging =
=== Using the Firetuner console ===
If you correctly set up your [[#Configuration]], Civ5 will send all the Lua output to the Firetuner (and also to the <code>Lua.log</code> file). This includes all the debugging output but also any error that may arise, with their calls stack traces.
<pre>
Runtime Error: [string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:41: attempt to concatenate local 'name' (a nil value)
stack traceback:
[string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:41: in function 'dumpObj'
[string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:95: in function 'ScanAll'
[string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:188: in main chunk
[C]: ?
</pre>
Here we can see that a C/C++ code (the game engine) ran the main chunk called (the Lua file), which then called the function ''ScanAll'' on line 188, which then called ''dumpObj'' on line 95. And this one caused an error on line 41.

Note that paths are truncated in the provided example, which makes debugging harder sometimes. This happens when the file is in a {{Type5|context}} registered by the project's ''content'' tab. Here are the workarounds:
* Provide a custom stack trace, as explained in a further section.
* Register only a minimalist context, that will load additional contexts (through the UI LuaContext markup). Do not initiate any action from the root context, let the children context handle everything.
* Modifying your system paths is not recommended as it can cause incompatibilities with a few applications (old or badly written).

=== Print, assert and error ===
<code>print('''...''')</code> can be used to print anything to the Firetuner output. This allows you to check the flow of a program, or the values of variables. Print calls '''tostring''' on every argument and displays them all on a single line with tabulations as separators between them. Nil values are not displayed, so it is advised you provide expressions such as: <code>(expr or 'nil')</code>

<code>error('''string''' message, '''int''' level = 1)</code> throws an error with the specified message. The execution is then halted and the hand returned to the game engine (or the current protected call if you did use '''pcall''' or '''xpcall'''). The level parameter controls the error position that will be reported. 1 for the line where error is located, 2 for the function call that contained an error, etc. 0 for no position.

<code>assert('''variant''' condition, '''string''' message = "assertion failed")</code> can be used to assert the provided condition is neither nil nor false (everything else is evaluated to true in Lua). Otherwise, an error with the specified message is thrown. You can use them punctually, as a debugging technique. But they may also be used as a defensive programming technique similar to [http://en.wikipedia.org/wiki/Design_by_contract design-by-contract]: the idea is that whenever your program's correctness relies on an assumption, you should explicitly check it. For example, if a function takes an array as an argument and assumes that it is not empty, you should add two conditions at the beginning: <code>assert(type(t) == "table")</code> and <code>assert(#t > 0)</code>. This makes the code more self-explanatory (implicit assumptions are now explicitly stated) and it allows you to catch bugs as soon as possible, which typically makes them easier to understand and fix.

=== The end users' feedback ===
Most of the time, when one of your user encounters an error with your mod, he just stops using it. A fraction of them will do the effort of reporting bugs but too often the informations they provide is unusable (from "it doesn't work" to wrong reproduction steps "play until turn 173 and wait for Mars being aligned with Venus"). The best way to increase the number of reports and their usefulness is to let your mod tell them the info it needs, as illustrated below.

[[File:IGE-Error.png|none|frame|[http://forums.civfanatics.com/showthread.php?t=436912 In-game editor] tells its users what they must report, even including a calls stack trace when available. The user only needs to make a screenshot that will then land on his Steam profile (provided he didn't change the Steam settings). Reporting made easy!]]

The [[Lua introduction for confirmed developers]] describes a number of techniques you can use to achieve similar results. Here we present an implementation you can use to handle errors in the most dangerous parts of your code in order to present them to the user. The message will even include a full stack trace when available (you can provide your users a link to the [[#Configuration]] section and ask them to modify their config.ini).
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Returns an array of strings, one for each call level.
-- We could use debug.traceback instead but this ones truncates path and we cannot easily ignore the topmost levels.
function getStackTrace()
-- Level 1 is getStackTrace, 2 is its caller
local level = 2
local trace = {}
while true do
-- Gets that level's informations: function name, source file and line.
local info = debug.getinfo(level, "nSl")
if not info then break end

-- C code or Lua code?
if info.what == "C" then
table.insert(trace, "C function");
else
local userStr = Path.GetFileName(info.source)..": "..info.currentline;
if info.name and string.len(info.name) then
userStr = userStr.." ("..info.name..")";
end
table.insert(trace, userStr);
end
level = level + 1
end
return trace;
end

-- Gets a nicely formatted string of the error.
-- The second parameter is the number of levels to ignore in the calls stack (formatError excluded). Defaults to 0.
function formatError(err, levelsToIgnoreBelow)
print(err);

-- We do not want to include formatError in the stack trace, hence the +1
levelsToIgnoreBelow = (levelsToIgnoreBelow or 0) + 1;

-- 'err' is like: [string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:41: attempt to concatenate local 'name' (a nil value)
-- We retrieve important positions in this string. Remember: not all paths are truncated.
local elipsisIndex = string.find(err, "...", 1, true) or -5;
local lineIndex = elipsisIndex + 6
local msgIndex = string.find(err, ":", lineIndex, true) + 1

-- Can we append the stack trace?
local result = ""
if debug and debug.getinfo then
result = string.sub(err, msgIndex)

local trace = getStackTrace()
for i, v in ipairs(trace) do
print(v)
if (i > levelsToIgnoreBelow) then
result = result.."[NEWLINE]"..v;
end
end
-- Otherwise just report the line and message, and the source file when not truncated.
else
result = "line "..string.sub(err, elipsisIndex)
end

return result
end

-- The error handler to provide to xpcall
local function errorHandler(err)
-- The stack trace at this point is:
-- 1: this error handler (must not be reported),
-- 2: C function calling the handler (kept for security)
-- 3: the error source
err = formatError(err, 1);

-- Show a popup to the user
local str = L("Oops, an error occured:").."[NEWLINE][ICON_PIRATE] "..err;
Events.SerialEventGameMessagePopup( { Type = ButtonPopupTypes.BUTTONPOPUP_TEXT, Data1 = 800, Option1 = true, Text = str } );

-- Restore things up here when needed. Beware to not cause any error as it would cause an infinite recursive call up to the stack overflow!
return false
end

-- Calls someDangerousFunction with the given error handler
xpcall(someDangerousFunction, errorHandler)
</syntaxhighlight></div>

= Troubleshooting =
The [[Civ5 Useful Programs]] page presents you a number of tools you can use to inspect or modify the game. This is especially useful if you want to quickly reproduce a bug or test something, or to understand what is happening.
* Let's say your mod adds a tech but you do not see in the techs panel. There is a FireTuner panel you can use to see a flat list of all the techs in-game.
* Let's say your mod adds a unit or a wonder, the IGE mod allows you to quickly create an unit or build that wonder (including the splash screen).
* Let's say your mod modifies the yields when the player acquire a specific tech. Once again IGE allows you to grant you that tech and see how the yields are modified.

= Configuration =
Look for the following files under <code>My Documents/My Games/Sid Meiers' Civilization V</code> and open them in a text editor like the notepad (not in a word processor).
* '''config.ini'''
** Set <code>EnableTuner</code> to 1. Civ5 will duplicate the Lua output to FireTuner this one is when present.
** Set <code>LoggingEnabled</code> to 1. Civ5 will write log files under the <code>Logs</code> folder.
** Set <code>EnableLuaDebugLibrary</code> to 1. Civ5 will display stack traces on Lua errors and you will be able to use the [http://www.lua.org/manual/5.1/manual.html#pdf-debug.debug debug] object.
** Set <code>DebugPanel</code> to 1. By pressing the '''²''' key (may be '''ù''' or something else depending on your computer's language) during a game, Civ5 will display a debug panel.
* '''usersettings.ini'''
** Set <code>DebugMode</code> to 1. Needed to enable other features previously mentioned.

[[Category:Civ5 Tutorials]]

Debugging (Civ5)

2012-09-25T12:05:15Z

DonQuich:

''This page is a part of the [[Civ5 Modding Tutorials]].''

== Checklist ==
* Did you correctly import to the [[VFS (Civ5)|VFS]] the files that need to be?
* Did you correctly set up the actions and content tab in your project?
* Did you restart civ5 after you added new files?

== XML Debugging ==
[[File:SQLiteManager.png|frame|View of the snapshot using SQLiteManager]]
=== Checking the logs ===
If you correctly set up your [[#Configuration]], whenever you start a game, Civ5 saves some logs under <code>My Games/Sid Medier's Civilization V/cache/Civ5DebugDatabase.db</code>.
* If there were errors with the XML formatting of your data files (wrong column names for example), they will logged in XML.log. Some of those errors may be fatal: in such a case no mod is loaded!
:<pre>[6904.323] Tag (TXT_KEYMODDING_SHOWDLCMODS) does not start with 'TXT_KEY_'</pre>
* If there were errors with the data integrity (missing foreign keys for example - types that reference rows from other tables), they will logged in database.log.
:<pre>[6903.917] Invalid Reference on Leader_Flavors.LeaderType - "LEADER_HARALD" does not exist in Leaders</pre>

=== Using the snapshots ===
If you correctly set up your [[#Configuration]], whenever you start a game, Civ5 saves a snapshot of the database under <code>My Games/Sid Medier's Civilization V/cache/Civ5DebugDatabase.db</code>
* This allows you to check how your XML and SQL files have been merged with the standard game data.

== Lua Debugging ==
=== Using the Firetuner console ===
If you correctly set up your [[#Configuration]], Civ5 will send all the Lua output to the Firetuner (and also to the <code>Lua.log</code> file). This includes all the debugging output but also any error that may arise, with their calls stack traces.
<pre>
Runtime Error: [string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:41: attempt to concatenate local 'name' (a nil value)
stack traceback:
[string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:41: in function 'dumpObj'
[string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:95: in function 'ScanAll'
[string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:188: in main chunk
[C]: ?
</pre>
Here we can see that a C/C++ code (the game engine) ran the main chunk called (the Lua file), which then called the function ''ScanAll'' on line 188, which then called ''dumpObj'' on line 95. And this one caused an error on line 41.

Note that paths are truncated in the provided example, which makes debugging harder sometimes. This happens when the file is in a {{Type5|context}} registered by the project's ''content'' tab. Here are the workarounds:
* Provide a custom stack trace, as explained in a further section.
* Register only a minimalist context, that will load additional contexts (through the UI LuaContext markup). Do not initiate any action from the root context, let the children context handle everything.
* Modifying your system paths is not recommended as it can cause incompatibilities with a few applications (old or badly written).

=== Print, assert and error ===
<code>print('''...''')</code> can be used to print anything to the Firetuner output. This allows you to check the flow of a program, or the values of variables. Print calls '''tostring''' on every argument and displays them all on a single line with tabulations as separators between them. Nil values are not displayed, so it is advised you provide expressions such as: <code>(expr or 'nil')</code>

<code>error('''string''' message, '''int''' level = 1)</code> throws an error with the specified message. The execution is then halted and the hand returned to the game engine (or the current protected call if you did use '''pcall''' or '''xpcall'''). The level parameter controls the error position that will be reported. 1 for the line where error is located, 2 for the function call that contained an error, etc. 0 for no position.

<code>assert('''variant''' condition, '''string''' message = "assertion failed")</code> can be used to assert the provided condition is neither nil nor false (everything else is evaluated to true in Lua). Otherwise, an error with the specified message is thrown. You can use them punctually, as a debugging technique. But they may also be used as a defensive programming technique similar to [http://en.wikipedia.org/wiki/Design_by_contract design-by-contract]: the idea is that whenever your program's correctness relies on an assumption, you should explicitly check it. For example, if a function takes an array as an argument and assumes that it is not empty, you should add two conditions at the beginning: <code>assert(type(t) == "table")</code> and <code>assert(#t > 0)</code>. This makes the code more self-explanatory (implicit assumptions are now explicitly stated) and it allows you to catch bugs as soon as possible, which typically makes them easier to understand and fix.

=== The end users' feedback ===
Most of the time, when one of your user encounters an error with your mod, he just stops using it. A fraction of them will do the effort of reporting bugs but too often the informations they provide is unusable (from "it doesn't work" to wrong reproduction steps "play until turn 173 and wait for Mars being aligned with Venus"). The best way to increase the number of reports and their usefulness is to let your mod tell them the info it needs, as illustrated below.

[[File:IGE-Error.png|none|frame|[http://forums.civfanatics.com/showthread.php?t=436912 In-game editor] tells its users what they must report, even including a calls stack trace when available. The user only needs to make a screenshot that will then land on his Steam profile (provided he didn't change the Steam settings). Reporting made easy!]]

The [[Lua introduction for confirmed developers]] describes a number of techniques you can use to achieve similar results. Here we present an implementation you can use to handle errors in the most dangerous parts of your code in order to present them to the user. The message will even include a full stack trace when available (you can provide your users a link to the [[#Configuration]] section and ask them to modify their config.ini).
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Returns an array of strings, one for each call level.
-- We could use debug.traceback instead but this ones truncates path and we cannot easily ignore the topmost levels.
function getStackTrace()
-- Level 1 is getStackTrace, 2 is its caller
local level = 2
local trace = {}
while true do
-- Gets that level's informations: function name, source file and line.
local info = debug.getinfo(level, "nSl")
if not info then break end

-- C code or Lua code?
if info.what == "C" then
table.insert(trace, "C function");
else
local userStr = Path.GetFileName(info.source)..": "..info.currentline;
if info.name and string.len(info.name) then
userStr = userStr.." ("..info.name..")";
end
table.insert(trace, userStr);
end
level = level + 1
end
return trace;
end

-- Gets a nicely formatted string of the error.
-- The second parameter is the number of levels to ignore in the calls stack (formatError excluded). Defaults to 0.
function formatError(err, levelsToIgnoreBelow)
print(err);

-- We do not want to include formatError in the stack trace, hence the +1
levelsToIgnoreBelow = (levelsToIgnoreBelow or 0) + 1;

-- 'err' is like: [string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:41: attempt to concatenate local 'name' (a nil value)
-- We retrieve important positions in this string. Remember: not all paths are truncated.
local elipsisIndex = string.find(err, "...", 1, true) or -5;
local lineIndex = elipsisIndex + 6
local msgIndex = string.find(err, ":", lineIndex, true) + 1

-- Can we append the stack trace?
local result = ""
if debug and debug.getinfo then
result = string.sub(err, msgIndex)

local trace = getStackTrace()
for i, v in ipairs(trace) do
print(v)
if (i > levelsToIgnoreBelow) then
result = result.."[NEWLINE]"..v;
end
end
-- Otherwise just report the line and message, and the source file when not truncated.
else
result = "line "..string.sub(err, elipsisIndex)
end

return result
end

-- The error handler to provide to xpcall
local function errorHandler(err)
-- The stack trace at this point is:
-- 1: this error handler (must not be reported),
-- 2: C function calling the handler (kept for security)
-- 3: the error source
err = formatError(err, 1);

-- Show a popup to the user
local str = L("Oops, an error occured:").."[NEWLINE][ICON_PIRATE] "..err;
Events.SerialEventGameMessagePopup( { Type = ButtonPopupTypes.BUTTONPOPUP_TEXT, Data1 = 800, Option1 = true, Text = str } );

-- Restore things up here when needed. Beware to not cause any error as it would cause an infinite recursive call up to the stack overflow!
return false
end

-- Calls someDangerousFunction with the given error handler
xpcall(someDangerousFunction, errorHandler)
</syntaxhighlight></div>

== Troubleshooting ==
The [[Civ5 Useful Programs]] page presents you a number of tools you can use to inspect or modify the game. This is especially useful if you want to quickly reproduce a bug or test something, or to understand what is happening.
* Let's say your mod adds a tech but you do not see in the techs panel. There is a FireTuner panel you can use to see a flat list of all the techs in-game.
* Let's say your mod adds a unit or a wonder, the IGE mod allows you to quickly create an unit or build that wonder (including the splash screen).
* Let's say your mod modifies the yields when the player acquire a specific tech. Once again IGE allows you to grant you that tech and see how the yields are modified.

== Configuration ==
Look for the following files under <code>My Documents/My Games/Sid Meiers' Civilization V</code> and open them in a text editor like the notepad (not in a word processor).
* '''config.ini'''
** Set <code>EnableTuner</code> to 1. Civ5 will duplicate the Lua output to FireTuner this one is when present.
** Set <code>LoggingEnabled</code> to 1. Civ5 will write log files under the <code>Logs</code> folder.
** Set <code>EnableLuaDebugLibrary</code> to 1. Civ5 will display stack traces on Lua errors and you will be able to use the [http://www.lua.org/manual/5.1/manual.html#pdf-debug.debug debug] object.
** Set <code>DebugPanel</code> to 1. By pressing the '''²''' key (may be '''ù''' or something else depending on your computer's language) during a game, Civ5 will display a debug panel.
* '''usersettings.ini'''
** Set <code>DebugMode</code> to 1. Needed to enable other features previously mentioned.

[[Category:Civ5 Tutorials]]

Debugging (Civ5)

2012-09-25T11:59:28Z

DonQuich:

''This page is a part of the [[Civ5 Modding Tutorials]].''

== Checklist ==
* Did you correctly import to the [[VFS (Civ5)|VFS]] the files that need to be?
* Did you correctly set up the actions and content tab in your project?
* Did you restart civ5 after you added new files?

== XML Debugging ==
[[File:SQLiteManager.png|frame|View of the snapshot using SQLiteManager]]
=== Checking the logs ===
If you correctly set up your [[#Configuration]], whenever you start a game, Civ5 saves some logs under <code>My Games/Sid Medier's Civilization V/cache/Civ5DebugDatabase.db</code>.
* If there were errors with the XML formatting of your data files (wrong column names for example), they will logged in XML.log. Some of those errors may be fatal: in such a case no mod is loaded!
:<pre>[6904.323] Tag (TXT_KEYMODDING_SHOWDLCMODS) does not start with 'TXT_KEY_'</pre>
* If there were errors with the data integrity (missing foreign keys for example - types that reference rows from other tables), they will logged in database.log.
:<pre>[6903.917] Invalid Reference on Leader_Flavors.LeaderType - "LEADER_HARALD" does not exist in Leaders</pre>

=== Using the snapshots ===
If you correctly set up your [[#Configuration]], whenever you start a game, Civ5 saves a snapshot of the database under <code>My Games/Sid Medier's Civilization V/cache/Civ5DebugDatabase.db</code>
* This allows you to check how your XML and SQL files have been merged with the standard game data.

== Lua Debugging ==
=== Using the Firetuner console ===
If you correctly set up your [[#Configuration]], Civ5 will send all the Lua output to the Firetuner (and also to the <code>Lua.log</code> file). This includes all the debugging output but also any error that may arise, with their calls stack traces.
<pre>
Runtime Error: [string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:41: attempt to concatenate local 'name' (a nil value)
stack traceback:
[string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:41: in function 'dumpObj'
[string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:95: in function 'ScanAll'
[string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:188: in main chunk
[C]: ?
</pre>
Here we can see that a C/C++ code (the game engine) ran the main chunk called (the Lua file), which then called the function ''ScanAll'' on line 188, which then called ''dumpObj'' on line 95. And this one caused an error on line 41.

Note that paths are truncated in the provided example, which makes debugging harder sometimes. This happens when the file is in a {{Type5|context}} registered by the project's ''content'' tab. Here are the workarounds:
* Provide a custom stack trace, as explained in a further section.
* Register only a minimalist context, that will load additional contexts (through the UI LuaContext markup). Do not initiate any action from the root context, let the children context handle everything.
* Modifying your system paths is not recommended as it can cause incompatibilities with a few applications (old or badly written).

=== Print, assert and error ===
<code>print('''...''')</code> can be used to print anything to the Firetuner output. This allows you to check the flow of a program, or the values of variables. Print calls '''tostring''' on every argument and displays them all on a single line with tabulations as separators between them. Nil values are not displayed, so it is advised you provide expressions such as: <code>(expr or 'nil')</code>

<code>error('''string''' message, '''int''' level = 1)</code> throws an error with the specified message. The execution is then halted and the hand returned to the game engine (or the current protected call if you did use '''pcall''' or '''xpcall'''). The level parameter controls the error position that will be reported. 1 for the line where error is located, 2 for the function call that contained an error, etc. 0 for no position.

<code>assert('''variant''' condition, '''string''' message = "assertion failed")</code> can be used to assert the provided condition is neither nil nor false (everything else is evaluated to true in Lua). Otherwise, an error with the specified message is thrown. You can use them punctually, as a debugging technique. But they may also be used as a defensive programming technique similar to [http://en.wikipedia.org/wiki/Design_by_contract design-by-contract]: the idea is that whenever your program's correctness relies on an assumption, you should explicitly check it. For example, if a function takes an array as an argument and assumes that it is not empty, you should add two conditions at the beginning: <code>assert(type(t) == "table")</code> and <code>assert(#t > 0)</code>. This makes the code more self-explanatory (implicit assumptions are now explicitly stated) and it allows you to catch bugs as soon as possible, which typically makes them easier to understand and fix.

=== The end users' feedback ===
Most of the time, when one of your user encounters an error with your mod, he just stops using it. A fraction of them will do the effort of reporting bugs but too often the informations they provide is unusable (from "it doesn't work" to wrong reproduction steps "play until turn 173 and wait for Mars being aligned with Venus"). The best way to increase the number of reports and their usefulness is to let your mod tell them the info it needs, as illustrated below.

[[File:IGE-Error.png|none|frame|[http://forums.civfanatics.com/showthread.php?t=436912 In-game editor] tells its users what they must report, even including a calls stack trace when available. The user only needs to make a screenshot that will then land on his Steam profile (provided he didn't change the Steam settings). Reporting made easy!]]

The [[Lua introduction for confirmed developers]] describes a number of techniques you can use to achieve similar results. Here we present an implementation you can use to handle errors in the most dangerous parts of your code in order to present them to the user with a full stack trace when available.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Returns an array of strings, one for each call level.
-- We could use debug.traceback instead but this ones truncates path and we cannot easily ignore the topmost levels.
function getStackTrace()
-- Level 1 is getStackTrace, 2 is its caller
local level = 2
local trace = {}
while true do
-- Gets that level's informations: function name, source file and line.
local info = debug.getinfo(level, "nSl")
if not info then break end

-- C code or Lua code?
if info.what == "C" then
table.insert(trace, "C function");
else
local userStr = Path.GetFileName(info.source)..": "..info.currentline;
if info.name and string.len(info.name) then
userStr = userStr.." ("..info.name..")";
end
table.insert(trace, userStr);
end
level = level + 1
end
return trace;
end

-- Gets a nicely formatted string of the error.
-- The second parameter is the number of levels to ignore in the calls stack (formatError excluded). Defaults to 0.
function formatError(err, levelsToIgnoreBelow)
print(err);

-- We do not want to include formatError in the stack trace, hence the +1
levelsToIgnoreBelow = (levelsToIgnoreBelow or 0) + 1;

-- 'err' is like: [string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:41: attempt to concatenate local 'name' (a nil value)
-- We retrieve important positions in this string. Remember: not all paths are truncated.
local elipsisIndex = string.find(err, "...", 1, true) or -5;
local lineIndex = elipsisIndex + 6
local msgIndex = string.find(err, ":", lineIndex, true) + 1

-- Can we append the stack trace?
local result = ""
if debug and debug.getinfo then
result = string.sub(err, msgIndex)

local trace = getStackTrace()
for i, v in ipairs(trace) do
print(v)
if (i > levelsToIgnoreBelow) then
result = result.."[NEWLINE]"..v;
end
end
-- Otherwise just report the line and message, and the source file when not truncated.
else
result = "line "..string.sub(err, elipsisIndex)
end

return result
end

-- The error handler to provide to xpcall
local function errorHandler(err)
-- The stack trace at this point is:
-- 1: this error handler (must not be reported),
-- 2: C function calling the handler (kept for security)
-- 3: the error source
err = formatError(err, 1);

-- Show a popup to the user
local str = L("Oops, an error occured:").."[NEWLINE][ICON_PIRATE] "..err;
Events.SerialEventGameMessagePopup( { Type = ButtonPopupTypes.BUTTONPOPUP_TEXT, Data1 = 800, Option1 = true, Text = str } );

-- Restore things up here when needed. Beware to not cause any error as it would cause an infinite recursive call up to the stack overflow!
return false
end

-- Calls someDangerousFunction with the given error handler
xpcall(someDangerousFunction, errorHandler)
</syntaxhighlight></div>

== Troubleshooting ==
The [[Civ5 Useful Programs]] page presents you a number of tools you can use to inspect or modify the game. This is especially useful if you want to quickly reproduce a bug or test something, or to understand what is happening.
* Let's say your mod adds a tech but you do not see in the techs panel. There is a FireTuner panel you can use to see a flat list of all the techs in-game.
* Let's say your mod adds a unit or a wonder, the IGE mod allows you to quickly create an unit or build that wonder (including the splash screen).
* Let's say your mod modifies the yields when the player acquire a specific tech. Once again IGE allows you to grant you that tech and see how the yields are modified.

== Configuration ==
Look for the following files under <code>My Documents/My Games/Sid Meiers' Civilization V</code> and open them in a text editor like the notepad (not in a word processor).
* '''config.ini'''
** Set <code>EnableTuner</code> to 1. Civ5 will duplicate the Lua output to FireTuner this one is when present.
** Set <code>LoggingEnabled</code> to 1. Civ5 will write log files under the <code>Logs</code> folder.
** Set <code>EnableLuaDebugLibrary</code> to 1. Civ5 will display stack traces on Lua errors and you will be able to use the [http://www.lua.org/manual/5.1/manual.html#pdf-debug.debug debug] object.
** Set <code>DebugPanel</code> to 1. By pressing the '''²''' key (may be '''ù''' or something else depending on your computer's language) during a game, Civ5 will display a debug panel.
* '''usersettings.ini'''
** Set <code>DebugMode</code> to 1. Needed to enable other features previously mentioned.

[[Category:Civ5 Tutorials]]

Debugging (Civ5)

2012-09-25T10:11:32Z

DonQuich:

''This page is a part of the [[Civ5 Modding Tutorials]].''

== Checklist ==
* Did you correctly import to the [[VFS (Civ5)|VFS]] the files that need to be?
* Did you correctly set up the actions and content tab in your project?
* Did you restart civ5 after you added new files?

== XML Debugging ==
[[File:SQLiteManager.png|frame|View of the snapshot using SQLiteManager]]
=== Checking the logs ===
If you correctly set up your [[#Configuration]], whenever you start a game, Civ5 saves some logs under <code>My Games/Sid Medier's Civilization V/cache/Civ5DebugDatabase.db</code>.
* If there were errors with the XML formatting of your data files (wrong column names for example), they will logged in XML.log. Some of those errors may be fatal: in such a case no mod is loaded!
:<pre>[6904.323] Tag (TXT_KEYMODDING_SHOWDLCMODS) does not start with 'TXT_KEY_'</pre>
* If there were errors with the data integrity (missing foreign keys for example - types that reference rows from other tables), they will logged in database.log.
:<pre>[6903.917] Invalid Reference on Leader_Flavors.LeaderType - "LEADER_HARALD" does not exist in Leaders</pre>

=== Using the snapshots ===
If you correctly set up your [[#Configuration]], whenever you start a game, Civ5 saves a snapshot of the database under <code>My Games/Sid Medier's Civilization V/cache/Civ5DebugDatabase.db</code>
* This allows you to check how your XML and SQL files have been merged with the standard game data.

== Lua Debugging ==
=== Using the Firetuner console ===
If you correctly set up your [[#Configuration]], Civ5 will send all the Lua output to the Firetuner (and also to the <code>Lua.log</code> file). This includes all the debugging output but also any error that may arise, with their calls stack traces.
<pre>
Runtime Error: [string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:41: attempt to concatenate local 'name' (a nil value)
stack traceback:
[string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:41: in function 'dumpObj'
[string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:95: in function 'ScanAll'
[string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:188: in main chunk
[C]: ?
</pre>
Here we can see that a C/C++ code (the game engine) ran the main chunk called (the Lua file), which then called the function ''ScanAll'' on line 188, which then called ''dumpObj'' on line 95. And this one caused an error on line 41.

Note that paths are truncated in the provided example, which makes debugging harder sometimes. This happens when the file is in a {{Type5|context}} registered by the project's ''content'' tab. Here are the workarounds:
* Provide a custom stack trace, as explained in a further section.
* Register only a minimalist context, that will load additional contexts (through the UI LuaContext markup). Do not initiate any action from the root context, let the children context handle everything.
* Modifying your system paths is not recommended as it can cause incompatibilities with a few applications (old or badly written).

=== Print, assert and error ===
<code>print('''...''')</code> can be used to print anything to the Firetuner output. This allows you to check the flow of a program, or the values of variables. Print calls '''tostring''' on every argument and displays them all on a single line with tabulations as separators between them. Nil values are not displayed, so it is advised you provide expressions such as: <code>(expr or 'nil')</code>

<code>error('''string''' message, '''int''' level = 1)</code> throws an error with the specified message. The execution is then halted and the hand returned to the game engine (or the current protected call if you did use '''pcall''' or '''xpcall'''). The level parameter controls the error position that will be reported. 1 for the line where error is located, 2 for the function call that contained an error, etc. 0 for no position.

<code>assert('''variant''' condition, '''string''' message = "assertion failed")</code> can be used to assert the provided condition is neither nil nor false (everything else is evaluated to true in Lua). Otherwise, an error with the specified message is thrown. You can use them punctually, as a debugging technique. But they may also be used as a defensive programming technique similar to [http://en.wikipedia.org/wiki/Design_by_contract design-by-contract]: the idea is that whenever your program's correctness relies on an assumption, you should explicitly check it. For example, if a function takes an array as an argument and assumes that it is not empty, you should add two conditions at the beginning: <code>assert(type(t) == "table")</code> and <code>assert(#t > 0)</code>. This makes the code more self-explanatory (implicit assumptions are now explicitly stated) and it allows you to catch bugs as soon as possible, which typically makes them easier to understand and fix.

=== Handling errors for the end user ===
Most of the time, when one of your user encounters an error with your mod, he just stops using it. A fraction of them will do the effort of reporting bugs but too often the informations they provide is unusable (from "it doesn't work" to wrong reproduction steps "play until turn 173 and wait for Mars being aligned with Venus"). The best way to increase the number of reports and their usefulness is to let your mod tell them the info it needs, as illustrated below.

[[File:IGE-Error.png|none|frame|[http://forums.civfanatics.com/showthread.php?t=436912 In-game editor] tells its users what they must report, even including a calls stack trace when available. The user only needs to make a screenshot that will then land on his Steam profile (provided he didn't change the Steam settings). Reporting made easy!]]

The [[Lua introduction for confirmed developers]] describes a number of techniques you can use to achieve similar results. Here we present an implementation you can use to handle errors in the most dangerous parts of your code in order to present them to the user with a full stack trace when available.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Returns an array of strings, one for each call level.
-- We could use debug.traceback instead but this ones truncates path and we cannot easily ignore the topmost levels.
function getStackTrace()
-- Level 1 is getStackTrace, 2 is its caller
local level = 2
local trace = {}
while true do
-- Gets that level's informations: function name, source file and line.
local info = debug.getinfo(level, "nSl")
if not info then break end

-- C code or Lua code?
if info.what == "C" then
table.insert(trace, "C function");
else
local userStr = Path.GetFileName(info.source)..": "..info.currentline;
if info.name and string.len(info.name) then
userStr = userStr.." ("..info.name..")";
end
table.insert(trace, userStr);
end
level = level + 1
end
return trace;
end

-- Gets a nicely formatted string of the error.
-- The second parameter is the number of levels to ignore in the calls stack (formatError excluded). Defaults to 0.
function formatError(err, levelsToIgnoreBelow)
print(err);

-- We do not want to include formatError in the stack trace, hence the +1
levelsToIgnoreBelow = (levelsToIgnoreBelow or 0) + 1;

-- 'err' is like: [string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:41: attempt to concatenate local 'name' (a nil value)
-- We retrieve important positions in this string. Remember: not all paths are truncated.
local elipsisIndex = string.find(err, "...", 1, true) or -5;
local lineIndex = elipsisIndex + 6
local msgIndex = string.find(err, ":", lineIndex, true) + 1

-- Can we append the stack trace?
local result = ""
if debug and debug.getinfo then
result = string.sub(err, msgIndex)

local trace = getStackTrace()
for i, v in ipairs(trace) do
print(v)
if (i > levelsToIgnoreBelow) then
result = result.."[NEWLINE]"..v;
end
end
-- Otherwise just report the line and message, and the source file when not truncated.
else
result = "line "..string.sub(err, elipsisIndex)
end

return result
end

-- The error handler to provide to xpcall
local function errorHandler(err)
-- The stack trace at this point is:
-- 1: this error handler (must not be reported),
-- 2: C function calling the handler (kept for security)
-- 3: the error source
err = formatError(err, 1);

-- Show a popup to the user
local str = L("Oops, an error occured:").."[NEWLINE][ICON_PIRATE] "..err;
Events.SerialEventGameMessagePopup( { Type = ButtonPopupTypes.BUTTONPOPUP_TEXT, Data1 = 800, Option1 = true, Text = str } );

-- Restore things up here when needed. Beware to not cause any error as it would cause an infinite recursive call up to the stack overflow!
return false
end

-- Calls someDangerousFunction with the given error handler
xpcall(someDangerousFunction, errorHandler)
</syntaxhighlight></div>

== Troubleshooting ==
The [[Civ5 Useful Programs]] page presents you a number of tools you can use to inspect or modify the game. This is especially useful if you want to quickly reproduce a bug or test something, or to understand what is happening.
* Let's say your mod adds a tech but you do not see in the techs panel. There is a FireTuner panel you can use to see a flat list of all the techs in-game.
* Let's say your mod adds a unit or a wonder, the IGE mod allows you to quickly create an unit or build that wonder (including the splash screen).
* Let's say your mod modifies the yields when the player acquire a specific tech. Once again IGE allows you to grant you that tech and see how the yields are modified.

== Configuration ==
Look for the following files under <code>My Documents/My Games/Sid Meiers' Civilization V</code> and open them in a text editor like the notepad (not in a word processor).
* '''config.ini'''
** Set <code>EnableTuner</code> to 1. Civ5 will duplicate the Lua output to FireTuner this one is when present.
** Set <code>LoggingEnabled</code> to 1. Civ5 will write log files under the <code>Logs</code> folder.
** Set <code>EnableLuaDebugLibrary</code> to 1. Civ5 will display stack traces on Lua errors and you will be able to use the [http://www.lua.org/manual/5.1/manual.html#pdf-debug.debug debug] object.
** Set <code>DebugPanel</code> to 1. By pressing the '''²''' key (may be '''ù''' or something else depending on your computer's language) during a game, Civ5 will display a debug panel.
* '''usersettings.ini'''
** Set <code>DebugMode</code> to 1. Needed to enable other features previously mentioned.

[[Category:Civ5 Tutorials]]

Debugging (Civ5)

2012-09-25T10:10:01Z

DonQuich:

''This page is a part of the [[Civ5 Modding Tutorials]].''

== Checklist ==
* Did you correctly import to the [[VFS (Civ5)|VFS]] the files that need to be?
* Did you correctly set up the actions and content tab in your project?
* Did you restart civ5 after you added new files?

== XML Debugging ==
[[File:SQLiteManager.png|frame|View of the snapshot using SQLiteManager]]
=== Checking the logs ===
If you correctly set up your [[#Configuration]], whenever you start a game, Civ5 saves some logs under <code>My Games/Sid Medier's Civilization V/cache/Civ5DebugDatabase.db</code>.
* If there were errors with the XML formatting of your data files (wrong column names for example), they will logged in XML.log. Some of those errors may be fatal: in such a case no mod is loaded!
:<pre>[6904.323] Tag (TXT_KEYMODDING_SHOWDLCMODS) does not start with 'TXT_KEY_'</pre>
* If there were errors with the data integrity (missing foreign keys for example - types that reference rows from other tables), they will logged in database.log.
:<pre>[6903.917] Invalid Reference on Leader_Flavors.LeaderType - "LEADER_HARALD" does not exist in Leaders</pre>

=== Using the snapshots ===
If you correctly set up your [[#Configuration]], whenever you start a game, Civ5 saves a snapshot of the database under <code>My Games/Sid Medier's Civilization V/cache/Civ5DebugDatabase.db</code>
* This allows you to check how your XML and SQL files have been merged with the standard game data.

== Lua Debugging ==
=== Using the Firetuner console ===
If you correctly set up your [[#Configuration]], Civ5 will send all the Lua output to the Firetuner. This includes all the debugging output but also any error that may arise, with their calls stack traces.
<pre>
Runtime Error: [string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:41: attempt to concatenate local 'name' (a nil value)
stack traceback:
[string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:41: in function 'dumpObj'
[string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:95: in function 'ScanAll'
[string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:188: in main chunk
[C]: ?
</pre>
Here we can see that a C/C++ code (the game engine) ran the main chunk called (the Lua file), which then called the function ''ScanAll'' on line 188, which then called ''dumpObj'' on line 95. And this one caused an error on line 41.

Note that paths are truncated in the provided example, which makes debugging harder sometimes. This happens when the file is in a {{Type5|context}} registered by the project's ''content'' tab. Here are the workarounds:
* Register only a minimalist context, that will load additional contexts (through the UI LuaContext markup). Do not initiate any action from the root context, let the children context handle everything.
* Provide a custom stack trace, as explained in a further section.

=== Print, assert and error ===
<code>print('''...''')</code> can be used to print anything to the Firetuner output. This allows you to check the flow of a program, or the values of variables. Print calls '''tostring''' on every argument and displays them all on a single line with tabulations as separators between them. Nil values are not displayed, so it is advised you provide expressions such as: <code>(expr or 'nil')</code>

<code>error('''string''' message, '''int''' level = 1)</code> throws an error with the specified message. The execution is then halted and the hand returned to the game engine (or the current protected call if you did use '''pcall''' or '''xpcall'''). The level parameter controls the error position that will be reported. 1 for the line where error is located, 2 for the function call that contained an error, etc. 0 for no position.

<code>assert('''variant''' condition, '''string''' message = "assertion failed")</code> can be used to assert the provided condition is neither nil nor false (everything else is evaluated to true in Lua). Otherwise, an error with the specified message is thrown. You can use them punctually, as a debugging technique. But they may also be used as a defensive programming technique similar to [http://en.wikipedia.org/wiki/Design_by_contract design-by-contract]: the idea is that whenever your program's correctness relies on an assumption, you should explicitly check it. For example, if a function takes an array as an argument and assumes that it is not empty, you should add two conditions at the beginning: <code>assert(type(t) == "table")</code> and <code>assert(#t > 0)</code>. This makes the code more self-explanatory (implicit assumptions are now explicitly stated) and it allows you to catch bugs as soon as possible, which typically makes them easier to understand and fix.

=== Handling errors for the end user ===
Most of the time, when one of your user encounters an error with your mod, he just stops using it. A fraction of them will do the effort of reporting bugs but too often the informations they provide is unusable (from "it doesn't work" to wrong reproduction steps "play until turn 173 and wait for Mars being aligned with Venus"). The best way to increase the number of reports and their usefulness is to let your mod tell them the info it needs, as illustrated below.

[[File:IGE-Error.png|none|frame|[http://forums.civfanatics.com/showthread.php?t=436912 In-game editor] tells its users what they must report, even including a calls stack trace when available. The user only needs to make a screenshot that will then land on his Steam profile (provided he didn't change the Steam settings). Reporting made easy!]]

The [[Lua introduction for confirmed developers]] describes a number of techniques you can use to achieve similar results. Here we present an implementation you can use to handle errors in the most dangerous parts of your code in order to present them to the user with a full stack trace when available.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Returns an array of strings, one for each call level.
-- We could use debug.traceback instead but this ones truncates path and we cannot easily ignore the topmost levels.
function getStackTrace()
-- Level 1 is getStackTrace, 2 is its caller
local level = 2
local trace = {}
while true do
-- Gets that level's informations: function name, source file and line.
local info = debug.getinfo(level, "nSl")
if not info then break end

-- C code or Lua code?
if info.what == "C" then
table.insert(trace, "C function");
else
local userStr = Path.GetFileName(info.source)..": "..info.currentline;
if info.name and string.len(info.name) then
userStr = userStr.." ("..info.name..")";
end
table.insert(trace, userStr);
end
level = level + 1
end
return trace;
end

-- Gets a nicely formatted string of the error.
-- The second parameter is the number of levels to ignore in the calls stack (formatError excluded). Defaults to 0.
function formatError(err, levelsToIgnoreBelow)
print(err);

-- We do not want to include formatError in the stack trace, hence the +1
levelsToIgnoreBelow = (levelsToIgnoreBelow or 0) + 1;

-- 'err' is like: [string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:41: attempt to concatenate local 'name' (a nil value)
-- We retrieve important positions in this string. Remember: not all paths are truncated.
local elipsisIndex = string.find(err, "...", 1, true) or -5;
local lineIndex = elipsisIndex + 6
local msgIndex = string.find(err, ":", lineIndex, true) + 1

-- Can we append the stack trace?
local result = ""
if debug and debug.getinfo then
result = string.sub(err, msgIndex)

local trace = getStackTrace()
for i, v in ipairs(trace) do
print(v)
if (i > levelsToIgnoreBelow) then
result = result.."[NEWLINE]"..v;
end
end
-- Otherwise just report the line and message, and the source file when not truncated.
else
result = "line "..string.sub(err, elipsisIndex)
end

return result
end

-- The error handler to provide to xpcall
local function errorHandler(err)
-- The stack trace at this point is:
-- 1: this error handler (must not be reported),
-- 2: C function calling the handler (kept for security)
-- 3: the error source
err = formatError(err, 1);

-- Show a popup to the user
local str = L("Oops, an error occured:").."[NEWLINE][ICON_PIRATE] "..err;
Events.SerialEventGameMessagePopup( { Type = ButtonPopupTypes.BUTTONPOPUP_TEXT, Data1 = 800, Option1 = true, Text = str } );

-- Restore things up here when needed. Beware to not cause any error as it would cause an infinite recursive call up to the stack overflow!
return false
end

-- Calls someDangerousFunction with the given error handler
xpcall(someDangerousFunction, errorHandler)
</syntaxhighlight></div>

== Troubleshooting ==
The [[Civ5 Useful Programs]] page presents you a number of tools you can use to inspect or modify the game. This is especially useful if you want to quickly reproduce a bug or test something, or to understand what is happening.
* Let's say your mod adds a tech but you do not see in the techs panel. There is a FireTuner panel you can use to see a flat list of all the techs in-game.
* Let's say your mod adds a unit or a wonder, the IGE mod allows you to quickly create an unit or build that wonder (including the splash screen).
* Let's say your mod modifies the yields when the player acquire a specific tech. Once again IGE allows you to grant you that tech and see how the yields are modified.

== Configuration ==
Look for the following files under <code>My Documents/My Games/Sid Meiers' Civilization V</code> and open them in a text editor like the notepad (not in a word processor).
* '''config.ini'''
** Set <code>EnableTuner</code> to 1. Civ5 will duplicate the Lua output to FireTuner this one is when present.
** Set <code>LoggingEnabled</code> to 1. Civ5 will write log files under the <code>Logs</code> folder.
** Set <code>EnableLuaDebugLibrary</code> to 1. Civ5 will display stack traces on Lua errors and you will be able to use the [http://www.lua.org/manual/5.1/manual.html#pdf-debug.debug debug] object.
** Set <code>DebugPanel</code> to 1. By pressing the '''²''' key (may be '''ù''' or something else depending on your computer's language) during a game, Civ5 will display a debug panel.
* '''usersettings.ini'''
** Set <code>DebugMode</code> to 1. Needed to enable other features previously mentioned.

[[Category:Civ5 Tutorials]]

XML-SQL Cheat Sheet (Civ5)

2012-09-25T08:44:53Z

DonQuich:

''This page is a part of the [[Civ5 XML Reference]].''

== Things to remember ==
* '''Booleans:''' SQLite does not have booleans, it uses integers. So do not use <code>true</code> or <code>false</code>, use <code>1</code> and <code>0</code>.

== Inserting rows ==
=== XML ===
<div class="civ5-example"><syntaxhighlight lang="xml" style="left:40px;">
<GameData>
<Colors>

<Row>
<Type>COLOR_CUSTOM</Type>
<Red>0.1</Red>
<Green>0.1</Green>
<Blue>0.1</Blue>
<Alpha>0.45</Alpha>
</Row>
</Colors>
<GameData>
</syntaxhighlight></div>

=== SQL ===
<div class="civ5-example"><syntaxhighlight lang="sql">
/* Inserts a new color */
INSERT INTO Colors (Type, Red, Green, Blue, Alpha)
VALUES ('COLOR_CUSTOM', 0.1, 0.1, 0.1, 0.45);
</syntaxhighlight></div>

== Deleting rows ==
{{Warning}} See [http://forums.civfanatics.com/showthread.php?t=463429 Deleting data and issues, and how to avoid them] if you plan to delete rows and are not aware of the troubles that may arise.
=== XML ===
<div class="civ5-example"><syntaxhighlight lang="xml">
<GameData>
<Colors>

<Delete Type="COLOR_CUSTOM" />

<Delete R="1" G="1"/>
</Colors>
<GameData>
</syntaxhighlight></div>

=== SQL ===
<div class="civ5-example"><syntaxhighlight lang="sql">
/* Deletes all colors named TYPE_CUSTOM whose red channel is equal to 1 */
DELETE FROM Colors
WHERE Type = 'COLOR_CUSTOM' AND Red = 1;
</syntaxhighlight></div>

== Updating rows ==
=== XML ===
<div class="civ5-example"><syntaxhighlight lang="xml">
<GameData>
<Colors>

<Update>
<Where Type="COLOR_CUSTOM" Red="0"/>
<Set Red="1" Green="0"/>
</Update>

<Update>
<Where>
<Type>COLOR_CUSTOM</Type>
</Where>
<Set>
<Red>1</Red>
<Green>1</Green>
</Set>
</Update>
</Colors>
</GameData>
</syntaxhighlight></div>

=== SQL ===
<div class="civ5-example"><syntaxhighlight lang="sql">
/* Update all colors whose names are COLOR_CUSTOM and red channel is 0 */
UPDATE Colors
SET Red = 1, Green = 0
WHERE Type = 'COLOR_CUSTOM' AND Red = 0;

/* Makes everything brighter */
UPDATE Colors
SET Red = Red + 0.1, Green = Green + 0.1, Blue=Blue + 0.1;
</syntaxhighlight></div>

== New tables ==
=== XML ===
<div class="civ5-example"><syntaxhighlight lang="xml">
<GameData>
<Table Name="MyColors">
<Column name="ID" type="integer" primarykey="true" autoincrement="true"/>
<Column name="Type" type="text" notnull="true" unique="true"/>
</Table>
</GameData>
</syntaxhighlight></div>

=== SQL ===
<div class="civ5-example"><syntaxhighlight lang="sql">
/* Create one new table with two columns */
CREATE TABLE MyColors( id INTEGER PRIMARY KEY AUTOINCREMENT, Type TEXT UNIQUE );
</syntaxhighlight></div>

== New columns ==
=== SQL ===
<div class="civ5-example"><syntaxhighlight lang="sql">
/* Adds one Description column to Colors. */
ALTER TABLE Colors COLUMN 'Description' TEXT DEFAULT NULL;
</syntaxhighlight></div>

[[Category:Civ5 XML Files]]
[[Category:Civ5 Tutorials]]

Category:Civ5 API Images

2012-09-24T15:42:53Z

DonQuich:

Images used in the [[Lua and UI Reference|Lua and UI Reference (Civ5)]].

[[Category:Civ5 Images]]

File:SQLiteManager.png

2012-09-24T15:40:56Z

DonQuich:

:'''Author:''' [[User:DonQuich]]
:'''License:''' Public Domain
:'''Software:''' SQLite Manager

[[Category:Civ5 Images]]

File:SQLiteManager.png

2012-09-24T15:40:35Z

DonQuich:

:'''Author:''' [[User:DonQuich]]
:'''License:''' Public Domain
:'''Software:''' SQLite Manager

[[Category:Civ5]]

File:ModBuddy.ImportIntoVFS.png

2012-09-24T15:39:57Z

DonQuich:

:'''Author:''' [[User:DonQuich]]
:'''License:''' Public Domain

[[Category:Civ5 Images]]

Civ5 Useful Programs

2012-09-24T15:37:27Z

DonQuich:

This page includes information on the Civ5 Modding Tools as well as links to other useful programs.

== SDK ==
'''World Builder'''
:The stand-alone world builder allows users to create and modify maps and scenarios for Civilization V.

'''Mod Buddy'''
:An editor (IDE) for the XML and Lua elements of the game and allows for the creation, packaging, and uploading of mods. To use it, you have to install the [http://www.microsoft.com/downloads/en/details.aspx?FamilyID=DFBA7AC4-5366-456E-ABD6-0E3E6BA83B7C&displaylang=enMicrosoft Visual Studio 2010 Shell (Isolated) Redistributable Package].
:[http://forums.civfanatics.com/showthread.php?t=387554 Installing ModBuddy Extensions]

'''Nexus'''
:A collection of tools to to work with the art in Civilization V.
:[http://forums.civfanatics.com/showthread.php?t=386972 Initial Look at Nexus, 3D Unit Art, and Reskinning]
:Note that Photoshop templates for icons are also bundled in the SDK, under the ''Art'' folder (in ''Programs Files/Steam/...'').

'''FireTuner'''
:An advanced debugging terminal. It displays the lua output, provides an interactive console and can be simply extended with custom controls and tables.
:Do not forget to modify your *.ini files, see [[Debugging (Civ5)#Configuration|Debugging#Configuration]].
:[http://forums.civfanatics.com/showthread.php?t=399821 Simple Tuner Modifications]

== Digging the source code and the data tables ==
Since the documentation is sparse, you need a tool to quickly inspect the civ5 source and data files and search in all of them at once. See also [http://forums.civfanatics.com/showthread.php?t=475076 this comparison of search tools].

'''Notepad++'''
:A great and renowned text editor with a "search in all files" feature (hit ctrl + shift + f). Used by many developers around the world. [http://sourceforge.net/projects/notepad-plus/ Download].

== Browsing the art assets ==
'''Dragon unpacker'''
:Can extract the Firaxis packages (.fpk files). [http://sourceforge.net/projects/dragonunpacker/ Download].

'''DDS Unpacker'''
:Some DDS files have been compressed even further and look messed up if you open them in an image viewer. This tool rebuilds them. [http://forums.civfanatics.com/showthread.php?t=389316 Download].

'''XnView'''
:An images browser to get a quick look at all the DDS files to spot the one you're looking for. [http://www.xnview.com/en/download.html Download].

'''FireTuner: Textures Viewer'''
:A FireTuner panel to browse most of the game's textures. [http://forums.2kgames.com/showthread.php?118165-MOD-LiveTuner-Texture-Viewer Download].

'''FireTuner: Icons Viewer'''
:A FireTuner panel to browse the game's icons. [http://forums.2kgames.com/showthread.php?118055-MOD-LiveTuner-Icon-Viewer Download].

== Creating textures ==
'''NVidia Texture Tools for Photoshop'''
:A Photoshop plugin to save textures under the DDS format. [http://developer.nvidia.com/content/nvidia-texture-tools-adobe-photoshop Download]

'''Paint.net'''
:An easy-to-use and moderately powerful open-source image editor for Windows that natively supports the DDS format. [http://www.getpaint.net/ Download]

== Testing and debugging ==

=== SQLite tools ===
Anytime it starts a game, Civilization V saves a SQLite snapshot of the database, including the changes made by mods, under ''Civ5DebugDatabase.db''.

'''SQLite Manager'''
:A Firefox plug-in, slightly more powerful than the previous tool. [https://addons.mozilla.org/en-US/firefox/addon/sqlite-manager/ Download]

'''SQLiteSpy'''
:A Windows software to inspect the SQLite files. [http://www.yunqa.de/delphi/doku.php/products/sqlitespy/index Download]

'''SQLite Browser'''
:A Windows software to inspect the SQLite files. [http://sqlitebrowser.sourceforge.net/screenshots.html Download]

=== Cheating tools and game inspectors ===
'''In-game Editor (IGE)'''
:Add or remove units, cities, resources, change the terrain, trigger wars, etc. Convenient to quickly test your mod. [http://forums.civfanatics.com/showthread.php?t=436912 Download] (also on the Steam Workshop).

'''FireTuner: Techs and policies panel'''
:A FireTuner panel to list, grant and revoke techs and policies. [http://forums.2kgames.com/showthread.php?108533-MOD-LiveTuner-Tech-and-Policy-Panels Download].

[[Category:Civ5]]

Lua introduction for confirmed developers

2012-09-24T15:30:23Z

DonQuich:

''This page is a part of the [[Lua and UI Reference (Civ5)|Lua and UI Reference]].''

== About Lua ==
===Lua, not LUA===
This is a Portuguese word meaning "moon", not an acronym.

===Presentation===
Lua is an interpreted, dynamically typed, multi-paradigm language. It was designed in 1993 with the following objectives in mind:
* Extensible semantics. A small set of features allows the support of multiple paradigms, from functional programming to object programming. For example, while inheritance is not natively supported, it can be easily set up through metatables. The same features allow events in civ5 to behave both as functions and objects with Add and Remove methods.
* Highly portable. The con is a lightweight and somewhat lacking API.
* Easy to embed and to interface from other languages.
* Well suited for data description (''à la'' JSON).
* A beginners-friendly syntax.

===Performances===
As usual with interpreted and dynamically typed languages (hereby abusively named "scripting languages"), expect a 10 to 100 order of magnitude in performances decrease when compared to compiled and statically typed languages like C, C++ or C#. While it is possible for scripting languages to drastically improve the performances through more or less sophisticated means (expression trees/opcodes caching, JIT compiler, type inference to perform static resolutions), no such solution has been used in Civ5 (aside, probably, of the caching). And while an external JIT library exists, it causes compatibility problems with most mods using Lua.

That being said, Lua is still pretty good for a scripting language, better than the Python implementation from Civ4 for example. And all in all, it is fast enough for most of what modders want to achieve without the need to compromise code elegance, readability and maintainability for performances. So keep in mind that "premature optimization is the root of all evil" (Donald Knuth).

==Syntax cheatsheet==
=== Basics ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Literals
local x = 5
local x = 5.0
local x = nil -- A nil value is the same as an undefined value
local x = true
local x = false

-- Strings (single and double quotes can be used indifferently, there is no difference)
local x = "five"
local x = 'five'
local x = "five\n" -- Escape characters with "\".
local x = [[Five is a number.
Did you know?]] -- Multi-line string: equivalent to "Five is number.\nDid you know?"

-- Globals versus locals
x = 5 -- For globals, assigning is declaring.
local x = 5
</syntaxhighlight></div>

=== Operators ===
<div class="civ5-example"><syntaxhighlight lang="lua">
local x = a or b
local x = a and b

local x = "hello ".."world" .. "!" -- concatenation: two dots
local x = 4..5 -- Result is "45". On concatenation, conversions occur.

local x = (a + b - d) * f ^ g % h -- ^ is exponentiation, % is modulo
local x = "4" + "5" -- Result is 9. On arithmetic operations, conversions occur.

local x = a == b -- equality -- True only if a and b have the same values and types.
local x = a ~= b -- inequality

local x = ((a <= b) == not (a > b)) == ((a >= b) == not (a < b))
local x = "abc" < "def" -- Byte-wise comparison, not Unicode-compliant. Use Locale's methods instead.

local x = #"abc" -- Returns 3, the number of bytes in the string (3 characters, 1 byte each).
local x = #"您好世界" -- Returns 8, the number of bytes in the string (4 characters, 2 bytes each).
local x = #SomeTable -- Returns the biggest integer key in the table, or nil if there is no integer key.

-- No increment operator (++ --), no binary-assign operator (+= *=), no ternary operator (? :), no coalescence operator (??)
</syntaxhighlight></div>

=== Tables and multiple assignments ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Table declaration
SomeTable = {}

SomeArray = { "abc", "def" }
-- 1 => "abc", 2 => "def"

SomeComplexTable = { name = "John", surname = "Doe", age = 25, 43, [7] = 8 }
-- "name" => "John", "surname" => "Doe", "age" => 25, 1 => 43, 7 => 8.

-- Member access (all equivalent)
SomeTable.SomeMember = 5
SomeTable["SomeMember"] = 5

-- Multiple assignment
-- Both statements are equivalent since SomeArray contains "abc" and "def".
local x, y = "abc", "def"
local x, y = unpack(SomeArray)
</syntaxhighlight></div>

=== Functions ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Functions declarations (all equivalent)
function HelloWorld(a, b) print("Hello world") end
HelloWorld = function(a, b) print("Hello world") end
-- Functions are first-class objects and can be assigned like any other value!

-- Methods declarations (all equivalent)
SomeTable.HelloWorld(a, b) print("Hello world") end
SomeTable.HelloWorld = function(a, b) print("Hello world") end

-- Instanced methods declarations (all equivalent)
SomeTable.HelloWorldInstanced(self, a, b) print(self.SomeMember) end
SomeTable:HelloWorldInstanced(a, b) print(self.SomeMember) end

-- Functions and methods calls
HelloWorld(a) -- b will be nil in the function
HelloWorld(a, b)
SomeTable.HelloWorld(a, b)

-- Instanced methods calls (all equivalent)
SomeTable:HelloWorldInstanced(a, b)
SomeTable.HelloWorldInstanced(SomeTable, a, b)

-- Multiple return values
function func(a, b) return a, b end
local x, y, z = func(5, 6) -- Assigns 5 to x and 6 to y, z will be nil

-- Variable arguments
function SomeFunc(a, b, ...)
print(a)
print(b)
for i, v in ipairs(arg) do -- arg is a keyword for a table containing the variable arguments
print(v)
end
end
SomeFunc(1, 2, 3, 4, 5) -- prints 1, 2, 3, 4, 5
SomeFunc(1, 2) -- prints 1, 2
</syntaxhighlight></div>

=== Control flow ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- If
if name == "Wu Zetian" then
print("Hello China")
elseif name == "Napoleon" then -- "elseif", not "else if". Beware C developers!
print("Hello France")
else -- no "then" after "else"!
print("Hello unknown")
end

-- For loop (with counter)
for i = 1, 8 do print(i) end -- Prints 1, 2, 3, 4, 5, 6, 7, 8
for i = 1, 8, 2 do print(i) end -- Prints 1, 3, 5, 7

-- For loop (with iterator)
for playerID, pPlayer in pairs(Players) do -- Prints 1 Wu Zetian, 2 Napoleon, ...
print(playerID, pPlayer:GetName())
end
for plot in Plots() do -- Prints 0 0, 0 1, 0 2, ...
print(plot:GetX(), plot:GetY())
end

-- While (i will be 5 in the end)
while i < 5 do
i = i + 1
end

-- Repeat until (i will be 5 in the end)
repeat
i = i + 1
until i == 5

-- Infinite loops
-- Lua supports "break" for all loops but not "continue" instruction does not exist!
do
i = i + 1
if i > 5 then break end
end

</syntaxhighlight></div>

== Basics ==
=== Type system ===
You can get a variable's type by using the '''type''' function. It takes any value and returns a string. Here are the possible results:
* '''nil''': Lua makes do distinction between an undefined variable and a variable with a nil value. Assigning nil to a variable or table member is equivalent to undefining it.
* '''number''': a 64 bits floating-point number. Lua has no support for integers and only use floating-points. See also [[#No integer type]].
* '''string''': your usual string of characters. In Lua all strings are interned. This speeds up comparisons but it makes allocation of new strings slower.
* '''boolean''': true or false obviously.
* '''table''': any table.
* '''userdata''': objects defined in C for use in Lua. They may not be enumerated through pairs and other limitations. Now the Civ5 API tend to return regular tables whose metatable is of type userdata, this allows us to use the provided objects as regular Lua tables.
* '''function''': remember that functions are first-class objects in Lua.
* '''thread''': coroutines actually. Lua does not support threads.

=== Implicit conversions ===
* Whenever you concatenate two values (and possibly when you invoke a standard function that takes a string), an automatic conversion to string occurs, as if you had used the '''tostring''' function. The expression <code>4..5</code> returns "45".
* Whenever you perform an arithmetic operation, the operands are both converted to numbers, as if you had used the '''tonumber''' function. The expression <code>"4" + "5"</code> returns 9.

=== Strict equality comparisons ===
'''Two values are equal only if their types are the same.'''<br/>
This is stricter than C and far stricter than PHP for example.
* 4 is not equal to "4". (number type and string type). In PHP they would be equal.
* 0 is not equal to false (number type and bool type). In C they would be equal.
* 0 is not equal to nil. (number type and nil type). In C they would be equal.

Regarding tables and C-made objects, they are compared by reference.
<div class="civ5-example"><syntaxhighlight lang="lua">
a = { 5 }
b = { 5 }
c = a
assert(a == c) -- OK
assert(a == b) -- ERROR
</syntaxhighlight></div>

=== Boolean logic ===
'''Anything that is neither false nor nil is evaluated to true.'''<br/>
This is pretty simple. Especially, an empty string or the zero number are evaluated to true.
<div class="civ5-example"><syntaxhighlight lang="lua">
if 0 then print("hello world") end -- prints hello world
</syntaxhighlight></div>

Now regarding the and/or operators, two rules to remember:
* '''The right operand is only evaluated when needed.'''
** <code>false and x()</code> does not call x() since the result will be false anyway.
** <code>true or x()</code> does not call x() since the result will be true anyway.
* '''The result is the last operand to have been evaluated.'''
** <code>x() and y()</code> returns x() if it was false, y() otherwise.
** <code>x() or y()</code> returns x() if it was true, y() otherwise.

=== Ternary and coalescence statements ===
We can exploit the and/or operators behavior:
* '''Coalescence:''' <code>x or y</code>. It returns x if x is neither nil nor false, y otherwise.
:In other words <code>result = x or y</code> is equivalent to: <code>if x then result = x else result = y end</code>.
* '''Ternary:''' <code>condition and x or y</code> (as long as x is not nil or false). It returns x if condition was true, y if it was false.
:Indeed the expression becomes: <code>(condition and x) or y</code>. If condition is true the '''and''' operator returns x, and since x is true, y is not evaluated and '''or''' returns x.
:In other words <code>result = condition and x or y</code> is equivalent to: <code>if condition then result = x else result = y end</code>.

=== Arrays versus tables ===
'''In Lua, an array is a table whose keys are integers.'''

Since this is a common programming pattern, a number of things are designed for arrays:
* <code>{"abc", "def", "ghi"}</code> starts at index 1, up to index 3. Arrays typically start at 1.
* <code>table.insert({}, "abc")</code> will transform the provided empty table to <code>{"abc"}</code>
* <code>table.insert({"abc", "def"}, "ghi")</code> will transform the provided table to <code>{"abc", "def", "ghi"}</code>
* <code>table.insert({"abc", "ghi"}, 2, "def")</code> will transform the provided table to <code>{"abc", "def", "ghi"}</code>
* <code>table.remove({"abc", "def", "ghi"}, 2)</code> will transform the provided table to <code>{"abc", ""ghi"}</code>
* <code>#{"abc", "def", "ghi"}</code> returns 3, the biggest integer key.

=== Ipairs versus pairs ===
You could say that '''pairs''' is for table and '''ipairs''' for arrays.
* '''Pairs''' enumerate all the key/value pairs in an unordered matter.
* '''Ipairs''' only enumerates the key/value pairs for consecutive integer keys, in an ascending order, starting from 1 up to the largest key. If at some point a key is missing, the enumeration stops.
::It does not matter whether the table was crated with table.insert or directly by inserting the values through, for example <code>table[i] = value</code>.

<div class="civ5-example"><syntaxhighlight lang="lua">
-- Produces: { 1 => "one", 2 => "two", 4 => "four", "name" => "John", "age" => 25 }
local t = { "one", "two", name = "John", age = 25, [4] = "four" }

-- Will print (for example, the order is undetermined): "name", 2, 4, "age", 1
for k in pairs(t) do print(k) end

-- Will print 1, 2
for k in ipairs(t) do print(k) end

-- Both ipairs and pairs return a key and a value, so you could also use:
for k, v in pairs(t) do print(k, v) end
</syntaxhighlight></div>

=== Semicolons and line breaks ===
'''Statements need to be separated either by a line break or a semicolon.'''
* You can use both a semicolon and a line break but then the semicolon is redundant and not required, although it does not cause any problem.
* Line breaks can also be freely added about everywhere and behave as whitespaces most of the time (you can add them after most keywords for example, so you can keep if...then...end structures on one line or split them across multiple lines).

=== Locals, globals and includes ===
* The include statement allows you to include a lua file into another one (see [[Specificities of the Lua implementation in Civ5]]). When you do so, the globals defined in the included file are imported in the parent file. However the local variables are only visible from within the file that declared them.
* Another specificities of locals: they're only visible after the point they have been declared in the file, while globals are always visible. An example is worth thousand of words.
<div class="civ5-example"><syntaxhighlight lang="lua">
function Func1()
print(someLocal or "nil")
print(someGlobal or "nil")
end

local someLocal = "foo"
function Func2()
print(someLocal or "nil")
print(someGlobal or "nil")
end

someGlobal = "global"
someLocal = "local"
Func1() -- prints "nil", then "global": someLocal is assigned but not visible from Func1
Func2() -- prints "local", then "global": someLocal is assigned and visible from Func2
</syntaxhighlight></div>
* Performances-wise, Lua first searches a variable name in the current scope, then in the parent scope, etcetera until it reaches the highest scope, and finally it searches the global scope. So the deeper a local is declared, the faster it is accessed. On the contrary, globals are the slowest to retrieve.

== Semi-advanced topics ==
=== Closures ===
'''Closures are functions that embed variables that are persisted across calls.'''<br/>
This is typically achieved through a "parent" function that declares a local "closed" variable and returns another child "closure" function using this local. The "closed" variable is then unreachable for anyone but the "closure". And since it the "closed" variable is not in the "closure"'s scope, it is not reinitialized on every call of "closure".
<div class="civ5-example"><syntaxhighlight lang="lua">
function GiveMeAFunc() -- the parent function
local x = 0 -- the closed variable
return function() -- the closure function embedding "closed"
x = x + 1
return closure
end
end

local func = GiveMeAFunc()
print(func()) -- Prints 1
print(func()) -- Prints 2
print(func()) -- Prints 3
</syntaxhighlight></div>

=== Iterators ===
'''Iterators are functions for use in <code>for...in</code> loops.'''<br/>
Let's consider the following code: <code>for var1, var2, var3 in iterable() do</code>.
* iterable has the following signature: <code>iterator, state, var1 iterable()</code>. It returns a function, a state, and the initial value of var1.
* iterator has the following signature: <code>var1, var2, var3 iterator(state, var1)</code>. It takes the state and the last value of var1 and returns var1, var2 and var3.
* The loop stops when var1 is nil.
* The for...in loop is equivalent to:
<div class="civ5-example"><syntaxhighlight lang="lua">
local iterator, state, var1, var2, var3
iterator, state, var1 = iterable()
do
var1, var2, var3 = iterator(state, var1)
if var1 == nil then break end

-- Inserts here the user code defined in the for..in loop
end
</syntaxhighlight></div>
* Note that we used var1, var2 and var3 for the example but there is no restriction to the number of variables. You could have one or hundred.

Let's write the "ipairs" function.
<div class="civ5-example"><syntaxhighlight lang="lua">
local function ipairs(table) -- The iterable function
local iterator = function(table, key) -- The iterator function
key = key + 1
return key, table[key]
end
return iterator, table, 0
end
</syntaxhighlight></div>

The same with closures: it's easier.
<div class="civ5-example"><syntaxhighlight lang="lua">
local function ipairs(table) -- The iterable function
local key = 0 -- Both "table" and "key" are closed variables.
local iterator = function() -- The iterator function, a closure: it ignores the arguments provided to it
key = key + 1
return key, table[key]
end
return iterator -- No need to return anything since we do not require any argument.
end
</syntaxhighlight></div>

=== No integer type ===
'''Lua offers no support for integers and only has a 64-bits floating point number type.'''<br/>
Actually, this is only troublesome for a few algorithms that use very large integers (>2^52) or require fast integer arithmetics. But many developers misunderstand floating points and believe the problem is broader than it is. For example, does the following assertion surprise you at least a bit: "any integer smaller than 2^52 can be accurately represented with a 64-bits floating point without any error"? If it did, you suffer from some misconceptions and you should better read carefully what's coming.

Many developers are confusing rounding errors with representation errors.
* '''Rounding errors''' actually only happen if you need a very high number of digits to represent a number. For example if you are adding a very large number with a small number. Rounding errors are very rarely encountered in day to day to applications. Actually most developers work their whole career without ever encountering them.
* '''Representation errors''' are the real problem: 0.1 is expressed in a decimal basis, but it has no finite representation in binary: it requires an infinite number of binary digits. This means that if you write 0.1 in your code it will be translated to a binary number close enough from 0.1 bot not exactly equal to it. So if you sum ten times 0.1, you sill sum ten times something close from 0.1 and the result will not be 1.

'''So the real problem for most developers only lies in the decimal-binary conversion that arises when you manipulate numbers in your code that do not have a finite representation in binary. As long as you do not use such numbers, there will be no problem. And here are the good news: integers do not suffer from any representation problem!''' Indeed, any integer can be represented with a finite number of binary digits. This is why the absence of an integer type typically does not cause problems, minus the performance penalty.

Here are a few examples to illustrate that point.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- This loop works as intended: no representation error and the upper bound is far below 2^52.
local sum = 0
for i = 0, 10000000000, 1 do sum = sum + 1 end
assert(sum == 10000000001)

-- This loop works as intended: 1/16 is a floating-point with an exact representation in binary
local sum = 0
for i = 0, 1, 1/16 do sum = sum + 1 end
assert(sum == 17/16)

-- This loop does NOT work as intended: 0.1 does not have an exact representation in binary.
-- It's the same for Lua, C and almost every programming language.
local sum = 0
for i = 0, 1, 0.1 do sum = sum + 1 end
assert(sum == 1.1) -- throws an error
</syntaxhighlight></div>

=== Errors management ===
Lua offers a error handling mechanism similar to exception handling but unfortunately not very convenient.
* Errors are thrown using the '''error''' function. It takes a string and it immediately aborts Lua execution until the game handles the error and prints it in Firetuner (when enabled).
* Errors are caught before that point using '''pcall''' or '''xpcall''', in order to let you resume execution by managing the error. "pcall" stands for "protected call".

Here are the syntaxes for pcall and xpcall:
* <code>bool, ... pcall(func, ...)</code>
** The function is called with the specified arguments.
** Pcall returns either true followed by the values returned by func, or false followed by the error text.
* <code>bool, ... xpcall(func, errorHandler)</code>:
** The function is called without any argument. If an error occurs the specified errorHandler is invoked with the error text as the only argument.
** Xpcall returns either true followed by the values returned by func, or false followed by the returned values from errorHandler.

Examples to invoke "someFunc" with "someArg" as the only argument. In both examples we want to display the error on the console, or the result if it was a success. A complete errors management example with a reporting mechanism for the end-user is presented in [[Debugging (Civ5)]].
<div class="civ5-example"><syntaxhighlight lang="lua">
-- pcall
local status, result = pcall(someFunc, someArg)
if not status then
print("error was: "..(result or "?"))
else
print("success: "..result)
end

-- xpcall
local status, result = xpcall(
function() someFunc(someArg) end,
function(err) print("error was: "..(result or "?")) end)

if status then
print("success: "..result)
end
</syntaxhighlight></div>

== Advanced topics==
=== Metatables and metamethods ===
* Every value in Lua, from a number to a userdata, has a metatable.
** Many objects can share the same metatable.
** Tables and userdata each have their own metatables by default. Numbers, bools, nils and strings all share the same metatable.
* A metatable may contain a few metamethods and index tables.
** Metamethods are methods stored under special fields names. They implement operators overloads.
** Index tables behave as "base classes": if a field name is not defined on an table, then Lua looks for this field on the index.
** In a way, metatables are analogous to virtual tables in object languages, but they are not just for methods, but also for fields and operators.
* You can get an object's metatable through '''getmetatable''' and assign it with '''setmetatable'''.
* See also the [http://www.lua.org/manual/5.1/manual.html#2.8 official metatables reference]

One example.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Define two tables A and B, and set "meta" their metatable
local a, b, meta = {}, {}, {}
setmetatable(a, meta)
setmetatable(b, meta)

-- Define an __index table on the metatable. It contains one key/value pair.
meta.__index = { "hello world" };

-- Print "hello world" twice
print(a[1])
print(b[1])

-- Now make our tables read-only
meta.__newindex = function(table, key, value) error("this table is read-only!") end
a[1] = "foo" -- throws an error
</syntaxhighlight></div>

Here are the most important fields a metatable can have:
* '''__index''': used when you read a member from an object. On tables, Lua will first search for a regular field on the table itself (not its index) before it looks at the index. The index may be a table or a function: <code>value func(object, key)</code>
* '''__newindex''': used when you assign a value to an object's member. On tables, newindex is only called if the table itself (not its index) does not already contains the specified key. May be a table or a function: <code>func(object, key, value)</code>
* '''__call''': used when you invoke the object as a function. Must be a function: <code>func(object, <args>)</code>
* '''__tostring''': used when you invoke the '''tostring''' function with this object in argument. Must be a function: <code>string func(object)</code>

Besides of that it can have fields for binary operators. When each of the two operands defined overloads, the left one is used. They must be functions: <code>result func(object)</code>
* '''__add''': addition
* '''__sub''': subtraction
* '''__mul''': multiplication
* '''__div''': division
* '''__mod''': module
* '''__pow''': exponentiation
* '''__eq''': equality comparison. Prior to calling this overload, Lua checks that types are equal.
* '''__neq''': inequality comparison. Prior to calling this overload, Lua checks whether types are different.
* '''__lt''': lesser than comparison. (b >= a) is considered equivalent to (a < b)
* '''__le''': lesser than or equal to comparison. (b > a) is considered equivalent to (a <= b). If __le is not defined, lua will use __lt, considering that (a <= b) is equivalent to not (b < a).
* '''__concat''': concatenation

Finally it can have the following fields for unary operators. They must be functions: <code>result func(object)</code>
* '''__unm''': unary minus
* '''__len''': the sharp operator (#). Can only be used on userdata ; on tables the default operator will always be called.

=== Implementing inheritance ===
The most common use of metatables is to mimic the behavior of object languages' types hierarchy. Here is how to do it:
<div class="civ5-example"><syntaxhighlight lang="lua">
local Dog = {}
function Dog:specie()
return "dog"
end
function Dog:race()
return "unknown"
end
function Dog:description()
return self.specie().." - "..self.race()
end
function Dog:new()
local instance = {}
setmetatable(instance, { __index = self})
return instance
end

local Pitbull = dog:new()
function Pitbull:race()
return "pitbull"
end

pitbull = Pitbull:new()
print(pitbull:description()) -- prints "dog - pitbull"
</syntaxhighlight></div>

This implementation is very elegant: the "new" method both creates a new instance and subtypes the creator, since "pitbull"'s index is now "Pitbull". However, should you define an operator overload on Dog's metatable, Pitbull would not inherit it. This is the limit of inheritance in Lua: operator overloads must be defined on the metatable itself, they cannot be defined on the metatable's index. As a result, there is no way to inherit those overloads while subtyping.

=== Coroutines ===
Coroutines provide a way to slice a function in many shorter calls and optionally return intermediate results. On each call, the function execution is resumed to the point where it stopped previously, with all locals being properly restored with the value they had at this time.
* Coroutines are often compared to threads. Indeed, when there are more threads than CPU cores, the operating system slices threads' execution into many little time frames and sequentially runs them in order to achieve multitasking.
* However while coroutines allows you to implement cooperative multitasking (the coroutines need to explicitly give the hand back), they cannot be used for preemptive multitasking or to use more than one system thread or CPU Core.
* As a result, coroutines are rather used as syntactic sugar (mostly to write iterators), or as a way to split a long function execution across many frames (through Context.{{Func5|UIElement|SetUpdate}}).

The following methods are mainly used:
* <code>'''coroutine''' coroutine.create('''function''' func)</code> creates a coroutine for the specified function. The function signature can be anything.
* <code>'''bool''', '''...''' coroutine.resume('''coroutine''' co, '''...''')</code> resumes the coroutine with the specified arguments. Then it returns either '''true''' followed by the returned results (either though '''return''' or '''yield'''), or '''false''' followed by an error message.
* <code>'''string''' coroutine.status('''coroutine''' co)</code> returns either "running" (the active coroutine), "normal" (a parent of the active coroutine), "suspended" (not started or waiting to be resumed) or "dead" (finished or threw an error).
* <code>coroutine.yield('''...''')</code> suspends the execution of the running coroutine and gives the hand back to the caller of coroutine.resume. The arguments will be returned by coroutine.resume.

Here is a base example:
<div class="civ5-example"><syntaxhighlight lang="lua">
function neighborsCoroutine(plot)
for i = 0, 5 do
coroutine.yield(Map.PlotDirection(plot:GetX(), plot:GetY(), i))
end
end

local co = coroutine.create(neighborsCoroutine)
while coroutine.status(co) == "suspended"
local _, neighbor = co.resume(plot)
-- Do something with plot
end
</syntaxhighlight></div>

Here is how to transform it into an iterator:
<div class="civ5-example"><syntaxhighlight lang="lua">
function neighbors(plot)
local co = coroutine.create(neighbors)
return function()
if coroutine.status(co) ~= "suspended" then return end
return select(2, coroutine.resume(plot))
end
end

for neighbor in neighbors(plot) do
-- Do something with plot
end
</syntaxhighlight></div>

Here is an example that spreads a long function call across many frames:
<div class="civ5-example"><syntaxhighlight lang="lua">
function SpreadAcrossFrames(longFunctionCall, ...)
local co = coroutine.create(longFunctionCall)
ContextPtr.SetUpdate(function()
coroutine.resume(unpack(arg))
if coroutine.status(co) ~= "suspended" then
ContextPtr:ClearUpdate()
end
end)
end

SpreadAcrossFrames(SomeLongFunction, arg1, arg2)
</syntaxhighlight></div>

=== Design philosophy for Lua ===
Do not use a butter knife as you would use a chainsaw (the opposite is even more true and usually ends up badly). When designing your code, remember that:
* Lua is not an object language. While you can use objects and inheritance in some extent, you do not have to and there may be better alternatives sometimes.
* Lua is not a functional language. While you can use lambdas and similar concepts, you do not have to and there may be better alternatives sometimes.
* Lua is a multi-paradigm and dynamic language, take advantage of those.
* Lua is very suited for prototyping and small programs, and this is perfect for mods. Try to adjust your mindset: you're not writing a framework that a whole team will still use and maintain in twenty years.

[[Category:Civ5 API]]
[[Category:Civ5 Tutorials]]

Lua introduction for confirmed developers

2012-09-24T15:29:05Z

DonQuich:

''This page is a part of the [[Lua and UI Reference (Civ5)|Lua and UI Reference]].''

== About Lua ==
===Lua, not LUA===
This is a Portuguese word meaning "moon", not an acronym.

===Presentation===
Lua is an interpreted, dynamically typed, multi-paradigm language. It was designed in 1993 with the following objectives in mind:
* Extensible semantics. A small set of features allows the support of multiple paradigms, from functional programming to object programming. For example, while inheritance is not natively supported, it can be easily set up through metatables. The same features allow events in civ5 to behave both as functions and objects with Add and Remove methods.
* Highly portable. The con is a lightweight and somewhat lacking API.
* Easy to embed and to interface from other languages.
* Well suited for data description (''à la'' JSON).
* A beginners-friendly syntax.

===Performances===
As usual with interpreted and dynamically typed languages (hereby abusively named "scripting languages"), expect a 10 to 100 order of magnitude in performances decrease when compared to compiled and statically typed languages like C, C++ or C#. While it is possible for scripting languages to drastically improve the performances through more or less sophisticated means (expression trees/opcodes caching, JIT compiler, type inference to perform static resolutions), no such solution has been used in Civ5 (aside, probably, of the caching). And while an external JIT library exists, it causes compatibility problems with most mods using Lua.

That being said, Lua is still pretty good for a scripting language, better than the Python implementation from Civ4 for example. And all in all, it is fast enough for most of what modders want to achieve without the need to compromise code elegance, readability and maintainability for performances. So keep in mind that "premature optimization is the root of all evil" (Donald Knuth).

==Syntax cheatsheet==
=== Basics ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Literals
local x = 5
local x = 5.0
local x = nil -- A nil value is the same as an undefined value
local x = true
local x = false

-- Strings (single and double quotes can be used indifferently, there is no difference)
local x = "five"
local x = 'five'
local x = "five\n" -- Escape characters with "\".
local x = [[Five is a number.
Did you know?]] -- Multi-line string: equivalent to "Five is number.\nDid you know?"

-- Globals versus locals
x = 5 -- For globals, assigning is declaring.
local x = 5
</syntaxhighlight></div>

=== Operators ===
<div class="civ5-example"><syntaxhighlight lang="lua">
local x = a or b
local x = a and b

local x = "hello ".."world" .. "!" -- concatenation: two dots
local x = 4..5 -- Result is "45". On concatenation, conversions occur.

local x = (a + b - d) * f ^ g % h -- ^ is exponentiation, % is modulo
local x = "4" + "5" -- Result is 9. On arithmetic operations, conversions occur.

local x = a == b -- equality -- True only if a and b have the same values and types.
local x = a ~= b -- inequality

local x = ((a <= b) == not (a > b)) == ((a >= b) == not (a < b))
local x = "abc" < "def" -- Byte-wise comparison, not Unicode-compliant. Use Locale's methods instead.

local x = #"abc" -- Returns 3, the number of bytes in the string (3 characters, 1 byte each).
local x = #"您好世界" -- Returns 8, the number of bytes in the string (4 characters, 2 bytes each).
local x = #SomeTable -- Returns the biggest integer key in the table, or nil if there is no integer key.

-- No increment operator (++ --), no binary-assign operator (+= *=), no ternary operator (? :), no coalescence operator (??)
</syntaxhighlight></div>

=== Tables and multiple assignments ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Table declaration
SomeTable = {}

SomeArray = { "abc", "def" }
-- 1 => "abc", 2 => "def"

SomeComplexTable = { name = "John", surname = "Doe", age = 25, 43, [7] = 8 }
-- "name" => "John", "surname" => "Doe", "age" => 25, 1 => 43, 7 => 8.

-- Member access (all equivalent)
SomeTable.SomeMember = 5
SomeTable["SomeMember"] = 5

-- Multiple assignment
-- Both statements are equivalent since SomeArray contains "abc" and "def".
local x, y = "abc", "def"
local x, y = unpack(SomeArray)
</syntaxhighlight></div>

=== Functions ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Functions declarations (all equivalent)
function HelloWorld(a, b) print("Hello world") end
HelloWorld = function(a, b) print("Hello world") end
-- Functions are first-class objects and can be assigned like any other value!

-- Methods declarations (all equivalent)
SomeTable.HelloWorld(a, b) print("Hello world") end
SomeTable.HelloWorld = function(a, b) print("Hello world") end

-- Instanced methods declarations (all equivalent)
SomeTable.HelloWorldInstanced(self, a, b) print(self.SomeMember) end
SomeTable:HelloWorldInstanced(a, b) print(self.SomeMember) end

-- Functions and methods calls
HelloWorld(a) -- b will be nil in the function
HelloWorld(a, b)
SomeTable.HelloWorld(a, b)

-- Instanced methods calls (all equivalent)
SomeTable:HelloWorldInstanced(a, b)
SomeTable.HelloWorldInstanced(SomeTable, a, b)

-- Multiple return values
function func(a, b) return a, b end
local x, y, z = func(5, 6) -- Assigns 5 to x and 6 to y, z will be nil

-- Variable arguments
function SomeFunc(a, b, ...)
print(a)
print(b)
for i, v in ipairs(arg) do -- arg is a keyword for a table containing the variable arguments
print(v)
end
end
SomeFunc(1, 2, 3, 4, 5) -- prints 1, 2, 3, 4, 5
SomeFunc(1, 2) -- prints 1, 2
</syntaxhighlight></div>

=== Control flow ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- If
if name == "Wu Zetian" then
print("Hello China")
elseif name == "Napoleon" then -- "elseif", not "else if". Beware C developers!
print("Hello France")
else -- no "then" after "else"!
print("Hello unknown")
end

-- For loop (with counter)
for i = 1, 8 do print(i) end -- Prints 1, 2, 3, 4, 5, 6, 7, 8
for i = 1, 8, 2 do print(i) end -- Prints 1, 3, 5, 7

-- For loop (with iterator)
for playerID, pPlayer in pairs(Players) do -- Prints 1 Wu Zetian, 2 Napoleon, ...
print(playerID, pPlayer:GetName())
end
for plot in Plots() do -- Prints 0 0, 0 1, 0 2, ...
print(plot:GetX(), plot:GetY())
end

-- While (i will be 5 in the end)
while i < 5 do
i = i + 1
end

-- Repeat until (i will be 5 in the end)
repeat
i = i + 1
until i == 5

-- Infinite loops
-- Lua supports "break" for all loops but not "continue" instruction does not exist!
do
i = i + 1
if i > 5 then break end
end

</syntaxhighlight></div>

== Basics ==
=== Type system ===
You can get a variable's type by using the '''type''' function. It takes any value and returns a string. Here are the possible results:
* '''nil''': Lua makes do distinction between an undefined variable and a variable with a nil value. Assigning nil to a variable or table member is equivalent to undefining it.
* '''number''': a 64 bits floating-point number. Lua has no support for integers and only use floating-points. See also [[#No integer type]].
* '''string''': your usual string of characters. In Lua all strings are interned. This speeds up comparisons but it makes allocation of new strings slower.
* '''boolean''': true or false obviously.
* '''table''': any table.
* '''userdata''': objects defined in C for use in Lua. They may not be enumerated through pairs and other limitations. Now the Civ5 API tend to return regular tables whose metatable is of type userdata, this allows us to use the provided objects as regular Lua tables.
* '''function''': remember that functions are first-class objects in Lua.
* '''thread''': coroutines actually. Lua does not support threads.

=== Implicit conversions ===
* Whenever you concatenate two values (and possibly when you invoke a standard function that takes a string), an automatic conversion to string occurs, as if you had used the '''tostring''' function. The expression <code>4..5</code> returns "45".
* Whenever you perform an arithmetic operation, the operands are both converted to numbers, as if you had used the '''tonumber''' function. The expression <code>"4" + "5"</code> returns 9.

=== Strict equality comparisons ===
'''Two values are equal only if their types are the same.'''<br/>
This is stricter than C and far stricter than PHP for example.
* 4 is not equal to "4". (number type and string type). In PHP they would be equal.
* 0 is not equal to false (number type and bool type). In C they would be equal.
* 0 is not equal to nil. (number type and nil type). In C they would be equal.

Regarding tables and C-made objects, they are compared by reference.
<div class="civ5-example"><syntaxhighlight lang="lua">
a = { 5 }
b = { 5 }
c = a
assert(a == c) -- OK
assert(a == b) -- ERROR
</syntaxhighlight></div>

=== Boolean logic ===
'''Anything that is neither false nor nil is evaluated to true.'''<br/>
This is pretty simple. Especially, an empty string or the zero number are evaluated to true.
<div class="civ5-example"><syntaxhighlight lang="lua">
if 0 then print("hello world") end -- prints hello world
</syntaxhighlight></div>

Now regarding the and/or operators, two rules to remember:
* '''The right operand is only evaluated when needed.'''
** <code>false and x()</code> does not call x() since the result will be false anyway.
** <code>true or x()</code> does not call x() since the result will be true anyway.
* '''The result is the last operand to have been evaluated.'''
** <code>x() and y()</code> returns x() if it was false, y() otherwise.
** <code>x() or y()</code> returns x() if it was true, y() otherwise.

=== Ternary and coalescence statements ===
We can exploit the and/or operators behavior:
* '''Coalescence:''' <code>x or y</code>. It returns x if x is neither nil nor false, y otherwise.
:In other words <code>result = x or y</code> is equivalent to: <code>if x then result = x else result = y end</code>.
* '''Ternary:''' <code>condition and x or y</code> (as long as x is not nil or false). It returns x if condition was true, y if it was false.
:Indeed the expression becomes: <code>(condition and x) or y</code>. If condition is true the '''and''' operator returns x, and since x is true, y is not evaluated and '''or''' returns x.
:In other words <code>result = condition and x or y</code> is equivalent to: <code>if condition then result = x else result = y end</code>.

=== Arrays versus tables ===
'''In Lua, an array is a table whose keys are integers.'''

Since this is a common programming pattern, a number of things are designed for arrays:
* <code>{"abc", "def", "ghi"}</code> starts at index 1, up to index 3. Arrays typically start at 1.
* <code>table.insert({}, "abc")</code> will transform the provided empty table to <code>{"abc"}</code>
* <code>table.insert({"abc", "def"}, "ghi")</code> will transform the provided table to <code>{"abc", "def", "ghi"}</code>
* <code>table.insert({"abc", "ghi"}, 2, "def")</code> will transform the provided table to <code>{"abc", "def", "ghi"}</code>
* <code>table.remove({"abc", "def", "ghi"}, 2)</code> will transform the provided table to <code>{"abc", ""ghi"}</code>
* <code>#{"abc", "def", "ghi"}</code> returns 3, the biggest integer key.

=== Ipairs versus pairs ===
You could say that '''pairs''' is for table and '''ipairs''' for arrays.
* '''Pairs''' enumerate all the key/value pairs in an unordered matter.
* '''Ipairs''' only enumerates the key/value pairs for consecutive integer keys, in an ascending order, starting from 1 up to the largest key. If at some point a key is missing, the enumeration stops.
::It does not matter whether the table was crated with table.insert or directly by inserting the values through, for example <code>table[i] = value</code>.

<div class="civ5-example"><syntaxhighlight lang="lua">
-- Produces: { 1 => "one", 2 => "two", 4 => "four", "name" => "John", "age" => 25 }
local t = { "one", "two", name = "John", age = 25, [4] = "four" }

-- Will print (for example, the order is undetermined): "name", 2, 4, "age", 1
for k in pairs(t) do print(k) end

-- Will print 1, 2
for k in ipairs(t) do print(k) end

-- Both ipairs and pairs return a key and a value, so you could also use:
for k, v in pairs(t) do print(k, v) end
</syntaxhighlight></div>

=== Semicolons and line breaks ===
'''Statements need to be separated either by a line break or a semicolon.'''
* You can use both a semicolon and a line break but then the semicolon is redundant and not required, although it does not cause any problem.
* Line breaks can also be freely added about everywhere and behave as whitespaces most of the time (you can add them after most keywords for example, so you can keep if...then...end structures on one line or split them across multiple lines).

=== Locals, globals and includes ===
* The include statement allows you to include a lua file into another one (see [[Specificities of the Lua implementation in Civ5]]). When you do so, the globals defined in the included file are imported in the parent file. However the local variables are only visible from within the file that declared them.
* Another specificities of locals: they're only visible after the point they have been declared in the file, while globals are always visible. An example is worth thousand of words.
<div class="civ5-example"><syntaxhighlight lang="lua">
function Func1()
print(someLocal or "nil")
print(someGlobal or "nil")
end

local someLocal = "foo"
function Func2()
print(someLocal or "nil")
print(someGlobal or "nil")
end

someGlobal = "global"
someLocal = "local"
Func1() -- prints "nil", then "global": someLocal is assigned but not visible from Func1
Func2() -- prints "local", then "global": someLocal is assigned and visible from Func2
</syntaxhighlight></div>
* Performances-wise, Lua first searches a variable name in the current scope, then in the parent scope, etcetera until it reaches the highest scope, and finally it searches the global scope. So the deeper a local is declared, the faster it is accessed. On the contrary, globals are the slowest to retrieve.

== Semi-advanced topics ==
=== Closures ===
'''Closures are functions that embed variables that are persisted across calls.'''<br/>
This is typically achieved through a "parent" function that declares a local "closed" variable and returns another child "closure" function using this local. The "closed" variable is then unreachable for anyone but the "closure". And since it the "closed" variable is not in the "closure"'s scope, it is not reinitialized on every call of "closure".
<div class="civ5-example"><syntaxhighlight lang="lua">
function GiveMeAFunc() -- the parent function
local x = 0 -- the closed variable
return function() -- the closure function embedding "closed"
x = x + 1
return closure
end
end

local func = GiveMeAFunc()
print(func()) -- Prints 1
print(func()) -- Prints 2
print(func()) -- Prints 3
</syntaxhighlight></div>

=== Iterators ===
'''Iterators are functions for use in <code>for...in</code> loops.'''<br/>
Let's consider the following code: <code>for var1, var2, var3 in iterable() do</code>.
* iterable has the following signature: <code>iterator, state, var1 iterable()</code>. It returns a function, a state, and the initial value of var1.
* iterator has the following signature: <code>var1, var2, var3 iterator(state, var1)</code>. It takes the state and the last value of var1 and returns var1, var2 and var3.
* The loop stops when var1 is nil.
* The for...in loop is equivalent to:
<div class="civ5-example"><syntaxhighlight lang="lua">
local iterator, state, var1, var2, var3
iterator, state, var1 = iterable()
do
var1, var2, var3 = iterator(state, var1)
if var1 == nil then break end

-- Inserts here the user code defined in the for..in loop
end
</syntaxhighlight></div>
* Note that we used var1, var2 and var3 for the example but there is no restriction to the number of variables. You could have one or hundred.

Let's write the "ipairs" function.
<div class="civ5-example"><syntaxhighlight lang="lua">
local function ipairs(table) -- The iterable function
local iterator = function(table, key) -- The iterator function
key = key + 1
return key, table[key]
end
return iterator, table, 0
end
</syntaxhighlight></div>

The same with closures: it's easier.
<div class="civ5-example"><syntaxhighlight lang="lua">
local function ipairs(table) -- The iterable function
local key = 0 -- Both "table" and "key" are closed variables.
local iterator = function() -- The iterator function, a closure: it ignores the arguments provided to it
key = key + 1
return key, table[key]
end
return iterator -- No need to return anything since we do not require any argument.
end
</syntaxhighlight></div>

=== No integer type ===
'''Lua offers no support for integers and only has a 64-bits floating point number type.'''<br/>
Actually, this is only troublesome for a few algorithms that use very large integers (>2^52) or require fast integer arithmetics. But many developers misunderstand floating points and believe the problem is broader than it is. For example, does the following assertion surprise you at least a bit: "any integer smaller than 2^52 can be accurately represented with a 64-bits floating point without any error"? If it did, you suffer from some misconceptions and you should better read carefully what's coming.

Many developers are confusing rounding errors with representation errors.
* '''Rounding errors''' actually only happen if you need a very high number of digits to represent a number. For example if you are adding a very large number with a small number. Rounding errors are very rarely encountered in day to day to applications. Actually most developers work their whole career without ever encountering them.
* '''Representation errors''' are the real problem: 0.1 is expressed in a decimal basis, but it has no finite representation in binary: it requires an infinite number of binary digits. This means that if you write 0.1 in your code it will be translated to a binary number close enough from 0.1 bot not exactly equal to it. So if you sum ten times 0.1, you sill sum ten times something close from 0.1 and the result will not be 1.

'''So the real problem for most developers only lies in the decimal-binary conversion that arises when you manipulate numbers in your code that do not have a finite representation in binary. As long as you do not use such numbers, there will be no problem. And here are the good news: integers do not suffer from any representation problem!''' Indeed, any integer can be represented with a finite number of binary digits. This is why the absence of an integer type typically does not cause problems, minus the performance penalty.

Here are a few examples to illustrate that point.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- This loop works as intended: no representation error and the upper bound is far below 2^52.
local sum = 0
for i = 0, 10000000000, 1 do sum = sum + 1 end
assert(sum == 10000000001)

-- This loop works as intended: 1/16 is a floating-point with an exact representation in binary
local sum = 0
for i = 0, 1, 1/16 do sum = sum + 1 end
assert(sum == 17/16)

-- This loop does NOT work as intended: 0.1 does not have an exact representation in binary.
-- It's the same for Lua, C and almost every programming language.
local sum = 0
for i = 0, 1, 0.1 do sum = sum + 1 end
assert(sum == 1.1) -- throws an error
</syntaxhighlight></div>

=== Errors management ===
Lua offers a error handling mechanism similar to exception handling but unfortunately not very convenient.
* Errors are thrown using the '''error''' function. It takes a string and it immediately aborts Lua execution until the game handles the error and prints it in Firetuner (when enabled).
* Errors are caught before that point using '''pcall''' or '''xpcall''', in order to let you resume execution by managing the error. "pcall" stands for "protected call".

Here are the syntaxes for pcall and xpcall:
* <code>bool, ... pcall(func, ...)</code>
** The function is called with the specified arguments.
** Pcall returns either true followed by the values returned by func, or false followed by the error text.
* <code>bool, ... xpcall(func, errorHandler)</code>:
** The function is called without any argument. If an error occurs the specified errorHandler is invoked with the error text as the only argument.
** Xpcall returns either true followed by the values returned by func, or false followed by the returned values from errorHandler.

Examples to invoke "someFunc" with "someArg" as the only argument. In both examples we want to display the error on the console, or the result if it was a success. A complete errors management example with a reporting mechanism for the end-user is presented in [[Debugging (Civ5)]].
<div class="civ5-example"><syntaxhighlight lang="lua">
-- pcall
local status, result = pcall(someFunc, someArg)
if not status then
print("error was: "..(result or "?"))
else
print("success: "..result)
end

-- xpcall
local status, result = xpcall(
function() someFunc(someArg) end,
function(err) print("error was: "..(result or "?")) end)

if status then
print("success: "..result)
end
</syntaxhighlight></div>

== Advanced topics==
=== Metatables and metamethods ===
* Every value in Lua, from a number to a userdata, has a metatable.
** Many objects can share the same metatable.
** Tables and userdata each have their own metatables by default. Numbers, bools, nils and strings all share the same metatable.
* A metatable may contain a few metamethods and index tables.
** Metamethods are methods stored under special fields names. They implement operators overloads.
** Index tables behave as "base classes": if a field name is not defined on an table, then Lua looks for this field on the index.
** In a way, metatables are analogous to virtual tables in object languages, but they are not just for methods, but also for fields and operators.
* You can get an object's metatable through '''getmetatable''' and assign it with '''setmetatable'''.
* See also the [http://www.lua.org/manual/5.1/manual.html#2.8 official metatables reference]

One example.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Define two tables A and B, and set "meta" their metatable
local a, b, meta = {}, {}, {}
setmetatable(a, meta)
setmetatable(b, meta)

-- Define an __index table on the metatable. It contains one key/value pair.
meta.__index = { "hello world" };

-- Print "hello world" twice
print(a[1])
print(b[1])

-- Now make our tables read-only
meta.__newindex = function(table, key, value) error("this table is read-only!") end
a[1] = "foo" -- throws an error
</syntaxhighlight></div>

Here are the most important fields a metatable can have:
* '''__index''': used when you read a member from an object. On tables, Lua will first search for a regular field on the table itself (not its index) before it looks at the index. The index may be a table or a function: <code>value func(object, key)</code>
* '''__newindex''': used when you assign a value to an object's member. On tables, newindex is only called if the table itself (not its index) does not already contains the specified key. May be a table or a function: <code>func(object, key, value)</code>
* '''__call''': used when you invoke the object as a function. Must be a function: <code>func(object, <args>)</code>
* '''__tostring''': used when you invoke the '''tostring''' function with this object in argument. Must be a function: <code>string func(object)</code>

Besides of that it can have fields for binary operators. When each of the two operands defined overloads, the left one is used. They must be functions: <code>result func(object)</code>
* '''__add''': addition
* '''__sub''': subtraction
* '''__mul''': multiplication
* '''__div''': division
* '''__mod''': module
* '''__pow''': exponentiation
* '''__eq''': equality comparison. Prior to calling this overload, Lua checks that types are equal.
* '''__neq''': inequality comparison. Prior to calling this overload, Lua checks whether types are different.
* '''__lt''': lesser than comparison. (b >= a) is considered equivalent to (a < b)
* '''__le''': lesser than or equal to comparison. (b > a) is considered equivalent to (a <= b). If __le is not defined, lua will use __lt, considering that (a <= b) is equivalent to not (b < a).
* '''__concat''': concatenation

Finally it can have the following fields for unary operators. They must be functions: <code>result func(object)</code>
* '''__unm''': unary minus
* '''__len''': the sharp operator (#). Can only be used on userdata ; on tables the default operator will always be called.

=== Implementing inheritance ===
The most common use of metatables is to mimic the behavior of object languages' types hierarchy. Here is how to do it:
<div class="civ5-example"><syntaxhighlight lang="lua">
local Dog = {}
function Dog:specie()
return "dog"
end
function Dog:race()
return "unknown"
end
function Dog:description()
return self.specie().." - "..self.race()
end
function Dog:new()
local instance = {}
setmetatable(instance, { __index = self})
return instance
end

local Pitbull = dog:new()
function Pitbull:race()
return "pitbull"
end

pitbull = Pitbull:new()
print(pitbull:description()) -- prints "dog - pitbull"
</syntaxhighlight></div>

This implementation is very elegant: the "new" method both creates a new instance and subtypes the creator, since "pitbull"'s index is now "Pitbull". However, should you define an operator overload on Dog's metatable, Pitbull would not inherit it. This is the limit of inheritance in Lua: operator overloads must be defined on the metatable itself, they cannot be defined on the metatable's index. As a result, there is no way to inherit those overloads while subtyping.

=== Coroutines ===
Coroutines provide a way to slice a function in many shorter calls and optionally return intermediate results. On each call, the function execution is resumed to the point where it stopped previously, with all locals being properly restored with the value they had at this time.
* Coroutines are often compared to threads. Indeed, when there are more threads than CPU cores, the operating system slices threads' execution into many little time frames and sequentially runs them in order to achieve multitasking.
* However while coroutines allows you to implement cooperative multitasking (the coroutines need to explicitly give the hand back), they cannot be used for preemptive multitasking or to use more than one system thread or CPU Core.
* As a result, coroutines are rather used as syntactic sugar (mostly to write iterators), or as a way to split a long function execution across many frames (through Context.{{Func5|UIElement|SetUpdate}}).

The following methods are mainly used:
* <code>'''coroutine''' coroutine.create('''function''' func)</code> creates a coroutine for the specified function. The function signature can be anything.
* <code>'''bool''', '''...''' coroutine.resume('''coroutine''' co, '''...''')</code> resumes the coroutine with the specified arguments. Then it returns either '''true''' followed by the returned results (either though '''return''' or '''yield'''), or '''false''' followed by an error message.
* <code>coroutine.yield('''...''')</code> suspends the execution of the coroutine and gives the hand back to the caller of coroutine.resume. The arguments will be returned by coroutine.resume.
* <code>'''string''' coroutine.status('''coroutine''' co)</code> returns either "running" (the active coroutine), "normal" (a parent of the active coroutine), "suspended" (not started or waiting to be resumed) or "dead" (finished or threw an error).

Here is a base example:
<div class="civ5-example"><syntaxhighlight lang="lua">
function neighborsCoroutine(plot)
for i = 0, 5 do
coroutine.yield(Map.PlotDirection(plot:GetX(), plot:GetY(), i))
end
end

local co = coroutine.create(neighborsCoroutine)
while coroutine.status(co) == "suspended"
local _, neighbor = co.resume(plot)
-- Do something with plot
end
</syntaxhighlight></div>

Here is how to transform it into an iterator:
<div class="civ5-example"><syntaxhighlight lang="lua">
function neighbors(plot)
local co = coroutine.create(neighbors)
return function()
if coroutine.status(co) ~= "suspended" then return end
return select(2, coroutine.resume(plot))
end
end

for neighbor in neighbors(plot) do
-- Do something with plot
end
</syntaxhighlight></div>

Here is an example that spreads a long function call across many frames:
<div class="civ5-example"><syntaxhighlight lang="lua">
function SpreadAcrossFrames(longFunctionCall, ...)
local co = coroutine.create(longFunctionCall)
ContextPtr.SetUpdate(function()
coroutine.resume(unpack(arg))
if coroutine.status(co) ~= "suspended" then
ContextPtr:ClearUpdate()
end
end)
end

SpreadAcrossFrames(SomeLongFunction, arg1, arg2)
</syntaxhighlight></div>

=== Design philosophy for Lua ===
Do not use a butter knife as you would use a chainsaw (the opposite is even more true and usually ends up badly). When designing your code, remember that:
* Lua is not an object language. While you can use objects and inheritance in some extent, you do not have to and there may be better alternatives sometimes.
* Lua is not a functional language. While you can use lambdas and similar concepts, you do not have to and there may be better alternatives sometimes.
* Lua is a multi-paradigm and dynamic language, take advantage of those.
* Lua is very suited for prototyping and small programs, and this is perfect for mods. Try to adjust your mindset: you're not writing a framework that a whole team will still use and maintain in twenty years.

[[Category:Civ5 API]]
[[Category:Civ5 Tutorials]]

Lua introduction for confirmed developers

2012-09-24T15:27:30Z

DonQuich:

''This page is a part of the [[Lua and UI Reference (Civ5)|Lua and UI Reference]].''

== About Lua ==
===Lua, not LUA===
This is a Portuguese word meaning "moon", not an acronym.

===Presentation===
Lua is an interpreted, dynamically typed, multi-paradigm language. It was designed in 1993 with the following objectives in mind:
* Extensible semantics. A small set of features allows the support of multiple paradigms, from functional programming to object programming. For example, while inheritance is not natively supported, it can be easily set up through metatables. The same features allow events in civ5 to behave both as functions and objects with Add and Remove methods.
* Highly portable. The con is a lightweight and somewhat lacking API.
* Easy to embed and to interface from other languages.
* Well suited for data description (''à la'' JSON).
* A beginners-friendly syntax.

===Performances===
As usual with interpreted and dynamically typed languages (hereby abusively named "scripting languages"), expect a 10 to 100 order of magnitude in performances decrease when compared to compiled and statically typed languages like C, C++ or C#. While it is possible for scripting languages to drastically improve the performances through more or less sophisticated means (expression trees/opcodes caching, JIT compiler, type inference to perform static resolutions), no such solution has been used in Civ5 (aside, probably, of the caching). And while an external JIT library exists, it causes compatibility problems with most mods using Lua.

That being said, Lua is still pretty good for a scripting language, better than the Python implementation from Civ4 for example. And all in all, it is fast enough for most of what modders want to achieve without the need to compromise code elegance, readability and maintainability for performances. So keep in mind that "premature optimization is the root of all evil" (Donald Knuth).

==Syntax cheatsheet==
=== Basics ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Literals
local x = 5
local x = 5.0
local x = nil -- A nil value is the same as an undefined value
local x = true
local x = false

-- Strings (single and double quotes can be used indifferently, there is no difference)
local x = "five"
local x = 'five'
local x = "five\n" -- Escape characters with "\".
local x = [[Five is a number.
Did you know?]] -- Multi-line string: equivalent to "Five is number.\nDid you know?"

-- Globals versus locals
x = 5 -- For globals, assigning is declaring.
local x = 5
</syntaxhighlight></div>

=== Operators ===
<div class="civ5-example"><syntaxhighlight lang="lua">
local x = a or b
local x = a and b

local x = "hello ".."world" .. "!" -- concatenation: two dots
local x = 4..5 -- Result is "45". On concatenation, conversions occur.

local x = (a + b - d) * f ^ g % h -- ^ is exponentiation, % is modulo
local x = "4" + "5" -- Result is 9. On arithmetic operations, conversions occur.

local x = a == b -- equality -- True only if a and b have the same values and types.
local x = a ~= b -- inequality

local x = ((a <= b) == not (a > b)) == ((a >= b) == not (a < b))
local x = "abc" < "def" -- Byte-wise comparison, not Unicode-compliant. Use Locale's methods instead.

local x = #"abc" -- Returns 3, the number of bytes in the string (3 characters, 1 byte each).
local x = #"您好世界" -- Returns 8, the number of bytes in the string (4 characters, 2 bytes each).
local x = #SomeTable -- Returns the biggest integer key in the table, or nil if there is no integer key.

-- No increment operator (++ --), no binary-assign operator (+= *=), no ternary operator (? :), no coalescence operator (??)
</syntaxhighlight></div>

=== Tables and multiple assignments ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Table declaration
SomeTable = {}

SomeArray = { "abc", "def" }
-- 1 => "abc", 2 => "def"

SomeComplexTable = { name = "John", surname = "Doe", age = 25, 43, [7] = 8 }
-- "name" => "John", "surname" => "Doe", "age" => 25, 1 => 43, 7 => 8.

-- Member access (all equivalent)
SomeTable.SomeMember = 5
SomeTable["SomeMember"] = 5

-- Multiple assignment
-- Both statements are equivalent since SomeArray contains "abc" and "def".
local x, y = "abc", "def"
local x, y = unpack(SomeArray)
</syntaxhighlight></div>

=== Functions ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Functions declarations (all equivalent)
function HelloWorld(a, b) print("Hello world") end
HelloWorld = function(a, b) print("Hello world") end
-- Functions are first-class objects and can be assigned like any other value!

-- Methods declarations (all equivalent)
SomeTable.HelloWorld(a, b) print("Hello world") end
SomeTable.HelloWorld = function(a, b) print("Hello world") end

-- Instanced methods declarations (all equivalent)
SomeTable.HelloWorldInstanced(self, a, b) print(self.SomeMember) end
SomeTable:HelloWorldInstanced(a, b) print(self.SomeMember) end

-- Functions and methods calls
HelloWorld(a) -- b will be nil in the function
HelloWorld(a, b)
SomeTable.HelloWorld(a, b)

-- Instanced methods calls (all equivalent)
SomeTable:HelloWorldInstanced(a, b)
SomeTable.HelloWorldInstanced(SomeTable, a, b)

-- Multiple return values
function func(a, b) return a, b end
local x, y, z = func(5, 6) -- Assigns 5 to x and 6 to y, z will be nil

-- Variable arguments
function SomeFunc(a, b, ...)
print(a)
print(b)
for i, v in ipairs(arg) do -- arg is a keyword for a table containing the variable arguments
print(v)
end
end
SomeFunc(1, 2, 3, 4, 5) -- prints 1, 2, 3, 4, 5
SomeFunc(1, 2) -- prints 1, 2
</syntaxhighlight></div>

=== Control flow ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- If
if name == "Wu Zetian" then
print("Hello China")
elseif name == "Napoleon" then -- "elseif", not "else if". Beware C developers!
print("Hello France")
else -- no "then" after "else"!
print("Hello unknown")
end

-- For loop (with counter)
for i = 1, 8 do print(i) end -- Prints 1, 2, 3, 4, 5, 6, 7, 8
for i = 1, 8, 2 do print(i) end -- Prints 1, 3, 5, 7

-- For loop (with iterator)
for playerID, pPlayer in pairs(Players) do -- Prints 1 Wu Zetian, 2 Napoleon, ...
print(playerID, pPlayer:GetName())
end
for plot in Plots() do -- Prints 0 0, 0 1, 0 2, ...
print(plot:GetX(), plot:GetY())
end

-- While (i will be 5 in the end)
while i < 5 do
i = i + 1
end

-- Repeat until (i will be 5 in the end)
repeat
i = i + 1
until i == 5

-- Infinite loops
-- Lua supports "break" for all loops but not "continue" instruction does not exist!
do
i = i + 1
if i > 5 then break end
end

</syntaxhighlight></div>

== Basics ==
=== Type system ===
You can get a variable's type by using the '''type''' function. It takes any value and returns a string. Here are the possible results:
* '''nil''': Lua makes do distinction between an undefined variable and a variable with a nil value. Assigning nil to a variable or table member is equivalent to undefining it.
* '''number''': a 64 bits floating-point number. Lua has no support for integers and only use floating-points. See also [[#No integer type]].
* '''string''': your usual string of characters. In Lua all strings are interned. This speeds up comparisons but it makes allocation of new strings slower.
* '''boolean''': true or false obviously.
* '''table''': any table.
* '''userdata''': objects defined in C for use in Lua. They may not be enumerated through pairs and other limitations. Now the Civ5 API tend to return regular tables whose metatable is of type userdata, this allows us to use the provided objects as regular Lua tables.
* '''function''': remember that functions are first-class objects in Lua.
* '''thread''': coroutines actually. Lua does not support threads.

=== Implicit conversions ===
* Whenever you concatenate two values (and possibly when you invoke a standard function that takes a string), an automatic conversion to string occurs, as if you had used the '''tostring''' function. The expression <code>4..5</code> returns "45".
* Whenever you perform an arithmetic operation, the operands are both converted to numbers, as if you had used the '''tonumber''' function. The expression <code>"4" + "5"</code> returns 9.

=== Strict equality comparisons ===
'''Two values are equal only if their types are the same.'''<br/>
This is stricter than C and far stricter than PHP for example.
* 4 is not equal to "4". (number type and string type). In PHP they would be equal.
* 0 is not equal to false (number type and bool type). In C they would be equal.
* 0 is not equal to nil. (number type and nil type). In C they would be equal.

Regarding tables and C-made objects, they are compared by reference.
<div class="civ5-example"><syntaxhighlight lang="lua">
a = { 5 }
b = { 5 }
c = a
assert(a == c) -- OK
assert(a == b) -- ERROR
</syntaxhighlight></div>

=== Boolean logic ===
'''Anything that is neither false nor nil is evaluated to true.'''<br/>
This is pretty simple. Especially, an empty string or the zero number are evaluated to true.
<div class="civ5-example"><syntaxhighlight lang="lua">
if 0 then print("hello world") end -- prints hello world
</syntaxhighlight></div>

Now regarding the and/or operators, two rules to remember:
* '''The right operand is only evaluated when needed.'''
** <code>false and x()</code> does not call x() since the result will be false anyway.
** <code>true or x()</code> does not call x() since the result will be true anyway.
* '''The result is the last operand to have been evaluated.'''
** <code>x() and y()</code> returns x() if it was false, y() otherwise.
** <code>x() or y()</code> returns x() if it was true, y() otherwise.

=== Ternary and coalescence statements ===
We can exploit the and/or operators behavior:
* '''Coalescence:''' <code>x or y</code>. It returns x if x is neither nil nor false, y otherwise.
:In other words <code>result = x or y</code> is equivalent to: <code>if x then result = x else result = y end</code>.
* '''Ternary:''' <code>condition and x or y</code> (as long as x is not nil or false). It returns x if condition was true, y if it was false.
:Indeed the expression becomes: <code>(condition and x) or y</code>. If condition is true the '''and''' operator returns x, and since x is true, y is not evaluated and '''or''' returns x.
:In other words <code>result = condition and x or y</code> is equivalent to: <code>if condition then result = x else result = y end</code>.

=== Arrays versus tables ===
'''In Lua, an array is a table whose keys are integers.'''

Since this is a common programming pattern, a number of things are designed for arrays:
* <code>{"abc", "def", "ghi"}</code> starts at index 1, up to index 3. Arrays typically start at 1.
* <code>table.insert({}, "abc")</code> will transform the provided empty table to <code>{"abc"}</code>
* <code>table.insert({"abc", "def"}, "ghi")</code> will transform the provided table to <code>{"abc", "def", "ghi"}</code>
* <code>table.insert({"abc", "ghi"}, 2, "def")</code> will transform the provided table to <code>{"abc", "def", "ghi"}</code>
* <code>table.remove({"abc", "def", "ghi"}, 2)</code> will transform the provided table to <code>{"abc", ""ghi"}</code>
* <code>#{"abc", "def", "ghi"}</code> returns 3, the biggest integer key.

=== Ipairs versus pairs ===
You could say that '''pairs''' is for table and '''ipairs''' for arrays.
* '''Pairs''' enumerate all the key/value pairs in an unordered matter.
* '''Ipairs''' only enumerates the key/value pairs for consecutive integer keys, in an ascending order, starting from 1 up to the largest key. If at some point a key is missing, the enumeration stops.
::It does not matter whether the table was crated with table.insert or directly by inserting the values through, for example <code>table[i] = value</code>.

<div class="civ5-example"><syntaxhighlight lang="lua">
-- Produces: { 1 => "one", 2 => "two", 4 => "four", "name" => "John", "age" => 25 }
local t = { "one", "two", name = "John", age = 25, [4] = "four" }

-- Will print (for example, the order is undetermined): "name", 2, 4, "age", 1
for k in pairs(t) do print(k) end

-- Will print 1, 2
for k in ipairs(t) do print(k) end

-- Both ipairs and pairs return a key and a value, so you could also use:
for k, v in pairs(t) do print(k, v) end
</syntaxhighlight></div>

=== Semicolons and line breaks ===
'''Statements need to be separated either by a line break or a semicolon.'''
* You can use both a semicolon and a line break but then the semicolon is redundant and not required, although it does not cause any problem.
* Line breaks can also be freely added about everywhere and behave as whitespaces most of the time (you can add them after most keywords for example, so you can keep if...then...end structures on one line or split them across multiple lines).

=== Locals, globals and includes ===
* For a documentation on the '''include''' statement, see [[Specificities of the Lua implementation in Civ5#Include]].
* The include statement allows you to include a lua file into another one (see [[Specificities of the Lua implementation in Civ5]]). When you do so, the globals defined in the included file are imported in the parent file. However the local variables are only visible from within the file that declared them.
* Another specificities of locals: they're only visible after the point they have been declared in the file, while globals are always visible. An example is worth thousand of words.
<div class="civ5-example"><syntaxhighlight lang="lua">
function Func1()
print(someLocal or "nil")
print(someGlobal or "nil")
end

local someLocal = "foo"
function Func2()
print(someLocal or "nil")
print(someGlobal or "nil")
end

someGlobal = "global"
someLocal = "local"
Func1() -- prints "nil", then "global": someLocal is assigned but not visible from Func1
Func2() -- prints "local", then "global": someLocal is assigned and visible from Func2
</syntaxhighlight></div>
* Performances-wise, Lua first searches a variable name in the current scope, then in the parent scope, etcetera until it reaches the highest scope, and finally it searches the global scope. So the deeper a local is declared, the faster it is accessed. On the contrary, globals are the slowest to retrieve.

== Semi-advanced topics ==
=== Closures ===
'''Closures are functions that embed variables that are persisted across calls.'''<br/>
This is typically achieved through a "parent" function that declares a local "closed" variable and returns another child "closure" function using this local. The "closed" variable is then unreachable for anyone but the "closure". And since it the "closed" variable is not in the "closure"'s scope, it is not reinitialized on every call of "closure".
<div class="civ5-example"><syntaxhighlight lang="lua">
function GiveMeAFunc() -- the parent function
local x = 0 -- the closed variable
return function() -- the closure function embedding "closed"
x = x + 1
return closure
end
end

local func = GiveMeAFunc()
print(func()) -- Prints 1
print(func()) -- Prints 2
print(func()) -- Prints 3
</syntaxhighlight></div>

=== Iterators ===
'''Iterators are functions for use in <code>for...in</code> loops.'''<br/>
Let's consider the following code: <code>for var1, var2, var3 in iterable() do</code>.
* iterable has the following signature: <code>iterator, state, var1 iterable()</code>. It returns a function, a state, and the initial value of var1.
* iterator has the following signature: <code>var1, var2, var3 iterator(state, var1)</code>. It takes the state and the last value of var1 and returns var1, var2 and var3.
* The loop stops when var1 is nil.
* The for...in loop is equivalent to:
<div class="civ5-example"><syntaxhighlight lang="lua">
local iterator, state, var1, var2, var3
iterator, state, var1 = iterable()
do
var1, var2, var3 = iterator(state, var1)
if var1 == nil then break end

-- Inserts here the user code defined in the for..in loop
end
</syntaxhighlight></div>
* Note that we used var1, var2 and var3 for the example but there is no restriction to the number of variables. You could have one or hundred.

Let's write the "ipairs" function.
<div class="civ5-example"><syntaxhighlight lang="lua">
local function ipairs(table) -- The iterable function
local iterator = function(table, key) -- The iterator function
key = key + 1
return key, table[key]
end
return iterator, table, 0
end
</syntaxhighlight></div>

The same with closures: it's easier.
<div class="civ5-example"><syntaxhighlight lang="lua">
local function ipairs(table) -- The iterable function
local key = 0 -- Both "table" and "key" are closed variables.
local iterator = function() -- The iterator function, a closure: it ignores the arguments provided to it
key = key + 1
return key, table[key]
end
return iterator -- No need to return anything since we do not require any argument.
end
</syntaxhighlight></div>

=== No integer type ===
'''Lua offers no support for integers and only has a 64-bits floating point number type.'''<br/>
Actually, this is only troublesome for a few algorithms that use very large integers (>2^52) or require fast integer arithmetics. But many developers misunderstand floating points and believe the problem is broader than it is. For example, does the following assertion surprise you at least a bit: "any integer smaller than 2^52 can be accurately represented with a 64-bits floating point without any error"? If it did, you suffer from some misconceptions and you should better read carefully what's coming.

Many developers are confusing rounding errors with representation errors.
* '''Rounding errors''' actually only happen if you need a very high number of digits to represent a number. For example if you are adding a very large number with a small number. Rounding errors are very rarely encountered in day to day to applications. Actually most developers work their whole career without ever encountering them.
* '''Representation errors''' are the real problem: 0.1 is expressed in a decimal basis, but it has no finite representation in binary: it requires an infinite number of binary digits. This means that if you write 0.1 in your code it will be translated to a binary number close enough from 0.1 bot not exactly equal to it. So if you sum ten times 0.1, you sill sum ten times something close from 0.1 and the result will not be 1.

'''So the real problem for most developers only lies in the decimal-binary conversion that arises when you manipulate numbers in your code that do not have a finite representation in binary. As long as you do not use such numbers, there will be no problem. And here are the good news: integers do not suffer from any representation problem!''' Indeed, any integer can be represented with a finite number of binary digits. This is why the absence of an integer type typically does not cause problems, minus the performance penalty.

Here are a few examples to illustrate that point.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- This loop works as intended: no representation error and the upper bound is far below 2^52.
local sum = 0
for i = 0, 10000000000, 1 do sum = sum + 1 end
assert(sum == 10000000001)

-- This loop works as intended: 1/16 is a floating-point with an exact representation in binary
local sum = 0
for i = 0, 1, 1/16 do sum = sum + 1 end
assert(sum == 17/16)

-- This loop does NOT work as intended: 0.1 does not have an exact representation in binary.
-- It's the same for Lua, C and almost every programming language.
local sum = 0
for i = 0, 1, 0.1 do sum = sum + 1 end
assert(sum == 1.1) -- throws an error
</syntaxhighlight></div>

=== Errors management ===
Lua offers a error handling mechanism similar to exception handling but unfortunately not very convenient.
* Errors are thrown using the '''error''' function. It takes a string and it immediately aborts Lua execution until the game handles the error and prints it in Firetuner (when enabled).
* Errors are caught before that point using '''pcall''' or '''xpcall''', in order to let you resume execution by managing the error. "pcall" stands for "protected call".

Here are the syntaxes for pcall and xpcall:
* <code>bool, ... pcall(func, ...)</code>
** The function is called with the specified arguments.
** Pcall returns either true followed by the values returned by func, or false followed by the error text.
* <code>bool, ... xpcall(func, errorHandler)</code>:
** The function is called without any argument. If an error occurs the specified errorHandler is invoked with the error text as the only argument.
** Xpcall returns either true followed by the values returned by func, or false followed by the returned values from errorHandler.

Examples to invoke "someFunc" with "someArg" as the only argument. In both examples we want to display the error on the console, or the result if it was a success. A complete errors management example with a reporting mechanism for the end-user is presented in [[Debugging (Civ5)]].
<div class="civ5-example"><syntaxhighlight lang="lua">
-- pcall
local status, result = pcall(someFunc, someArg)
if not status then
print("error was: "..(result or "?"))
else
print("success: "..result)
end

-- xpcall
local status, result = xpcall(
function() someFunc(someArg) end,
function(err) print("error was: "..(result or "?")) end)

if status then
print("success: "..result)
end
</syntaxhighlight></div>

== Advanced topics==
=== Metatables and metamethods ===
* Every value in Lua, from a number to a userdata, has a metatable.
** Many objects can share the same metatable.
** Tables and userdata each have their own metatables by default. Numbers, bools, nils and strings all share the same metatable.
* A metatable may contain a few metamethods and index tables.
** Metamethods are methods stored under special fields names. They implement operators overloads.
** Index tables behave as "base classes": if a field name is not defined on an table, then Lua looks for this field on the index.
** In a way, metatables are analogous to virtual tables in object languages, but they are not just for methods, but also for fields and operators.
* You can get an object's metatable through '''getmetatable''' and assign it with '''setmetatable'''.
* See also the [http://www.lua.org/manual/5.1/manual.html#2.8 official metatables reference]

One example.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Define two tables A and B, and set "meta" their metatable
local a, b, meta = {}, {}, {}
setmetatable(a, meta)
setmetatable(b, meta)

-- Define an __index table on the metatable. It contains one key/value pair.
meta.__index = { "hello world" };

-- Print "hello world" twice
print(a[1])
print(b[1])

-- Now make our tables read-only
meta.__newindex = function(table, key, value) error("this table is read-only!") end
a[1] = "foo" -- throws an error
</syntaxhighlight></div>

Here are the most important fields a metatable can have:
* '''__index''': used when you read a member from an object. On tables, Lua will first search for a regular field on the table itself (not its index) before it looks at the index. The index may be a table or a function: <code>value func(object, key)</code>
* '''__newindex''': used when you assign a value to an object's member. On tables, newindex is only called if the table itself (not its index) does not already contains the specified key. May be a table or a function: <code>func(object, key, value)</code>
* '''__call''': used when you invoke the object as a function. Must be a function: <code>func(object, <args>)</code>
* '''__tostring''': used when you invoke the '''tostring''' function with this object in argument. Must be a function: <code>string func(object)</code>

Besides of that it can have fields for binary operators. When each of the two operands defined overloads, the left one is used. They must be functions: <code>result func(object)</code>
* '''__add''': addition
* '''__sub''': subtraction
* '''__mul''': multiplication
* '''__div''': division
* '''__mod''': module
* '''__pow''': exponentiation
* '''__eq''': equality comparison. Prior to calling this overload, Lua checks that types are equal.
* '''__neq''': inequality comparison. Prior to calling this overload, Lua checks whether types are different.
* '''__lt''': lesser than comparison. (b >= a) is considered equivalent to (a < b)
* '''__le''': lesser than or equal to comparison. (b > a) is considered equivalent to (a <= b). If __le is not defined, lua will use __lt, considering that (a <= b) is equivalent to not (b < a).
* '''__concat''': concatenation

Finally it can have the following fields for unary operators. They must be functions: <code>result func(object)</code>
* '''__unm''': unary minus
* '''__len''': the sharp operator (#). Can only be used on userdata ; on tables the default operator will always be called.

=== Implementing inheritance ===
The most common use of metatables is to mimic the behavior of object languages' types hierarchy. Here is how to do it:
<div class="civ5-example"><syntaxhighlight lang="lua">
local Dog = {}
function Dog:specie()
return "dog"
end
function Dog:race()
return "unknown"
end
function Dog:description()
return self.specie().." - "..self.race()
end
function Dog:new()
local instance = {}
setmetatable(instance, { __index = self})
return instance
end

local Pitbull = dog:new()
function Pitbull:race()
return "pitbull"
end

pitbull = Pitbull:new()
print(pitbull:description()) -- prints "dog - pitbull"
</syntaxhighlight></div>

This implementation is very elegant: the "new" method both creates a new instance and subtypes the creator, since "pitbull"'s index is now "Pitbull". However, should you define an operator overload on Dog's metatable, Pitbull would not inherit it. This is the limit of inheritance in Lua: operator overloads must be defined on the metatable itself, they cannot be defined on the metatable's index. As a result, there is no way to inherit those overloads while subtyping.

=== Coroutines ===
Coroutines provide a way to slice a function in many shorter calls and optionally return intermediate results. On each call, the function execution is resumed to the point where it stopped previously, with all locals being properly restored with the value they had at this time.
* Coroutines are often compared to threads. Indeed, when there are more threads than CPU cores, the operating system slices threads' execution into many little time frames and sequentially runs them in order to achieve multitasking.
* However while coroutines allows you to implement cooperative multitasking (the coroutines need to explicitly give the hand back), they cannot be used for preemptive multitasking or to use more than one system thread or CPU Core.
* As a result, coroutines are rather used as syntactic sugar (mostly to write iterators), or as a way to split a long function execution across many frames (through Context.{{Func5|UIElement|SetUpdate}}).

The following methods are mainly used:
* <code>'''coroutine''' coroutine.create('''function''' func)</code> creates a coroutine for the specified function. The function signature can be anything.
* <code>'''bool''', '''...''' coroutine.resume('''coroutine''' co, '''...''')</code> resumes the coroutine with the specified arguments. Then it returns either '''true''' followed by the returned results (either though '''return''' or '''yield'''), or '''false''' followed by an error message.
* <code>coroutine.yield('''...''')</code> suspends the execution of the coroutine and gives the hand back to the caller of coroutine.resume. The arguments will be returned by coroutine.resume.
* <code>'''string''' coroutine.status('''coroutine''' co)</code> returns either "running" (the active coroutine), "normal" (a parent of the active coroutine), "suspended" (not started or waiting to be resumed) or "dead" (finished or threw an error).

Here is a base example:
<div class="civ5-example"><syntaxhighlight lang="lua">
function neighborsCoroutine(plot)
for i = 0, 5 do
coroutine.yield(Map.PlotDirection(plot:GetX(), plot:GetY(), i))
end
end

local co = coroutine.create(neighborsCoroutine)
while coroutine.status(co) == "suspended"
local _, neighbor = co.resume(plot)
-- Do something with plot
end
</syntaxhighlight></div>

Here is how to transform it into an iterator:
<div class="civ5-example"><syntaxhighlight lang="lua">
function neighbors(plot)
local co = coroutine.create(neighbors)
return function()
if coroutine.status(co) ~= "suspended" then return end
return select(2, coroutine.resume(plot))
end
end

for neighbor in neighbors(plot) do
-- Do something with plot
end
</syntaxhighlight></div>

Here is an example that spreads a long function call across many frames:
<div class="civ5-example"><syntaxhighlight lang="lua">
function SpreadAcrossFrames(longFunctionCall, ...)
local co = coroutine.create(longFunctionCall)
ContextPtr.SetUpdate(function()
coroutine.resume(unpack(arg))
if coroutine.status(co) ~= "suspended" then
ContextPtr:ClearUpdate()
end
end)
end

SpreadAcrossFrames(SomeLongFunction, arg1, arg2)
</syntaxhighlight></div>

=== Design philosophy for Lua ===
Do not use a butter knife as you would use a chainsaw (the opposite is even more true and usually ends up badly). When designing your code, remember that:
* Lua is not an object language. While you can use objects and inheritance in some extent, you do not have to and there may be better alternatives sometimes.
* Lua is not a functional language. While you can use lambdas and similar concepts, you do not have to and there may be better alternatives sometimes.
* Lua is a multi-paradigm and dynamic language, take advantage of those.
* Lua is very suited for prototyping and small programs, and this is perfect for mods. Try to adjust your mindset: you're not writing a framework that a whole team will still use and maintain in twenty years.

[[Category:Civ5 API]]
[[Category:Civ5 Tutorials]]

Lua introduction for confirmed developers

2012-09-24T15:26:37Z

DonQuich:

''This page is a part of the [[Lua and UI Reference (Civ5)|Lua and UI Reference]].''

== About Lua ==
===Lua, not LUA===
This is a Portuguese word meaning "moon", not an acronym.

===Presentation===
Lua is an interpreted, dynamically typed, multi-paradigm language. It was designed in 1993 with the following objectives in mind:
* Extensible semantics. A small set of features allows the support of multiple paradigms, from functional programming to object programming. For example, while inheritance is not natively supported, it can be easily set up through metatables. The same features allow events in civ5 to behave both as functions and objects with Add and Remove methods.
* Highly portable. The con is a lightweight and somewhat lacking API.
* Easy to embed and to interface from other languages.
* Well suited for data description (''à la'' JSON).
* A beginners-friendly syntax.

===Performances===
As usual with interpreted and dynamically typed languages (hereby abusively named "scripting languages"), expect a 10 to 100 order of magnitude in performances decrease when compared to compiled and statically typed languages like C, C++ or C#. While it is possible for scripting languages to drastically improve the performances through more or less sophisticated means (expression trees/opcodes caching, JIT compiler, type inference to perform static resolutions), no such solution has been used in Civ5 (aside, probably, of the caching). And while an external JIT library exists, it causes compatibility problems with most mods using Lua.

That being said, Lua is still pretty good for a scripting language, better than the Python implementation from Civ4 for example. And all in all, it is fast enough for most of what modders want to achieve without the need to compromise code elegance, readability and maintainability for performances. So keep in mind that "premature optimization is the root of all evil" (Donald Knuth).

==Syntax cheatsheet==
=== Basics ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Literals
local x = 5
local x = 5.0
local x = nil -- A nil value is the same as an undefined value
local x = true
local x = false

-- Strings (single and double quotes can be used indifferently, there is no difference)
local x = "five"
local x = 'five'
local x = "five\n" -- Escape characters with "\".
local x = [[Five is a number.
Did you know?]] -- Multi-line string: equivalent to "Five is number.\nDid you know?"

-- Globals versus locals
x = 5 -- For globals, assigning is declaring.
local x = 5
</syntaxhighlight></div>

=== Operators ===
<div class="civ5-example"><syntaxhighlight lang="lua">
local x = a or b
local x = a and b

local x = "hello ".."world" .. "!" -- concatenation: two dots
local x = 4..5 -- Result is "45". On concatenation, conversions occur.

local x = (a + b - d) * f ^ g % h -- ^ is exponentiation, % is modulo
local x = "4" + "5" -- Result is 9. On arithmetic operations, conversions occur.

local x = a == b -- equality -- True only if a and b have the same values and types.
local x = a ~= b -- inequality

local x = ((a <= b) == not (a > b)) == ((a >= b) == not (a < b))
local x = "abc" < "def" -- Byte-wise comparison, not Unicode-compliant. Use Locale's methods instead.

local x = #"abc" -- Returns 3, the number of bytes in the string (3 characters, 1 byte each).
local x = #"您好世界" -- Returns 8, the number of bytes in the string (4 characters, 2 bytes each).
local x = #SomeTable -- Returns the biggest integer key in the table, or nil if there is no integer key.

-- No increment operator (++ --), no binary-assign operator (+= *=), no ternary operator (? :), no coalescence operator (??)
</syntaxhighlight></div>

=== Tables and multiple assignments ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Table declaration
SomeTable = {}

SomeArray = { "abc", "def" }
-- 1 => "abc", 2 => "def"

SomeComplexTable = { name = "John", surname = "Doe", age = 25, 43, [7] = 8 }
-- "name" => "John", "surname" => "Doe", "age" => 25, 1 => 43, 7 => 8.

-- Member access (all equivalent)
SomeTable.SomeMember = 5
SomeTable["SomeMember"] = 5

-- Multiple assignment
-- Both statements are equivalent since SomeArray contains "abc" and "def".
local x, y = "abc", "def"
local x, y = unpack(SomeArray)
</syntaxhighlight></div>

=== Functions ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Functions declarations (all equivalent)
function HelloWorld(a, b) print("Hello world") end
HelloWorld = function(a, b) print("Hello world") end
-- Functions are first-class objects and can be assigned like any other value!

-- Methods declarations (all equivalent)
SomeTable.HelloWorld(a, b) print("Hello world") end
SomeTable.HelloWorld = function(a, b) print("Hello world") end

-- Instanced methods declarations (all equivalent)
SomeTable.HelloWorldInstanced(self, a, b) print(self.SomeMember) end
SomeTable:HelloWorldInstanced(a, b) print(self.SomeMember) end

-- Functions and methods calls
HelloWorld(a) -- b will be nil in the function
HelloWorld(a, b)
SomeTable.HelloWorld(a, b)

-- Instanced methods calls (all equivalent)
SomeTable:HelloWorldInstanced(a, b)
SomeTable.HelloWorldInstanced(SomeTable, a, b)

-- Multiple return values
function func(a, b) return a, b end
local x, y, z = func(5, 6) -- Assigns 5 to x and 6 to y, z will be nil

-- Variable arguments
function SomeFunc(a, b, ...)
print(a)
print(b)
for i, v in ipairs(arg) do -- arg is a keyword for a table containing the variable arguments
print(v)
end
end
SomeFunc(1, 2, 3, 4, 5) -- prints 1, 2, 3, 4, 5
SomeFunc(1, 2) -- prints 1, 2
</syntaxhighlight></div>

=== Control flow ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- If
if name == "Wu Zetian" then
print("Hello China")
elseif name == "Napoleon" then -- "elseif", not "else if". Beware C developers!
print("Hello France")
else -- no "then" after "else"!
print("Hello unknown")
end

-- For loop (with counter)
for i = 1, 8 do print(i) end -- Prints 1, 2, 3, 4, 5, 6, 7, 8
for i = 1, 8, 2 do print(i) end -- Prints 1, 3, 5, 7

-- For loop (with iterator)
for playerID, pPlayer in pairs(Players) do -- Prints 1 Wu Zetian, 2 Napoleon, ...
print(playerID, pPlayer:GetName())
end
for plot in Plots() do -- Prints 0 0, 0 1, 0 2, ...
print(plot:GetX(), plot:GetY())
end

-- While (i will be 5 in the end)
while i < 5 do
i = i + 1
end

-- Repeat until (i will be 5 in the end)
repeat
i = i + 1
until i == 5

-- Infinite loops
-- Lua supports "break" for all loops but not "continue" instruction does not exist!
do
i = i + 1
if i > 5 then break end
end

</syntaxhighlight></div>

== Basics ==
=== Type system ===
You can get a variable's type by using the '''type''' function. It takes any value and returns a string. Here are the possible results:
* '''nil''': Lua makes do distinction between an undefined variable and a variable with a nil value. Assigning nil to a variable or table member is equivalent to undefining it.
* '''number''': a 64 bits floating-point number. Lua has no support for integers and only use floating-points. See also [[#No integer type]].
* '''string''': your usual string of characters. In Lua all strings are interned. This speeds up comparisons but it makes allocation of new strings slower.
* '''boolean''': true or false obviously.
* '''table''': any table.
* '''userdata''': objects defined in C for use in Lua. They may not be enumerated through pairs and other limitations. Now the Civ5 API tend to return regular tables whose metatable is of type userdata, this allows us to use the provided objects as regular Lua tables.
* '''function''': remember that functions are first-class objects in Lua.
* '''thread''': coroutines actually. Lua does not support threads.

=== Implicit conversions ===
* Whenever you concatenate two values (and possibly when you invoke a standard function that takes a string), an automatic conversion to string occurs, as if you had used the '''tostring''' function. The expression <code>4..5</code> returns "45".
* Whenever you perform an arithmetic operation, the operands are both converted to numbers, as if you had used the '''tonumber''' function. The expression <code>"4" + "5"</code> returns 9.

=== Strict equality comparisons ===
'''Two values are equal only if their types are the same.'''<br/>
This is stricter than C and far stricter than PHP for example.
* 4 is not equal to "4". (number type and string type). In PHP they would be equal.
* 0 is not equal to false (number type and bool type). In C they would be equal.
* 0 is not equal to nil. (number type and nil type). In C they would be equal.

Regarding tables and C-made objects, they are compared by reference.
<div class="civ5-example"><syntaxhighlight lang="lua">
a = { 5 }
b = { 5 }
c = a
assert(a == c) -- OK
assert(a == b) -- ERROR
</syntaxhighlight></div>

=== Boolean logic ===
'''Anything that is neither false nor nil is evaluated to true.'''<br/>
This is pretty simple. Especially, an empty string or the zero number are evaluated to true.
<div class="civ5-example"><syntaxhighlight lang="lua">
if 0 then print("hello world") end -- prints hello world
</syntaxhighlight></div>

Now regarding the and/or operators, two rules to remember:
* '''The right operand is only evaluated when needed.'''
** <code>false and x()</code> does not call x() since the result will be false anyway.
** <code>true or x()</code> does not call x() since the result will be true anyway.
* '''The result is the last operand to have been evaluated.'''
** <code>x() and y()</code> returns x() if it was false, y() otherwise.
** <code>x() or y()</code> returns x() if it was true, y() otherwise.

=== Ternary and coalescence statements ===
We can exploit the and/or operators behavior:
* '''Coalescence:''' <code>x or y</code>. It returns x if x is neither nil nor false, y otherwise.
:In other words <code>result = x or y</code> is equivalent to: <code>if x then result = x else result = y end</code>.
* '''Ternary:''' <code>condition and x or y</code> (as long as x is not nil or false). It returns x if condition was true, y if it was false.
:Indeed the expression becomes: <code>(condition and x) or y</code>. If condition is true the '''and''' operator returns x, and since x is true, y is not evaluated and '''or''' returns x.
:In other words <code>result = condition and x or y</code> is equivalent to: <code>if condition then result = x else result = y end</code>.

=== Arrays versus tables ===
'''In Lua, an array is a table whose keys are integers.'''

Since this is a common programming pattern, a number of things are designed for arrays:
* <code>{"abc", "def", "ghi"}</code> starts at index 1, up to index 3. Arrays typically start at 1.
* <code>table.insert({}, "abc")</code> will transform the provided empty table to <code>{"abc"}</code>
* <code>table.insert({"abc", "def"}, "ghi")</code> will transform the provided table to <code>{"abc", "def", "ghi"}</code>
* <code>table.insert({"abc", "ghi"}, 2, "def")</code> will transform the provided table to <code>{"abc", "def", "ghi"}</code>
* <code>table.remove({"abc", "def", "ghi"}, 2)</code> will transform the provided table to <code>{"abc", ""ghi"}</code>
* <code>#{"abc", "def", "ghi"}</code> returns 3, the biggest integer key.

=== Ipairs versus pairs ===
You could say that '''pairs''' is for table and '''ipairs''' for arrays.
* '''Pairs''' enumerate all the key/value pairs in an unordered matter.
* '''Ipairs''' only enumerates the key/value pairs for consecutive integer keys, in an ascending order, starting from 1 up to the largest key. If at some point a key is missing, the enumeration stops.
::It does not matter whether the table was crated with table.insert or directly by inserting the values through, for example <code>table[i] = value</code>.

<div class="civ5-example"><syntaxhighlight lang="lua">
-- Produces: { 1 => "one", 2 => "two", 4 => "four", "name" => "John", "age" => 25 }
local t = { "one", "two", name = "John", age = 25, [4] = "four" }

-- Will print (for example, the order is undetermined): "name", 2, 4, "age", 1
for k in pairs(t) do print(k) end

-- Will print 1, 2
for k in ipairs(t) do print(k) end

-- Both ipairs and pairs return a key and a value, so you could also use:
for k, v in pairs(t) do print(k, v) end
</syntaxhighlight></div>

=== Semicolons and line breaks ===
'''Statements need to be separated either by a line break or a semicolon.'''
* You can use both a semicolon and a line break but then the semicolon is redundant and not required, although it does not cause any problem.
* Line breaks can also be freely added about everywhere and behave as whitespaces most of the time (you can add them after most keywords for example, so you can keep if...then...end structures on one line or split them across multiple lines).

=== Locals, globals and includes ===
* For a documentation on the '''include''' statement, see [[Specificities of the Lua implementation in Civ5#Include]].
* The include statement allows you to include a lua file into another one (see [[Specificities of the Lua implementation in Civ5]]). When you do so, the globals defined in the included file are imported in the parent file. However the local variables are only visible from within the file that declared them.
* Another specificities of locals: they're only visible after the point they have been declared in the file, while globals are always visible. An example is worth thousand of words.
<div class="civ5-example"><syntaxhighlight lang="lua">
function Func1()
print(someLocal or "nil")
print(someGlobal or "nil")
end

local someLocal = "foo"
function Func2()
print(someLocal or "nil")
print(someGlobal or "nil")
end

someGlobal = "global"
someLocal = "local"
Func1() -- prints "nil", then "global": someLocal is assigned but not visible from Func1
Func2() -- prints "local", then "global": someLocal is assigned and visible from Func2
</syntaxhighlight></div>
* Performances-wise, Lua first searches a variable name in the current scope, then in the parent scope, etcetera until it reaches the highest scope, and finally it searches the global scope. So the deeper a local is declared, the faster it is accessed. On the contrary, globals are the slowest to retrieve.

== Semi-advanced topics ==
=== Closures ===
'''Closures are functions that embed variables that are persisted across calls.'''<br/>
This is typically achieved through a "parent" function that declares a local "closed" variable and returns another child "closure" function using this local. The "closed" variable is then unreachable for anyone but the "closure". And since it the "closed" variable is not in the "closure"'s scope, it is not reinitialized on every call of "closure".
<div class="civ5-example"><syntaxhighlight lang="lua">
function GiveMeAFunc() -- the parent function
local x = 0 -- the closed variable
return function() -- the closure function embedding "closed"
x = x + 1
return closure
end
end

local func = GiveMeAFunc()
print(func()) -- Prints 1
print(func()) -- Prints 2
print(func()) -- Prints 3
</syntaxhighlight></div>

=== Iterators ===
'''Iterators are functions for use in <code>for...in</code> loops.'''<br/>
Let's consider the following code: <code>for var1, var2, var3 in iterable() do</code>.
* iterable has the following signature: <code>iterator, state, var1 iterable()</code>. It returns a function, a state, and the initial value of var1.
* iterator has the following signature: <code>var1, var2, var3 iterator(state, var1)</code>. It takes the state and the last value of var1 and returns var1, var2 and var3.
* The loop stops when var1 is nil.
* The for...in loop is equivalent to:
<div class="civ5-example"><syntaxhighlight lang="lua">
local iterator, state, var1, var2, var3
iterator, state, var1 = iterable()
do
var1, var2, var3 = iterator(state, var1)
if var1 == nil then break end

-- Inserts here the user code defined in the for..in loop
end
</syntaxhighlight></div>
* Note that we used var1, var2 and var3 for the example but there is no restriction to the number of variables. You could have one or hundred.

Let's write the "ipairs" function.
<div class="civ5-example"><syntaxhighlight lang="lua">
local function ipairs(table) -- The iterable function
local iterator = function(table, key) -- The iterator function
key = key + 1
return key, table[key]
end
return iterator, table, 0
end
</syntaxhighlight></div>

The same with closures: it's easier.
<div class="civ5-example"><syntaxhighlight lang="lua">
local function ipairs(table) -- The iterable function
local key = 0 -- Both "table" and "key" are closed variables.
local iterator = function() -- The iterator function, a closure: it ignores the arguments provided to it
key = key + 1
return key, table[key]
end
return iterator -- No need to return anything since we do not require any argument.
end
</syntaxhighlight></div>

=== No integer type ===
'''Lua offers no support for integers and only has a 64-bits floating point number type.'''<br/>
Actually, this is only troublesome for a few algorithms that use very large integers (>2^52) or require fast integer arithmetics. But many developers misunderstand floating points and believe the problem is broader than it is. For example, does the following assertion surprise you at least a bit: "any integer smaller than 2^52 can be accurately represented with a 64-bits floating point without any error"? If it did, you suffer from some misconceptions and you should better read carefully what's coming.

Many developers are confusing rounding errors with representation errors.
* '''Rounding errors''' actually only happen if you need a very high number of digits to represent a number. For example if you are adding a very large number with a small number. Rounding errors are very rarely encountered in day to day to applications. Actually most developers work their whole career without ever encountering them.
* '''Representation errors''' are the real problem: 0.1 is expressed in a decimal basis, but it has no finite representation in binary: it requires an infinite number of binary digits. This means that if you write 0.1 in your code it will be translated to a binary number close enough from 0.1 bot not exactly equal to it. So if you sum ten times 0.1, you sill sum ten times something close from 0.1 and the result will not be 1.

'''So the real problem for most developers only lies in the decimal-binary conversion that arises when you manipulate numbers in your code that do not have a finite representation in binary. As long as you do not use such numbers, there will be no problem. And here are the good news: integers do not suffer from any representation problem!''' Indeed, any integer can be represented with a finite number of binary digits. This is why the absence of an integer type typically does not cause problems, minus the performance penalty.

Here are a few examples to illustrate that point.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- This loop works as intended: no representation error and the upper bound is far below 2^52.
local sum = 0
for i = 0, 10000000000, 1 do sum = sum + 1 end
assert(sum == 10000000001)

-- This loop works as intended: 1/16 is a floating-point with an exact representation in binary
local sum = 0
for i = 0, 1, 1/16 do sum = sum + 1 end
assert(sum == 17/16)

-- This loop does NOT work as intended: 0.1 does not have an exact representation in binary.
-- It's the same for Lua, C and almost every programming language.
local sum = 0
for i = 0, 1, 0.1 do sum = sum + 1 end
assert(sum == 1.1) -- throws an error
</syntaxhighlight></div>

=== Errors management ===
Lua offers a error handling mechanism similar to exception handling but unfortunately not very convenient.
* Errors are thrown using the '''error''' function. It takes a string and it immediately aborts Lua execution until the game handles the error and prints it in Firetuner (when enabled).
* Errors are caught before that point using '''pcall''' or '''xpcall''', in order to let you resume execution by managing the error. "pcall" stands for "protected call".

Here are the syntaxes for pcall and xpcall:
* <code>bool, ... pcall(func, ...)</code>
** The function is called with the specified arguments.
** Pcall returns either true followed by the values returned by func, or false followed by the error text.
* <code>bool, ... xpcall(func, errorHandler)</code>:
** The function is called without any argument. If an error occurs the specified errorHandler is invoked with the error text as the only argument.
** Xpcall returns either true followed by the values returned by func, or false followed by the returned values from errorHandler.

Examples to invoke "someFunc" with "someArg" as the only argument. In both examples we want to display the error on the console, or the result if it was a success. A complete errors management example with a reporting mechanism for the end-user is presented in [[Debugging (Civ5)]].
<div class="civ5-example"><syntaxhighlight lang="lua">
-- pcall
local status, result = pcall(someFunc, someArg)
if not status then
print("error was: "..(result or "?"))
else
print("success: "..result)
end

-- xpcall
local status, result = xpcall(
function() someFunc(someArg) end,
function(err) print("error was: "..(result or "?")) end)

if status then
print("success: "..result)
end
</syntaxhighlight></div>

== Advanced topics==
=== Metatables and metamethods ===
* Every value in Lua, from a number to a userdata, has a metatable.
** Many objects can share the same metatable.
** Tables and userdata each have their own metatables by default. Numbers, bools, nils and strings all share the same metatable.
* A metatable may contain a few metamethods and index tables.
** Metamethods are methods stored under special fields names. They implement operators overloads.
** Index tables behave as "base classes": if a field name is not defined on an table, then Lua looks for this field on the index.
** In a way, metatables are analogous to virtual tables in object languages, but they are not just for methods, but also for fields and operators.
* You can get an object's metatable through '''getmetatable''' and assign it with '''setmetatable'''.
* See also the [http://www.lua.org/manual/5.1/manual.html#2.8 official metatables reference]

One example.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Define two tables A and B, and set "meta" their metatable
local a, b, meta = {}, {}, {}
setmetatable(a, meta)
setmetatable(b, meta)

-- Define an __index table on the metatable. It contains one key/value pair.
meta.__index = { "hello world" };

-- Print "hello world" twice
print(a[1])
print(b[1])

-- Now make our tables read-only
meta.__newindex = function(table, key, value) error("this table is read-only!") end
a[1] = "foo" -- throws an error
</syntaxhighlight></div>

Here are the most important fields a metatable can have:
* '''__index''': used when you read a member from an object. On tables, Lua will first search for a regular field on the table itself (not its index) before it looks at the index. The index may be a table or a function: <code>value func(object, key)</code>
* '''__newindex''': used when you assign a value to an object's member. On tables, newindex is only called if the table itself (not its index) does not already contains the specified key. May be a table or a function: <code>func(object, key, value)</code>
* '''__call''': used when you invoke the object as a function. Must be a function: <code>func(object, <args>)</code>
* '''__tostring''': used when you invoke the '''tostring''' function with this object in argument. Must be a function: <code>string func(object)</code>

Besides of that it can have fields for binary operators. When each of the two operands defined overloads, the left one is used. They must be functions: <code>result func(object)</code>
* '''__add''': addition
* '''__sub''': subtraction
* '''__mul''': multiplication
* '''__div''': division
* '''__mod''': module
* '''__pow''': exponentiation
* '''__eq''': equality comparison. Prior to calling this overload, Lua checks that types are equal.
* '''__neq''': inequality comparison. Prior to calling this overload, Lua checks whether types are different.
* '''__lt''': lesser than comparison. (b >= a) is considered equivalent to (a < b)
* '''__le''': lesser than or equal to comparison. (b > a) is considered equivalent to (a <= b). If __le is not defined, lua will use __lt, considering that (a <= b) is equivalent to not (b < a).
* '''__concat''': concatenation

Finally it can have the following fields for unary operators. They must be functions: <code>result func(object)</code>
* '''__unm''': unary minus
* '''__len''': the sharp operator (#). Can only be used on userdata ; on tables the default operator will always be called.

=== Implementing inheritance ===
The most common use of metatables is to mimic the behavior of object languages' types hierarchy. Here is how to do it:
<div class="civ5-example"><syntaxhighlight lang="lua">
local Dog = {}
function Dog:specie()
return "dog"
end
function Dog:race()
return "unknown"
end
function Dog:description()
return self.specie().." - "..self.race()
end
function Dog:new()
local instance = {}
setmetatable(instance, { __index = self})
return instance
end

local Pitbull = dog:new()
function Pitbull:race()
return "pitbull"
end

pitbull = Pitbull:new()
print(pitbull:description()) -- prints "dog - pitbull"
</syntaxhighlight></div>

This implementation is very elegant: the "new" method both creates a new instance and subtypes the creator, since "pitbull"'s index is now "Pitbull". However, should you define an operator overload on Dog's metatable, Pitbull would not inherit it. This is the limit of inheritance in Lua: operator overloads must be defined on the metatable itself, they cannot be defined on the metatable's index. As a result, there is no way to inherit those overloads while subtyping.

=== Coroutines ===
Coroutines provide a way to slice a function in many shorter calls and optionally return intermediate results. On each call, the function execution is resumed to the point where it stopped previously, with all locals being properly restored with the value they had at this time.
* Coroutines are often compared to threads. Indeed, when there are more threads than CPU cores, the operating system slices threads' execution into many little time frames and sequentially runs them in order to achieve multitasking.
* However while coroutines allows you to implement cooperative multitasking (the coroutines need to explicitly give the hand back), they cannot be used for preemptive multitasking or to use more than one system thread or CPU Core.
* As a result, coroutines are rather used as syntactic sugar (mostly to write iterators), or as a way to split a long function execution across many frames (through Context.{{Func5|Context|SetUpdate}}).

The following methods are mainly used:
* <code>'''coroutine''' coroutine.create('''function''' func)</code> creates a coroutine for the specified function. The function signature can be anything.
* <code>'''bool''', '''...''' coroutine.resume('''coroutine''' co, '''...''')</code> resumes the coroutine with the specified arguments. Then it returns either '''true''' followed by the returned results (either though '''return''' or '''yield'''), or '''false''' followed by an error message.
* <code>coroutine.yield('''...''')</code> suspends the execution of the coroutine and gives the hand back to the caller of coroutine.resume. The arguments will be returned by coroutine.resume.
* <code>'''string''' coroutine.status('''coroutine''' co)</code> returns either "running" (the active coroutine), "normal" (a parent of the active coroutine), "suspended" (not started or waiting to be resumed) or "dead" (finished or threw an error).

Here is a base example:
<div class="civ5-example"><syntaxhighlight lang="lua">
function neighborsCoroutine(plot)
for i = 0, 5 do
coroutine.yield(Map.PlotDirection(plot:GetX(), plot:GetY(), i))
end
end

local co = coroutine.create(neighborsCoroutine)
while coroutine.status(co) == "suspended"
local _, neighbor = co.resume(plot)
-- Do something with plot
end
</syntaxhighlight></div>

Here is how to transform it into an iterator:
<div class="civ5-example"><syntaxhighlight lang="lua">
function neighbors(plot)
local co = coroutine.create(neighbors)
return function()
if coroutine.status(co) ~= "suspended" then return end
return select(2, coroutine.resume(plot))
end
end

for neighbor in neighbors(plot) do
-- Do something with plot
end
</syntaxhighlight></div>

Here is an example that spreads a long function call across many frames:
<div class="civ5-example"><syntaxhighlight lang="lua">
function SpreadAcrossFrames(longFunctionCall, ...)
local co = coroutine.create(longFunctionCall)
ContextPtr.SetUpdate(function()
coroutine.resume(unpack(arg))
if coroutine.status(co) ~= "suspended" then
ContextPtr:ClearUpdate()
end
end)
end

SpreadAcrossFrames(SomeLongFunction, arg1, arg2)
</syntaxhighlight></div>

=== Design philosophy for Lua ===
Do not use a butter knife as you would use a chainsaw (the opposite is even more true and usually ends up badly). When designing your code, remember that:
* Lua is not an object language. While you can use objects and inheritance in some extent, you do not have to and there may be better alternatives sometimes.
* Lua is not a functional language. While you can use lambdas and similar concepts, you do not have to and there may be better alternatives sometimes.
* Lua is a multi-paradigm and dynamic language, take advantage of those.
* Lua is very suited for prototyping and small programs, and this is perfect for mods. Try to adjust your mindset: you're not writing a framework that a whole team will still use and maintain in twenty years.

[[Category:Civ5 API]]
[[Category:Civ5 Tutorials]]

Lua introduction for confirmed developers

2012-09-24T15:24:25Z

DonQuich:

''This page is a part of the [[Lua and UI Reference (Civ5)|Lua and UI Reference]].''

== About Lua ==
===Lua, not LUA===
This is a Portuguese word meaning "moon", not an acronym.

===Presentation===
Lua is an interpreted, dynamically typed, multi-paradigm language. It was designed in 1993 with the following objectives in mind:
* Extensible semantics. A small set of features allows the support of multiple paradigms, from functional programming to object programming. For example, while inheritance is not natively supported, it can be easily set up through metatables. The same features allow events in civ5 to behave both as functions and objects with Add and Remove methods.
* Highly portable. The con is a lightweight and somewhat lacking API.
* Easy to embed and to interface from other languages.
* Well suited for data description (''à la'' JSON).
* A beginners-friendly syntax.

===Performances===
As usual with interpreted and dynamically typed languages (hereby abusively named "scripting languages"), expect a 10 to 100 order of magnitude in performances decrease when compared to compiled and statically typed languages like C, C++ or C#. While it is possible for scripting languages to drastically improve the performances through more or less sophisticated means (expression trees/opcodes caching, JIT compiler, type inference to perform static resolutions), no such solution has been used in Civ5 (aside, probably, of the caching). And while an external JIT library exists, it causes compatibility problems with most mods using Lua.

That being said, Lua is still pretty good for a scripting language, better than the Python implementation from Civ4 for example. And all in all, it is fast enough for most of what modders want to achieve without the need to compromise code elegance, readability and maintainability for performances. So keep in mind that "premature optimization is the root of all evil" (Donald Knuth).

==Syntax cheatsheet==
=== Basics ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Literals
local x = 5
local x = 5.0
local x = nil -- A nil value is the same as an undefined value
local x = true
local x = false

-- Strings (single and double quotes can be used indifferently, there is no difference)
local x = "five"
local x = 'five'
local x = "five\n" -- Escape characters with "\".
local x = [[Five is a number.
Did you know?]] -- Multi-line string: equivalent to "Five is number.\nDid you know?"

-- Globals versus locals
x = 5 -- For globals, assigning is declaring.
local x = 5
</syntaxhighlight></div>

=== Operators ===
<div class="civ5-example"><syntaxhighlight lang="lua">
local x = a or b
local x = a and b

local x = "hello ".."world" .. "!" -- concatenation: two dots
local x = 4..5 -- Result is "45". On concatenation, conversions occur.

local x = (a + b - d) * f ^ g % h -- ^ is exponentiation, % is modulo
local x = "4" + "5" -- Result is 9. On arithmetic operations, conversions occur.

local x = a == b -- equality -- True only if a and b have the same values and types.
local x = a ~= b -- inequality

local x = ((a <= b) == not (a > b)) == ((a >= b) == not (a < b))
local x = "abc" < "def" -- Byte-wise comparison, not Unicode-compliant. Use Locale's methods instead.

local x = #"abc" -- Returns 3, the number of bytes in the string (3 characters, 1 byte each).
local x = #"您好世界" -- Returns 8, the number of bytes in the string (4 characters, 2 bytes each).
local x = #SomeTable -- Returns the biggest integer key in the table, or nil if there is no integer key.

-- No increment operator (++ --), no binary-assign operator (+= *=), no ternary operator (? :), no coalescence operator (??)
</syntaxhighlight></div>

=== Tables and multiple assignments ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Table declaration
SomeTable = {}

SomeArray = { "abc", "def" }
-- 1 => "abc", 2 => "def"

SomeComplexTable = { name = "John", surname = "Doe", age = 25, 43, [7] = 8 }
-- "name" => "John", "surname" => "Doe", "age" => 25, 1 => 43, 7 => 8.

-- Member access (all equivalent)
SomeTable.SomeMember = 5
SomeTable["SomeMember"] = 5

-- Multiple assignment
-- Both statements are equivalent since SomeArray contains "abc" and "def".
local x, y = "abc", "def"
local x, y = unpack(SomeArray)
</syntaxhighlight></div>

=== Functions ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Functions declarations (all equivalent)
function HelloWorld(a, b) print("Hello world") end
HelloWorld = function(a, b) print("Hello world") end
-- Functions are first-class objects and can be assigned like any other value!

-- Methods declarations (all equivalent)
SomeTable.HelloWorld(a, b) print("Hello world") end
SomeTable.HelloWorld = function(a, b) print("Hello world") end

-- Instanced methods declarations (all equivalent)
SomeTable.HelloWorldInstanced(self, a, b) print(self.SomeMember) end
SomeTable:HelloWorldInstanced(a, b) print(self.SomeMember) end

-- Functions and methods calls
HelloWorld(a) -- b will be nil in the function
HelloWorld(a, b)
SomeTable.HelloWorld(a, b)

-- Instanced methods calls (all equivalent)
SomeTable:HelloWorldInstanced(a, b)
SomeTable.HelloWorldInstanced(SomeTable, a, b)

-- Multiple return values
function func(a, b) return a, b end
local x, y, z = func(5, 6) -- Assigns 5 to x and 6 to y, z will be nil

-- Variable arguments
function SomeFunc(a, b, ...)
print(a)
print(b)
for i, v in ipairs(arg) do -- arg is a keyword for a table containing the variable arguments
print(v)
end
end
SomeFunc(1, 2, 3, 4, 5) -- prints 1, 2, 3, 4, 5
SomeFunc(1, 2) -- prints 1, 2
</syntaxhighlight></div>

=== Control flow ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- If
if name == "Wu Zetian" then
print("Hello China")
elseif name == "Napoleon" then -- "elseif", not "else if". Beware C developers!
print("Hello France")
else -- no "then" after "else"!
print("Hello unknown")
end

-- For loop (with counter)
for i = 1, 8 do print(i) end -- Prints 1, 2, 3, 4, 5, 6, 7, 8
for i = 1, 8, 2 do print(i) end -- Prints 1, 3, 5, 7

-- For loop (with iterator)
for playerID, pPlayer in pairs(Players) do -- Prints 1 Wu Zetian, 2 Napoleon, ...
print(playerID, pPlayer:GetName())
end
for plot in Plots() do -- Prints 0 0, 0 1, 0 2, ...
print(plot:GetX(), plot:GetY())
end

-- While (i will be 5 in the end)
while i < 5 do
i = i + 1
end

-- Repeat until (i will be 5 in the end)
repeat
i = i + 1
until i == 5

-- Infinite loops
-- Lua supports "break" for all loops but not "continue" instruction does not exist!
do
i = i + 1
if i > 5 then break end
end

</syntaxhighlight></div>

== Basics ==
=== Type system ===
You can get a variable's type by using the '''type''' function. It takes any value and returns a string. Here are the possible results:
* '''nil''': Lua makes do distinction between an undefined variable and a variable with a nil value. Assigning nil to a variable or table member is equivalent to undefining it.
* '''number''': a 64 bits floating-point number. Lua has no support for integers and only use floating-points. See also [[#No integer type]].
* '''string''': your usual string of characters. In Lua all strings are interned. This speeds up comparisons but it makes allocation of new strings slower.
* '''boolean''': true or false obviously.
* '''table''': any table.
* '''userdata''': objects defined in C for use in Lua. They may not be enumerated through pairs and other limitations. Now the Civ5 API tend to return regular tables whose metatable is of type userdata, this allows us to use the provided objects as regular Lua tables.
* '''function''': remember that functions are first-class objects in Lua.
* '''thread''': coroutines actually. Lua does not support threads.

=== Implicit conversions ===
* Whenever you concatenate two values (and possibly when you invoke a standard function that takes a string), an automatic conversion to string occurs, as if you had used the '''tostring''' function. The expression <code>4..5</code> returns "45".
* Whenever you perform an arithmetic operation, the operands are both converted to numbers, as if you had used the '''tonumber''' function. The expression <code>"4" + "5"</code> returns 9.

=== Strict equality comparisons ===
'''Two values are equal only if their types are the same.'''<br/>
This is stricter than C and far stricter than PHP for example.
* 4 is not equal to "4". (number type and string type). In PHP they would be equal.
* 0 is not equal to false (number type and bool type). In C they would be equal.
* 0 is not equal to nil. (number type and nil type). In C they would be equal.

Regarding tables and C-made objects, they are compared by reference.
<div class="civ5-example"><syntaxhighlight lang="lua">
a = { 5 }
b = { 5 }
c = a
assert(a == c) -- OK
assert(a == b) -- ERROR
</syntaxhighlight></div>

=== Boolean logic ===
'''Anything that is neither false nor nil is evaluated to true.'''<br/>
This is pretty simple. Especially, an empty string or the zero number are evaluated to true.
<div class="civ5-example"><syntaxhighlight lang="lua">
if 0 then print("hello world") end -- prints hello world
</syntaxhighlight></div>

Now regarding the and/or operators, two rules to remember:
* '''The right operand is only evaluated when needed.'''
** <code>false and x()</code> does not call x() since the result will be false anyway.
** <code>true or x()</code> does not call x() since the result will be true anyway.
* '''The result is the last operand to have been evaluated.'''
** <code>x() and y()</code> returns x() if it was false, y() otherwise.
** <code>x() or y()</code> returns x() if it was true, y() otherwise.

=== Ternary and coalescence statements ===
We can exploit the and/or operators behavior:
* '''Coalescence:''' <code>x or y</code>. It returns x if x is neither nil nor false, y otherwise.
:In other words <code>result = x or y</code> is equivalent to: <code>if x then result = x else result = y end</code>.
* '''Ternary:''' <code>condition and x or y</code> (as long as x is not nil or false). It returns x if condition was true, y if it was false.
:Indeed the expression becomes: <code>(condition and x) or y</code>. If condition is true the '''and''' operator returns x, and since x is true, y is not evaluated and '''or''' returns x.
:In other words <code>result = condition and x or y</code> is equivalent to: <code>if condition then result = x else result = y end</code>.

=== Arrays versus tables ===
'''In Lua, an array is a table whose keys are integers.'''

Since this is a common programming pattern, a number of things are designed for arrays:
* <code>{"abc", "def", "ghi"}</code> starts at index 1, up to index 3. Arrays typically start at 1.
* <code>table.insert({}, "abc")</code> will transform the provided empty table to <code>{"abc"}</code>
* <code>table.insert({"abc", "def"}, "ghi")</code> will transform the provided table to <code>{"abc", "def", "ghi"}</code>
* <code>table.insert({"abc", "ghi"}, 2, "def")</code> will transform the provided table to <code>{"abc", "def", "ghi"}</code>
* <code>table.remove({"abc", "def", "ghi"}, 2)</code> will transform the provided table to <code>{"abc", ""ghi"}</code>
* <code>#{"abc", "def", "ghi"}</code> returns 3, the biggest integer key.

=== Ipairs versus pairs ===
You could say that '''pairs''' is for table and '''ipairs''' for arrays.
* '''Pairs''' enumerate all the key/value pairs in an unordered matter.
* '''Ipairs''' only enumerates the key/value pairs for consecutive integer keys, in an ascending order, starting from 1 up to the largest key. If at some point a key is missing, the enumeration stops.
::It does not matter whether the table was crated with table.insert or directly by inserting the values through, for example <code>table[i] = value</code>.

<div class="civ5-example"><syntaxhighlight lang="lua">
-- Produces: { 1 => "one", 2 => "two", 4 => "four", "name" => "John", "age" => 25 }
local t = { "one", "two", name = "John", age = 25, [4] = "four" }

-- Will print (for example, the order is undetermined): "name", 2, 4, "age", 1
for k in pairs(t) do print(k) end

-- Will print 1, 2
for k in ipairs(t) do print(k) end

-- Both ipairs and pairs return a key and a value, so you could also use:
for k, v in pairs(t) do print(k, v) end
</syntaxhighlight></div>

=== Semicolons and line breaks ===
'''Statements need to be separated either by a line break or a semicolon.'''
* You can use both a semicolon and a line break but then the semicolon is redundant and not required, although it does not cause any problem.
* Line breaks can also be freely added about everywhere and behave as whitespaces most of the time (you can add them after most keywords for example, so you can keep if...then...end structures on one line or split them across multiple lines).

=== Locals, globals and includes ===
* For a documentation on the '''include''' statement, see [[Specificities of the Lua implementation in Civ5#Include]].
* The include statement allows you to include a lua file into another one (see [[Specificities of the Lua implementation in Civ5]]). When you do so, the globals defined in the included file are imported in the parent file. However the local variables are only visible from within the file that declared them.
* Another specificities of locals: they're only visible after the point they have been declared in the file, while globals are always visible. An example is worth thousand of words.
<div class="civ5-example"><syntaxhighlight lang="lua">
function Func1()
print(someLocal or "nil")
print(someGlobal or "nil")
end

local someLocal = "foo"
function Func2()
print(someLocal or "nil")
print(someGlobal or "nil")
end

someGlobal = "global"
someLocal = "local"
Func1() -- prints "nil", then "global": someLocal is assigned but not visible from Func1
Func2() -- prints "local", then "global": someLocal is assigned and visible from Func2
</syntaxhighlight></div>
* Performances-wise, Lua first searches a variable name in the current scope, then in the parent scope, etcetera until it reaches the highest scope, and finally it searches the global scope. So the deeper a local is declared, the faster it is accessed. On the contrary, globals are the slowest to retrieve.

== Semi-advanced topics ==
=== Closures ===
'''Closures are functions that embed variables that are persisted across calls.'''<br/>
This is typically achieved through a "parent" function that declares a local "closed" variable and returns another child "closure" function using this local. The "closed" variable is then unreachable for anyone but the "closure". And since it the "closed" variable is not in the "closure"'s scope, it is not reinitialized on every call of "closure".
<div class="civ5-example"><syntaxhighlight lang="lua">
function GiveMeAFunc() -- the parent function
local x = 0 -- the closed variable
return function() -- the closure function embedding "closed"
x = x + 1
return closure
end
end

local func = GiveMeAFunc()
print(func()) -- Prints 1
print(func()) -- Prints 2
print(func()) -- Prints 3
</syntaxhighlight></div>

=== Iterators ===
'''Iterators are functions for use in <code>for...in</code> loops.'''<br/>
Let's consider the following code: <code>for var1, var2, var3 in iterable() do</code>.
* iterable has the following signature: <code>iterator, state, var1 iterable()</code>. It returns a function, a state, and the initial value of var1.
* iterator has the following signature: <code>var1, var2, var3 iterator(state, var1)</code>. It takes the state and the last value of var1 and returns var1, var2 and var3.
* The loop stops when var1 is nil.
* The for...in loop is equivalent to:
<div class="civ5-example"><syntaxhighlight lang="lua">
local iterator, state, var1, var2, var3
iterator, state, var1 = iterable()
do
var1, var2, var3 = iterator(state, var1)
if var1 == nil then break end

-- Inserts here the user code defined in the for..in loop
end
</syntaxhighlight></div>
* Note that we used var1, var2 and var3 for the example but there is no restriction to the number of variables. You could have one or hundred.

Let's write the "ipairs" function.
<div class="civ5-example"><syntaxhighlight lang="lua">
local function ipairs(table) -- The iterable function
local iterator = function(table, key) -- The iterator function
key = key + 1
return key, table[key]
end
return iterator, table, 0
end
</syntaxhighlight></div>

The same with closures: it's easier.
<div class="civ5-example"><syntaxhighlight lang="lua">
local function ipairs(table) -- The iterable function
local key = 0 -- Both "table" and "key" are closed variables.
local iterator = function() -- The iterator function, a closure: it ignores the arguments provided to it
key = key + 1
return key, table[key]
end
return iterator -- No need to return anything since we do not require any argument.
end
</syntaxhighlight></div>

=== No integer type ===
'''Lua offers no support for integers and only has a 64-bits floating point number type.'''<br/>
Actually, this is only troublesome for a few algorithms that use very large integers (>2^52) or require fast integer arithmetics. But many developers misunderstand floating points and believe the problem is broader than it is. For example, does the following assertion surprise you at least a bit: "any integer smaller than 2^52 can be accurately represented with a 64-bits floating point without any error"? If it did, you suffer from some misconceptions and you should better read carefully what's coming.

Many developers are confusing rounding errors with representation errors.
* '''Rounding errors''' actually only happen if you need a very high number of digits to represent a number. For example if you are adding a very large number with a small number. Rounding errors are very rarely encountered in day to day to applications. Actually most developers work their whole career without ever encountering them.
* '''Representation errors''' are the real problem: 0.1 is expressed in a decimal basis, but it has no finite representation in binary: it requires an infinite number of binary digits. This means that if you write 0.1 in your code it will be translated to a binary number close enough from 0.1 bot not exactly equal to it. So if you sum ten times 0.1, you sill sum ten times something close from 0.1 and the result will not be 1.

'''So the real problem for most developers only lies in the decimal-binary conversion that arises when you manipulate numbers in your code that do not have a finite representation in binary. As long as you do not use such numbers, there will be no problem. And here are the good news: integers do not suffer from any representation problem!''' Indeed, any integer can be represented with a finite number of binary digits. This is why the absence of an integer type typically does not cause problems, minus the performance penalty.

Here are a few examples to illustrate that point.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- This loop works as intended: no representation error and the upper bound is far below 2^52.
local sum = 0
for i = 0, 10000000000, 1 do sum = sum + 1 end
assert(sum == 10000000001)

-- This loop works as intended: 1/16 is a floating-point with an exact representation in binary
local sum = 0
for i = 0, 1, 1/16 do sum = sum + 1 end
assert(sum == 17/16)

-- This loop does NOT work as intended: 0.1 does not have an exact representation in binary.
-- It's the same for Lua, C and almost every programming language.
local sum = 0
for i = 0, 1, 0.1 do sum = sum + 1 end
assert(sum == 1.1) -- throws an error
</syntaxhighlight></div>

=== Errors management ===
Lua offers a error handling mechanism similar to exception handling but unfortunately not very convenient.
* Errors are thrown using the '''error''' function. It takes a string and it immediately aborts Lua execution until the game handles the error and prints it in Firetuner (when enabled).
* Errors are caught before that point using '''pcall''' or '''xpcall''', in order to let you resume execution by managing the error. "pcall" stands for "protected call".

Here are the syntaxes for pcall and xpcall:
* <code>bool, ... pcall(func, ...)</code>
** The function is called with the specified arguments.
** Pcall returns either true followed by the values returned by func, or false followed by the error text.
* <code>bool, ... xpcall(func, errorHandler)</code>:
** The function is called without any argument. If an error occurs the specified errorHandler is invoked with the error text as the only argument.
** Xpcall returns either true followed by the values returned by func, or false followed by the returned values from errorHandler.

Examples to invoke "someFunc" with "someArg" as the only argument. In both examples we want to display the error on the console, or the result if it was a success. A complete errors management example with a reporting mechanism for the end-user is presented in [[Debugging (Civ5)]].
<div class="civ5-example"><syntaxhighlight lang="lua">
-- pcall
local status, result = pcall(someFunc, someArg)
if not status then
print("error was: "..(result or "?"))
else
print("success: "..result)
end

-- xpcall
local status, result = xpcall(
function() someFunc(someArg) end,
function(err) print("error was: "..(result or "?")) end)

if status then
print("success: "..result)
end
</syntaxhighlight></div>

== Advanced topics==
=== Metatables and metamethods ===
* Every value in Lua, from a number to a userdata, has a metatable.
** Many objects can share the same metatable.
** Tables and userdata each have their own metatables by default. Numbers, bools, nils and strings all share the same metatable.
* A metatable may contain a few metamethods and index tables.
** Metamethods are methods stored under special fields names. They implement operators overloads.
** Index tables behave as "base classes": if a field name is not defined on an table, then Lua looks for this field on the index.
** In a way, metatables are analogous to virtual tables in object languages, but they are not just for methods, but also for fields and operators.
* You can get an object's metatable through '''getmetatable''' and assign it with '''setmetatable'''.
* See also the [http://www.lua.org/manual/5.1/manual.html#2.8 official metatables reference]

One example.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Define two tables A and B, and set "meta" their metatable
local a, b, meta = {}, {}, {}
setmetatable(a, meta)
setmetatable(b, meta)

-- Define an __index table on the metatable. It contains one key/value pair.
meta.__index = { "hello world" };

-- Print "hello world" twice
print(a[1])
print(b[1])

-- Now make our tables read-only
meta.__newindex = function(table, key, value) error("this table is read-only!") end
a[1] = "foo" -- throws an error
</syntaxhighlight></div>

Here are the most important fields a metatable can have:
* '''__index''': used when you read a member from an object. On tables, Lua will first search for a regular field on the table itself (not its index) before it looks at the index. The index may be a table or a function: <code>value func(object, key)</code>
* '''__newindex''': used when you assign a value to an object's member. On tables, newindex is only called if the table itself (not its index) does not already contains the specified key. May be a table or a function: <code>func(object, key, value)</code>
* '''__call''': used when you invoke the object as a function. Must be a function: <code>func(object, <args>)</code>
* '''__tostring''': used when you invoke the '''tostring''' function with this object in argument. Must be a function: <code>string func(object)</code>

Besides of that it can have fields for binary operators. When each of the two operands defined overloads, the left one is used. They must be functions: <code>result func(object)</code>
* '''__add''': addition
* '''__sub''': subtraction
* '''__mul''': multiplication
* '''__div''': division
* '''__mod''': module
* '''__pow''': exponentiation
* '''__eq''': equality comparison. Prior to calling this overload, Lua checks that types are equal.
* '''__neq''': inequality comparison. Prior to calling this overload, Lua checks whether types are different.
* '''__lt''': lesser than comparison. (b >= a) is considered equivalent to (a < b)
* '''__le''': lesser than or equal to comparison. (b > a) is considered equivalent to (a <= b). If __le is not defined, lua will use __lt, considering that (a <= b) is equivalent to not (b < a).
* '''__concat''': concatenation

Finally it can have the following fields for unary operators. They must be functions: <code>result func(object)</code>
* '''__unm''': unary minus
* '''__len''': the sharp operator (#). Can only be used on userdata ; on tables the default operator will always be called.

=== Implementing inheritance ===
The most common use of metatables is to mimic the behavior of object languages' types hierarchy. Here is how to do it:
<div class="civ5-example"><syntaxhighlight lang="lua">
local Dog = {}
function Dog:specie()
return "dog"
end
function Dog:race()
return "unknown"
end
function Dog:description()
return self.specie().." - "..self.race()
end
function Dog:new()
local instance = {}
setmetatable(instance, { __index = self})
return instance
end

local Pitbull = dog:new()
function Pitbull:race()
return "pitbull"
end

pitbull = Pitbull:new()
print(pitbull:description()) -- prints "dog - pitbull"
</syntaxhighlight></div>

This implementation is very elegant: the "new" method both creates a new instance and subtypes the creator, since "pitbull"'s index is now "Pitbull". However, should you define an operator overload on Dog's metatable, Pitbull would not inherit it. This is the limit of inheritance in Lua: operator overloads must be defined on the metatable itself, they cannot be defined on the metatable's index. As a result, there is no way to inherit those overloads while subtyping.

=== Coroutines ===
Coroutines provide a way to slice a function in many shorter calls and optionally return intermediate results. On each call, the function execution is resumed to the point where it stopped previously, with all locals being properly restored with the value they had at this time.
* Coroutines are often compared to threads. Indeed, when there are more threads than CPU cores, the operating system slices threads' execution into many little time frames and sequentially runs them in order to achieve multitasking. However while coroutines allows you to implement cooperative multitasking (the coroutines need to explicitly give the hand back), they cannot be used for preemptive multitasking or to use more than one system thread or CPU Core.
* As a result, coroutines are rather used as syntactic sugar (mostly to write iterators), or as a way to split a long function execution across many frames (through Context.{{Func5|Context|SetUpdate}}).

The following methods are mainly used:
* <code>'''coroutine''' coroutine.create('''function''' func)</code> creates a coroutine for the specified function. The function signature can be anything.
* <code>'''bool''', '''...''' coroutine.resume('''coroutine''' co, '''...''')</code> resumes the coroutine with the specified arguments. Then it returns either '''true''' followed by the returned results (either though '''return''' or '''yield'''), or '''false''' followed by an error message.
* <code>coroutine.yield('''...''')</code> suspends the execution of the coroutine and gives the hand back to the caller of coroutine.resume. The arguments will be returned by coroutine.resume.
* <code>'''string''' coroutine.status('''coroutine''' co)</code> returns either "running" (the active coroutine), "normal" (a parent of the active coroutine), "suspended" (not started or waiting to be resumed) or "dead" (finished or threw an error).

Here is a base example:
<div class="civ5-example"><syntaxhighlight lang="lua">
function neighborsCoroutine(plot)
for i = 0, 5 do
coroutine.yield(Map.PlotDirection(plot:GetX(), plot:GetY(), i))
end
end

local co = coroutine.create(neighborsCoroutine)
while coroutine.status(co) == "suspended"
local _, neighbor = co.resume(plot)
-- Do something with plot
end
</syntaxhighlight></div>

Here is how to transform it into an iterator:
<div class="civ5-example"><syntaxhighlight lang="lua">
function neighbors(plot)
local co = coroutine.create(neighbors)
return function()
if coroutine.status(co) ~= "suspended" then return end
return select(2, coroutine.resume(plot))
end
end

for neighbor in neighbors(plot) do
-- Do something with plot
end
</syntaxhighlight></div>

Here is an example that spreads a long function call across many frames:
<div class="civ5-example"><syntaxhighlight lang="lua">
function SpreadAcrossFrames(longFunctionCall, ...)
local co = coroutine.create(longFunctionCall)
ContextPtr.SetUpdate(function()
coroutine.resume(unpack(arg))
if coroutine.status(co) ~= "suspended" then
ContextPtr:ClearUpdate()
end
end)
end

SpreadAcrossFrames(SomeLongFunction, arg1, arg2)
</syntaxhighlight></div>

=== Design philosophy for Lua ===
Do not use a butter knife as you would use a chainsaw (the opposite is even more true and usually ends up badly). When designing your code, remember that:
* Lua is not an object language. While you can use objects and inheritance in some extent, you do not have to and there may be better alternatives sometimes.
* Lua is not a functional language. While you can use lambdas and similar concepts, you do not have to and there may be better alternatives sometimes.
* Lua is a multi-paradigm and dynamic language, take advantage of those.
* Lua is very suited for prototyping and small programs, and this is perfect for mods. Try to adjust your mindset: you're not writing a framework that a whole team will still use and maintain in twenty years.

[[Category:Civ5 API]]
[[Category:Civ5 Tutorials]]

Lua introduction for confirmed developers

2012-09-24T15:21:50Z

DonQuich:

''This page is a part of the [[Lua and UI Reference (Civ5)|Lua and UI Reference]].''

== About Lua ==
===Lua, not LUA===
This is a Portuguese word meaning "moon", not an acronym.

===Presentation===
Lua is an interpreted, dynamically typed, multi-paradigm language. It was designed in 1993 with the following objectives in mind:
* Extensible semantics. A small set of features allows the support of multiple paradigms, from functional programming to object programming. For example, while inheritance is not natively supported, it can be easily set up through metatables. The same features allow events in civ5 to behave both as functions and objects with Add and Remove methods.
* Highly portable. The con is a lightweight and somewhat lacking API.
* Easy to embed and to interface from other languages.
* Well suited for data description (''à la'' JSON).
* A beginners-friendly syntax.

===Performances===
As usual with interpreted and dynamically typed languages (hereby abusively named "scripting languages"), expect a 10 to 100 order of magnitude in performances decrease when compared to compiled and statically typed languages like C, C++ or C#. While it is possible for scripting languages to drastically improve the performances through more or less sophisticated means (expression trees/opcodes caching, JIT compiler, type inference to perform static resolutions), no such solution has been used in Civ5 (aside, probably, of the caching). And while an external JIT library exists, it causes compatibility problems with most mods using Lua.

That being said, Lua is still pretty good for a scripting language, better than the Python implementation from Civ4 for example. And all in all, it is fast enough for most of what modders want to achieve without the need to compromise code elegance, readability and maintainability for performances. So keep in mind that "premature optimization is the root of all evil" (Donald Knuth).

==Syntax cheatsheet==
=== Basics ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Literals
local x = 5
local x = 5.0
local x = nil -- A nil value is the same as an undefined value
local x = true
local x = false

-- Strings (single and double quotes can be used indifferently, there is no difference)
local x = "five"
local x = 'five'
local x = "five\n" -- Escape characters with "\".
local x = [[Five is a number.
Did you know?]] -- Multi-line string: equivalent to "Five is number.\nDid you know?"

-- Globals versus locals
x = 5 -- For globals, assigning is declaring.
local x = 5
</syntaxhighlight></div>

=== Operators ===
<div class="civ5-example"><syntaxhighlight lang="lua">
local x = a or b
local x = a and b

local x = "hello ".."world" .. "!" -- concatenation: two dots
local x = 4..5 -- Result is "45". On concatenation, conversions occur.

local x = (a + b - d) * f ^ g % h -- ^ is exponentiation, % is modulo
local x = "4" + "5" -- Result is 9. On arithmetic operations, conversions occur.

local x = a == b -- equality -- True only if a and b have the same values and types.
local x = a ~= b -- inequality

local x = ((a <= b) == not (a > b)) == ((a >= b) == not (a < b))
local x = "abc" < "def" -- Byte-wise comparison, not Unicode-compliant. Use Locale's methods instead.

local x = #"abc" -- Returns 3, the number of bytes in the string (3 characters, 1 byte each).
local x = #"您好世界" -- Returns 8, the number of bytes in the string (4 characters, 2 bytes each).
local x = #SomeTable -- Returns the biggest integer key in the table, or nil if there is no integer key.

-- No increment operator (++ --), no binary-assign operator (+= *=), no ternary operator (? :), no coalescence operator (??)
</syntaxhighlight></div>

=== Tables and multiple assignments ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Table declaration
SomeTable = {}

SomeArray = { "abc", "def" }
-- 1 => "abc", 2 => "def"

SomeComplexTable = { name = "John", surname = "Doe", age = 25, 43, [7] = 8 }
-- "name" => "John", "surname" => "Doe", "age" => 25, 1 => 43, 7 => 8.

-- Member access (all equivalent)
SomeTable.SomeMember = 5
SomeTable["SomeMember"] = 5

-- Multiple assignment
-- Both statements are equivalent since SomeArray contains "abc" and "def".
local x, y = "abc", "def"
local x, y = unpack(SomeArray)
</syntaxhighlight></div>

=== Functions ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Functions declarations (all equivalent)
function HelloWorld(a, b) print("Hello world") end
HelloWorld = function(a, b) print("Hello world") end
-- Functions are first-class objects and can be assigned like any other value!

-- Methods declarations (all equivalent)
SomeTable.HelloWorld(a, b) print("Hello world") end
SomeTable.HelloWorld = function(a, b) print("Hello world") end

-- Instanced methods declarations (all equivalent)
SomeTable.HelloWorldInstanced(self, a, b) print(self.SomeMember) end
SomeTable:HelloWorldInstanced(a, b) print(self.SomeMember) end

-- Functions and methods calls
HelloWorld(a) -- b will be nil in the function
HelloWorld(a, b)
SomeTable.HelloWorld(a, b)

-- Instanced methods calls (all equivalent)
SomeTable:HelloWorldInstanced(a, b)
SomeTable.HelloWorldInstanced(SomeTable, a, b)

-- Multiple return values
function func(a, b) return a, b end
local x, y, z = func(5, 6) -- Assigns 5 to x and 6 to y, z will be nil

-- Variable arguments
function SomeFunc(a, b, ...)
print(a)
print(b)
for i, v in ipairs(arg) do -- arg is a keyword for a table containing the variable arguments
print(v)
end
end
SomeFunc(1, 2, 3, 4, 5) -- prints 1, 2, 3, 4, 5
SomeFunc(1, 2) -- prints 1, 2
</syntaxhighlight></div>

=== Control flow ===
<div class="civ5-example"><syntaxhighlight lang="lua">
-- If
if name == "Wu Zetian" then
print("Hello China")
elseif name == "Napoleon" then -- "elseif", not "else if". Beware C developers!
print("Hello France")
else -- no "then" after "else"!
print("Hello unknown")
end

-- For loop (with counter)
for i = 1, 8 do print(i) end -- Prints 1, 2, 3, 4, 5, 6, 7, 8
for i = 1, 8, 2 do print(i) end -- Prints 1, 3, 5, 7

-- For loop (with iterator)
for playerID, pPlayer in pairs(Players) do -- Prints 1 Wu Zetian, 2 Napoleon, ...
print(playerID, pPlayer:GetName())
end
for plot in Plots() do -- Prints 0 0, 0 1, 0 2, ...
print(plot:GetX(), plot:GetY())
end

-- While (i will be 5 in the end)
while i < 5 do
i = i + 1
end

-- Repeat until (i will be 5 in the end)
repeat
i = i + 1
until i == 5

-- Infinite loops
-- Lua supports "break" for all loops but not "continue" instruction does not exist!
do
i = i + 1
if i > 5 then break end
end

</syntaxhighlight></div>

== Basics ==
=== Type system ===
You can get a variable's type by using the '''type''' function. It takes any value and returns a string. Here are the possible results:
* '''nil''': Lua makes do distinction between an undefined variable and a variable with a nil value. Assigning nil to a variable or table member is equivalent to undefining it.
* '''number''': a 64 bits floating-point number. Lua has no support for integers and only use floating-points. See also [[#No integer type]].
* '''string''': your usual string of characters. In Lua all strings are interned. This speeds up comparisons but it makes allocation of new strings slower.
* '''boolean''': true or false obviously.
* '''table''': any table.
* '''userdata''': objects defined in C for use in Lua. They may not be enumerated through pairs and other limitations. Now the Civ5 API tend to return regular tables whose metatable is of type userdata, this allows us to use the provided objects as regular Lua tables.
* '''function''': remember that functions are first-class objects in Lua.
* '''thread''': coroutines actually. Lua does not support threads.

=== Implicit conversions ===
* Whenever you concatenate two values (and possibly when you invoke a standard function that takes a string), an automatic conversion to string occurs, as if you had used the '''tostring''' function. The expression <code>4..5</code> returns "45".
* Whenever you perform an arithmetic operation, the operands are both converted to numbers, as if you had used the '''tonumber''' function. The expression <code>"4" + "5"</code> returns 9.

=== Strict equality comparisons ===
'''Two values are equal only if their types are the same.'''<br/>
This is stricter than C and far stricter than PHP for example.
* 4 is not equal to "4". (number type and string type). In PHP they would be equal.
* 0 is not equal to false (number type and bool type). In C they would be equal.
* 0 is not equal to nil. (number type and nil type). In C they would be equal.

Regarding tables and C-made objects, they are compared by reference.
<div class="civ5-example"><syntaxhighlight lang="lua">
a = { 5 }
b = { 5 }
c = a
assert(a == c) -- OK
assert(a == b) -- ERROR
</syntaxhighlight></div>

=== Boolean logic ===
'''Anything that is neither false nor nil is evaluated to true.'''<br/>
This is pretty simple. Especially, an empty string or the zero number are evaluated to true.
<div class="civ5-example"><syntaxhighlight lang="lua">
if 0 then print("hello world") end -- prints hello world
</syntaxhighlight></div>

Now regarding the and/or operators, two rules to remember:
* '''The right operand is only evaluated when needed.'''
** <code>false and x()</code> does not call x() since the result will be false anyway.
** <code>true or x()</code> does not call x() since the result will be true anyway.
* '''The result is the last operand to have been evaluated.'''
** <code>x() and y()</code> returns x() if it was false, y() otherwise.
** <code>x() or y()</code> returns x() if it was true, y() otherwise.

=== Ternary and coalescence statements ===
We can exploit the and/or operators behavior:
* '''Coalescence:''' <code>x or y</code>. It returns x if x is neither nil nor false, y otherwise.
:In other words <code>result = x or y</code> is equivalent to: <code>if x then result = x else result = y end</code>.
* '''Ternary:''' <code>condition and x or y</code> (as long as x is not nil or false). It returns x if condition was true, y if it was false.
:Indeed the expression becomes: <code>(condition and x) or y</code>. If condition is true the '''and''' operator returns x, and since x is true, y is not evaluated and '''or''' returns x.
:In other words <code>result = condition and x or y</code> is equivalent to: <code>if condition then result = x else result = y end</code>.

=== Arrays versus tables ===
'''In Lua, an array is a table whose keys are integers.'''

Since this is a common programming pattern, a number of things are designed for arrays:
* <code>{"abc", "def", "ghi"}</code> starts at index 1, up to index 3. Arrays typically start at 1.
* <code>table.insert({}, "abc")</code> will transform the provided empty table to <code>{"abc"}</code>
* <code>table.insert({"abc", "def"}, "ghi")</code> will transform the provided table to <code>{"abc", "def", "ghi"}</code>
* <code>table.insert({"abc", "ghi"}, 2, "def")</code> will transform the provided table to <code>{"abc", "def", "ghi"}</code>
* <code>table.remove({"abc", "def", "ghi"}, 2)</code> will transform the provided table to <code>{"abc", ""ghi"}</code>
* <code>#{"abc", "def", "ghi"}</code> returns 3, the biggest integer key.

=== Ipairs versus pairs ===
You could say that '''pairs''' is for table and '''ipairs''' for arrays.
* '''Pairs''' enumerate all the key/value pairs in an unordered matter.
* '''Ipairs''' only enumerates the key/value pairs for consecutive integer keys, in an ascending order, starting from 1 up to the largest key. If at some point a key is missing, the enumeration stops.
::It does not matter whether the table was crated with table.insert or directly by inserting the values through, for example <code>table[i] = value</code>.

<div class="civ5-example"><syntaxhighlight lang="lua">
-- Produces: { 1 => "one", 2 => "two", 4 => "four", "name" => "John", "age" => 25 }
local t = { "one", "two", name = "John", age = 25, [4] = "four" }

-- Will print (for example, the order is undetermined): "name", 2, 4, "age", 1
for k in pairs(t) do print(k) end

-- Will print 1, 2
for k in ipairs(t) do print(k) end

-- Both ipairs and pairs return a key and a value, so you could also use:
for k, v in pairs(t) do print(k, v) end
</syntaxhighlight></div>

=== Semicolons and line breaks ===
'''Statements need to be separated either by a line break or a semicolon.'''
* You can use both a semicolon and a line break but then the semicolon is redundant and not required, although it does not cause any problem.
* Line breaks can also be freely added about everywhere and behave as whitespaces most of the time (you can add them after most keywords for example, so you can keep if...then...end structures on one line or split them across multiple lines).

=== Locals, globals and includes ===
* For a documentation on the '''include''' statement, see [[Specificities of the Lua implementation in Civ5#Include]].
* The include statement allows you to include a lua file into another one (see [[Specificities of the Lua implementation in Civ5]]). When you do so, the globals defined in the included file are imported in the parent file. However the local variables are only visible from within the file that declared them.
* Another specificities of locals: they're only visible after the point they have been declared in the file, while globals are always visible. An example is worth thousand of words.
<div class="civ5-example"><syntaxhighlight lang="lua">
function Func1()
print(someLocal or "nil")
print(someGlobal or "nil")
end

local someLocal = "foo"
function Func2()
print(someLocal or "nil")
print(someGlobal or "nil")
end

someGlobal = "global"
someLocal = "local"
Func1() -- prints "nil", then "global": someLocal is assigned but not visible from Func1
Func2() -- prints "local", then "global": someLocal is assigned and visible from Func2
</syntaxhighlight></div>
* Performances-wise, Lua first searches a variable name in the current scope, then in the parent scope, etcetera until it reaches the highest scope, and finally it searches the global scope. So the deeper a local is declared, the faster it is accessed. On the contrary, globals are the slowest to retrieve.

== Semi-advanced topics ==
=== Closures ===
'''Closures are functions that embed variables that are persisted across calls.'''<br/>
This is typically achieved through a "parent" function that declares a local "closed" variable and returns another child "closure" function using this local. The "closed" variable is then unreachable for anyone but the "closure". And since it the "closed" variable is not in the "closure"'s scope, it is not reinitialized on every call of "closure".
<div class="civ5-example"><syntaxhighlight lang="lua">
function GiveMeAFunc() -- the parent function
local x = 0 -- the closed variable
return function() -- the closure function embedding "closed"
x = x + 1
return closure
end
end

local func = GiveMeAFunc()
print(func()) -- Prints 1
print(func()) -- Prints 2
print(func()) -- Prints 3
</syntaxhighlight></div>

=== Iterators ===
'''Iterators are functions for use in <code>for...in</code> loops.'''<br/>
Let's consider the following code: <code>for var1, var2, var3 in iterable() do</code>.
* iterable has the following signature: <code>iterator, state, var1 iterable()</code>. It returns a function, a state, and the initial value of var1.
* iterator has the following signature: <code>var1, var2, var3 iterator(state, var1)</code>. It takes the state and the last value of var1 and returns var1, var2 and var3.
* The loop stops when var1 is nil.
* The for...in loop is equivalent to:
<div class="civ5-example"><syntaxhighlight lang="lua">
local iterator, state, var1, var2, var3
iterator, state, var1 = iterable()
do
var1, var2, var3 = iterator(state, var1)
if var1 == nil then break end

-- Inserts here the user code defined in the for..in loop
end
</syntaxhighlight></div>
* Note that we used var1, var2 and var3 for the example but there is no restriction to the number of variables. You could have one or hundred.

Let's write the "ipairs" function.
<div class="civ5-example"><syntaxhighlight lang="lua">
local function ipairs(table) -- The iterable function
local iterator = function(table, key) -- The iterator function
key = key + 1
return key, table[key]
end
return iterator, table, 0
end
</syntaxhighlight></div>

The same with closures: it's easier.
<div class="civ5-example"><syntaxhighlight lang="lua">
local function ipairs(table) -- The iterable function
local key = 0 -- Both "table" and "key" are closed variables.
local iterator = function() -- The iterator function, a closure: it ignores the arguments provided to it
key = key + 1
return key, table[key]
end
return iterator -- No need to return anything since we do not require any argument.
end
</syntaxhighlight></div>

=== No integer type ===
'''Lua offers no support for integers and only has a 64-bits floating point number type.'''<br/>
Actually, this is only troublesome for a few algorithms that use very large integers (>2^52) or require fast integer arithmetics. But many developers misunderstand floating points and believe the problem is broader than it is. For example, does the following assertion surprise you at least a bit: "any integer smaller than 2^52 can be accurately represented with a 64-bits floating point without any error"? If it did, you suffer from some misconceptions and you should better read carefully what's coming.

Many developers are confusing rounding errors with representation errors.
* '''Rounding errors''' actually only happen if you need a very high number of digits to represent a number. For example if you are adding a very large number with a small number. Rounding errors are very rarely encountered in day to day to applications. Actually most developers work their whole career without ever encountering them.
* '''Representation errors''' are the real problem: 0.1 is expressed in a decimal basis, but it has no finite representation in binary: it requires an infinite number of binary digits. This means that if you write 0.1 in your code it will be translated to a binary number close enough from 0.1 bot not exactly equal to it. So if you sum ten times 0.1, you sill sum ten times something close from 0.1 and the result will not be 1.

'''So the real problem for most developers only lies in the decimal-binary conversion that arises when you manipulate numbers in your code that do not have a finite representation in binary. As long as you do not use such numbers, there will be no problem. And here are the good news: integers do not suffer from any representation problem!''' Indeed, any integer can be represented with a finite number of binary digits. This is why the absence of an integer type typically does not cause problems, minus the performance penalty.

Here are a few examples to illustrate that point.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- This loop works as intended: no representation error and the upper bound is far below 2^52.
local sum = 0
for i = 0, 10000000000, 1 do sum = sum + 1 end
assert(sum == 10000000001)

-- This loop works as intended: 1/16 is a floating-point with an exact representation in binary
local sum = 0
for i = 0, 1, 1/16 do sum = sum + 1 end
assert(sum == 17/16)

-- This loop does NOT work as intended: 0.1 does not have an exact representation in binary.
-- It's the same for Lua, C and almost every programming language.
local sum = 0
for i = 0, 1, 0.1 do sum = sum + 1 end
assert(sum == 1.1) -- throws an error
</syntaxhighlight></div>

=== Errors management ===
Lua offers a error handling mechanism similar to exception handling but unfortunately not very convenient.
* Errors are thrown using the '''error''' function. It takes a string and it immediately aborts Lua execution until the game handles the error and prints it in Firetuner (when enabled).
* Errors are caught before that point using '''pcall''' or '''xpcall''', in order to let you resume execution by managing the error. "pcall" stands for "protected call".

Here are the syntaxes for pcall and xpcall:
* <code>bool, ... pcall(func, ...)</code>
** The function is called with the specified arguments.
** Pcall returns either true followed by the values returned by func, or false followed by the error text.
* <code>bool, ... xpcall(func, errorHandler)</code>:
** The function is called without any argument. If an error occurs the specified errorHandler is invoked with the error text as the only argument.
** Xpcall returns either true followed by the values returned by func, or false followed by the returned values from errorHandler.

Examples to invoke "someFunc" with "someArg" as the only argument. In both examples we want to display the error on the console, or the result if it was a success. A complete errors management example with a reporting mechanism for the end-user is presented in [[Debugging (Civ5)]].
<div class="civ5-example"><syntaxhighlight lang="lua">
-- pcall
local status, result = pcall(someFunc, someArg)
if not status then
print("error was: "..(result or "?"))
else
print("success: "..result)
end

-- xpcall
local status, result = xpcall(
function() someFunc(someArg) end,
function(err) print("error was: "..(result or "?")) end)

if status then
print("success: "..result)
end
</syntaxhighlight></div>

== Advanced topics==
=== Metatables and metamethods ===
* Every value in Lua, from a number to a userdata, has a metatable.
** Many objects can share the same metatable.
** Tables and userdata each have their own metatables by default. Numbers, bools, nils and strings all share the same metatable.
* A metatable may contain a few metamethods and index tables.
** Metamethods are methods stored under special fields names. They implement operators overloads.
** Index tables behave as "base classes": if a field name is not defined on an table, then Lua looks for this field on the index.
** In a way, metatables are analogous to virtual tables in object languages, but they are not just for methods, but also for fields and operators.
* You can get an object's metatable through '''getmetatable''' and assign it with '''setmetatable'''.
* See also the [http://www.lua.org/manual/5.1/manual.html#2.8 official metatables reference]

One example.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Define two tables A and B, and set "meta" their metatable
local a, b, meta = {}, {}, {}
setmetatable(a, meta)
setmetatable(b, meta)

-- Define an __index table on the metatable. It contains one key/value pair.
meta.__index = { "hello world" };

-- Print "hello world" twice
print(a[1])
print(b[1])

-- Now make our tables read-only
meta.__newindex = function(table, key, value) error("this table is read-only!") end
a[1] = "foo" -- throws an error
</syntaxhighlight></div>

Here are the most important fields a metatable can have:
* '''__index''': used when you read a member from an object. On tables, Lua will first search for a regular field on the table itself (not its index) before it looks at the index. The index may be a table or a function: <code>value func(object, key)</code>
* '''__newindex''': used when you assign a value to an object's member. On tables, newindex is only called if the table itself (not its index) does not already contains the specified key. May be a table or a function: <code>func(object, key, value)</code>
* '''__call''': used when you invoke the object as a function. Must be a function: <code>func(object, <args>)</code>
* '''__tostring''': used when you invoke the '''tostring''' function with this object in argument. Must be a function: <code>string func(object)</code>

Besides of that it can have fields for binary operators. When each of the two operands defined overloads, the left one is used. They must be functions: <code>result func(object)</code>
* '''__add''': addition
* '''__sub''': subtraction
* '''__mul''': multiplication
* '''__div''': division
* '''__mod''': module
* '''__pow''': exponentiation
* '''__eq''': equality comparison. Prior to calling this overload, Lua checks that types are equal.
* '''__neq''': inequality comparison. Prior to calling this overload, Lua checks whether types are different.
* '''__lt''': lesser than comparison. (b >= a) is considered equivalent to (a < b)
* '''__le''': lesser than or equal to comparison. (b > a) is considered equivalent to (a <= b). If __le is not defined, lua will use __lt, considering that (a <= b) is equivalent to not (b < a).
* '''__concat''': concatenation

Finally it can have the following fields for unary operators. They must be functions: <code>result func(object)</code>
* '''__unm''': unary minus
* '''__len''': the sharp operator (#). Can only be used on userdata ; on tables the default operator will always be called.

=== Implementing inheritance ===
The most common use of metatables is to mimic the behavior of object languages' types hierarchy. Here is how to do it:
<div class="civ5-example"><syntaxhighlight lang="lua">
local Dog = {}
function Dog:specie()
return "dog"
end
function Dog:race()
return "unknown"
end
function Dog:description()
return self.specie().." - "..self.race()
end
function Dog:new()
local instance = {}
setmetatable(instance, { __index = self})
return instance
end

local Pitbull = dog:new()
function Pitbull:race()
return "pitbull"
end

pitbull = Pitbull:new()
print(pitbull:description()) -- prints "dog - pitbull"
</syntaxhighlight></div>

This implementation is very elegant: the "new" method both creates a new instance and subtypes the creator, since "pitbull"'s index is now "Pitbull". However, should you define an operator overload on Dog's metatable, Pitbull would not inherit it. This is the limit of inheritance in Lua: operator overloads must be defined on the metatable itself, they cannot be defined on the metatable's index. As a result, there is no way to inherit those overloads while subtyping.

=== Coroutines ===
Coroutines provide a way to slice a function in many shorter calls and optionally return intermediate results. On each call, the function execution is resumed to the point where it stopped previously, with all locals being properly restored with the value they had at this time.
* Coroutines are often compared to threads. Indeed, when there are more threads than CPU cores, the operating system slices threads' execution into many little time frames and sequentially runs them in order to achieve multitasking. However while coroutines allows you to implement cooperative multitasking (the coroutines need to explicitly give the hand back), they cannot be used for preemptive multitasking or to use more than one system thread or CPU Core.
* As a result, coroutines are rather used as syntactic sugar (mostly to write iterators), or as a way to split a long function execution across many frames (through Context.{{Func5|Context|SetUpdate}}).

The following methods are mainly used:
* <code>'''coroutine''' coroutine.create('''function''' func)</code> creates a coroutine for the specified function. The function signature can be anything.
* <code>'''bool''', '''...''' coroutine.resume('''coroutine''' co, '''...''')</code> resumes the coroutine with the specified arguments. Then it returns either '''true''' followed by the returned results (either though '''return''' or '''yield'''), or '''false''' followed by an error message.
* <code>coroutine.yield('''...''')</code> suspends the execution of the coroutine and gives the hand back to the caller of coroutine.resume. The arguments will be returned by coroutine.resume.
* <code>'''string''' coroutine.status('''coroutine''' co)</code> returns either "running" (the active coroutine), "normal" (a parent of the active coroutine), "suspended" (not started or waiting to be resumed) or "dead" (finished or threw an error).

Here is a base example:
<div class="civ5-example"><syntaxhighlight lang="lua">
function neighborsCoroutine(plot)
for i = 0, 5 do
coroutine.yield(Map.PlotDirection(plot:GetX(), plot:GetY(), i))
end
end

local co = coroutine.create(neighborsCoroutine)
while coroutine.status(co) == "suspended"
local _, neighbor = co.resume(plot)
-- Do something with plot
end
</syntaxhighlight></div>

Here is how to transform it into an iterator:
<div class="civ5-example"><syntaxhighlight lang="lua">
function neighbors(plot)
local co = coroutine.create(neighbors)
return function()
if coroutine.status(co) ~= "suspended" then return end
return select(2, coroutine.resume(plot))
end
end

for neighbor in neighbors(plot) do
-- Do something with plot
end
</syntaxhighlight></div>

Here is an example that spreads a long function call across many frames:
<div class="civ5-example"><syntaxhighlight lang="lua">
function SpreadAcrossFrames(longFunctionCall, ...)
local co = coroutine.create(longFunctionCall)
ContextPtr.SetUpdate(function()
coroutine.resume(unpack(arg))
if coroutine.status(co) ~= "suspended" then
ContextPtr:ClearUpdate()
return
end
end)
end

SpreadAcrossFrames(SomeLongFunction, arg1, arg2)
</syntaxhighlight></div>

=== Design philosophy for Lua ===
Do not use a butter knife as you would use a chainsaw (the opposite is even more true and usually ends up badly). When designing your code, remember that:
* Lua is not an object language. While you can use objects and inheritance in some extent, you do not have to and there may be better alternatives sometimes.
* Lua is not a functional language. While you can use lambdas and similar concepts, you do not have to and there may be better alternatives sometimes.
* Lua is a multi-paradigm and dynamic language, take advantage of those.
* Lua is very suited for prototyping and small programs, and this is perfect for mods. Try to adjust your mindset: you're not writing a framework that a whole team will still use and maintain in twenty years.

[[Category:Civ5 API]]
[[Category:Civ5 Tutorials]]

Debugging (Civ5)

2012-09-24T14:02:52Z

DonQuich:

''This page is a part of the [[Civ5 Modding Tutorials]].''

== Checklist ==
* Did you correctly import to the [[VFS (Civ5)|VFS]] the files that need to be?
* Did you correctly set up the actions and content tab in your project?
* Did you restart civ5 after you added new files?

== XML Debugging ==
[[File:SQLiteManager.png|frame|View of the snapshot using SQLiteManager]]
=== Checking the logs ===
If you correctly set up your [[#Configuration]], whenever you start a game, Civ5 saves some logs under <code>My Games/Sid Medier's Civilization V/cache/Civ5DebugDatabase.db</code>.
* If there were errors with the XML formatting of your data files (wrong column names for example), they will logged in XML.log. Some of those errors may be fatal: in such a case no mod is loaded!
:<pre>[6904.323] Tag (TXT_KEYMODDING_SHOWDLCMODS) does not start with 'TXT_KEY_'</pre>
* If there were errors with the data integrity (missing foreign keys for example - types that reference rows from other tables), they will logged in database.log.
:<pre>[6903.917] Invalid Reference on Leader_Flavors.LeaderType - "LEADER_HARALD" does not exist in Leaders</pre>

=== Using the snapshots ===
If you correctly set up your [[#Configuration]], whenever you start a game, Civ5 saves a snapshot of the database under <code>My Games/Sid Medier's Civilization V/cache/Civ5DebugDatabase.db</code>
* This allows you to check how your XML and SQL files have been merged with the standard game data.

== Lua Debugging ==
=== Using the Firetuner console ===
If you correctly set up your [[#Configuration]], Civ5 will send all the Lua output to the Firetuner. This includes all the debugging output but also any error that may arise, with their calls stack traces.
<pre>
Runtime Error: [string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:41: attempt to concatenate local 'name' (a nil value)
stack traceback:
[string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:41: in function 'dumpObj'
[string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:95: in function 'ScanAll'
[string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:188: in main chunk
[C]: ?
</pre>
Here we can see that a C/C++ code (the game engine) ran the main chunk called (the Lua file), which then called the function ''ScanAll'' on line 188, which then called ''dumpObj'' on line 95. And this one caused an error on line 41.

Note that paths are truncated in the provided example, which makes debugging harder sometimes. This happens when the file is in a {{Type5|context}} registered by the project's ''content'' tab. Here are the workarounds:
* Register only a minimalist context, that will load additional contexts (through the UI LuaContext markup). Do not initiate any action from the root context, let the children context handle everything.
* Provide a custom stack trace, as explained in a further section.

=== Print, assert and error ===
<code>print('''...''')</code> can be used to print anything to the Firetuner output. This allows you to check the flow of a program, or the values of variables. Print calls '''tostring''' on every argument and displays them all on a single line with tabulations as separators between them. Nil values are not displayed, so it is advised you provide expressions such as: <code>(expr or 'nil')</code>

<code>error('''string''' message, '''int''' level = 1)</code> throws an error with the specified message. The execution is then halted and the hand returned to the game engine (or the current protected call if you did use '''pcall''' or '''xpcall'''). The level parameter controls the error position that will be reported. 1 for the line where error is located, 2 for the function call that contained an error, etc. 0 for no position.

<code>assert('''variant''' condition, '''string''' message = "assertion failed")</code> can be used to assert the provided condition is neither nil nor false (everything else is evaluated to true in Lua). Otherwise, an error with the specified message is thrown. You can use them punctually, as a debugging technique. But they may also be used as a defensive programming technique similar to [http://en.wikipedia.org/wiki/Design_by_contract design-by-contract]: the idea is that whenever your program's correctness relies on an assumption, you should explicitly check it. For example, if a function takes an array as an argument and assumes that it is not empty, you should add two conditions at the beginning: <code>assert(type(t) == "table")</code> and <code>assert(#t > 0)</code>. This makes the code more self-explanatory (implicit assumptions are now explicitly stated) and it allows you to catch bugs as soon as possible, which typically makes them easier to understand and fix.

=== Handling errors for the end user ===
Most of the time, when one of your user encounters an error with your mod, he just stops using it. A fraction of them will do the effort of reporting bugs but too often the informations they provide is unusable (from "it doesn't work" to wrong reproduction steps "play until turn 173 and wait for Mars being aligned with Venus"). The best way to increase the number of reports and their usefulness is to let your mod tell them the info it needs, as illustrated below.

[[File:IGE-Error.png|none|frame|[http://forums.civfanatics.com/showthread.php?t=436912 In-game editor] tells its users what they must report, even including a calls stack trace when available. The user only needs to make a screenshot that will then land on his Steam profile (provided he didn't change the Steam settings). Reporting made easy!]]

The [[Lua introduction for confirmed developers]] describes a number of techniques you can use to achieve similar results. Here we present an implementation you can use to handle errors in the most dangerous parts of your code in order to present them to the user with a full stack trace when available.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Returns an array of strings, one for each call level.
-- We could use debug.traceback instead but this ones truncates path and we cannot easily ignore the topmost levels.
function getStackTrace()
-- Level 1 is getStackTrace, 2 is its caller
local level = 2
local trace = {}
while true do
-- Gets that level's informations: function name, source file and line.
local info = debug.getinfo(level, "nSl")
if not info then break end

-- C code or Lua code?
if info.what == "C" then
table.insert(trace, "C function");
else
local userStr = Path.GetFileName(info.source)..": "..info.currentline;
if info.name and string.len(info.name) then
userStr = userStr.." ("..info.name..")";
end
table.insert(trace, userStr);
end
level = level + 1
end
return trace;
end

-- Gets a nicely formatted string of the error.
-- The second parameter is the number of levels to ignore in the calls stack (formatError excluded). Defaults to 0.
function formatError(err, levelsToIgnoreBelow)
print(err);

-- We do not want to include formatError in the stack trace, hence the +1
levelsToIgnoreBelow = (levelsToIgnoreBelow or 0) + 1;

-- 'err' is like: [string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:41: attempt to concatenate local 'name' (a nil value)
-- We retrieve important positions in this string. Remember: not all paths are truncated.
local elipsisIndex = string.find(err, "...", 1, true) or -5;
local lineIndex = elipsisIndex + 6
local msgIndex = string.find(err, ":", lineIndex, true) + 1

-- Can we append the stack trace?
local result = ""
if debug and debug.getinfo then
result = string.sub(err, msgIndex)

local trace = getStackTrace()
for i, v in ipairs(trace) do
print(v)
if (i > levelsToIgnoreBelow) then
result = result.."[NEWLINE]"..v;
end
end
-- Otherwise just report the line and message, and the source file when not truncated.
else
result = "line "..string.sub(err, elipsisIndex)
end

return result
end

-- The error handler to provide to xpcall
local function errorHandler(err)
-- The stack trace at this point is:
-- 1: this error handler (must not be reported),
-- 2: C function calling the handler (kept for security)
-- 3: the error source
err = formatError(err, 1);

-- Show a popup to the user
local str = L("Oops, an error occured:").."[NEWLINE][ICON_PIRATE] "..err;
Events.SerialEventGameMessagePopup( { Type = ButtonPopupTypes.BUTTONPOPUP_TEXT, Data1 = 800, Option1 = true, Text = str } );

-- Restore things up here when needed. Beware to not cause any error as it would cause an infinite recursive call up to the stack overflow!
return false
end

-- Calls someDangerousFunction with the given error handler
xpcall(someDangerousFunction, errorHandler)
</syntaxhighlight></div>

== Troubleshooting ==
The [[Civ5 Useful Programs]] page presents you a number of tools you can use to inspect or modify the game. This is especially useful if you want to quickly reproduce a bug or test something, or to understand what is happening.
* Let's say your mod adds a tech but you do not see in the techs panel. There is a FireTuner panel you can use to see a flat list of all the techs in-game.
* Let's say your mod adds a unit or a wonder, the IGE mod allows you to quickly create an unit or build that wonder (including the splash screen).
* Let's say your mod modifies the yields when the player acquire a specific tech. Once again IGE allows you to grant you that tech and see how the yields are modified.

== Configuration ==
Look for the following files under <code>My Documents/My Games/Sid Meiers' Civilization V</code> and open them in a text editor like the notepad (not in a word processor).
* '''config.ini'''
** Set <code>LoggingEnabled</code> to 1. Civ5 will write log files under the <code>Logs</code> folder.
** Set <code>EnableLuaDebugLibrary</code> to 1. Civ5 will display stack traces on Lua errors and you will be able to use the [http://www.lua.org/manual/5.1/manual.html#pdf-debug.debug debug] object.
** Set <code>DebugPanel</code> to 1. By pressing the '''²''' key (may be '''ù''' or something else depending on your computer's language) during a game, Civ5 will display a debug panel.
* '''usersettings.ini'''
** Set <code>DebugMode</code> to 1. Needed to enable other features previously mentioned.

[[Category:Civ5 Tutorials]]

Debugging (Civ5)

2012-09-24T14:00:38Z

DonQuich:

''This page is a part of the [[Civ5 Modding Tutorials]].''

== Checklist ==
* Did you correctly import to the [[VFS (Civ5)|VFS]] the files that need to be?
* Did you correctly set up the actions and content tab in your project?
* Did you restart civ5 after you added new files?

== XML Debugging ==
[[File:SQLiteManager.png|frame|View of the snapshot using SQLiteManager]]
=== Checking the logs ===
If you correctly set up your [[#Configuration]], whenever you start a game, Civ5 saves some logs under <code>My Games/Sid Medier's Civilization V/cache/Civ5DebugDatabase.db</code>.
* If there were errors with the XML formatting of your data files (wrong column names for example), they will logged in XML.log. Some of those errors may be fatal: in such a case no mod is loaded!
:<pre>[6904.323] Tag (TXT_KEYMODDING_SHOWDLCMODS) does not start with 'TXT_KEY_'</pre>
* If there were errors with the data integrity (missing foreign keys for example - types that reference rows from other tables), they will logged in database.log.
:<pre>[6903.917] Invalid Reference on Leader_Flavors.LeaderType - "LEADER_HARALD" does not exist in Leaders</pre>

=== Using the snapshots ===
If you correctly set up your [[#Configuration]], whenever you start a game, Civ5 saves a snapshot of the database under <code>My Games/Sid Medier's Civilization V/cache/Civ5DebugDatabase.db</code>
* This allows you to check how your XML and SQL files have been merged with the standard game data.

== Lua Debugging ==
=== Using the Firetuner console ===
If you correctly set up your [[#Configuration]], Civ5 will send all the Lua output to the Firetuner. This includes all the debugging output but also any error that may arise, with their calls stack traces.
<pre>
Runtime Error: [string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:41: attempt to concatenate local 'name' (a nil value)
stack traceback:
[string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:41: in function 'dumpObj'
[string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:95: in function 'ScanAll'
[string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:188: in main chunk
[C]: ?
</pre>
Here we can see that a C/C++ code (the game engine) ran the main chunk called (the Lua file), which then called the function ''ScanAll'' on line 188, which then called ''dumpObj'' on line 95. And this one caused an error on line 41.

Note that paths are truncated in the provided example, which makes debugging harder sometimes. This happens when the file is in a {{Type5|context}} registered by the project's ''content'' tab. Here are the workarounds:
* Register only a minimalist context, that will load additional contexts (through the UI LuaContext markup). Do not initiate any action from the root context, let the children context handle everything.
* Provide a custom stack trace, as explained in a further section.

=== Print, assert and error ===
<code>print('''...''')</code> can be used to print anything to the Firetuner output. This allows you to check the flow of a program, or the values of variables. Print calls '''tostring''' on every argument and displays them all on a single line with tabulations as separators between them. Nil values are not displayed, so it is advised you provide expressions such as: <code>(expr or 'nil')</code>

<code>error('''string''' message, '''int''' level = 1)</code> throws an error with the specified message. The execution is then halted and the hand returned to the game engine (or the current protected call if you did use '''pcall''' or '''xpcall'''). The level parameter controls the error position that will be reported. 1 for the line where error is located, 2 for the function call that contained an error, etc. 0 for no position.

<code>assert('''variant''' condition, '''string''' message = "assertion failed")</code> can be used to assert the provided condition is neither nil nor false (everything else is evaluated to true in Lua). Otherwise, an error with the specified message is thrown. You can use them punctually, as a debugging technique. But they may also be used as a defensive programming technique similar to [http://en.wikipedia.org/wiki/Design_by_contract design-by-contract]: the idea is that whenever your program's correctness relies on an assumption, you should explicitly check it. For example, if a function takes an array as an argument and assumes that it is not empty, you should add two conditions at the beginning: <code>assert(type(t) == "table")</code> and <code>assert(#t > 0)</code>. This makes the code more self-explanatory (implicit assumptions are now explicitly stated) and it allows you to catch bugs as soon as possible, which typically makes them easier to understand and fix.

=== Handling errors for the end user ===
Most of the time, when one of your user encounters an error with your mod, he just stops using it. A fraction of them will do the effort of reporting bugs but too often the informations they provide is unusable (from "it doesn't work" to wrong reproduction steps "play until turn 173 and wait for Mars being aligned with Venus"). The best way to increase the number of reports and their usefulness is to let your mod tell them the info it needs, as illustrated below.

[[File:IGE-Error.png|none|frame|[http://forums.civfanatics.com/showthread.php?t=436912 In-game editor] tells its users what they must report, even including a calls stack trace when available. The user only needs to make a screenshot that will then land on his Steam profile (provided he didn't change the Steam settings). Reporting made easy!]]

The [[Lua introduction for confirmed developers]] describes a number of techniques you can use to achieve similar results. Here we present an implementation you can use to handle errors in the most dangerous parts of your code in order to present them to the user with a full stack trace when available.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Returns an array of strings, one for each call level.
function getStackTrace()
-- Level 1 is getStackTrace, 2 is its caller
local level = 2
local trace = {}
while true do
-- Gets that level's informations: function name, source file and line.
local info = debug.getinfo(level, "nSl")
if not info then break end

-- C code or Lua code?
if info.what == "C" then
table.insert(trace, "C function");
else
local userStr = Path.GetFileName(info.source)..": "..info.currentline;
if info.name and string.len(info.name) then
userStr = userStr.." ("..info.name..")";
end
table.insert(trace, userStr);
end
level = level + 1
end
return trace;
end

-- Gets a nicely formatted string of the error.
-- The second parameter is the number of levels to ignore in the calls stack (formatError excluded). Defaults to 0.
function formatError(err, levelsToIgnoreBelow)
print(err);

-- We do not want to include formatError in the stack trace, hence the +1
levelsToIgnoreBelow = (levelsToIgnoreBelow or 0) + 1;

-- 'err' is like: [string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:41: attempt to concatenate local 'name' (a nil value)
-- We retrieve important positions in this string. Remember: not all paths are truncated.
local elipsisIndex = string.find(err, "...", 1, true) or -5;
local lineIndex = elipsisIndex + 6
local msgIndex = string.find(err, ":", lineIndex, true) + 1

-- Can we append the stack trace?
local result = ""
if debug and debug.getinfo then
result = string.sub(err, msgIndex)

local trace = getStackTrace()
for i, v in ipairs(trace) do
print(v)
if (i > levelsToIgnoreBelow) then
result = result.."[NEWLINE]"..v;
end
end
-- Otherwise just report the line and message, and the source file when not truncated.
else
result = "line "..string.sub(err, elipsisIndex)
end

return result
end

-- The error handler to provide to xpcall
local function errorHandler(err)
-- The stack trace at this point is:
-- 1: this error handler (must not be reported),
-- 2: C function calling the handler (kept for security)
-- 3: the error source
err = formatError(err, 1);

-- Show a popup to the user
local str = L("Oops, an error occured:").."[NEWLINE][ICON_PIRATE] "..err;
Events.SerialEventGameMessagePopup( { Type = ButtonPopupTypes.BUTTONPOPUP_TEXT, Data1 = 800, Option1 = true, Text = str } );

-- Restore things up here when needed. Beware to not cause any error as it would cause an infinite recursive call up to the stack overflow!
return false
end

-- Calls someDangerousFunction with the given error handler
xpcall(someDangerousFunction, errorHandler)
</syntaxhighlight></div>

== Troubleshooting ==
The [[Civ5 Useful Programs]] page presents you a number of tools you can use to inspect or modify the game. This is especially useful if you want to quickly reproduce a bug or test something, or to understand what is happening.
* Let's say your mod adds a tech but you do not see in the techs panel. There is a FireTuner panel you can use to see a flat list of all the techs in-game.
* Let's say your mod adds a unit or a wonder, the IGE mod allows you to quickly create an unit or build that wonder (including the splash screen).
* Let's say your mod modifies the yields when the player acquire a specific tech. Once again IGE allows you to grant you that tech and see how the yields are modified.

== Configuration ==
Look for the following files under <code>My Documents/My Games/Sid Meiers' Civilization V</code> and open them in a text editor like the notepad (not in a word processor).
* '''config.ini'''
** Set <code>LoggingEnabled</code> to 1. Civ5 will write log files under the <code>Logs</code> folder.
** Set <code>EnableLuaDebugLibrary</code> to 1. Civ5 will display stack traces on Lua errors and you will be able to use the [http://www.lua.org/manual/5.1/manual.html#pdf-debug.debug debug] object.
** Set <code>DebugPanel</code> to 1. By pressing the '''²''' key (may be '''ù''' or something else depending on your computer's language) during a game, Civ5 will display a debug panel.
* '''usersettings.ini'''
** Set <code>DebugMode</code> to 1. Needed to enable other features previously mentioned.

[[Category:Civ5 Tutorials]]

Debugging (Civ5)

2012-09-24T13:59:53Z

DonQuich:

''This page is a part of the [[Civ5 Modding Tutorials]].''

== Checklist ==
* Did you correctly import to the [[VFS (Civ5)|VFS]] the files that need to be?
* Did you correctly set up the actions and content tab in your project?
* Did you restart civ5 after you added new files?

== XML Debugging ==
[[File:SQLiteManager.png|frame|View of the snapshot using SQLiteManager]]
=== Checking the logs ===
If you correctly set up your [[#Configuration]], whenever you start a game, Civ5 saves some logs under <code>My Games/Sid Medier's Civilization V/cache/Civ5DebugDatabase.db</code>.
* If there were errors with the XML formatting of your data files (wrong column names for example), they will logged in XML.log. Some of those errors may be fatal: in such a case no mod is loaded!
:<pre>[6904.323] Tag (TXT_KEYMODDING_SHOWDLCMODS) does not start with 'TXT_KEY_'</pre>
* If there were errors with the data integrity (missing foreign keys for example - types that reference rows from other tables), they will logged in database.log.
:<pre>[6903.917] Invalid Reference on Leader_Flavors.LeaderType - "LEADER_HARALD" does not exist in Leaders</pre>

=== Using the snapshots ===
If you correctly set up your [[#Configuration]], whenever you start a game, Civ5 saves a snapshot of the database under <code>My Games/Sid Medier's Civilization V/cache/Civ5DebugDatabase.db</code>
* This allows you to check how your XML and SQL files have been merged with the standard game data.

== Lua Debugging ==
=== Using the Firetuner console ===
If you correctly set up your [[#Configuration]], Civ5 will send all the Lua output to the Firetuner. This includes all the debugging output but also any error that may arise, with their calls stack traces.
<pre>
Runtime Error: [string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:41: attempt to concatenate local 'name' (a nil value)
stack traceback:
[string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:41: in function 'dumpObj'
[string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:95: in function 'ScanAll'
[string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:188: in main chunk
[C]: ?
</pre>
Here we can see that a C/C++ code (the game engine) ran the main chunk called (the Lua file), which then called the function ''ScanAll'' on line 188, which then called ''dumpObj'' on line 95. And this one caused an error on line 41.

Note that paths are truncated in the provided example, which makes debugging harder sometimes. This happens when the file is in a {{Type5|context}} registered by the project's ''content'' tab. Here are the workarounds:
* Register only a minimalist context, that will load additional contexts (through the UI LuaContext markup). Do not initiate any action from the root context, let the children context handle everything.
* Provide a custom stack trace, as explained in a further section.

=== Print, assert and error ===
<code>print('''...''')</code> can be used to print anything to the Firetuner output. This allows you to check the flow of a program, or the values of variables. Print calls '''tostring''' on every argument and displays them all on a single line with tabulations as separators between them. Nil values are not displayed, so it is advised you provide expressions such as: <code>(expr or 'nil')</code>

<code>error('''string''' message, '''int''' level = 1)</code> throws an error with the specified message. The execution is then halted and the hand returned to the game engine (or the current protected call if you did use '''pcall''' or '''xpcall'''). The level parameter controls the error position that will be reported. 1 for the line where error is located, 2 for the function call that contained an error, etc. 0 for no position.

<code>assert('''variant''' condition, '''string''' message = "assertion failed")</code> can be used to assert the provided condition is neither nil nor false (everything else is evaluated to true in Lua). Otherwise, an error with the specified message is thrown. You can use them punctually, as a debugging technique. But they may also be used as a defensive programming technique such as [http://en.wikipedia.org/wiki/Design_by_contract design-by-contract]: the idea is that whenever your program's correctness relies on an assumption, you should explicitly check it. For example, if a function takes an array as an argument and assumes that it is not empty, you should add two conditions at the beginning: <code>assert(type(t) == "table")</code> and <code>assert(#t > 0)</code>. This makes the code more self-explanatory (implicit assumptions are now explicitly stated) and it allows you to catch bugs as soon as possible, which typically makes them easier to understand and fix.

=== Handling errors for the end user ===
Most of the time, when one of your user encounters an error with your mod, he just stops using it. A fraction of them will do the effort of reporting bugs but too often the informations they provide is unusable (from "it doesn't work" to wrong reproduction steps "play until turn 173 and wait for Mars being aligned with Venus"). The best way to increase the number of reports and their usefulness is to let your mod tell them the info it needs, as illustrated below.

[[File:IGE-Error.png|none|frame|[http://forums.civfanatics.com/showthread.php?t=436912 In-game editor] tells its users what they must report, even including a calls stack trace when available. The user only needs to make a screenshot that will then land on his Steam profile (provided he didn't change the Steam settings). Reporting made easy!]]

The [[Lua introduction for confirmed developers]] describes a number of techniques you can use to achieve similar results. Here we present an implementation you can use to handle errors in the most dangerous parts of your code in order to present them to the user with a full stack trace when available.
<div class="civ5-example"><syntaxhighlight lang="lua">
-- Returns an array of strings, one for each call level.
function getStackTrace()
-- Level 1 is getStackTrace, 2 is its caller
local level = 2
local trace = {}
while true do
-- Gets that level's informations: function name, source file and line.
local info = debug.getinfo(level, "nSl")
if not info then break end

-- C code or Lua code?
if info.what == "C" then
table.insert(trace, "C function");
else
local userStr = Path.GetFileName(info.source)..": "..info.currentline;
if info.name and string.len(info.name) then
userStr = userStr.." ("..info.name..")";
end
table.insert(trace, userStr);
end
level = level + 1
end
return trace;
end

-- Gets a nicely formatted string of the error.
-- The second parameter is the number of levels to ignore in the calls stack (formatError excluded). Defaults to 0.
function formatError(err, levelsToIgnoreBelow)
print(err);

-- We do not want to include formatError in the stack trace, hence the +1
levelsToIgnoreBelow = (levelsToIgnoreBelow or 0) + 1;

-- 'err' is like: [string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:41: attempt to concatenate local 'name' (a nil value)
-- We retrieve important positions in this string. Remember: not all paths are truncated.
local elipsisIndex = string.find(err, "...", 1, true) or -5;
local lineIndex = elipsisIndex + 6
local msgIndex = string.find(err, ":", lineIndex, true) + 1

-- Can we append the stack trace?
local result = ""
if debug and debug.getinfo then
result = string.sub(err, msgIndex)

local trace = getStackTrace()
for i, v in ipairs(trace) do
print(v)
if (i > levelsToIgnoreBelow) then
result = result.."[NEWLINE]"..v;
end
end
-- Otherwise just report the line and message, and the source file when not truncated.
else
result = "line "..string.sub(err, elipsisIndex)
end

return result
end

-- The error handler to provide to xpcall
local function errorHandler(err)
-- The stack trace at this point is:
-- 1: this error handler (must not be reported),
-- 2: C function calling the handler (kept for security)
-- 3: the error source
err = formatError(err, 1);

-- Show a popup to the user
local str = L("Oops, an error occured:").."[NEWLINE][ICON_PIRATE] "..err;
Events.SerialEventGameMessagePopup( { Type = ButtonPopupTypes.BUTTONPOPUP_TEXT, Data1 = 800, Option1 = true, Text = str } );

-- Restore things up here when needed. Beware to not cause any error as it would cause an infinite recursive call up to the stack overflow!
return false
end

-- Calls someDangerousFunction with the given error handler
xpcall(someDangerousFunction, errorHandler)
</syntaxhighlight></div>

== Troubleshooting ==
The [[Civ5 Useful Programs]] page presents you a number of tools you can use to inspect or modify the game. This is especially useful if you want to quickly reproduce a bug or test something, or to understand what is happening.
* Let's say your mod adds a tech but you do not see in the techs panel. There is a FireTuner panel you can use to see a flat list of all the techs in-game.
* Let's say your mod adds a unit or a wonder, the IGE mod allows you to quickly create an unit or build that wonder (including the splash screen).
* Let's say your mod modifies the yields when the player acquire a specific tech. Once again IGE allows you to grant you that tech and see how the yields are modified.

== Configuration ==
Look for the following files under <code>My Documents/My Games/Sid Meiers' Civilization V</code> and open them in a text editor like the notepad (not in a word processor).
* '''config.ini'''
** Set <code>LoggingEnabled</code> to 1. Civ5 will write log files under the <code>Logs</code> folder.
** Set <code>EnableLuaDebugLibrary</code> to 1. Civ5 will display stack traces on Lua errors and you will be able to use the [http://www.lua.org/manual/5.1/manual.html#pdf-debug.debug debug] object.
** Set <code>DebugPanel</code> to 1. By pressing the '''²''' key (may be '''ù''' or something else depending on your computer's language) during a game, Civ5 will display a debug panel.
* '''usersettings.ini'''
** Set <code>DebugMode</code> to 1. Needed to enable other features previously mentioned.

[[Category:Civ5 Tutorials]]