- 3 Talk
-
Events Reference Manual
Redirected from Events specification
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.
Contents |
Modules
Edit
Module functions are accessed as members of the module: module.function(..)
Emphasised items are still in design or to be implemented.
findEdit
An argument with a question mark '?' is allowed to be empty. The empty value is 'nil'
Player player (player_id)
City city (player?, city_id)
Unit unit (player?, unit_id)
Tile tile (nat_x, nat_y)
Tile tile (tile_id) New in 2.2.1
Government government (government_id)
Government government (name)
Nation_Type nation_type (nation_type_id)
Nation_Type nation_type (name)
Building_Type building_type (building_type_id)
Building_Type building_type (name)
Unit_Type unit_type (unit_type_id)
Unit_Type unit_type (name)
Unit_Type 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 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.
Tech_Type tech_type (tech_type_id)
Tech_Type tech_type (name)
Terrain terrain (terrain_id)
Terrain terrain (name)
String signal (index) New in 2.4
String signal_callback (signal_name, index) New in 2.4
Player leader (nation_name) Player player (player_name) City city (player, city_name) Unit_Type a_unit_type (role, role_tech)
effectsEdit
Calculate the current value of a ruleset effect
Number world_bonus (effect_type_name) New in 2.3 Number player_bonus (player, effect_type_name) New in 2.3 Number city_bonus (city, effect_type_name) New in 2.3
notifyEdit
An argument with a question mark '?' is allowed to be empty. The empty value is 'nil'
all (message)
player (player?, message)
event (player?, tile?, event, message)
embassies (player?, tile?, event, message)
-- event may be: an event type from the E module,
-- for example E.SCRIPT
signalEdit
connect (signal_name, callback_name)
-- 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.
remove (signal_name, callback_name) New in 2.4
replace (signal_name, callback_name) New in 2.4
defined (signal_name, callback_name) New in 2.4
list () New in 2.4
serverEdit
Boolean started () New in 2.4
String setting.get (setting_name)
save (filename) New in 2.4
-- As with the /save command, if filename is
-- empty, the server chooses an appropriate
-- filename.
constEdit
New in 2.4: This Lua constants implementation is included as const. A couple of predefined constants:
const.TRUE
const.FALSE
FunctionsEdit
Emphasised items are still in design or to be implemented.
GameEdit
Iterator (Player) players_iterate () New in 2.3 Iterator (Tile) whole_map_iterate () New in 2.3
InternationalizationEdit
String translation functions are used for localizable event scripts included with Freeciv (ruleset and tutorial). See Internationalization.
String _(msg) String N_(msg) String Q_(msg) String PL_(singular, plural, n)
UtilitiesEdit
Number random (min, max)
error_log (msg) New in 2.2
debug_log (msg) New in 2.2
Direction str2direction (str) New in 2.4
String fc_version () New in 2.4
ActionsEdit
An argument with a question mark '?' is allowed to be empty. The empty value is 'nil'
Unit create_unit (owner, tile, unit_type, veteran_level, homecity?, moves_left)
Unit create_unit_full (owner, tile, unit_type, veteran_level, homecity?, moves_left, hp_left, transport?) New in 2.3
-- 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)
create_city (owner, tile, name)
Player create_player (username, nation?) New in 2.3
change_gold (player, amount)
Tech_Type give_technology (player, technology?, reason)
-- return nil if player already has technology
-- you may pass nil for technology to grant a random tech
create_base (tile, base_name, player?) New in 2.2
unleash_barbarians (tile) New in 2.2
place_partisans (tile, player, count, sq_radius) New in 2.3
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.
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.
Script debugging Edit
String _freeciv_state_dump ()
-- Dump the state of user scalar variables to
-- a Lua code string.
listenv () New in 2.4
Events Edit
Connect to an event signal using signal.connect(signal_name, callback_name)
turn_started (Number turn, Number year)
unit_moved (Unit unit, Tile src_tile, Tile dst_tile)
city_built (City city)
city_growth (City city, Number city_size)
unit_built (Unit unit, City city)
building_built (Building_Type type, City city)
city_lost (City city, Player loser, Player winner) New in 2.2
city_destroyed (City city, Player loser, Player destroyer) New in 2.2
unit_lost (Unit unit, Player loser, String reason New in 2.4) New in 2.2
unit_cant_be_built (Unit unit, City city, String reason)
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".
--
tech_researched (Tech_Type type, Player player, String source)
--
-- source may be: "researched", "traded", "stolen", "hut".
--
hut_enter (Unit unit)
TypesEdit
Player {
String name
Nation_Type nation
Boolean is_alive New in 2.4
Boolean ai_controlled was in ai_data in 2.2, ai in 2.1
Number id Removed in 2.2.0, restored in 2.2.1
Boolean is_human()
Number num_cities()
Number num_units()
victory() New in 2.2
Boolean has_wonder(building) New in 2.2
Boolean knows_tech(tech) New in 2.3
Number civilization_score() New in 2.3
Number gold() New in 2.3
Iterator (Unit) units_iterate() New in 2.3
Iterator (City) cities_iterate() New in 2.3
Boolean exists() New in 2.4
}
City {
String name
Player owner
Player original New in 2.3
Tile tile
Number size New in 2.3
Number id
Boolean has_building(building) New in 2.2
Boolean exists() New in 2.2.1
Number map_sq_radius() New in 2.3
}
Unit {
Unit_Type utype
Player owner
Number homecity was homecity_id in 2.1
Tile tile
Number id
City get_homecity() was homecity() in 2.1
Boolean is_on_possible_city_tile() New in 2.2
Boolean exists() New in 2.2.1
Boolean teleport(tile) New in 2.4
void turn(Direction) New in 2.4
Direction facing() New in 2.4
}
Tile {
Number nat_x
Number nat_y
Terrain terrain
Number id
Boolean city_exists_within_city_radius(may_be_on_center) deprecated in 2.3
Boolean city_exists_within_max_city_map(may_be_on_center) New in 2.3
City city() New in 2.3
Number num_units() New in 2.3
Number sq_distance(tile) New in 2.3
bool has_base(name) New in 2.4
Iterator (Unit) units_iterate() New in 2.3
Iterator (Tile) square_iterate(radius) New in 2.3
Iterator (Tile) circle_iterate(sq_radius) New in 2.3
}
Government {
Number id
String rule_name() New in 2.2
String name_translation() New in 2.2
}
Nation_Type {
Number id
String rule_name() New in 2.2
String name_translation() New in 2.2
String plural_translation() New in 2.2
}
Building_Type {
Number build_cost
Number id
Number build_shield_cost()
Boolean is_wonder()
Boolean is_great_wonder()
Boolean is_small_wonder()
Boolean is_improvement()
String rule_name() New in 2.2
String name_translation() New in 2.2
}
Unit_Type {
Number build_cost
Number id
Boolean has_flag(flag_name)
Boolean has_role(role_name)
Boolean can_exist_at_tile(tile) New in 2.3
Number build_shield_cost()
String rule_name() New in 2.2
String name_translation() New in 2.2
}
Tech_Type {
Number id
String rule_name() New in 2.2
String name_translation() New in 2.2
}
Terrain {
Number id
String rule_name() New in 2.2
String name_translation() New in 2.2
}
Nonexistent {
Boolean exists() New in 2.2.1
}
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 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 server/scripting/*.pkg, 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:
