Freeciv
Advertisement

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"
 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[1]. "(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 ( i  before 3.2), Tile ( i  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
 i  New in 2.?
Explanation
"CityTile" Local ( i  before 3.2), Tile ( i  since 3.2), Adjacent, CAdjacent "Center",  i  since 2.6: "Claimed", meaning that the tile is within borders of any nation,  i  since 3.2: "Worked"
"MinYear" World
"TerrainAlter" Local ( i  before 3.2), Tile ( i  since 3.2) "CanMine", "CanIrrigate", "CanRoad", or  i  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
 i  New in 2.2
Explanation
"Base"
 i Replaced by "Extra" in 2.6
???
"AI" Player AI player difficulty level
"TerrainClass" Local ( i  before 3.2), Tile ( i  since 3.2), 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 ( i  before 3.2), Tile ( i  since 3.2), Adjacent, CAdjacent, Traderoute, City
"TechFlag" World, Alliance, Team, Player
"TerrainFlag" Local ( i  before 3.2), Tile ( i  since 3.2), 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  i  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"  i  renamed since 3.1 as "Foreign",  i  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
 i  since 3.2: Tile
 i  Changed in 3.2: Previous meaning of Local range moved to Tile range
"ExtraFlag" Local ( i  before 3.2), Tile ( i  since 3.2), 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", "MovedThisTurn"

Requirement type Supported Ranges
 i  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
 i  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",  i  Since 3.2: "Starved", "Disorder", "Celebration"
"MinForeignPct" City, Traderoute Minimum percent of citizens to be foreigners
Requirement type Supported Ranges
 i  New in 3.2
Explanation
"MinLatitude" Tile, CAdjacent, Adjacent, World A tile's latitude goes from -1000 (south pole) to +1000 (north pole).
 i  Must not be negated at Tile range.
"MaxLatitude"
"BuildingFlag" Local, Tile, City
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 ( i  before 3.2), Tile ( i  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).  i  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"
 i  New in 2.4
"CAdjacent" Cardinally Adjacent omits diagonally 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 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
 i  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.


  1. Obsoletion is tested towards target player and target city even if the wonder is located elsewhere.

See also[]

Editing Rulesets
Editing BuildingsEditing CitiesEditing EffectsEditing GameEditing Governments
Editing NationsEditing StylesEditing TechsEditing TerrainEditing Units
Advertisement