Requirements

Requirements are elementary rules of Freeciv ruleset. Each of them represents a statement that can be true, false, or sometimes undefined (that can be resolved to either true or false in specific cases). Requirements typically are bundled into requirement vectors that represent complex statements that are true if and only if each requirement inside them is true (with an exception of nreqs vectors in v.2.4 that have "or" logical operation, but they are negated overall). These vectors are found in effects, action enablers, disaster causes and other elements of the ruleset.

Elements of a requirement

type

The property of something that is checked, e.g. wether we are interested in a number of units on a tile, an extra on it, its owning player etc.

Requirement type	Supported Ranges	Explanation
"None"		(default)
"Special"  i Replaced by "Extra" in 2.6	???
"Building"	World, Player, Continent, City, Local  i  since 2.6: Alliance, Team, Traderoute	Only wonders can have range "Continent", or "Player" or higher (and thus "survives" flag). Always FALSE for buildings obsolete for the target. "(C)Adjacent" ranges don't give ruleset errors but are always FALSE. "Local" range gives positive result iff the target building equals name (restricts "Upkeep_Free" effect to a specific building).
"Gov"	Player
"MinSize"	Traderoute, City	Minimum size of a city required.
"Nation"	World, Alliance, Team, Player
"OutputType"	Local	"Food", "Shield", "Trade", "Gold", "Luxury", "Science"
"Tech"	World, Player  i  since 2.6: Alliance, Team
"Terrain"	Local, Adjacent, CAdjacent, Traderoute, City
"UnitClass"	Local	Effect "Defend_Bonus" evaluates Attacker only.
"UnitFlag"	Local	Effect "Defend_Bonus" evaluates Attacker only.
"UnitType"	Local	Effect "Defend_Bonus" evaluates Attacker only.
Requirement type	Supported Ranges  i  New in 2.?	Explanation
"CityTile"	Local, Adjacent, CAdjacent	"Center" or "Claimed", the latter means that the tile is within borders of any nation
"MinYear"	World
"TerrainAlter"	Local	"CanMine", "CanIrrigate" or "CanRoad": if the actual terrain has a defined result of mining/irrigation or a positive road building time.
"UnitClassFlag"	Local	Effect "Defend_Bonus" evaluates Attacker only.
Requirement type	Supported Ranges  i  New in 2.2	Explanation
"Base"  i Replaced by "Extra" in 2.6	???
"AI"	Player	AI player difficulty level
"TerrainClass"	Local, Adjacent, CAdjacent, Traderoute, City	Either "Land" or "Oceanic"
Requirement type	Supported Ranges  i  New in 2.5	Explanation
"Road"  i Replaced by "Extra" in 2.6	???
"Resource"  i Replaced by "Extra" in 3.0	Local, Adjacent, CAdjacent, Traderoute, City
"Nationality"	Traderoute, City	Are there any citizens of given nationality.
"RoadFlag"	Local, Adjacent, CAdjacent, Traderoute, City
"TechFlag"	World, Alliance, Team, Player
"TerrainFlag"	Local, Adjacent, CAdjacent, Traderoute, City
Requirement type	Supported Ranges  i  New in 2.6	Explanation
"Achievement"	World, Alliance, Team, Player
"BaseFlag"	Local, Adjacent, CAdjacent, Traderoute, City
"DiplRel"	World, Alliance, Team, Player, Local	"Armistice", "War", "Cease-fire", "Peace", "Alliance", "Never met", "Team", "Gives shared vision", "Receives shared vision", "Hosts embassy", "Has embassy", "Hosts real embassy", "Has real embassy","Has Casus Belli", "Provided Casus Belli", "Is foreign" "Local" range tests relation between specific players while "Player" and upper tests if any player in the range has such relation to any other living player
"Extra"	Local, Adjacent, CAdjacent, Traderoute, City
"ExtraFlag"	Local, Adjacent, CAdjacent, Traderoute, City
"MinCulture"	World, Alliance, Team, Player	A player in the range has this much culture
	Traderoute, City	A city in the range has this much culture
"MinMoveFrags"	Local	Minimum move fragments the unit must have left
"Style"	Player	Civilization Style
"UnitState"	Local	"Transported", "OnLivableTile",  i  New in 3.0: "Transporting", "OnDomesticTile", "HasHomeCity", "OnNativeTile",  i  New in 3.1: "InNativeExtra"
Requirement type	Supported Ranges  i  New in 3.0	Explanation
"Action"	Local	"Attack", "Bombard"...
"BuildingGenus"	Local	"GreatWonder", "SmallWonder", "Improvement", "Special"
"Good"	City, Traderoute	If any traderoute brings the good into the city
"MinCalFrag"	World	Calendar fragments passed since the start of the game year
"MinTechs"	Player, World	For World range, counts all techs learned by any player (e.g. P1 knows Ta, Tb, P2 knows Ta, Tc, then 2 for P1 and P2 and 3 for world)
"ServerSetting"	World	3.x: Supports only boolean-type settings (e.g. "mgr_foodneeded")
Requirement type	Supported Ranges  i  ???	Explanation
"Age"	Local, City, Player	Target unit, city or player is in the game for at least so many turns.
"MaxUnitsOnTile"	Local, CAdjacent, Adjacent	If on at least any one of the tiles in the range currently stand not more than this number of units (not in sum, not on every one)
"NationGroup"	Player, Team, Alliance, World
"Specialist"	Local	The specialist (e.g. "Scientist") to consider in a per-citizen effect.
"Topology"	World	"WrapX" (glue E-W), "WrapY" (glue N-S), "ISO"(metric) or "Hex"(agonal).

range

Kind of target we are checking, e.g. a player, a city, any city trading with a city, or the whole world. Ranges are limited for specific requirement types and targets (e.g. you can't get DiplRel of a continent). For terrain-specific requirements accepting "City"/"Traderoute" range, the city/cities working map is iterated over.

Requirement range	Explanation
"None"
"Adjacent"
"City"
"Continent"	Continents are bodies of land tiles connected by paths of steps between adjacent tiles.
"Local"
"Player"
"World"
	i  New in 2.4
"CAdjacent"	Cardinally Adjacent omits diagnally adjacent tiles on tetragonal maps
	i  New in 2.6
"Alliance"	Living players allied (including teamed) with the target one including him/herself, not necessarily with each other.
"Team"
"Traderoute"	Tests either end of the route.

name

Not necessarily something you would call "name", but a value of the property for the target.

Flags

survives

The requirement is met even after the target (must be a wonder) is destroyed.

quiet

Do not generate automatic help for the requirement.

present (2.6+)/negated (2.5)

Wether the requirement value should be negated.

Example of a requirement vector

Consider a definition of an effect:

[effect_hydro_plant]
name  = "Output_Bonus"
value = 25
reqs  = {"type", "name", "range"
         "Building", "Factory", "City"
         "Building", "Hydro Plant", "City"
         "OutputType", "Shield", "Local"
        } 

Here reqs is the requirement vector for the effect. First line lists the elements of the requirement, and all the other lines list their values in the same order. The flags are optional and can be omitted from the header line if they are never set in the vector ("survives", "quiet" and (2.5 only) "negated" default to FALSE and "present" (2.6 and later) to TRUE) and from any value line where they are default. The requirements tell that the effect of increasing output on 25 % happens in cities where there are buildings Factory and HydroPlant for Shield-type output.

Programming realization

Requirements are described in common/requirements.[ch]. Each requirement is stored in struct requirement which contains, among others, struct universal source field in which the effect's type and name are stored; possible types are listed in specenum universals_n (VUT_...) (in common/fc_types.h) while possible ranges are in req_range (REQ_RANGE_...). The main function that calculates a requirement (redirecting necessary information to a function appropriate for specific requirement type and range) is

is_req_active(const struct player *target_player, // Player and upper ranges
		   const struct player *other_player, // To whom calculate DiplRel at Local range
		   const struct city *target_city, // City and base of Traderoute range
		   const struct impr_type *target_building, 
		   const struct tile *target_tile,// All the rest is referred as "Local" range
                   const struct unit *target_unit,
                   const struct unit_type *target_unittype,// If not specified, calculated from target_unit
		   const struct output_type *target_output,// shields/science/etc.
		   const struct specialist *target_specialist,
		   const struct action *target_action,//new in 3.0
		   const struct requirement *req,// The requirement itself
                   const enum   req_problem_type prob_type)// Wether resolve uncertainity to true or false

This function is usually called through are_reqs_active() that has the same parameters except being applied to a vector of requirements that are tested in order (it had been suggested to reorder them for optimisation but that is not actually done). When and how the parameters are filled can be seen from certain places of the code; there are multiple wrapping functions to call this one that mask irrelevant parameters. For World-range effects, all parameters are NULLs. Effects for units use as a city parameter the city where the unit is situated now or is being built, if any; requirements defined for terrain extras mostly ignore the city. Effects generally don't fill other_player ("Illegal_Action_Move_Cost" is among the exceptions) while action enablers use target player for the actor reqs and actor player for the target reqs, and extras' reqs supply tile owner as it.

Requirement vectors have some additional restrictions that block loading senseless rules (e.g. requiring both terrain and terrain class, or two min-same-thing requirements), that is handled in server/rssanity.c. The text that is added to automatic help for game objects for non-quiet requirements is defined in common/reqtext.c.