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