Requirements

Requirements are elementary statements in the rules of a Freeciv ruleset. Each of them, applied to a set of certain game objects (below as factors), 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 and obsolete_by vectors from buildings.ruleset 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" 	 	Dummy requirement, always fulfilled
"Special"Replaced by "Extra" in 2.6 	??? 	
"Building" 	World, Player, Continent, City, Local 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 targetObsoletion is tested towards target player and target city even if the wonder is located elsewhere.. "(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 since 2.6: Alliance, Team 	
"Terrain" 	Local ( before 3.2), Tile ( since 3.2), 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 New in 2.? 	Explanation
"CityTile" 	Local ( before 3.2), Tile ( since 3.2), Adjacent, CAdjacent 	"Center", since 2.6: "Claimed", meaning that the tile is within borders of any nation, since 3.2: "Worked"
"MinYear" 	World 	
"TerrainAlter" 	Local ( before 3.2), Tile ( since 3.2) 	"CanMine", "CanIrrigate", "CanRoad", or since 3.2 "CanBase": if the actual terrain has a defined result of mining/irrigation or a positive road or base building time.
"UnitClassFlag" 	Local 	Effect "Defend_Bonus" evaluates Attacker only.
Requirement type 	Supported Ranges New in 2.2 	Explanation
"Base"Replaced by "Extra" in 2.6 	??? 	
"AI" 	Player 	AI player difficulty level
"TerrainClass" 	Local ( before 3.2), Tile ( since 3.2), Adjacent, CAdjacent, Traderoute, City	Either "Land" or "Oceanic"
Requirement type 	Supported Ranges New in 2.5 	Explanation
"Road"Replaced by "Extra" in 2.6 	??? 	
"Resource"Replaced by "Extra" in 3.0	Local, Adjacent, CAdjacent, Traderoute, City 	
"Nationality" 	Traderoute, City 	Are there any citizens of given nationality.
"RoadFlag" 	Local ( before 3.2), Tile ( since 3.2), Adjacent, CAdjacent, Traderoute, City	
"TechFlag" 	World, Alliance, Team, Player 	
"TerrainFlag" 	Local ( before 3.2), Tile ( since 3.2), Adjacent, CAdjacent, Traderoute, City	
Requirement type 	Supported Ranges New in 2.6 	Explanation
"Achievement" 	World, Alliance, Team, Player 	
"BaseFlag" 	Local, Adjacent, CAdjacent, Traderoute, City 	Removed in 3.1
"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" renamed since 3.1 as "Foreign", since 3.2: "Has team embassy", "Hosts team embassy""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 since 3.2: Tile 	Changed in 3.2: Previous meaning of Local range moved to Tile range
"ExtraFlag" 	Local ( before 3.2), Tile ( since 3.2), Adjacent, CAdjacent, Traderoute, City	
"MinCulture" 	World, Alliance, Team, Player 	A player in the range has this much culture
"MinCulture" 	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",
 New in 3.0: "Transporting", "OnDomesticTile", "HasHomeCity", "OnNativeTile",
 New in 3.1: "InNativeExtra", "MovedThisTurn"
Requirement type 	Supported Ranges New in 3.0 	Explanation
"Action" 	Local 	"Attack", "Bombard"...
"BuildingGenus" 	Local 	"GreatWonder", "SmallWonder", "Improvement", "Special"
"Good" 	City 	If any traderoute brings the good into the city
"MinCalFrag" 	World 	Calendar fragments passed since the start of the game year
"MinHitPoints" 	Local 	Unit has at least so many hp
"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 New in 3.1 	Explanation
"Activity" 	Local 	Unit activity; "Idle", "Pollution", "Mine", "Irrigate", "Fortified", "Fortress", "Sentry", "Pillage", "Goto", "Explore", "Transform", "Fortifying", "Fallout", "Base", "Road", "Convert", "Cultivate", or "Plant"
"CityStatus" 	City, Traderoute 	"OwnedByOriginal", Since 3.2: "Starved", "Disorder", "Celebration"
"MinForeignPct" 	City, Traderoute 	Minimum percent of citizens to be foreigners
Requirement type 	Supported Ranges New in 3.2 	Explanation
"MinLatitude" 	Tile, CAdjacent, Adjacent, World 	A tile's latitude goes from -1000 (south pole) to +1000 (north pole). Must not be negated at Tile range.
"MaxLatitude" 	Tile, CAdjacent, Adjacent, World 	A tile's latitude goes from -1000 (south pole) to +1000 (north pole). Must not be negated at Tile range.
"BuildingFlag" 	Local, Tile, City 	
Requirement type 	Supported Ranges ??? 	Explanation
"Age" 	Local, City, Player 	Target unit, city or player is in the game for at least so many turns.
"MaxUnitsOnTile" 	Local ( before 3.2), Tile ( since 3.2), 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). Units with UnitClassFlag "DoesntOccupyTile" and transported units count.
"NationGroup" 	Player, Team, Alliance, World 	
"Specialist" 	Local 	The specialist (e.g. "Scientist") to consider in a per-citizen effect.
"Topology" 	World 	"ISO"(metric) or "Hex"(agonal). before 3.2: "WrapX" (glue E-W), "WrapY" (glue N-S)
===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. "(C)Adjacent" ranges include the target tile.
Requirement range	Explanation
"None" 	
"Adjacent" 	
"City" 	
"Continent" 	Continents are bodies of land tiles connected by paths of steps between adjacent tiles (oceans are the same for oceanic terrain masses, considered continents with negative numbers). Actually, this range scans only cities of the target player on the target city's continent (and only for a building that is a wonder).
"Local" 	
"Player" 	
"World" 	
 	New in 2.4
"CAdjacent" 	Cardinally Adjacent omits diagonally adjacent tiles on tetragonal maps
 	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 cities at either end of the route, i.e. the target one and each one that has a route to or from it, wether any of them matches
 	New in 3.2
"Tile" 	The tile a requirement is evaluated against; this takes over a part of the responsibilities previously held by the Local range.
===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 is destroyed. This flag is supported only for requirements of type "Building" (if the building is a great or small wonder and the range is not "Continent"), "Nation" (with a range "World" only, still true if a nation ever existed now is left only in chronicles but not if a player is removed by /remove command) and "Advance" (range "World").
;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(), that in v.2.6 and 3.0 has the prototype
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
Since v.3.1, most of the factors (except the other player) are bundled in a context structure:
struct req_context {
 const struct player *player;
 const struct city *city;
 const struct tile *tile;
 /* for local-ranged requirements only */
 const struct unit *unit;
 const struct unit_type *unittype;
 const struct impr_type *building;
 const struct extra_type *extra;
 const struct output_type *output;
 const struct specialist *specialist;
 const struct action *action;
};
bool is_req_active(const struct req_context *context,
 const struct player *other_player,
 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 (except sometimes "Trade_Revenue_Bonus" and "Unit_Bribe_Cost_Pct"); 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.
----
== See also ==
Category:Editing rulesets