Actions
=======
An action is something a player can do to achieve something in the game.
It has properties like cost, chance of success and effects. Some of those
properties are configurable using effects and other rule set settings. To
learn how to change them read README.effects and the rule set files of
classic. An action enabler allows a player to do an action.

Generalized action enablers
===============================
Some actions have generalized action enablers. An action like that can have
zero, one or more action enablers defined for it in the ruleset. The player can
do the action only when at least one generalized action enabler says that the
action is enabled (and all its hard requirements are fulfilled). A ruleset
author can therefore disable an action by not defining any action enablers for
it in his ruleset.

A generalized action enabler lives in game.ruleset. It consists of the action it
enables and two requirement vectors. The first requirement vector, actor_reqs,
applies to the entity doing the action. The second, target_reqs, applies to its
target. If both requirement vectors are fulfilled the action is enabled as far
as the action enabler is concerned. Note that an action's hard requirements
still may make it impossible.

In some situations an action controlled by generalized action enablers may be
impossible because of limitations in Freeciv it self. Those limitations are
called hard requirements. The hard requirements of each action are documented
below in the section called "Actions and their hard coded requirements".

If the player don't have the knowledge required to find out if an action is
enabled or not the action is shown to the player in case it is possible. The
client will indicate the uncertainty to the player.

Should the player order a unit to do an illegal action the server will
inform the player that his unit was unable to perform the action. The actor
unit may also lose a ruleset configurable amount of move fragments.

Example
=======
[actionenabler_veil_the_threat_of_terror]
action = "Incite City"
actor_reqs    =
    { "type",   "name", "range", "present"
      "DiplRel", "Has Casus Belli", "Local", TRUE
      "DiplRel", "Provided Casus Belli", "Local", FALSE
    }

[actionenabler_go_bind_your_sons_to_exile]
action = "Incite City"
actor_reqs    =
    { "type",   "name", "range", "present"
      "Tech", "Flight", "Player", TRUE
    }
target_reqs    =
    { "type",   "name", "range", "present"
      "Tech", "Writing", "Player", False
    }

Above are two action enablers. They both enable the action "Incite City". If
all the conditions of at least one of them are fulfilled it will be enabled.
No information is given to the player about what action enabler enabled an
action.

The first action enabler, actionenabler_veil_the_threat_of_terror, is
simple. It allows a player to incite a city if he has a reason to declare
war on its owner AND the cities owner don't have a reason to declare war on
him.

The second action enabler, actionenabler_go_bind_your_sons_to_exile, is more
complex. It allows a player that has Flight to bribe the cities of
civilizations that don't have Writing. The complexity is caused by the
requirement that the target don't know Writing. If the civilization of the
target city knows Writing or not may be unknown to the acting player. To
avoid this complexity a requirement that the acting player has an embassy to
the target cities civilization (and therefore knowledge about its techs) can
be added.

Requirement vector rules
========================
An action enabler has two requirement vectors that must be true at the same
time. This creates some corner cases you won't find with single requirement
vectors. The rules below tries to deal with them.

A "DiplRel" requirement with the range "Local" should always be put in the
actor requirements.
 * A local DiplRel requirement can always be expressed as an actor
   requirement.
 * Only having to care about local DiplRel requirements in the actor
   requirements allows the Freeciv code responsible for reasoning about
   action enablers to be simpler and faster.
 * If player A having a diplomatic relationship to player B implies that
   player B has the same relationship to player A the relationship is
   symmetric. Examples: "Is foreign" and "War"
 * Symmetric local DiplRel requirements can be moved directly from the
   target requirement vector to the actor requirement vector.
 * Asymmetric local DiplRel requirements must test for the same thing in
   the opposite direction. Example: "Hosts embassy" -> "Has embassy"

Actions and Lua
===============
Right before an action is executed, but after it is known to be legal, a
signal is emitted to Lua. It has access to the same information as the
server. It obviously don't have access to the result of the action since it
isn't done yet.

The signal's name starts with action_started_, then the actor kind, then
another _ and in the end the target kind. The signal that is emitted when a
unit performs an action on a city is therefore action_started_unit_city.

The signal has three parameters. The first parameter is the action that is
about to get started. The second is the actor. The third parameter is the
target. The parameters of action_started_unit_city is therefore action,
actor_unit and finally target city.

To get the rule name of an action, that is the name used in action enablers,
you can use the method rule_name(). To get a translated name that is nice to
show to players use name_translation().

Example 1
=========
The following Lua code will log all actions done by any unit to a city or to
another unit:

function action_started_callback(action, actor, target)
  log.normal(_("%s (rule name: %s) performed by %s on %s"),
             action:name_translation(),
             action:rule_name(),
             actor.owner.nation:plural_translation(),
             target.owner.nation:plural_translation())
end

signal.connect("action_started_unit_city", "action_started_callback")
signal.connect("action_started_unit_unit", "action_started_callback")

Example 2
=========
The following Lua code will make a player that poisons the population of
cities risk civil war:

function action_started_callback(action, actor, target)
  if action:rule_name() == "Poison City" then
     edit.civil_war(actor.owner, 5);
  end
end

signal.connect("action_started_unit_city", "action_started_callback")

Actions and their hard coded requirements
=========================================

Actions done by a unit against a city
=====================================
"Establish Embassy" - Establish a real embassy to the target player
 * UI name can be set using ui_name_establish_embassy
 * actor must be aware that the target exists
 * actor can't have a real embassy to the target player
 * actor must be on the same tile as the target or on the tile next to it.
 * target must be foreign.

"Investigate City" - Look at the city dialog of a foreign city
 * UI name can be set using ui_name_investigate_city
 * actor must be aware that the target exists
 * actor must be on the same tile as the target or on the tile next to it.
 * target must be foreign.

"Sabotage City" - Destroy a building or the production in the target city.
 * UI name can be set using ui_name_sabotage_city
 * actor must be aware that the target exists
 * actor must be on the same tile as the target or on the tile next to it.

"Targeted Sabotage City" - Targeted version of the above.
 * UI name can be set using ui_name_targeted_sabotage_city
 * actor must be aware that the target exists
 * actor must be on the same tile as the target or on the tile next to it.

"Poison City" - Kill a citizen in the target city.
 * UI name can be set using ui_name_poison_city
 * actor must be aware that the target exists
 * actor must be on the same tile as the target or on the tile next to it.

"Steal Tech" - Steal a random tech from the targets owner.
 * UI name can be set using ui_name_steal_tech
 * actor must be aware that the target exists
 * actor must be on the same tile as the target or on the tile next to it.
 * target must be foreign.

"Targeted Steal Tech" - Targeted version of the above.
 * UI name can be set using ui_name_targeted_steal_tech
 * actor must be aware that the target exists
 * actor must be on the same tile as the target or on the tile next to it.
 * target must be foreign.

"Incite City" - Pay the target city to join the actors owners side.
 * UI name can be set using ui_name_incite_city
 * actor must be aware that the target exists
 * actor must be on the same tile as the target or on the tile next to it.
 * target must be foreign.

"Steal Gold" - Steal some gold from the owner of the target city.
 * UI name can be set using ui_name_steal_gold
 * adjustable with the Max_Stolen_Gold_Pm effect and with the
   Thiefs_Share_Pm effect
 * actor must be aware that the target exists
 * the targets owner must have more than 0 gold.
 * actor must be on the same tile as the target or on the tile next to it.
 * target must be foreign.

"Establish Trade Route" - Establish a trade route to the target city.
 * UI name can be set using ui_name_establish_trade_route
 * actor must be aware that the target exists
 * actor must be on the same tile as the target or on the tile next to it.
 * actor must have a home city.
 * target must be foreign or trademindist tiles away from that home city.
 * trade route type pct (see "Trade settings") can't be 0%.
 * it is possible to establish a trade route between the cities as far as
   the two cities them self are concerned. (Example: If one of the cities
   can't have any trade routes at all it is impossible to establish a new
   one.)

"Enter Marketplace" - Get a one time bounus without creating a trade route.
 * UI name can be set using ui_name_enter_marketplace
 * actor must be aware that the target exists
 * if force_trade_route is true "Establish Trade Route" must be impossible
 * actor must be on the same tile as the target or on the tile next to it.
 * actor must have a home city.
 * target must be foreign or trademindist tiles away from that home city.
 * trade route type (see Trade settings) can't be 0%.

"Help Wonder" - Add the shields used to build the actor to the target city.
 * UI name can be set using ui_name_help_wonder
 * actor must be aware that the target exists
 * actor must be on the same tile as the target or on the tile next to it.
 * target must be building a wonder.
 * target city must still need the extra sheilds to build the wonder.

Actions done by a unit against another unit
===========================================
"Sabotage Unit" - Halve the target unit's hit points.
 * UI name can be set using ui_name_sabotage_unit
 * actor must be on the same tile as the target or on the tile next to it.
 * target must be visible for the actor.

"Bribe Unit" - Make the target unit join the actors owners side.
 * UI name can be set using ui_name_bribe_unit
 * actor must be on the same tile as the target or on the tile next to it.
 * target must be foreign.
 * target must be visible for the actor.
