Events Reference Manual
From Freeciv
Contents |
[edit] Modules
Items marked in RED are still in design or to be implemented.
[edit] Find
Player player (player_id) City city (player, city_id) Unit unit (player, unit_id) Tile tile (nat_x, nat_y)
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, returns best suitable unit this player can build. If player is nil, returns first unit for that role.
Tech_Type tech_type (tech_type_id) Tech_Type tech_type (name) Terrain terrain (terrain_id) Terrain terrain (name)
Player leader (nation_name) Player player (player_name) City city (player, city_name) Unit_Type a_unit_type (role, role_tech)
[edit] Notify
all (message)
player (player, message)
event (player, tile, event, message)
embassies (player, tile, event, message)
[edit] Functions
Items marked in RED are still in design or to be implemented.
[edit] Internationalization
_()
N_()
Q_()
PL_()
[edit] Utilities
Number random (min, max)
error_log (msg) New in 2.2
debug_log (msg) New in 2.2
[edit] Actions
Unit create_unit (owner, tile, unit_type, veteran_level, homecity, moves_left)
create_city (owner, tile, name)
change_gold (player, amount)
Boolean give_technology (player, technology)
Number teleport_units (dst_tile, src_tile, type, amount)
[edit] Events
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) 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", "never",
-- "unavailable".
--
tech_researched (Tech_Type type, Player player, String source)
--
-- source may be: "researched", "traded", "stolen", "hut".
--
hut_enter (Unit unit)
[edit] Types
Player {
String name
Nation_Type nation
Player_ai ai
Number id
Boolean is_human()
Number num_cities()
Number num_units()
}
City {
String name
Player owner
Tile tile
Number id
}
Unit {
Unit_Type type
Player owner
Number homecity_id
Tile tile
Number id
City homecity()
}
Tile {
Number nat_x
Number nat_y
Terrain terrain
Number id
}
Government {
String name
Number id
}
Nation_Type {
String name
String name_plural
Number id
}
Building_Type {
String name
Number id
Number build_shield_cost()
Boolean is_wonder()
Boolean is_great_wonder()
Boolean is_small_wonder()
Boolean is_improvement()
}
Unit_Type {
String name
Number id
Boolean has_flag(flag_name)
Boolean has_role(role_name)
Number build_shield_cost()
}
Tech_Type {
String name
Number id
}
Terrain {
String name
}
[edit] Examples
[edit] Simple example
The example code below should send the message 'Hello, World!' to all the players upon each new turn.
function hello_callback()
notify.all('Hello, World!')
return false
end
signal_connect('turn', 'hello_callback')
[edit] Advanced example
The example code below is a partial reimplementation of the sequence of actions triggered by a hut (Civilization II: minor tribe village) enter event.
function hut_get_gold(unit, gold)
local owner = unit.owner
notify.event(owner, unit.tile, E.HUT_GOLD, 'You found %d gold.', gold)
change_gold(owner, gold)
end
function hut_get_tech(unit)
local owner = unit.owner
local tech = give_technology(owner, nil)
notify.event(owner, unit.tile, E.HUT_TECH,
'You found %s in ancient scrolls of wisdom.',
tech.name)
notify.embassies(owner, unit.tile, E.HUT_TECH,
'The %s have acquired %s from ancient scrolls of wisdom.',
owner.nation.name_plural, tech.name)
end
function hut_get_mercenaries(unit)
local type = find.unit_type('Legion')
if type then
local owner = unit.owner
create_unit(owner, unit.tile, type, 0, unit:homecity(), -1)
notify.event(owner, unit.tile, E.HUT_MERC,
'A band of friendly mercenaries joins your cause.')
return true
else
return false
end
end
function hut_get_city(unit)
local owner = unit.owner
local settlers = find.unit_type('Settlers')
if create_city(owner, unit.tile, nil) then
notify.event(owner, unit.tile, E.HUT_CITY,
'You found a friendly city.')
else
create_unit(owner, unit.tile, settlers, 0, unit:homecity(), -1)
notify.event(owner, unit.tile, E.HUT_SETTLER,
'Friendly nomads are impressed by you, and join you.')
end
end
function hut_enter_callback(unit)
local chance = random(0, 11)
if chance == 0 then
hut_get_gold(unit, 25)
elseif chance == 1 or chance == 2 or chance == 3 then
hut_get_gold(unit, 50)
elseif chance == 4 then
hut_get_gold(unit, 100)
elseif chance == 5 or chance == 6 or chance == 7 then
hut_get_tech(unit)
elseif chance == 8 or chance == 9 then
if not hut_get_mercenaries(unit) then
hut_get_gold(unit, 25)
end
elseif chance == 10 then
-- barbarians.
elseif chance == 11 then
hut_get_city(unit)
end
-- continue processing.
return false
end
signal.connect('hut_enter', 'hut_enter_callback')
