webperimental: killstack decides stack protects.
[freeciv.git] / doc / README.actions
1 Actions
2 =======
3 An action is something a player can do to achieve something in the game.
4 It has properties like cost, chance of success and effects. Some of those
5 properties are configurable using effects and other rule set settings. To
6 learn how to change them read README.effects and the rule set files of
7 classic. An action enabler allows a player to do an action.
9 Generalized action enablers
10 ===============================
11 Some actions have generalized action enablers. An action like that can have
12 zero, one or more action enablers defined for it in the ruleset. The player can
13 do the action only when at least one generalized action enabler says that the
14 action is enabled (and all its hard requirements are fulfilled). A ruleset
15 author can therefore disable an action by not defining any action enablers for
16 it in his ruleset.
18 A generalized action enabler lives in game.ruleset. It consists of the action it
19 enables and two requirement vectors. The first requirement vector, actor_reqs,
20 applies to the entity doing the action. The second, target_reqs, applies to its
21 target. If both requirement vectors are fulfilled the action is enabled as far
22 as the action enabler is concerned. Note that an action's hard requirements
23 still may make it impossible.
25 In some situations an action controlled by generalized action enablers may be
26 impossible because of limitations in Freeciv it self. Those limitations are
27 called hard requirements. The hard requirements of each action are documented
28 below in the section called "Actions and their hard coded requirements".
30 If the player don't have the knowledge required to find out if an action is
31 enabled or not the action is shown to the player in case it is possible. The
32 client will indicate the uncertainty to the player.
34 Should the player order a unit to do an illegal action the server will
35 inform the player that his unit was unable to perform the action. The actor
36 unit may also lose a ruleset configurable amount of move fragments.
38 Example
39 =======
40 [actionenabler_veil_the_threat_of_terror]
41 action = "Incite City"
42 actor_reqs    =
43     { "type",    "name",                 "range", "present"
44       "DiplRel", "Has Casus Belli",      "Local", TRUE
45       "DiplRel", "Provided Casus Belli", "Local", FALSE
46       "DiplRel", "Is foreign",           "Local", TRUE
47     }
49 [actionenabler_go_bind_your_sons_to_exile]
50 action = "Incite City"
51 actor_reqs    =
52     { "type",    "name",       "range",  "present"
53       "Tech",    "Flight",     "Player", TRUE
54       "DiplRel", "Is foreign", "Local",  TRUE
55     }
56 target_reqs    =
57     { "type",   "name",    "range",  "present"
58       "Tech",   "Writing", "Player", False
59     }
61 Above are two action enablers. They both enable the action "Incite City". If
62 all the conditions of at least one of them are fulfilled it will be enabled.
63 No information is given to the player about what action enabler enabled an
64 action.
66 The first action enabler, actionenabler_veil_the_threat_of_terror, is
67 simple. It allows a player to incite a city if he has a reason to declare
68 war on its owner AND the cities owner don't have a reason to declare war on
69 him.
71 The second action enabler, actionenabler_go_bind_your_sons_to_exile, is more
72 complex. It allows a player that has Flight to bribe the cities of
73 civilizations that don't have Writing. The complexity is caused by the
74 requirement that the target don't know Writing. If the civilization of the
75 target city knows Writing or not may be unknown to the acting player. To
76 avoid this complexity a requirement that the acting player has an embassy to
77 the target cities civilization (and therefore knowledge about its techs) can
78 be added.
80 Requirement vector rules
81 ========================
82 An action enabler has two requirement vectors that must be true at the same
83 time. This creates some corner cases you won't find with single requirement
84 vectors. The rules below tries to deal with them.
86 A "DiplRel" requirement with the range "Local" should always be put in the
87 actor requirements.
88  * A local DiplRel requirement can always be expressed as an actor
89    requirement.
90  * Only having to care about local DiplRel requirements in the actor
91    requirements allows the Freeciv code responsible for reasoning about
92    action enablers to be simpler and faster.
93  * If player A having a diplomatic relationship to player B implies that
94    player B has the same relationship to player A the relationship is
95    symmetric. Examples: "Is foreign" and "War"
96  * Symmetric local DiplReal requirements can be moved directly from the
97    target requirement vector to the actor requirement vector.
98  * Asymmetric local DiplReal requirements must test for the same thing in
99    the opposite direction. Example: "Hosts embassy" -> "Has embassy"
101 Actions and Lua
102 ===============
103 Right before an action is executed, but after it is known to be legal, a
104 signal is emitted to Lua. It has access to the same information as the
105 server. It obviously don't have access to the result of the action since it
106 isn't done yet.
108 The signal's name starts with action_started_, then the actor kind, then
109 another _ and in the end the target kind. The signal that is emitted when a
110 unit performs an action on a city is therefore action_started_unit_city.
112 The signal has three parameters. The first parameter is the action that is
113 about to get started. The second is the actor. The third parameter is the
114 target. The parameters of action_started_unit_city is therefore action,
115 actor_unit and finally target city.
117 To get the rule name of an action, that is the name used in action enablers,
118 you can use the method rule_name(). To get a translated name that is nice to
119 show to players use name_translation().
121 Example 1
122 =========
123 The following Lua code will log all actions done by any unit to a city or to
124 another unit:
126 function action_started_callback(action, actor, target)
127   log.normal(_("%s (rule name: %s) performed by %s on %s"),
128              action:name_translation(),
129              action:rule_name(),
130              actor.owner.nation:plural_translation(),
131              target.owner.nation:plural_translation())
134 signal.connect("action_started_unit_city", "action_started_callback")
135 signal.connect("action_started_unit_unit", "action_started_callback")
137 Example 2
138 =========
139 The following Lua code will make a player that poisons the population of
140 cities risk civil war:
142 function action_started_callback(action, actor, target)
143   if action:rule_name() == "Poison City" then
144      edit.civil_war(actor.owner, 5);
145   end
148 signal.connect("action_started_unit_city", "action_started_callback")
150 Actions and their hard requirements
151 ===================================
152 Freeciv can only allow a player to perform an action when the action's hard
153 requirements are fulfilled. Some, but not all, hard requirements can be
154 expressed in an action enabler. Putting them there makes it clearer what the
155 rule actually is. Parts of Freeciv reasons about action enablers. Examples
156 are self contradicting rule detection and the help system. Including the
157 hard requirements rules in each enabler of its action is therefore
158 obligatory for some hard requirements. Those hard requirements are marked
159 with an exclamation mark (!).
161 Actions done by a unit against a city
162 =====================================
163 "Establish Embassy" - Establish a real embassy to the target player
164  * UI name can be set using ui_name_establish_embassy
165  * actor must be aware that the target exists
166  * actor can't have a real embassy to the target player
167  * actor must be on the same tile as the target or on the tile next to it.
168  * target must be foreign. (!)
170 "Establish Embassy Stay" - Establish a real embassy to the target player
171  * UI name can be set using ui_name_establish_embassy
172  * spends the actor unit
173  * actor must be aware that the target exists
174  * actor can't have a real embassy to the target player
175  * actor must be on the same tile as the target or on the tile next to it.
176  * target must be foreign. (!)
178 "Investigate City" - Look at the city dialog of a foreign city
179  * UI name can be set using ui_name_investigate_city
180  * actor must be aware that the target exists
181  * actor must be on the same tile as the target or on the tile next to it.
182  * target must be foreign. (!)
184 "Investigate City Spend Unit" - Look at the city dialog of a foreign city
185  * UI name can be set using ui_name_investigate_city
186  * spends the actor unit
187  * actor must be aware that the target exists
188  * actor must be on the same tile as the target or on the tile next to it.
189  * target must be foreign. (!)
191 "Sabotage City" - Destroy a building or the production in the target city.
192  * UI name can be set using ui_name_sabotage_city
193  * actor must be aware that the target exists
194  * actor must be on the same tile as the target or on the tile next to it.
196 "Targeted Sabotage City" - Targeted version of the above.
197  * UI name can be set using ui_name_targeted_sabotage_city
198  * actor must be aware that the target exists
199  * actor must be on the same tile as the target or on the tile next to it.
201 "Poison City" - Kill a citizen in the target city.
202  * UI name can be set using ui_name_poison_city
203  * actor must be aware that the target exists
204  * actor must be on the same tile as the target or on the tile next to it.
206 "Steal Tech" - Steal a random tech from the targets owner.
207  * UI name can be set using ui_name_steal_tech
208  * actor must be aware that the target exists
209  * actor must be on the same tile as the target or on the tile next to it.
210  * target must be foreign. (!)
212 "Targeted Steal Tech" - Targeted version of the above.
213  * UI name can be set using ui_name_targeted_steal_tech
214  * actor must be aware that the target exists
215  * actor must be on the same tile as the target or on the tile next to it.
216  * target must be foreign. (!)
218 "Incite City" - Pay the target city to join the actors owners side.
219  * UI name can be set using ui_name_incite_city
220  * spends the actor unit
221  * actor must be aware that the target exists
222  * actor must be on the same tile as the target or on the tile next to it.
223  * target must be foreign. (!)
225 "Incite City Escape" - Pay the target city to join the actors owners side.
226  * UI name can be set using ui_name_incite_city_escape
227  * actor must be aware that the target exists
228  * actor must be on the same tile as the target or on the tile next to it.
229  * target must be foreign. (!)
231 "Steal Gold" - Steal some gold from the owner of the target city.
232  * UI name can be set using ui_name_steal_gold
233  * actor must be aware that the target exists
234  * the targets owner must have more than 0 gold.
235  * actor must be on the same tile as the target or on the tile next to it.
236  * target must be foreign. (!)
238 "Steal Maps" - Steal parts of the owner of the target city's map.
239  * UI name can be set using ui_name_steal_maps
240  * actor must be aware that the target exists
241  * actor must be on the same tile as the target or on the tile next to it.
242  * target must be foreign. (!)
244 "Suitcase Nuke" - Cause a nuclear explosion in the target city.
245  * UI name can be set using ui_name_suitcase_nuke
246  * spends the actor unit
247  * actor must be aware that the target exists
248  * actor must be on the same tile as the target or on the tile next to it.
250 "Suitcase Nuke Escape" - Cause a nuclear explosion in the target city.
251  * UI name can be set using ui_name_suitcase_nuke_escape
252  * actor must be aware that the target exists
253  * actor must be on the same tile as the target or on the tile next to it.
255 "Destroy City" - Destroys the target city.
256  * UI name can be set using ui_name_destroy_city
257  * actor must be aware that the target exists
258  * actor must be on the same tile as the target or on the tile next to it.
260 "Establish Trade Route" - Establish a trade route to the target city.
261  * UI name can be set using ui_name_establish_trade_route
262  * actor must be aware that the target exists
263  * actor must be on the same tile as the target or on the tile next to it.
264  * actor must have a home city.
265  * target must be foreign or trademindist tiles away from that home city.
266  * trade route type pct (see "Trade settings") can't be 0%.
267  * it is possible to establish a trade route between the cities as far as
268    the two cities them self are concerned. (Example: If one of the cities
269    can't have any trade routes at all it is impossible to establish a new
270    one.)
272 "Enter Marketplace" - Get a one time bounus without creating a trade route.
273  * UI name can be set using ui_name_enter_marketplace
274  * actor must be aware that the target exists
275  * if force_trade_route is true "Establish Trade Route" must be impossible
276  * actor must be on the same tile as the target or on the tile next to it.
277  * actor must have a home city.
278  * target must be foreign or trademindist tiles away from that home city.
279  * trade route type (see Trade settings) can't be 0%.
281 "Help Wonder" - Add the shields used to build the actor to the target city.
282  * UI name can be set using ui_name_help_wonder
283  * actor must be aware that the target exists
284  * actor must be on the same tile as the target or on the tile next to it.
285  * target city must need the extra shields to complete its production.
287 "Recycle Unit" - Add half the shields used to build the unit to target
288  * UI name can be set using ui_name_recycle_unit
289  * actor must be aware that the target exists
290  * "Help Wonder" must be impossible
291  * actor must be on the same tile as the target or on the tile next to it.
292  * target city must need the extra shields to complete its production.
294 "Join City" - Add the actor to the target city's population.
295  * UI name can be set using ui_name_join_city
296  * actor must be aware that the target exists
297  * actor must have population to add (set in pop_cost)
298  * actor must be on the same tile as the target or on the tile next to it.
299  * target city population must not become higher that the add_to_size_limit
300    setting permits.
301  * target must be able to grow to the size that adding the unit would
302    result in.
304 "Home City" - Set target city as the actor unit's new home city
305  * UI name can be set using ui_name_home_city
306  * actor must be aware that the target exists
307  * actor must be on the same tile as the target
308  * actor must not have the "NoHome" unit type flag. (!)
309  * can't set existing home city as new home city
310  * target city has enough unused unit maintenance slots to support the actor
311    unit. (No problem if the actor unit spends 0 city slots)
313 "Upgrade Unit" - Upgrade the actor unit using the target's facilities.
314  * UI name can be set using ui_upgrade_unit.
315  * actor must be aware that the target exists
316  * actor must be on the same tile as the target.
317  * actor player must have enough gold to pay for the upgrade.
318  * actor unit must have a type to upgrade to (obsoleted_by).
319  * actor unit's upgraded form must be able to exist at its current
320    location.
321  * actor unit's upgraded form must have room for its current cargo.
322  * target player must be able to build the unit upgraded to
323  * target city must be domestic. (!)
325 "Airlift Unit" - Airlift actor unit to target city.
326  * UI name can be set using ui_airlift_unit
327  * actor must be aware that the target exists
328  * the actor unit isn't transporting another unit (!)
329  * the actor unit isn't inside the target city
330  * the actor unit can exist in the target city (outside a transport)
331  * the actor unit is in a city
332    - that is domestic or, if airliftingstyle permits it, allied
333    - that has Airlift (see the Airlift effect and the airliftingstyle
334      setting)
335  * the target city is domestic or, if airliftingstyle permits it, allied
336  * the target city has Airlift
338 "Conquer City" - Conquer the target city.
339  * UI name can be set using ui_name_conquer_city
340  * actor must be aware that the target exists
341  * if force_capture_units is true "Capture Units" must be impossible
342  * if force_bombard is true "Bombard" must be impossible
343  * if force_explode_nuclear is true "Explode Nuclear" must be impossible
344  * "Attack" must be impossible
345  * the actor unit must be on a tile next to the target.
346  * the actor player's nation can't be an animal barbarian. (!)
347  * the actor unit must, if transported, be able to disembark from its
348    transport.
349  * the actor unit doesn't have the "CoastStrict" unit type flag or the
350    target city is on or adjacent to a tile that doesn't have the
351    "UnsafeCoast" terrain flag.
352  * the actor unit can't be diplomatically forbidden from entering the tile
353    of the target city.
354  * the actor unit has the "CanOccupyCity" unit class flag (!)
355  * the actor can't have the "NonMil" unit type flag (!)
356  * the actor unit has at least one move fragment left (!)
357  * the actor's relationship to the target is War (!)
358  * actor unit must be able to exist outside of a transport at the target's
359    tile.
360  * the target must be foreign (!)
361  * the target city contains 0 units (!)
363 Actions done by a unit against another unit
364 ===========================================
365 "Sabotage Unit" - Halve the target unit's hit points.
366  * UI name can be set using ui_name_sabotage_unit
367  * actor must be on the same tile as the target or on the tile next to it.
368  * target must be visible for the actor.
370 "Bribe Unit" - Make the target unit join the actors owners side.
371  * UI name can be set using ui_name_bribe_unit
372  * actor must be on the same tile as the target or on the tile next to it.
373  * target must be foreign. (!)
374  * target must be visible for the actor.
376 "Expel Unit" - Expel the target unit to its owner's capital.
377  * UI name can be set using ui_name_expel_unit
378  * actor must be on the same tile as the target or on the tile next to it.
379  * target must be visible for the actor.
380  * target's owner must have a capital
382 "Heal Unit" - Restore the target unit's health.
383  * UI name can be set using ui_name_heal_unit
384  * spends all actor movement
385  * actor must be on the same tile as the target or on the tile next to it.
386  * target must be visible for the actor.
388 Actions done by a unit against all units at a tile
389 ==================================================
390 "Capture Units" - steal the target units.
391  * UI name can be set using ui_name_capture_units
392  * actor must be on a tile next to the target.
393  * target must be foreign. (!)
395 "Bombard" - bombard the units (and city) at the tile without killing them.
396  * UI name can be set using ui_name_bombard
397  * if force_capture_units is true "Capture Units" must be impossible
398  * actor must have a bombard_rate > 0
399  * actor must have an attack > 0
400  * actor must be on a tile next to the target or, if bombard_max_range
401    allows it, futher away.
402  * target can't be in a city the actor player isn't at war with.
403  * target owner must be at war with actor. (!)
405 Actions done by a unit against a tile
406 =====================================
407 "Found City" - Found a city at the target tile.
408  * UI name can be set using ui_name_found_city
409  * city name must be legal
410  * the scenario setting prevent_new_cities must be false.
411  * actor must be on the same tile as the target.
412  * target must not have the NoCities terrain flag.
413  * target must not be closer than citymindist to nearest city.
415 "Explode Nuclear" - Detonate at the target tile. Cause a nuclear explosion.
416  * UI name can be set using ui_name_explode_nuclear
417  * if force_capture_units is true "Capture Units" must be impossible
418  * if force_bombard is true "Bombard" must be impossible
419  * actor must be on the same tile as the target or on the tile next to it.
420  * if the actor unit isn't on the target tile
421    - the actor must have movement left
422    - the target tile must have a city or a unit
423    - the actor must be at war with any city on the target tile
424    - the actor must be at war with each unit on the target tile
425    - a unit at the target tile must be reachable unless it has a city
427 "Paradrop Unit" - move the actor unit to the target tile.
428  * UI name can be set using ui_paradrop_unit
429  * can result in the conquest of the city at the target tile if
430    - the actor player isn't an animal barbarian.
431    - the actor unit has the "CanOccupyCity" unit class flag
432    - the actor don't have the "NonMil" unit type flag
433    - the actor's relationship to the target is War
434    - the target city contains 0 units
435  * the distance between actor and target is from 1 to paratroopers_range
436  * the actor unit hasn't paradropped this turn
437  * the actor unit has paratroopers_mr_req moves left
438  * the actor unit isn't transporting another unit (!)
439  * the target tile is known (doesn't have to be seen) by the actor
441 "Attack"
442  * UI name can be set using ui_name_attack
443  * if force_capture_units is true "Capture Units" must be impossible
444  * if force_bombard is true "Bombard" must be impossible
445  * if force_explode_nuclear is true "Explode Nuclear" must be impossible
446  * the actor must be on the tile next to the target.
447  * the actor's attack must be above 0
448  * the actor can't have the "NonMil" unit type flag (!)
449  * the actor must be native to the target tile unless it has the
450    "AttackNonNative" unit class flag and not the "Only_Native_Attack" unit
451    type flag.
452  * the target tile has at least one enemy unit.
453  * the target tile has no non enemy units.
454  * the target tile has no non enemy city.
455  * one or all (unreachableprotects) non transported units at the target
456    tile must be reachable. A unit is reachable if any of the following is
457    true:
458    - it doesn't have the "Unreachable" unit class flag
459    - it is listed in the actor unit's targets
460    - it is in a city
461    - it is on a tile with a native Extra
463 Actions done by a unit to it self
464 =================================
465 "Disband Unit" - Disband the unit. Gives nothing in return.
466  * UI name can be set using ui_name_disband_unit
467  * "Help Wonder" must be impossible
468  * "Recycle Unit" must be impossible