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.
   8
   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.
  17
  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.
  24
  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".
  29
  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.
  33
  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.
  37
  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     }
  48
  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     }
  60
  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.
  65
  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.
  70
  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.
  79
  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.
  85
  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"
 100
 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.
 107
 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.
 111
 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.
 116
 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().
 120
 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:
 125
 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())
 132 end
 133
 134 signal.connect("action_started_unit_city", "action_started_callback")
 135 signal.connect("action_started_unit_unit", "action_started_callback")
 136
 137 Example 2
 138 =========
 139 The following Lua code will make a player that poisons the population of
 140 cities risk civil war:
 141
 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
 146 end
 147
 148 signal.connect("action_started_unit_city", "action_started_callback")
 149
 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 (!).
 160
 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. (!)
 169
 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. (!)
 177
 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. (!)
 183
 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. (!)
 190
 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.
 195
 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.
 200
 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.
 205
 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. (!)
 211
 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. (!)
 217
 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. (!)
 224
 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. (!)
 230
 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. (!)
 237
 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. (!)
 243
 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.
 249
 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.
 254
 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.
 259
 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.)
 271
 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%.
 280
 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.
 286
 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.
 293
 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.
 303
 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)
 312
 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. (!)
 324
 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
 337
 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 (!)
 362
 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.
 369
 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.
 375
 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
 381
 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.
 387
 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. (!)
 394
 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. (!)
 404
 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.
 414
 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
 426
 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
 440
 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
 462
 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