Effects Tutorial

== Introduction ==
This an article containing a reference guide to all the effect types, and fields, and an explanation of how to use them.
Those who want to edit the rulesets and change the rules may be confronted with confusing situations as it may not be obvious how certain effects, or fields in an effect work. This page is there to help them, and those getting aquainted with rulesets.
Effects are used in the effects.ruleset and greatly affect the buildings, units, governement (and terrain) rulesets. Some of them are used as flags for units and all buildings and wonders have some requirements that make use of effects.
(please edit eroneous statements)
Bold text:
For now, It is filled with bold text. This is text that needs to be removed and replaced with actual useful/correct information.
When finishished it could be used to make a new README.effects file as well as be used in the online manual.
== General Effect Syntax ==
The general syntax of an effect entry in the effect.ruleset is:
 [effect_reference_name]
 name = "Name0,Ie. Name of the effect used."
 value = Integer (whole number), attributed to this effect.
 reqs = { "type", "field1", "field2", etc...
 "Type1", "entry for field 1","entry for field 2", etc...
 "Type3", "entry for field 1", entry for field 2", etc...
 "Type2", "entry for field 1", etc...
 }
In the units.rulesets, only effect names, specific to units are used, as follows:
 flags = "Name0","Name3","Name2", etc...
name, value, reqs and flags are called fields. The fields inside the 'reqs' field are called req-fields.
In the buildings.ruleset only the reqs and name fields are used. The name, there, is the name of the building, the req. typically a technology requirement.
As you can see from the syntax the order in which entries go is arbitrary, the order in a specific entry isn't.
Each requirement works in addition (cumulative?) to the previous one.
The Name0, Name1 etc... entries are specified under Names. They are also called effect-types, not to be confounded with requirement-types. They are given values in the effect.ruleset, and can sometimes be used in other rulesets.
The req-field entries are specified for each req-type, and the kind that one encounters are specified here.
?Can you use a user-defined event in effect.ruleset as a Type?
Effects have a permanent kind of nature: they work, as soon as the conditions are met, and stop working as soon as the conditions are no longer met. Use the reqs field to control the occurrence of an effect. Effects that are not mentioned are defaulted to 0?.
The use of certain effects is obligatory. (Well, I don't know, if it defaults to 0, it should work fine (al be it weird) with an empty effect.ruleset).
== Fields: ==
The general structure for an effect is: a name, a value for the effect, and a set of requirments.
name: The name of the effect to be used. See Names for the full list.
value: An integer value.(must be in the range -32767 to 32767). Refered to as AMOUNT in name explanations.(? are there also things like random? or variable values?)
reqs: A list of requirement entries, ie: conditions to be checked, or applied in certain cases. See Req-fields for a list.
The effect will not be active unless this requirement is met.
For MinSize it is the minimum (city) size at which the requirement is met.
The requirement applies to the target of the effect (not the source),
Note that a requirement applied at local range means that the requirement simply gives the target of the effect type (to) itself. (Not entirely clear. How does it differ from None?
flags: Specific effects and parameters to be given to units (like: Settler, AttackOnce etc...). Only used in Units.ruleset .
== Req-fields: ==
type: One of:
 "None" (default): No type, thus no requirement.
 "Tech": requires a "name" req-field after it with a Technology defined in the techs.ruleset.
 "Gov": requires a "name" req-field after it with one of the governments defined in the governments.ruleset
 "Building": requires a "name" req-field after it with an Improvement or Wonder, defined in the buildings.ruleset.
 "Special": requires a "name" tag with one of the following:
 "Road": ie only for tiles with roads (note that cities get free roads, irrigation, rail and farmland, when available).
 "Irrigation": ie only on irrigated tiles.
 "Railroad": ie only for tiles with railroads.
 "Mine": ie only for tiles with mines on them.
 "Pollution": ie only for tiles with pollution.
 "Hut": ie only for tiles with huts.
 "Fortress": ie only for tiles with forteresses (particularily usefull to improve defencive bonus of forteresses)
 "River": ie only for river tiles.
 "Farmland": ie only for tilse with farmland
 "Airbase": ie for tiles with an airbase.
 "Fallout": ie for tiles with nuclear fallout.
 "Terrain": requires a "name" tag with the name of one of the terrains defined in terrains.ruleset.
 "UnitType": requires a "name" tag with the type of unit.
 "land": for land units.
 "air": for planes (that, typically, need to refuel).
 "sea": for all naval units.
 "heli": for all helicopters (that, typically, suffer from attrition).
 "missile": for all missiles (that, typically, have only one use
 "UnitFlag": requires a "name" tag with one of the unit flags.
 See the default units.ruleset for a list of all unit flags. Note flags are not roles.
 "Nation": requires the name of a nation in the nation.ruleset. This nation does not have to be a game participant.
 ?Are there any values to give to this, for more general nations: ie european, asian, or player1, player2?
 "OutputType": requires a "name" tag with a city output type. Typically for specialist definitions.
 Must be one of the following: 
 "luxury"
 "science"
 "gold"
 "trade"
 "food"
 "production"
 (are those all? are they correctly named here?)
 "MinSize": requires a "value" tag with the minimal city cize
 "Specialist": requires a "name" tag with a kind of specialist, defined in the ...ruleset. 
 Renaming them there, means having to rename all the specialist entries in the effect.ruleset.
 "OTHERS": I get the feeling there are others, like MaxSize or so, specialist was undocumented for example. 
 
name: Value string for the type. What type of string is accepted depends on the functioning of the specific type, specified just above here.
value: instead of name, sometimes a value, ie integer number, needs to be used.
range: One of:
 "None",
 "Local",
 "Adjacent",
 "City",
 "Continent",
 "Player",
 "World" 
 ?(Is it still the case that certain ranges are limited to certain genus?)
survives: Default is 0. Used for Manhattan project and the Apolo Program to let their effects survive their destruction. 
Note: in stable 2.0.x versions 'req_type' and 'req' appear. req_type has become type (and effect= has become reqs=), req is now named name.
The structure has also changed to have 'values' appear in effects as a main field, rather than part of a the effect= or req= entry.
(The values mentioned under .req_type in the README.effects, are types! (and belong there))
(?Can the names req_type, req and value still be used inside a reqs= definition?
== Names: ==
There is a long list of effect names. They should be grouped by what they are about, rather than alphabetically. This isn't finshed yet.
 "Tech_Parasite" - gains advances known by AMOUNT other players.
 "Airlift"	 - allows airlift of units to/from a city (one per turn)
 "Any_Government" - allows the choice of any government form
 This must be either a "Player" or "World" ranged effect.
 "Capital_City"	 - marks the capital city of a nation (many special cases)
 "Corrupt_Pct"	 - Decreases corruption by AMOUNT percent
 "Waste_Pct" - Decreases waste by AMOUNT percent
 "Enable_Nuke" - allows production of nuclear units
 This must be either a "Player" or "World" ranged effect.
 "Enable_Space" - allows production of "Space_Part" improvements
 This must be either a "Player" or "World" ranged effect.
 "Food_Add_Tile" - each worked tile produces AMOUNT additional food
 "Food_Inc_Tile" - each worked tile that is already producing some
 food produces AMOUNT additional food (applied after
 Food_Add_Tile)
 "Food_Per_Tile" - increases food generated on each worked tile
 by AMOUNT percent
 "Force_Content" - makes AMOUNT unhappy citizens content
 (applied *after* martial law and aggressive units;
 all Force_Content's are summed before being applied)
 "Give_Imm_Tech" - immediately gain AMOUNT advances when built
 "Growth_Food" - food left after cities grow or shrink is AMOUNT
 percent of the capacity of the city's foodbox
 "Have_Embassies" - like having embassies with all other players
 "Make_Content" - makes AMOUNT unhappy citizens content
 (applied *before* martial law and aggressive units;
 all Make_Content's are summed before being applied)
 "Make_Content_Mil"- makes AMOUNT unhappy citizens caused
 by units outside of a city content
 "Make_Content_Mil_Per"- makes AMOUNT _per unit_ of unhappy citizens
 caused by units outside of a city content
 "Make_Happy" - makes AMOUNT content citizens happy
 (all Make_Happy's are summed before being applied)
 "No_Anarchy" - eliminates anarchy period between governments
 "No_Sink_Deep"	 - prevent certain sea units from sinking in deep sea
 "Nuke_Proof"	 - nuclear attacks will fail within AMOUNT distance
 "Pollu_Pop_Pct" - increases pollution caused by population by AMOUNT percent
 "Pollu_Prod_Pct" - increases pollution caused by shields by AMOUNT percent
 "Prod_Add_Tile" - each worked tile produces AMOUNT additional shield production
 "Prod_Inc_Tile" - each worked tile that is already producing some
 shields produces AMOUNT additional shields
 "Prod_Per_Tile" - increases shield production generated on each worked
 tile by AMOUNT percent
 "Prod_To_Gold"	 - convert production to gold at 1:1 ratio
 "Reveal_Cities" - make all city tiles known
 "Reveal_Map" - make entire map known
 "Incite_Dist_Pct"- multiplies effective distance to the capital by
 AMOUNT percent for purpose of computing revolt cost
 "Size_Adj" - Increases maximum city size by AMOUNT
 "Size_Unlimit"	 - Removes maximum city size limitation
 "SS_Structural" -
 "SS_Component" -
 "SS_Module"	 - 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.
 "Spy_Resistant" - 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)
 "Trade_Add_Tile" - each worked tile produces AMOUNT additional trade
 "Trade_Inc_Tile" - each worked tile that is already producing some
 trade produces AMOUNT additional trade
 "Trade_Per_Tile" - increases trade generated on each worked tile
 by AMOUNT percent
 "Specialist_Output"- increases specialist output (food, luxuries, etc.) by
 AMOUNT. This is generally only useful in conjunction with
 a Specialist and an OutputType requirement, each at
 local range. See the default ruleset for examples.
 "Food_Bonus" - city's production is increased by AMOUNT percent
 "Prod_Bonus" -
 "Trade_Bonus" -
 "Tax_Bonus" -
 "Luxury_Bonus" -
 "Science_Bonus" -
 "Food_Bonus_2" - production is increased by AMOUNT percent. This is
 "Prod_Bonus_2" - applied after the first bonus so it's multiplicative
 "Trade_Bonus_2" - with it.
 "Tax_Bonus_2" -
 "Luxury_Bonus_2" -
 "Science_Bonus_2"-
 "Sea_Move" - adds AMOUNT of movement points to sea units
 "Unit_No_Lose_Pop"- no population lost when a city's defender is lost
 "Unit_Recover" - units recover AMOUNT extra hitpoints per turn
 "Upgrade_Unit" - upgrade AMOUNT obsolete units per turn
 "Upkeep_Free" - improvements with AMOUNT or less upkeep cost become
 free to upkeep (others are unaffected)
 "No_Unhappy" - No citizens in the city are ever unhappy
 "Land_Veteran" -
 "Sea_Veteran" -
 "Air_Veteran" - New land units of this type have veteran class 1
 "Land_Vet_Combat"-
 "Sea_Vet_Combat" -
 "Air_Vet_Combat" - Increases the chance of units of this type becoming veteran
 after combat by AMOUNT percent
 "Gain_AI_Love" - Increase AI's love for you by AMOUNT units (out of 1000)
 per turn
 "Regen_Reputation"- Increase your reputation by AMOUNT units (out of 1000)
 per turn
 "Slow_Down_Timeline"- Slow down the timeline based on the AMOUNT. If
 AMOUNT >= 3 the timeline will be 1 year/turn; with
 AMOUNT == 2 it is 2 years/turn; with
 AMOUNT == 1 it is 5 years/turn; with
 AMOUNT <= 0 the timeline is unaffected.
 The effect will be ignored if game.spacerace isn't
 set.
Category:Technical docs