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     }
  47
  48 [actionenabler_go_bind_your_sons_to_exile]
  49 action = "Incite City"
  50 actor_reqs    =
  51     { "type",   "name", "range", "present"
  52       "Tech", "Flight", "Player", TRUE
  53     }
  54 target_reqs    =
  55     { "type",   "name", "range", "present"
  56       "Tech", "Writing", "Player", False
  57     }
  58
  59 Above are two action enablers. They both enable the action "Incite City". If
  60 all the conditions of at least one of them are fulfilled it will be enabled.
  61 No information is given to the player about what action enabler enabled an
  62 action.
  63
  64 The first action enabler, actionenabler_veil_the_threat_of_terror, is
  65 simple. It allows a player to incite a city if he has a reason to declare
  66 war on its owner AND the cities owner don't have a reason to declare war on
  67 him.
  68
  69 The second action enabler, actionenabler_go_bind_your_sons_to_exile, is more
  70 complex. It allows a player that has Flight to bribe the cities of
  71 civilizations that don't have Writing. The complexity is caused by the
  72 requirement that the target don't know Writing. If the civilization of the
  73 target city knows Writing or not may be unknown to the acting player. To
  74 avoid this complexity a requirement that the acting player has an embassy to
  75 the target cities civilization (and therefore knowledge about its techs) can
  76 be added.
  77
  78 Requirement vector rules
  79 ========================
  80 An action enabler has two requirement vectors that must be true at the same
  81 time. This creates some corner cases you won't find with single requirement
  82 vectors. The rules below tries to deal with them.
  83
  84 A "DiplRel" requirement with the range "Local" should always be put in the
  85 actor requirements.
  86  * A local DiplRel requirement can always be expressed as an actor
  87    requirement.
  88  * Only having to care about local DiplRel requirements in the actor
  89    requirements allows the Freeciv code responsible for reasoning about
  90    action enablers to be simpler and faster.
  91  * If player A having a diplomatic relationship to player B implies that
  92    player B has the same relationship to player A the relationship is
  93    symmetric. Examples: "Is foreign" and "War"
  94  * Symmetric local DiplReal requirements can be moved directly from the
  95    target requirement vector to the actor requirement vector.
  96  * Asymmetric local DiplReal requirements must test for the same thing in
  97    the opposite direction. Example: "Hosts embassy" -> "Has embassy"
  98
  99 Actions and Lua
 100 ===============
 101 Right before an action is executed, but after it is known to be legal, a
 102 signal is emitted to Lua. It has access to the same information as the
 103 server. It obviously don't have access to the result of the action since it
 104 isn't done yet.
 105
 106 The signal's name starts with action_started_, then the actor kind, then
 107 another _ and in the end the target kind. The signal that is emitted when a
 108 unit performs an action on a city is therefore action_started_unit_city.
 109
 110 The signal has three parameters. The first parameter is the action that is
 111 about to get started. The second is the actor. The third parameter is the
 112 target. The parameters of action_started_unit_city is therefore action,
 113 actor_unit and finally target city.
 114
 115 To get the rule name of an action, that is the name used in action enablers,
 116 you can use the method rule_name(). To get a translated name that is nice to
 117 show to players use name_translation().
 118
 119 Example 1
 120 =========
 121 The following Lua code will log all actions done by any unit to a city or to
 122 another unit:
 123
 124 function action_started_callback(action, actor, target)
 125   log.normal(_("%s (rule name: %s) performed by %s on %s"),
 126              action:name_translation(),
 127              action:rule_name(),
 128              actor.owner.nation:plural_translation(),
 129              target.owner.nation:plural_translation())
 130 end
 131
 132 signal.connect("action_started_unit_city", "action_started_callback")
 133 signal.connect("action_started_unit_unit", "action_started_callback")
 134
 135 Example 2
 136 =========
 137 The following Lua code will make a player that poisons the population of
 138 cities risk civil war:
 139
 140 function action_started_callback(action, actor, target)
 141   if action:rule_name() == "Poison City" then
 142      edit.civil_war(actor.owner, 5);
 143   end
 144 end
 145
 146 signal.connect("action_started_unit_city", "action_started_callback")
 147
 148 Actions and their hard coded requirements
 149 =========================================
 150
 151 Actions done by a unit against a city
 152 =====================================
 153 "Establish Embassy" - Establish a real embassy to the target player
 154  * UI name can be set using ui_name_establish_embassy
 155  * actor can't have a real embassy to the target player
 156  * actor must be on the same tile as the target or on the tile next to it.
 157  * target must be foreign.
 158
 159 "Investigate City" - Look at the city dialog of a foreign city
 160  * UI name can be set using ui_name_investigate_city
 161  * actor must be on the same tile as the target or on the tile next to it.
 162  * target must be foreign.
 163
 164 "Sabotage City" - Destroy a building or the production in the target city.
 165  * UI name can be set using ui_name_sabotage_city
 166  * actor must be on the same tile as the target or on the tile next to it.
 167
 168 "Targeted Sabotage City" - Targeted version of the above.
 169  * UI name can be set using ui_name_targeted_sabotage_city
 170  * actor must be on the same tile as the target or on the tile next to it.
 171
 172 "Poison City" - Kill a citizen in the target city.
 173  * UI name can be set using ui_name_poison_city
 174  * actor must be on the same tile as the target or on the tile next to it.
 175
 176 "Steal Tech" - Steal a random tech from the targets owner.
 177  * UI name can be set using ui_name_steal_tech
 178  * actor must be on the same tile as the target or on the tile next to it.
 179  * target must be foreign.
 180
 181 "Targeted Steal Tech" - Targeted version of the above.
 182  * UI name can be set using ui_name_targeted_steal_tech
 183  * actor must be on the same tile as the target or on the tile next to it.
 184  * target must be foreign.
 185
 186 "Incite City" - Pay the target city to join the actors owners side.
 187  * UI name can be set using ui_name_incite_city
 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 "Steal Gold" - Steal some gold from the owner of the target city.
 192  * UI name can be set using ui_name_steal_gold
 193  * the targets owner must have more than 0 gold.
 194  * actor must be on the same tile as the target or on the tile next to it.
 195  * target must be foreign.
 196
 197 "Establish Trade Route" - Establish a trade route to the target city.
 198  * UI name can be set using ui_name_establish_trade_route
 199  * actor must be on the same tile as the target or on the tile next to it.
 200  * actor must have a home city.
 201  * target must be foreign or trademindist tiles away from that home city.
 202  * trade route type pct (see "Trade settings") can't be 0%.
 203  * it is possible to establish a trade route between the cities as far as
 204    the two cities them self are concerned. (Example: If one of the cities
 205    can't have any trade routes at all it is impossible to establish a new
 206    one.)
 207
 208 "Enter Marketplace" - Get a one time bounus without creating a trade route.
 209  * UI name can be set using ui_name_enter_marketplace
 210  * if force_trade_route is true "Establish Trade Route" must be impossible
 211  * actor must be on the same tile as the target or on the tile next to it.
 212  * actor must have a home city.
 213  * target must be foreign or trademindist tiles away from that home city.
 214  * trade route type (see Trade settings) can't be 0%.
 215
 216 "Help Wonder" - Add the shields used to build the actor to the target city.
 217  * UI name can be set using ui_name_help_wonder
 218  * actor must be on the same tile as the target or on the tile next to it.
 219  * target must be building a wonder.
 220  * target city must still need the extra sheilds to build the wonder.
 221
 222 Actions done by a unit against another unit
 223 ===========================================
 224 "Sabotage Unit" - Halve the target unit's hit points.
 225  * UI name can be set using ui_name_sabotage_unit
 226  * actor must be on the same tile as the target or on the tile next to it.
 227  * target must be visible for the actor.
 228
 229 "Bribe Unit" - Make the target unit join the actors owners side.
 230  * UI name can be set using ui_name_bribe_unit
 231  * actor must be on the same tile as the target or on the tile next to it.
 232  * target must be foreign.
 233  * target must be visible for the actor.