Civ5 API Reference FAQ

Terminology

Types

unknown	This parameter's type could not be identified.
string	A Lua string.
int	Any integer.
float	Any number, integer or floating-point.
table	An unidentified table. Look at the code samples to figure it out by yourself.
table(key => value)	A table whose keys and values have the specified types. Example: table(PlayerID => Player) players It can be enumerated with: for playerID, player in ipairs(players) do The following will return a Player: players[0]
iterator(key => value)	To be used in a for... in... loop. Example: iterator(UnitID, Unit) Units() It can be enumerated with: for unitID, pUnit in Units() do.
variant	This parameter can be assigned with different types. Example: DB.Query(variant arg) This function can accept a string or a table.

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 Player.
• Static types exist as a single global variable, such as Game.
• Some types can be both, such as InstanceManager: a global variable exists with this name and calling its new method creates a new instance of InstanceManager.

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: caller.somefunc(caller, arg) and caller:somefunc(arg)
• 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: Events.SomeEvent.Add(Handler) and Events.SomeEvent.Remove(Handler)
• They can be invoked that way: Events.SomeEvent(arg1, arg2)
• Events typically do not expect any return type. But the ones in GameEvents usually expect an integer or a boolean, see their documentations.

Documentation content

Reliability

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.

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 balance compromise reliability and completeness is quite good but far to be perfect.

Pages generation process

The initial versions of those pages were automatically generated by a written by User:DonQuich. Here are the main steps of this bot:

To be documented...