(start: copy of [1])

Every event or action should have information about which versions of Freeciv support it. Important: Anything documented about unreleased versions can change at any time before the final release.

ModulesEdit

Module functions are accessed as members of the module:

module.function(..)

const Edit

New in 2.4. This Lua constants implementation is included as const. A couple of predefined constants:

• const.TRUE
• const.FALSE

log Edit

Logging facilities from lua script

Module log (tolua_common_a.pkg)

(return) type	function name / variable	arguments	comments
(void)	log.base	(level, message)	New in 2.4. Do not call his function direct but use the functions below for the different log levels.
(void)	log.fatal	(message)	New in 2.4.
(void)	log.error	(message)	New in 2.4.
(void)	log.normal	(message)	New in 2.4.
(void)	log.verbose	(message)	New in 2.4.
(void)	log.debug	(message)	New in 2.4.
(void)	error_log	(message)	Deprecated since 2.4. New in 2.2.
(void)	debug_log	(message)	Deprecated since 2.4. New in 2.2.

game Edit

This module is used for game related information.

Module game (tolua_game.pkg)

(return) type	function name / variable	arguments	comments
int	game.turn	()

find Edit

An argument with a question mark '?' is allowed to be empty. The empty value is 'nil'

Module find (tolua_game.pkg)

(return) type	function name / variable	arguments	comments
Player	find.player	(player_id)
Player	find.leader	(nation_name)	Missing.
Player	find.player	(player_name)	Missing.
City	find.city	(player?, city_id)
City	find.city	(player, city_name)	Missing
Unit	find.unit	(player?, unit_id)
Tile	find.tile	(nat_x, nat_y)
Tile	find.tile	(tile_id)	New in 2.2.1.
Government	find.government	(government_id)
Government	find.government	(name)
Nation_Type	find.nation_type	(nation_type_id)
Nation_Type	find.nation_type	(name)
Building_Type	find.building_type	(building_type_id)
Building_Type	find.building_type	(name)
Unit_Type	find.unit_type	(unit_type_id)
Unit_Type	find.unit_type	(name)
Unit_Type	find.role_unit_type	(role_name, player?)	New in 2.2. If player is not nil, role_unit_type returns the best suitable unit this player can build. If player is nil, returns first unit for that role.
Unit_Type	find.transport_unit	(player, unit_type, tile)	New in 2.3. Return a unit that can transport unit_type at tile. Intended to be used with create_unit_full.
Unit_Type	find.a_unit_type	(role, role_tech)	Missing.
Tech_Type	find.tech_type	(tech_type_id)
Tech_Type	find.tech_type	(name)
Terrain	find.terrain	(terrain_id)
Terrain	find.terrain	(name)

Module find (tolua_signal.pkg)

(return) type	function name / variable	arguments	comments
String	find.signal	(index)	New in 2.4.
String	find.signal_callback	(signal_name, index)	New in 2.4.

effects Edit

Calculate the current value of a ruleset effect

Module effects (tolua_game.pkg)

(return) type	function name / variable	arguments	comments
Number	effects.world_bonus	(effect_type_name)	New in 2.3.
Number	effects.player_bonus	(player, effect_type_name)	New in 2.3.
Number	effects.city_bonus	(city, effect_type_name)	New in 2.3.

direction Edit

Module direction (tolua_game.pkg)

(return) type	function name / variable	arguments	comments
Direction	direction:str2direction	(str)	New in 2.4.

notify Edit

An argument with a question mark '?' is allowed to be empty. The empty value is 'nil'

event may be: an event type from the E module, for example E.SCRIPT.

Module notify (tolua_server.pkg)

(return) type	function name / variable	arguments	comments
(void)	notify.embassies_msg	(player, tile, event, message)	Basic function for events. Do not call direct!
(void)	notify.event_msg	(player, tile, event, message)	Basic function for events. Do not call direct!
(void)	notify.all	(message)
(void)	notify.player	(player?, message)
(void)	notify.event	(player?, tile?, event, message)
(void)	notify.embassies	(player?, tile?, event, message)

server Edit

An argument with a question mark '?' is allowed to be empty. The empty value is 'nil'

Module server (tolua_server.pkg)

(return) type	function name / variable	arguments	comments
(void)	server.save	(filename?)	New in 2.4. As with the /save command, if filename is empty, the server chooses an appropriate filename.
Boolean	server.started	()	New in 2.4.
Number	server.civilization_score	(player)

edit Edit

An argument with a question mark '?' is allowed to be empty. The empty value is 'nil'

Module edit (tolua_server.pkg)

(return) type	function name / variable	arguments	comments
(void)	edit.player_victory	(player)	New in 2.2 as (Player):victory().
Unit	edit.create_unit	(player, tile, unit_type, veteran_level, homecity?, moves_left)	New in 2.4.
Unit	edit.create_unit_full	(player, tile, unit_type, veteran_level, homecity?, moves_left, hp_left, ptransport)	New in 2.4. More complex version of create_unit() allowing creation of unit already loaded on the Unit passed as 'transport' (use find.transport_unit() to create suitable transport).
(void)	edit.create_city	(player, tile, name)	New in 2.4.
(void)	edit.change_gold	(player, amount)	New in 2.4.
(void)	edit.give_technology	(player, technology?, reason)	New in 2.4. Returns nil if player already has technology. You may pass nil for technology to grant a random tech.
Player	edit.civil_war	(player, probability)	New in 2.4. Possibly throw a player into civil war. probability is the percentage chance of the civil war occurring (use 100 for certainty), or if it is zero, the normal calculation is used (affected by government, happiness, etc). Takes no account of the 'civilwarsize' server option (but the player must have at least two cities). If the chance is not met, nothing happens. If the chance is met, civil war happens as usual, with appropriate messages sent to the players. Returns the new AI player, or nil.
Boolean	edit.unit_teleport	(unit, dest)	New in 2.4.
(void)	edit.unit_turn	(unit, direction)	New in 2.4.
Boolean	edit.unit_move	(unit, moveto, movecost)	New in 2.4.
(void)	edit.create_base	(tile, name, player)	Added in 2.2 as create_base().
Boolean	edit.unleash_barbarians	(tile)	Added in 2.2 as unleash_barbarians().
(void)	edit.place_partisans	(tile, player, count, sq_radius)	New in 2.4.
Player	edit.create_player	(username, Nation_Type)	New in 2.4.
(void)	edit.climate_change	(climate_change_type, effect)	New in 2.4. Cause global climate change. type can be GLOBAL_WARMING or NUCLEAR_WINTER. effect is the magnitude of the effect (approximately, the number of tiles affected). Does not print any messages, or affect the counters for pollution/fallout-related climate change. Works regardless of 'global_warming' and 'nuclear_winter' server options.

signal Edit

Signal emission invokes all associated callbacks in the order they were connected. A callback can stop the current signal emission, preventing callbacks connected after it from being invoked, by returning true.

Module find (tolua_signal.pkg)

(return) type	function name / variable	arguments	comments
(void)	signal.connect	(signal_name, callback_name)
(void)	signal.remove	(signal_name, callback_name)	New in 2.4.
(void)	signal.defined	(signal_name, callback_name)	New in 2.4.
(void)	signal.list	()	New in 2.4. List all signals as well as the callbacks.
(void)	signal.replace	(signal_name, callback_name)	New in 2.4.

chat Edit

Module chat (tolua_client.pkg)

(return) type	function name / variable	arguments	comments
(void)	chat.base	(message)	New in 2.4. Do not call direct.
(void)	chat.msg	(message)	New in 2.4. Add a message to the chat window.

auth Edit

Module auth (tolua_fcdb.pkg)

(return) type	function name / variable	arguments	comments
String	auth.get_username	(Connection)	New in 2.4.
String	auth.get_ipaddr	(Connection)	New in 2.4.
Boolean	auth.set_password	(Connection, password)	New in 2.4.
String	auth.get_password	(Connection)	New in 2.4.

fcdb Edit

The Freeciv database (fcdb) module.

Module fcdb (tolua_fcdb.pkg)

(return) type	function name / variable	arguments	comments
String	fcdb.option	(type)	New in 2.4. Use it to get a fcdb option (HOST, USER, PORT, PASSWORD, DATABASE, TABLE_USER, TABLE_LOG)

Types Edit

Types functions are accessed as members of the module (=type)

module.function(..)

or as a function of a variable of the given type

type t
t:function()

Player Edit

Type Player (tolua_game.pkg)

(return) type	function name / variable	arguments	comments
String	(Player).name
Nation_Type	(Player).nation
Boolean	(Player).ai_controlled		was ai_data in 2.2, ai in 2.1.
Boolean	(Player).is_alive		New in 2.4.
Number	(Player).id		Removed in 2.2.0, restored in 2.2.1.
Boolean	(Player):is_human	()
Number	(Player):num_cities	()
Number	(Player):num_units	()
Boolean	(Player):has_wonder	(building)	New in 2.2.
Boolean	(Player):knows_tech	(tech)	New in 2.3.
Number	(Player):gold	()	New in 2.3.
Iterator (Unit)	(Player):units_iterate	()	New in 2.3.
Iterator (City)	(Player):cities_iterate	()	New in 2.3.
Boolean	(Player):exists	()	New in 2.4.

Type Player (tolua_server.pkg)

(return) type	function name / variable	arguments	comments
Number	(Player):civilization_score	()	New in 2.3. Reference to server.civilisation_score().
(void)	(Player):victory	()	New in 2.2. Reference to edit.player_victory().
Unit	(Player):create_unit	(tile, unit_type, veteran_level, homecity?, moves_left)	New in 2.4. Reference to edit.create_unit().
Unit	(Player):create_unit_full	(tile, unit_type, veteran_level, homecity?, moves_left, hp_left, ptransport)	New in 2.4. Reference to edit.create_unit_full().
(void)	(Player):create_city	(tile, name)	New in 2.4. Reference to edit.create_city().
(void)	(Player):change_gold	(amount)	New in 2.4. Reference to edit.change_gold().
(void)	(Player):give_technology	(technology?, reason)	New in 2.4. Reference to edit.give_technology().
Player	(Player):civil_war	(probability)	New in 2.4. Reference to edit.civil_war().

City Edit

Type City (tolua_game.pkg)

(return) type	function name / variable	arguments	comments
String	(City).name
Player	(City).owner
Tile	(City).tile
Number	(City).size
Number	(City).id
Boolean	(City):has_building	(building)	New in 2.2.
Boolean	(City):exists	()	New in 2.2.1.
Number	(City):map_sq_radius	()	New in 2.3.
Number	(City):size	()	New in 2.4.
Tile	(City):tile	()	New in 2.4.

Unit Edit

Type Unit (tolua_game.pkg)

(return) type	function name / variable	arguments	comments
Unit_Type	(Unit).utype
Player	(Unit).owner
Number	(Unit).homecity		was (Unit).homecity_id in 2.1.
Tile	(Unit).tile
Number	(Unit).id
City	(Unit):get_homecity	()	was (Unit):homecity() in 2.1.
Boolean	(Unit):is_on_possible_city_tile	()	New in 2.2.
Boolean	(Unit):exists	()	New in 2.2.1.
Direction	(Unit):facing	()	New in 2.4.
Tile	(Unit):tile	()	New in 2.4.

Type Unit (tolua_server.pkg)

(return) type	function name / variable	arguments	comments
Boolean	(Unit):teleport	(dest)	New in 2.4. Reference to edit.unit_teleport().
(void)	(Unit):turn	(direction)	New in 2.4. Reference to edit.unit_turn().
Boolean	(Unit):move	(moveto, movecost)	New in 2.4. Reference to edit.unit_move().

Tile Edit

Type Tile (tolua_server.pkg)

(return) type	function name / variable	arguments	comments
Number	(Tile).nat_x
Number	(Tile).nat_y
Terrain	(Tile).terrain
Number	(Tile).id
Boolean	(Tile):city_exists_within_city_radius	(may_be_on_center)	Deprecated in 2.3.
Boolean	(Tile):city_exists_within_max_city_map	(may_be_on_center)	New in 2.3.
City	(Tile):city	()	New in 2.3.
Number	(Tile):num_units	()	New in 2.3.
Number	(Tile):sq_distance	(Tile)	New in 2.3.
bool	(Tile):has_base	(name)	New in 2.4.
Iterator (Unit)	(Tile):units_iterate	()	New in 2.3.
Iterator (Tile)	(Tile):square_iterate	(radius)	New in 2.3.
Iterator (Tile)	(Tile):circle_iterate	(sq_radius)	New in 2.3.

Type Tile (tolua_server.pkg)

(return) type	function name / variable	arguments	comments
(void)	(Tile):create_base	(name, player)	New in 2.4. Reference to edit.create_base().
Boolean	(Tile):unleash_barbarians	()	New in 2.4. Reference to edit.unleash_barbarians().
(void)	(Tile):place_partisans	(player, count, sq_radius)	New in 2.4. Reference to edit.place_partisans().

Government Edit

Type Government (tolua_game.pkg)

(return) type	function name / variable	arguments	comments
Number	(Goverment).id
String	(Goverment):rule_name	()	New in 2.2.
String	(Goverment):name_translation	()	New in 2.2.

Nation_type Edit

Type Nation_type (tolua_game.pkg)

(return) type	function name / variable	arguments	comments
Number	(Nation_type).id
String	(Nation_type):rule_name	()	New in 2.2.
String	(Nation_type):name_translation	()	New in 2.2.
String	(Nation_type):plural_translation	()	New in 2.2.

Building_Type Edit

Type Building_Type (tolua_game.pkg)

(return) type	function name / variable	arguments	comments
Number	(Building_Type).build_cost
Number	(Building_Type).id
Number	(Building_Type):build_shield_cost	()
Boolean	(Building_Type):is_wonder	()
Boolean	(Building_Type):is_great_wonder	()
Boolean	(Building_Type):is_small_wonder	()
Boolean	(Building_Type):is_improvement	()
String	(Building_Type):rule_name	()	New in 2.2.
String	(Building_Type):name_translation	()	New in 2.2.

Unit_Type Edit

Type Unit_Type (tolua_game.pkg)

(return) type	function name / variable	arguments	comments
Number	(Unit_Type).build_cost
Number	(Unit_Type).id
Boolean	(Unit_Type):has_flag	(flag_name)
Boolean	(Unit_Type):has_role	(role_name)
Boolean	(Unit_Type):can_exist_at_tile	(tile)	New in 2.3.
Number	(Unit_Type):build_shield_cost	()
String	(Unit_Type):rule_name	()	New in 2.2.
String	(Unit_Type):name_translation	()	New in 2.2.

Tech_Type Edit

Type Tech_Type (tolua_game.pkg)

(return) type	function name / variable	arguments	comments
Number	(Tech_Type).id
String	(Tech_Type):rule_name	()	New in 2.2.
String	(Tech_Type):name_translation	()	New in 2.2.

Terrain Edit

Type Terrain (tolua_game.pkg)

(return) type	function name / variable	arguments	comments
Number	(Terrain).id
String	(Terrain):rule_name	()	New in 2.2.
String	(Terrain):name_translation	()	New in 2.2.

Nonexistent Edit

Type Nonexistent (tolua_common_a.pkg)

(return) type	function name / variable	arguments	comments
Boolean	(Nonexistent).exist	()	New in 2.2.1.

Functions Edit

Internationalization Edit

String translation functions are used for localizable event scripts included with Freeciv (ruleset and tutorial). See Internationalization.

Functions Internationalization (tolua_common_a.pkg)

(return) type	function name / variable	arguments	comments
String	_	(msg)
String	N_	(msg)
String	Q_	(msg)
String	PL_	(singular, plural, n)

Utilities Edit

Functions Utilities (tolua_common_a.pkg)

(return) type	function name / variable	arguments	comments
Number	random	(min, max)
Direction	str2direction	(str)	New in 2.4. Reference to direction.str2dir().
(void)	listenv	()	New in 2.4. Lists all defined variables and functions.
String	fc_version	()	New in 2.4.

Game Edit

Functions Game (tolua_game.pkg)

(return) type	function name / variable	arguments	comments
Iterator (Player)	players_iterate	()	New in 2.3.
Iterator (Tile)	whole_map_iterate	()	New in 2.3.

Actions Edit

An argument with a question mark '?' is allowed to be empty. The empty value is 'nil'

Functions Action (tolua_server.pkg)

(return) type	function name / variable	arguments	comments
Unit	create_unit	(player, tile, unit_type, veteran_level, homecity?, moves_left)	Depreciated in 2.4. Reference to edit.create_unit().
Unit	create_unit_full	(player, tile, unit_type, veteran_level, homecity?, moves_left, hp_left, ptransport)	Depreciated in 2.4. Reference to edit.create_unit_full().
Player	create_city	(player, tile, name)	Depreciated in 2.4. Reference to edit.create_city().
(void)	create_base	(tile, name, player)	Depreciated in 2.4. Reference to edit.create_base().
Boolean	unleash_barbarians	(tile)	Depreciated in 2.4. Reference to edit.unleash_barbarians().
(void)	place_partisans	(tile, player, count, sq_radius)	Depreciated in 2.4. Reference to edit.place_partisans().
Player	create_player	(username, Nation_Type)	Depreciated in 2.4. Reference to edit.create_player().
(void)	climate_change	(climate_change_type, effect)	Depreciated in 2.4. Reference to edit.climate_change().
(void)	give_technology	(player, technology?, reason)	Depreciated in 2.4. Reference to edit.give_technology().

ConstantsEdit

The following constants are defined in tolua_common_a.pkg:

• const.TRUE (=1)
• const.FALSE (=0)

Events Edit

Connect to an event signal using

signal.connect(signal_name, callback_name)

Signals server (server_signal.c)

(return) type	function name / variable	arguments	comments
Boolean	turn_started	(Number turn, Number year)
Boolean	unit_moved	(Unit unit, Tile src_tile, Tile dst_tile)
Boolean	city_built	(City city)
Boolean	city_growth	(City city, Number city_size)
Boolean	unit_built	(Unit unit, City city)
Boolean	building_built	(Building_Type type, City city)
Boolean	city_lost	(City city, Player loser, Player winner)	New in 2.2.
Boolean	city_destroyed	(City city, Player loser, Player destroyer)	New in 2.2.
Boolean	unit_lost	(Unit unit, Player loser, String reason)	New in 2.2. reason added in 2.4.
Boolean	unit_cant_be_built	(Unit unit, City city, String reason)
Boolean	building_cant_be_built	(Building_Type type, City city, String reason)	reason may be: "pop_cost", "need_tech", "need_building", "need_special", "need_terrain", "need_government", "need_nation", "need_minsize", "need_ai_level", "need_terrainclass", "need_minyear", "never", "unavailable".
Boolean	tech_researched	(Tech_Type type, Player player, String source)	source may be: "researched", "traded", "stolen", "hut".
Boolean	hut_enter	(Unit unit)

Script debugging Edit

The follow functions are helpfull in debugging lua scripts:

Functions debugging (tolua_common_a.pkg)

(return) type	function name / variable	arguments	comments
String	_freeciv_state_dump	()	Dump the state of user scalar variables to a Lua code string.
(void)	listenv	()	New in 2.4. List all defined lua variables and functions.

ExamplesEdit

Simple exampleEdit

The example code below should send the message 'Hello, World!' to all the players upon each new turn.

 function hello_callback(turn, year)
     notify.all('Hello, World!')
     return false
 end
 
 signal.connect('turn_started', 'hello_callback')

Advanced Examples Edit

Please read the Events Tutorial for examples of the most important concepts.

Part of Freeciv's ruleset is implemented in Lua. It can serve as an advanced example. Look at the files default/default.lua and default/script.lua in Freeciv's data directory. (You can also look at the current SVN version of these files)

Lua Edit

The language used for Freeciv event scripts is Lua. As of Freeciv 2.2, we use Lua 5.1.

Lua External Links:

• Lua-users Tutorial Directory
• Lua Manual

Lua Builtins Edit

Some Lua builtin functions and modules are also available in Freeciv (Some functionality is intentionally left out by policy). It is not our intention to document Lua builtins here, but just to mention a selection of the useful parts.

Functions

  Boolean, [Results]       pcall(f, arg1, ...)
  Iterator (Key, Object)   pairs(table)
  Iterator (Index, Object) ipairs(table)

Variables

  Table   _G   -- The global environment (all variables) as a table.

Modules

  math         -- math.sqrt and other useful functions
               -- Important: never use math.random. Always use freeciv's random(min, max)
  string       -- string matching
  table        -- table.sort can sort an array-like table

Reference Links Edit

The Scripting API is defined in *.pkg files, and that must be the canonical reference to this API. Please see these links for future updates, or if you suspect something is this Reference is wrong:

• Current development version (trunk; 2.4):
  • scriptcore
    • common/scriptcore/tolua_common_a.pkg
    • common/scriptcore/tolua_common_z.pkg
    • common/scriptcore/tolua_game.pkg
    • common/scriptcore/tolua_signal.pkg
  • fcdb
    • the common part of scriptcore
    • server/scripting/tolua_fcdb.pkg
  • server
    • all of scriptcore.
    • server/scripting/tolua_server.pkg
  • client
    • all of scriptcore.
    • client/luascript/tolua_client.pkg
• 2.3 api.pkg
• 2.2 api.pkg
• 2.1 api.pkg