Editing Effects

Modpack UI icon

This page partially describes the contents of a ruleset collection. It is intended as developer reference and for people wanting to create/compile alternative rulesets for Freeciv.

The anatomy of an effects ruleset file

…/data/classic/effects.ruleset

The effects.ruleset file contains all effects in play in a Freeciv scenario. Typically it contains *include ai_effects.ruleset as cheat sheet for AIs.

They have the following form:

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

The text in the brackets is the entry name, which just has to be unique, but is otherwise not used.

reqs is a requirements vector:

The name field tells Freeciv which Effect Type you are defining. The value is the effect's value, which depends on which effect it is. The reqs table contain a list of requirements for this effect being in effect. You need to satisfy all requirements listed here for this effect to take effect in the game.

The value field is the integer amount parameter for many effects (must be in the range -32767 to 32767; some do not handle negative numbers well).

The reqs table consists of sets of Requirement Type, Requirement, and Requirement Range.

Some requirement types may only work at certain ranges. In particular, at present, "Continent" range effects can affect only cities and units in cities.

2.4 Negation

There is the nreqs table which is the opposite of the reqs table, these are conditions which prevent the effect from taking place. Any one of the nreq conditions will prevent the effect from taking effect.

nreqs  = {"type", "name", "range"
         "Building", "Factory", "City"
        } 

2.5 Negation

A requirement may have a negated field, and if this is 'TRUE', the requirement is negated.

reqs  = {"type", "name", "range", "negated"
         "Building", "Factory", "City", TRUE
        } 

2.6 Negation

The negated field is replaced with present field, defaulting to 'TRUE', but if 'FALSE' requirement must not be fulfilled.

reqs  = {"type", "name", "range", "present"
         "Building", "Factory", "City", FALSE
        } 

Survives

A requirement may have a survives field, and if this is 'TRUE', the effect survives destruction (wonders only).

[effect_plastics_slowdown]
type    = "Slow_Down_Timeline"
value   = 1
reqs    =
    { "type", "name", "range", "survives"
      "Tech", "Plastics", "World", TRUE
    }

Effect Types

Effect Type	When affects game	Factors that may be considered in reqs				Explanation
		Player	City	Tile	Other
Empire_Size_Mod  i  Removed in version 2.2.						Once your civilization has more cities than amount + the server setting 'cityfactor', each city gets one more unhappy citizen.
No_Incite  i  Replaced with the Incite City action in 2.6						City cannot be incited.
Revolution_When_Unhappy  i  Replaced with Revolution_Unhappiness in 2.6						If a city owned by this player is in revolt for more than two turns, government falls.
Unbribable_Units  i  Replaced with the Bribe Unit action in 2.6						Units cannot be bribed.
Airlift	Phase end	Each player	Each player's city	City center	-	Allow airlift to/from a city. Starting from 2.2 amount of units can airlift each turn.
Any_Government	Any time	Any player	-	-	-	Allow instant government changes.
Capital_City	Any time	City owner	Any city	City center	-	The city with this effect is the capital city.
City_Vision_Radius_Sq	Virtually any time	City owner	City	City center	-	Increase city vision radius in squared distance by amount tiles.
Civil_War_Chance	When a capital is taken (maybe destroyed) and there are free player slots	Loser	-	-	-	Base chance in percent of a nation being split by civil war when its capital is captured is increased by this amount. This percentage is increased by 5 for each city in civil disorder and reduced by 5 for each one celebrating.
Defend_Bonus	When a unit defends	Unit owner	City on the tile (if present)	Unit tile	Unit type	Increases defensive bonuses of units. Any unit requirements on this effect will be applied to the _attacking_ unit. The defensive bonus is ignored by attackers with "IgWall" flag (up to 2.5). Attackers with "BadWallAttacker" flag will have their firepower set to 1.
Empire_Size_Step	Whenever a city happiness is updated	City owner	-	-	-	After your civilization reaches Empire_Size_Base size, it gets one more unhappy citizen for each amount of cities it gets above that. Set to zero to disable. You can use Empire_Size_Step even though Empire_Size_Base is zero.
Enable_Nuke	When production of a unit is changed to or is ready to happen	City owner	-	-	-	Allows the production of nuclear weapons.
Enable_Space	When production of a spaceship part is changed to or is ready to happen	City owner	-	-	-	Allows the production of space components.
Force_Content	Whenever the city happiness is updated	City owner	Any city	City tile	-	Make amount unhappy citizens content. Applied after martial law and unit penalties.
Gain_AI_Love	Phase start	Player	-	-	-	Gain amount points of "AI love" with AI(s) per turn. Maximal is 1000.
Give_Imm_Tech	When a building is finished	City owner	City	-	Building built	Give amount techs immediately.
Growth_Food	Phase end, when processing a city that changes its size, before and after production	City owner	City	City tile	-	Food left after cities grow or shrink is amount percent of the capacity of the city's foodbox. This also affects the 'aqueductloss' penalty.
Fanatics	Phase end	Player	-	-	-	Units with "Fanatics" flag incur no upkeep.
Happiness_To_Gold	Phase end	City owner	City	City tile	-	Make all Make_Content and Force_Content effects generate also gold in the same amount.
Has_Senate	When a player tries to break a treaty	Player	-	-	-	Has a senate that prevents declarations of war in most cases.
Have_Embassies	When a new tech is got known	Player learned a tech	-	-	-	Like having embassies with all the players one has ever had contact with. In 2.6 and prior provided embassy-like effect with all the players (like having both Have_Contacts and Have_Embassies)
HP_Regen	Phase start	Unit owner	Tile city (if present)	Unit tile	Unit, unit type	Units that do not move recover amount percentage of their full hitpoints per turn.
Incite_Cost_Pct	Whenever one tries to incite a city	City owner	City	City tile	-	Increases revolt cost by amount percent.
Inspire_Partisans	Queried by Lua callbacks, P and C supplied by Lua	P (former city owner)	C (a city)	City tile	-	Partisan units (defined in units.ruleset) may spring up. Partially unhardcoded and may be (more) city-dependent since 2.5.
Make_Content	Whenever the city happiness is updated	City owner	City	City tile	-	Make amount unhappy citizens content. Applied before martial law and unit penalties.
Make_Content_Mil						Make amount unhappy citizens caused by units outside of a city content.
Make_Content_Mil_Per						Make amount per unit of unhappy citizens caused by units outside of a city content.
Make_Happy						Make amount citizens happy.
Martial_Law_Each						The amount of citizens pacified by each military unit giving martial law.
Martial_Law_Max						The maximum amount of units that will give martial law in city.
Max_Rates	When one tries to change taxes	Player	-	-	-	The maximum setting for each tax rate is amount.
Move_Bonus	A lot (phase start, combat, transforming a unit...)	Unit owner	City on the tile (if present)	Unit tile	Unit type	Add amount movement to units. Use UnitClass' requirement with range of 'Local' to give it a specific class of units only.
No_Anarchy	When a player tries to break a treaty	Player	-	-	-	No period of anarchy between government changes. (This also neuters the Has_Senate effect.)
No_Diplomacy	Players make contact, split by CW or try to meet	Player	-	-	-	Cannot use any diplomacy.
No_Sink_Deep  i  Removed in version 2.2.						Triremes no longer sink when on dangerous seas.
No_Unhappy	Whenever the city happiness is updated	City owner	City	City tile	-	No citizens in the city are ever unhappy.
Nuke_Proof	When a nuclear unit tries to explode near the city	City owner	City	Targeted tile	-	City is nuke proof. Since 2.6, specifies the percentage chance of deflecting a nuke.
Output_Add_Tile	Phase end, in city processing order	City owner	Any city	Each worked tile	Output type	Add amount to each worked tile.
Output_Bonus						City production is increased by amount percent.
Output_Bonus_2						City production is increased by amount percent after Output_Bonus, so is multiplicative with it.
Output_Inc_Tile						Add amount to each worked tile that already has at least 1 output.
Output_Inc_Tile_Celebrate						Tiles get amount extra output when city working them is celebrating.
Output_Penalty_Tile						When a tile yields more output than amount, it gets a penalty of -1.
Output_Per_Tile						Increase tile output by amount percent.
Output_Waste	Phase end	City owner	Each city	-	Output type	Base amount in percentage that each city has in waste. Waste can be used with any output type, use an OutputType requirement to specify which.
Output_Waste_By_Distance						For each tile in real distance that a city is from your capital, it gets amount of extra waste.
Output_Waste_Pct						Reduce waste by amount percent.
Pollu_Pop_Pct	Phase end	City owner	Each city	-	-	Increases pollution caused by each unit of population by amount percent (adds to baseline of 100%, i.e. 1 pollution per citizen).
Pollu_Prod_Pct						Increases pollution caused by shields by amount percent.
Rapture_Grow	Phase end	City owner	City	City tile	-	Can rapture grow cities.
Reveal_Cities	Phase end, after all players are processed	Player	-	-	-	Immediately make all cities known (with their tiles).
Reveal_Map						Immediately make entire map known.
Size_Adj	Whenever a city tries to grow by food, adding etc.	City owner	City	City tile	-	Increase maximum size of a city by amount.
Size_Unlimit						Make the size of a city unlimited.
Slow_Down_Timeline	Between turn end and next turn start	-	-	-	-	Slow down the timeline based on the AMOUNT. If AMOUNT >= 3 the timeline will be max 1 year/turn; with AMOUNT == 2 it is max 2 years/turn; with AMOUNT == 1 it is max 5 years/turn; with AMOUNT <= 0 the timeline is unaffected. The effect will be ignored if game.spacerace isn't set.
Specialist_Output	Phase end	City owner	Any city	-	Specialist type, output type	Specify what outputs a specialist is producing. Should be used with an OutputType requirement.
Spy_Resistant	Whenever a diplomatic attack is performed on a tile with a diplomatic defender	Owner of the targrted tile (if present)	City on the tile (if present)	Targeted tile	-	If a spy specifies a target for sabotage, then she has an AMOUNT percent chance to fail. Also in diplomatic combat defending diplomatic units in cities will get an AMOUNT percent bonus. All Spy_Resistant's are summed before being applied.
SS_Structural, SS_Component, SS_Module	When switching to or producing a building	-	-	-	Only a "Building" requirement with any range turns these effects on	A part of a spaceship; this is a "Local" ranged effect. It (for now) applies to improvements which cannot be built unless "Enable_Space" is felt. Buildings which have this effect should probably not be given any other effects.
Tech_Parasite	Phase end, before processing cities	Each player	-	-	-	Gain any advance known already by amount number of other players. In 2.3 to 2.5, counts research-sharing teams instead of players, in 2.6.0 probably by accident restored old behaviour. Note that if you have two such effects, they combine into one much worse effect (the number of players required to gain an advance is increased).
Trade_Revenue_Bonus	When a caravan arrives into a city	Owner of target city / other: owner of caravan's original city	Target city	Target city tile	Since 2.6: caravan action ("Establish Trade Route"/"Enter Marketplace")	Trade revenue is multiplied by pow(2, amount/1000). The amount value is taken from the caravan's home city.
Unhappy_Factor	Whenever a city's happiness is updated	City owner	-	-	-	Multiply unhappy unit upkeep by amount.
Unit_No_Lose_Pop	When a city is attacked or bombarded	City owner	City	City tile	-	No population lost when a city's defender is lost.
Unit_Recover	Phase start	Unit owner	City on the tile (if present)	Unit tile	Unit, unit type	Units recover amount extra hitpoints per turn.
Unit_Upkeep_Free_Per_City	Phase end	City owner	City	-	Output type	In each city unit upkeep is deducted by this amount. As usual, you can use with OutputType requirement to specify which kind of upkeep this should be.
Unit_Vision_Radius_Sq	Virtually any time	Unit owner	Tile city (if present)	Unit tile	Unit type	Increase unit vision radius in squared distance by amount tiles.
Upgrade_Unit	Phase start, before restoring hp/mp	Player	-	-	-	Upgrade amount obsolete units per turn.
Upkeep_Free	Phase end	City owner	Each city	-	Each building in the city	Improvements with amount or less upkeep cost become free to upkeep (others are unaffected).
Upkeep_Factor	Phase end	Player	-	-	Output type	Multiply unit upkeep by amount.
Veteran_Build	When a unit is produced (even consuming last pop from a city)	City owner	City	City tile	Unit type	New units of this type start with veterancy. In 2.4 and prior, the amount value is ignored, so that you can have multiple Veteran_Build effects, and units will only get 1 free veterancy level. In 2.5 and later, amount specifies the initial veteran level and is cumulative.
Veteran_Combat	When a unit may become a combat veteran	Unit owner	Tile city (if present)	Unit tile	Unit, unit type	Increases the chance of units of this type becoming veteran after combat by amount percent.
Effect type	Value Range  i  New in 2.1					Explanation
Visible_Walls	When a city packet is sent to a client (no game value).	City owner	City	City tile	-	Positive amount only instructs clients to use wall graphics for city.  i  New in 2.6: Exact amount tells wall set to draw
Effect type	Value Range  i  New in 2.2					Explanation
City_Unhappy_Size	Whenever a city happiness is updated	City owner	-	-	-	Each citizen after amount of citizens are unhappy instead of content.
Empire_Size_Base						Once your civilization has more cities than the value of this effect, each city gets one more unhappy citizen. If the sum of this effect and Empire_Size_Step is zero, there is no such penalty.
Health_Pct	Phase end, when ilness may strike a city	City owner	City	City tile	-	Reduces possibility of illness (plague) in a city by amount percent. This has no effect in rulesets which do not have plague enabled.
Migration_Pct	Turn end	City owner	City	City center	-	Increase the calculated migration score for the a city by amount in percent.
Shield2Gold_Factor	Phase end	Player	-	-	-	Factor in percent for the conversion of unit shield upkeep to gold upkeep. A value of 200 would transfor 1 shield upkeep to 2 gold upkeep. The range of this effect must be player or world. Note that only units with the "Shield2Gold" flag will be affected by this.
Tech_Cost_Factor	Phase end	Player	-	-	-	Multiplier for research cost.
Tile_Workable	A lot (units move, city size or radius change...)	City owner	City	Tile	-	If value != 0, city can work target tile.
Turn_Years	Between turn end and next turn start	-	-	-	-	Calendar advances amount years each turn unless Slow_Down_Timeline effects override this.
Upgrade_Price_Pct	Player orders to upgrade a unit	Player	-	-	-	Increases unit upgrade cost by amount percent. This effect works at player level. You cannot adjust upgrade costs for certain unit type or for units upgraded in certain city.
Effect type	Value Range  i  New in 2.3					Explanation
City_Build_Slots	When a unit is produced	City owner	City	City tile	-	Increase the number of units with no population cost a city can build in a turn by amount. The required shields must be available.
City_Radius_Sq	On virtually any city change	City owner	City	City tile	-	Increase the squared city radius by amount. (In old versions could only usefully have "MinSize", "Building", or "Tech" requirements)
Tech_Upkeep_Free	Phase end, after processing all cities of all players	Each player	-	-	-	If this value is greater than 0, the tech upkeep is reduced by this value. For tech upkeep style Basic this is total reduction, for tech upkeep style Cities (new in 2.6) this is applied to every city.
Effect type	Value Range  i  New in 2.4					Explanation
City_Image						The index for the city image of the given city style. Allows to align the city image with the city radii.
Irrig_Possible						If value of this effect > 0, target tile can be irrigated. In addition to requirements of this effect, there's still hardcoded requirement that unit doing the irrigation has "Settlers" flag, and terrain.ruleset controls which terrain types can be irrigated at all.
Effect type	Value Range  i  New in 2.5					Explanation
Enemy_Citizen_Unhappy_Pct						During war, citizens of enemy nationality are more unhappy. Value of this effect tells how many percents of the enemy citizens in cities get unhappy because of the war.
Gov_Center						City with non-zero effect value is considered Governmental center. Unless corruption is flat for entire nation, it depends on distance to nearest such center. In earlier versions this effect was coupled in to Capital_City effect.
Irrig_TF_Possible						If value of this effect > 0, tile terrain can be changed by irrigating action. In addition to requirements of this effect, terrain.ruleset controls which terrain types can be transformed this way.
Max_Trade_Routes						Value of this effect tells how many trade routes city can establish. It affects only attempts to establish new routes, existing routes are not removed if value gets smaller than current number of routes. Maximum value, to which this value is clipped itself, is 5 routes.
Mining_Possible						If value of this effect > 0, mine can be built to target tile. In addition to requirements of this effect, terrain.ruleset controls which terrain types can have mines at all.
Mining_TF_Possible						If value of this effect > 0, tile terrain can be changed by mining action. In addition to requirements of this effect, terrain.ruleset controls which terrain types can be transformed this way.
Not_Tech_Source						Tech cannot be received from this player by any means.
Transform_Possible						If value of this effect > 0, target tile can be transformed. In addition to requirements of this effect, terrain.ruleset controls which terrain types can be transformed at all.
Effect type	Value Range  i  New in 2.6					Explanation
History						Value of this effect is how much cumulative History-type culture the city is producing.
Irrigation_Pct						This effect controls how much of the terrain specific irrigation bonus applies.
Mining_Pct						This effect controls how much of the terrain specific mining bonus applies.
National_History						Value of this effect is how much cumulative History-type culture the city is producing in addition to that produced by individual cities.
National_Performance						Value of this effect is how much Performance-type culture the nation is producing in addition to that produced by individual cities.
Output_Tile_Punish_Pct	Phase end, in city processing order	City owner	Any city	Each worked tile	Output type	Reduce the output of a tile by amount percent. The number of units to remove is rounded down. Applied after everything except a city center's minimal output.
Performance						Value of this effect is how much Performance-type culture the city is producing. Performance is not persistent culture, but affects only current turn.
Pollu_Pop_Pct2	Phase end, in city processing order	City owner	Any city	City center	-	Multiplicative effect with Pollu_Pop_Pct (i.e., if both 25, result is 125x125/100=156)
Revolution_Unhappiness	Phase end, after production and city-based upkeep	City owner	City	City center	-	If a city is in revolt for more than value turns, government falls. (Note: in 3.x it's a city-based effect but AI/advisors rely on it being player-based)
Traderoute_Pct	When city trade production is calculated	City owner	City	City center	-	Percentage bonus for trade from traderoutes. This bonus applies after the value of the traderoute is already calculated. It affects one end of the traderoute only.
Turn_Fragments	Between turn end and next turn start	-	-	-	-	Calendar advances amount fragments each turn, in addition to years advanced by Turn_Years.
Unit_Bribe_Cost_Pct						Increases unit bribe cost by amount percent.
Victory						When value of this effect gets positive, player wins the game. In simplest case you'll have just one such effect with value 1 (or any positive value) and thus requirements of that effect are requirements for winning the game.
Effect type	Value Range  i  New in 3.0					Explanation
Attack_Bonus						Increases offensive bonuses of units.
Building_Buy_Cost_Pct						Increases building buy cost by AMOUNT percent.
Combat_Rounds						Maximum number of rounds combat lasts. Zero or negative value means that combat is always to death.
Conquest_Tech_Pct						When a city is conquered, conqueror has a AMOUNT percentage chance to get a tech from the player losing the city.
Have_Contacts						Provides contact with all the other players.
Stealings_Ignore						When determining how difficult it is to steal a tech from enemy, AMOUNT previous times tech has been stolen from the city is ignored.
Unit_Buy_Cost_Pct						Increases unit buy cost by AMOUNT percent.
Effect type	Value Range  i  New in 3.1					Explanation
Building_Build_Cost_Pct						Increases building cost of a building.
Unit_Build_Cost_Pct						Increases building cost of a unit.