doc/README.effects

   1 The effects.ruleset file contains all effects in play in a Freeciv scenario.
   2 They have the following form (this is perhaps the most complicated example I
   3 could find):
   4
   5 [effect_hydro_plant]
   6 name  = "Output_Bonus"
   7 value = 25
   8 reqs  =
   9     { "type", "name", "range", "present", "quiet"
  10       "Building", "Factory", "City", TRUE, FALSE
  11       "Building", "Hydro Plant", "City", TRUE, FALSE
  12       "OutputType", "Shield", "Local", TRUE, TRUE
  13       "Building", "Hoover Dam", "Player", FALSE, FALSE
  14       "Building", "Nuclear Plant", "City", FALSE, FALSE
  15     }
  16
  17 The text in the brackets is the entry name, which just has to be unique, but
  18 is otherwise not used. The name field tells Freeciv which effect you are
  19 defining.  The value is the effect's value, which depends on which effect it
  20 is. The reqs table contain a list of requirements for this effect being in
  21 effect. You need to satisfy all requirements listed here for this effect to
  22 take effect in the game. Requirements with present = TRUE must be present,
  23 those with present = FALSE must not be present.
  24
  25 Value is integral amount parameter for many effects (must be in the range
  26 -32767 to 32767).
  27
  28 Requirement range may be one of: "None", "Local",
  29 "CAdjacent" (Cardinally Adjacent), "Adjacent", "City",
  30 "Continent", "Player", "Allied, "World". Some requirement types may only work at
  31 certain ranges; this is not yet documented. In particular, at present,
  32 "Continent" effects can affect only cities and units in cities.
  33
  34 A requirement may have a 'survives' field, and if this 'TRUE', the effect
  35 survives destruction. This is supported for only a few conditions and
  36 ranges: wonders (at world or player range), nations, and advances
  37 (both at world range only).
  38
  39 A requirement may have a 'present' field, and if this is 'FALSE',
  40 the requirement is negated (the condition must not be true for the req to be
  41 met).
  42
  43
  44 Requirement types and supported ranges
  45 ======================================
  46
  47 Tech:          World, Alliance, Team, Player
  48 TechFlag:      World, Alliance, Team, Player
  49 Achievement:   World, Alliance, Team, Player
  50 Gov:           Player
  51 Building:      World, Alliance, Team, Player, Continent, Traderoute, City, Local
  52 Extra:         Local, Adjacent, CAdjacent, Traderoute, City
  53 BaseFlag:      Local, Adjacent, CAdjacent, Traderoute, City
  54 RoadFlag:      Local, Adjacent, CAdjacent, Traderoute, City
  55 ExtraFlag:     Local, Adjacent, CAdjacent, Traderoute, City
  56 Terrain:       Local, Adjacent, CAdjacent, Traderoute, City
  57 Resource:      Local, Adjacent, CAdjacent, Traderoute, City
  58 UnitType:      Local
  59 UnitFlag:      Local
  60 UnitClass:     Local
  61 UnitClassFlag: Local
  62 Nation:        World, Alliance, Team, Player
  63 NationGroup:   World, Alliance, Team, Player
  64 Nationality:   Traderoute, City
  65 DiplRel:       World, Alliance, Team, Player, Local
  66 OutputType:    Local
  67 Specialist:    Local
  68 MinYear:       World
  69 Topology:      World
  70 Age:           Local, City
  71 MinSize:       Traderoute, City
  72 MinCulture:    World, Alliance, Team, Player, Traderoute, City
  73 AI:            Player
  74 MaxUnitsOnTile:Local, Adjacent, CAdjacent
  75 TerrainClass:  Local, Adjacent, CAdjacent, Traderoute, City
  76 TerrainFlag:   Local, Adjacent, CAdjacent, Traderoute, City
  77 TerrainAlter:  Local
  78 CityTile:      Local, Adjacent, CAdjacent
  79 Style:         Player
  80 UnitState:     Local
  81 MinMoveFrags:  Local
  82 MinVeteran:    Local
  83 MinHitPoints:  Local
  84
  85
  86 MinSize is the minimum size of a city required.
  87 AI is ai player difficulty level.
  88 TerrainClass is either "Land" or "Oceanic".
  89 CityTile is either "Center" (city center) or "Claimed" (owned).
  90 DiplRel is a diplomatic relationship.
  91 MaxUnitsOnTile is about the number of units present on a tile.
  92 UnitState is "Transported" or "OnLivableTile".
  93 MinMoveFargs is the minimum move fragments the unit must have left.
  94
  95 Effect types
  96 ============
  97
  98 Tech_Parasite
  99     Gain any advance known already by amount number of other players. Note
 100 that if you have two such effects, they combine into one much worse effect
 101 (the number of players required to gain an advance is increased).
 102
 103 Airlift
 104     Allow airlift to/from a city.
 105
 106 Any_Government
 107     Allow changing to any form of government regardless of tech prerequisites.
 108
 109 Capital_City
 110     The city with this effect is the capital city.
 111
 112 Gov_Center
 113     The city with this effect is governmental center. Corruption and
 114     waste depends on distance to nearest such city.
 115
 116 Enable_Nuke
 117     Allows the production of nuclear weapons.
 118
 119 Enable_Space
 120     Allows the production of space components.
 121
 122 Specialist_Output
 123     Specify what outputs a specialist is producing. Should be used with an
 124 OutputType requirement.
 125
 126 Output_Bonus
 127     City production is increased by amount percent.
 128
 129 Output_Bonus_2
 130     City production is increased by amount percent after Output_Bonus, so is
 131 multiplicative with it.
 132
 133 Output_Add_Tile
 134     Add amount to each worked tile.
 135
 136 Output_Inc_Tile
 137     Add amount to each worked tile that already has at least 1 output.
 138
 139 Output_Per_Tile
 140     Increase tile output by amount percent.
 141
 142 Output_Tile_Punish_Pct
 143     Reduce the output of a tile by amount percent. The number of units to
 144 remove is rounded down. Applied after everything except a city center's
 145 minimal output.
 146
 147 Output_Waste_Pct
 148     Reduce waste by amount percent.
 149
 150 Force_Content
 151     Make amount' unhappy citizens content. Applied after martial law and unit
 152 penalties.
 153
 154 Give_Imm_Tech
 155     Give amount techs immediately.
 156
 157 Growth_Food
 158     Food left after cities grow or shrink is amount percent of the capacity of
 159 the city's foodbox. This also affects the 'aqueductloss' penalty.
 160
 161 Have_Embassies
 162     Like having embassies with all other players.
 163
 164 Irrigation_Pct
 165     Irrigation output of the tile is value %.
 166
 167 Mining_Pct
 168     Mining output of the tile is value %.
 169
 170 Make_Content
 171     Make amount unhappy citizens content. Applied before martial law and unit
 172 penalties.
 173
 174 Make_Content_Mil
 175     Make amount unhappy citizens caused by units outside of a city content.
 176
 177 Make_Content_Mil_Per
 178     Make amount per unit of unhappy citizens caused by units outside of a city
 179 content.
 180
 181 Make_Happy
 182     Make amount citizens happy.
 183
 184 Enemy_Citizen_Unhappy_Pct
 185     There will be one extra unhappy citizen for each value/100 citizens
 186     of enemy nationality in the city.
 187
 188 No_Anarchy
 189     No period of anarchy between government changes. (This also neuters
 190 the Has_Senate effect.)
 191
 192 Nuke_Proof
 193     City is nuke proof.
 194
 195 Pollu_Pop_Pct
 196     Increases pollution caused by each unit of population by amount
 197 percent (adds to baseline of 100%, i.e. 1 pollution per citizen).
 198
 199 Pollu_Pop_Pct_2
 200     Increases pollution caused by each unit of population by amount
 201 percent (adds to baseline of 100%, i.e. 1 pollution per citizen).
 202 This factor is applied after Pollu_Pop_Pct, so is multiplicative with it.
 203
 204 Pollu_Prod_Pct
 205     Increases pollution caused by shields by amount percent.
 206
 207 Health_Pct
 208     Reduces possibility of illness (plague) in a city by amount percent.
 209
 210 Reveal_Cities
 211     Immediately make all cities known.
 212
 213 Reveal_Map
 214     Immediately make entire map known.
 215
 216 Incite_Cost_Pct
 217     Increases revolt cost by amount percent.
 218
 219 Unit_Bribe_Cost_Pct
 220     Increases unit bribe cost by amount percent. Requirements are from the
 221 point of view of the target unit, not the briber.
 222
 223 Max_Stolen_Gold_Pm
 224     The upper limit on the permille of the players gold that may be
 225 stolen by a unit doing the "Steal Gold" action. Evaluated against the city
 226 stolen from.
 227
 228 Thiefs_Share_Pm
 229     The permille of the gold stolen by a unit doing the "Steal Gold"
 230 action that is lost before it reaches the player ordering it. Evaluated
 231 against the actor unit.
 232
 233 Illegal_Action_Move_Cost
 234     The number of move fragments lost when the player tries to do an action
 235 that turns out to be illegal.
 236
 237 Size_Adj
 238     Increase maximum size of a city by amount.
 239
 240 Size_Unlimit
 241     Make the size of a city unlimited.
 242
 243 SS_Structural, SS_Component and SS_Module
 244     A part of a spaceship; this is a "Local" ranged effect. It (for now)
 245 applies to improvements which cannot be built unless "Enable_Space" is felt.
 246 Buildings which have this effect should probably not be given any other
 247 effects.
 248
 249 Spy_Resistant
 250     If a spy specifies a target for sabotage, then she has an AMOUNT percent
 251 chance to fail. Also in diplomatic combat defending diplomatic units in cities
 252 will get an AMOUNT percent bonus. All Spy_Resistant's are summed before being
 253 applied.
 254
 255 Move_Bonus
 256     Add amount movement to units. Use UnitClass' requirement with range of
 257 'Local' to give it a specific class of units only.
 258
 259 Unit_No_Lose_Pop
 260     No population lost when a city's defender is lost.
 261
 262 Unit_Recover
 263     Units recover amount extra hitpoints per turn.
 264
 265 Upgrade_Unit
 266     Upgrade amount obsolete units per turn.
 267
 268 Upkeep_Free
 269     Improvements with amount or less upkeep cost become free to upkeep (others
 270 are unaffected).
 271
 272 Tech_Upkeep_Free
 273     If this value is greater than 0, the tech upkeep is reduced by this value.
 274     For tech upkeep style "Basic" this is total reduction, for tech upkeep
 275     style "Cities" this reduction is applied to every city.
 276
 277 No_Unhappy
 278     No citizens in the city are ever unhappy.
 279
 280 Veteran_Build
 281     Increases the veteran class of newly created units of this type. The
 282 total amount determines the veteran class (clipped at the maximum for the
 283 unit).
 284
 285 Veteran_Combat
 286     Increases the chance of units of this type becoming veteran after combat
 287 by amount percent.
 288
 289 HP_Regen
 290     Units that do not move recover amount percentage of their full hitpoints
 291 per turn.
 292
 293 City_Vision_Radius_Sq
 294     Increase city vision radius in squared distance by amount tiles.
 295
 296 Unit_Vision_Radius_Sq
 297     Increase unit vision radius in squared distance by amount tiles.
 298
 299 Defend_Bonus
 300     Increases defensive bonuses of units. Any unit requirements on this effect
 301     will be applied to the _attacking_ unit. Attackers with "BadWallAttacker" flag
 302     will have their firepower set to 1.
 303
 304 Gain_AI_Love
 305     Gain amount points of "AI love" with AI(s).
 306
 307 Turn_Years
 308     Year advances by AMOUNT each turn unless Slow_Down_Timeline causes it
 309     to be less.
 310
 311 Turn_Fragments
 312     Year fragments advance by AMOUNT each turn.
 313
 314 Slow_Down_Timeline
 315     Slow down the timeline based on the AMOUNT. If AMOUNT >= 3 the timeline
 316 will be max 1 year/turn; with AMOUNT == 2 it is max 2 years/turn;
 317 with AMOUNT == 1 it is max 5 years/turn; with AMOUNT <= 0 the timeline is
 318 unaffected. The effect will be ignored if game.spacerace isn't set.
 319
 320 Civil_War_Chance
 321     Base chance in per cent of a nation being split by civil war when its
 322 capital is captured is increased by this amount. This percentage is in-
 323 creased by 5 for each city in civil disorder and reduced by 5 for each one
 324 celebrating.
 325
 326 City_Unhappy_Size
 327     The maximum number of citizens in each city that are naturally content;
 328 in larger cities, new citizens above this limit start out unhappy. (Before
 329 Empire_Size_Base/Step are applied.)
 330
 331 Empire_Size_Base
 332     Once your civilization has more cities than the value of this effect,
 333 each city gets one more unhappy citizen. If the sum of this effect and
 334 Empire_Size_Step is zero, there is no such penalty.
 335
 336 Empire_Size_Step
 337     After your civilization reaches Empire_Size_Base size, it gets one more
 338 unhappy citizen for each amount of cities it gets above that. Set to zero to
 339 disable. You can use Empire_Size_Step even if Empire_Size_Base is zero.
 340
 341 Max_Rates
 342     The maximum setting for each tax rate is amount.
 343
 344 Martial_Law_Each
 345     The amount of citizens pacified by each military unit giving martial law.
 346
 347 Martial_Law_Max
 348     The maximum amount of units that will give martial law in city.
 349
 350 Rapture_Grow
 351     Can rapture grow cities.
 352
 353 Revolution_Unhappiness
 354     If value is greater than zero, it tells how many turns citizens
 355     will tolerate city disorder before government falls. If value is
 356     zero, government never falls.
 357
 358 Has_Senate
 359     Has a senate that prevents declarations of war in most cases.
 360
 361 Inspire_Partisans
 362     Partisan units (defined in units.ruleset) may spring up when this player's
 363 cities are taken.
 364
 365 Happiness_To_Gold
 366     Make all Make_Content and Force_Content effects instead generate gold.
 367
 368 Max_Trade_Routes
 369     Number of trade routes that city can establish.
 370     This is forced on trade route creation only. Existing trade routes
 371     are never removed due to reduction of effect value. This is to
 372     avoid micro-management, need to create same trade routes again
 373     after their max number has been temporarily down.
 374
 375 Fanatics
 376     Units with "Fanatics" flag incur no upkeep.
 377
 378 No_Diplomacy
 379     Cannot use any diplomacy.
 380
 381 Not_Tech_Source
 382     Tech cannot be received from this player by any means.
 383
 384 Trade_Revenue_Bonus
 385     One time trade revenue bonus is multiplied by pow(2, amount/1000).
 386     The amount value is taken from the caravan's home city.
 387
 388 Traderoute_Pct
 389     Percentage bonus for trade from traderoutes. This bonus applies after
 390     the value of the traderoute is already calculated. It affects one end
 391     of the traderoute only.
 392
 393 Unhappy_Factor
 394     Multiply unhappy unit upkeep by amount.
 395
 396 Upkeep_Factor
 397     Multiply unit upkeep by amount.
 398
 399 Unit_Upkeep_Free_Per_City
 400     In each city unit upkeep is deducted by this amount. As usual, you can use
 401 with OutputType requirement to specify which kind of upkeep this should be.
 402
 403 Output_Waste
 404     Base amount in percentage that each city has in waste. Waste can be used
 405 with any output type, use an OutputType requirement to specify which.
 406
 407 Output_Waste_By_Distance
 408     For each tile in real distance that a city is from nearest
 409 Government Center, it gets amount of extra waste.
 410
 411 Output_Penalty_Tile
 412     When a tile yields more output than amount, it gets a penalty of -1.
 413
 414 Output_Inc_Tile_Celebrate
 415     Tiles get amount extra output when city working them is celebrating.
 416
 417 Upgrade_Price_Pct
 418     Increases unit upgrade cost by amount percent. This effect works at
 419     player level. You cannot adjust upgrade costs for certain unit type or
 420     for units upgraded in certain city.
 421
 422 Retire_Pct
 423     The chance that unit gets retired (removed) when turn changes.
 424     Retirement only happens if there are no enemy units or cities within
 425     a few tiles. (This exists mainly to implement barbarian behavior.)
 426
 427 Visible_Wall
 428     Instruct client to show specific buildings version of the city graphics.
 429     Zero or below are considered normal city graphics.
 430
 431 Tech_Cost_Factor
 432     Factor for research costs.
 433
 434 Shield2Gold_Factor
 435     Factor in percent for the conversion of unit shield upkeep to gold upkeep.
 436     A value of 200 would transfer 1 shield upkeep to 2 gold upkeep. The range
 437     of this effect must be player or world. Note that only units with the
 438     "Shield2Gold" flag will be affected by this.
 439
 440 Tile_Workable
 441     If value > 0, city can work target tile.
 442
 443 Irrig_Possible
 444     If value > 0, unit can build irrigation to target tile. In addition to
 445     requirements given to this effect, unit must also have Settlers flag.
 446
 447 Mining_Possible
 448     If value > 0, unit can build mine to target tile. In addition to
 449     requirements given to this effect, terrain type must be one to which mine
 450     can be built.
 451
 452 Transform_Possible
 453     If value > 0, unit can transform target tile. In addition to requirements
 454     given to this effect, terrain type needs to be one that can be transformed.
 455
 456 Irrig_TF_Possible
 457     If value > 0, unit can transform target tile terrain to another by irrigating.
 458     In addition to requirements given to this effect, terrain must be one that
 459     can be transformed by irrigating.
 460
 461 Mining_TF_Possible
 462     If value > 0, unit can transform target tile terrain to another by mining.
 463     In addition to requirements given to this effect, terrain must be one that
 464     can be transformed by mining.
 465
 466 Migration_Pct
 467     Increase the calculated migration score for the a city by amount in
 468     percent.
 469
 470 City_Radius_Sq
 471     Increase the squared city radius by amount. Currently, this can only
 472     usefully have "MinSize", "Building", or "Tech" requirements.
 473
 474 City_Build_Slots
 475     Increase the number of units with no population cost a city can build in
 476     a turn if there are enough shields.
 477
 478 City_Image
 479     The index for the city image of the given city style.
 480
 481 Victory
 482     Positive value means that player wins the game.
 483
 484 Performance
 485     Value is how much performance type culture city produces.
 486
 487 History
 488     Value is how much history type (cumulative) culture city produces.
 489
 490 National_Performance
 491     Value is how much performance type culture, not tied to any specific city,
 492     nation produces.
 493
 494 National_History
 495     Value is how much history type (cumulative) culture, not tied to any any
 496     specific city, nation produces.
 497
 498
 499 Details about requirement types
 500 ===============================
 501
 502 The DiplRel requirement type
 503 ----------------------------
 504 Look for the diplomatic relationship "Never met", "War", "Cease-fire",
 505 "Armistice", "Peace", "Alliance", "Team", "Gives shared vision",
 506 "Receives shared vision", "Hosts embassy", "Has embassy",
 507 "Hosts real embassy" (not from an effect), "Has real embassy",
 508 "Has Casus Belli" (reason for war), "Provided Casus Belli" or "Is foreign".
 509
 510 A DiplRel is considered fulfilled for the range
 511  * world if some player in the world has the specified diplomatic
 512    relationship to some other living player.
 513  * player if the player has the specified diplomatic relationship to some
 514    other living player.
 515  * local if the first player has the specified relationship to the second
 516    player. Example: When testing a build requirement for an extra the first
 517    player is the owner of the unit and the second player the owner of the
 518    terrain the extra is built on.
 519
 520 Only the exact relationship required fulfills it. Example: An alliance or
 521 an armistice agreement won't fulfill a "Peace" requirement.
 522
 523 It is possible to create a requirement that in some situations won't have a
 524 player to check. In those cases the requirement will always be considered
 525 unfulfilled. This applies to both present and not present requirements. The
 526 ranges Alliance, Team, Player and Local needs a player. The Local range also
 527 needs the player the first player's relationship is to.
 528
 529 Example: The requirements below are about the relationship to the owner of a
 530 tile. The table shows in what situations a requirement is fulfilled.
 531
 532 Requirement is                            fulfilled when the tile is
 533                                         | domestic | unclaimed | foreign
 534 "DiplRel", "Is foreign", "Local", TRUE  | no       | no        | yes
 535 "DiplRel", "Is foreign", "Local", FALSE | yes      | no        | no
 536
 537 The MaxUnitsOnTile requirement type
 538 -----------------------------------
 539 Check the number of units present on a tile. Is true if no more than the
 540 specified number of units are present on a single tile.
 541
 542 Hint: By using negation ("not present") it is possible to check if a tile
 543 has more than the given numbers. It is possible to combine a negated and a
 544 non negated requirement to specify a range.
 545
 546 The UnitState requirement type
 547 ------------------------------
 548 "Transported" is fulfilled if the unit is transported by another unit.
 549 "OnLivableTile" is fulfilled if the unit is on a tile where it can exist
 550                 outside of a transport.