Editing rulesets

edit

Game Anatomy & Modding

Editing Rulesets | Editing Tilesets | Nations | Sounds | Scenarios | Event Scripting

---

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.

Overview of Editing a Ruleset

Rulesets are specified using the server command "rulesetdir". The command above of "./fcser -r data/civ1.serv" just reads a file which uses this command (as well as a few of the standard server options). The server command specifies in which directory the ruleset files are to be found.

The ruleset files in the data directory are user-editable, so you can modify them to create modified or custom rulesets without having to recompile Freeciv. You should **not** edit the existing files in the "default", "civ1", and "civ2" directories. Instead you should copy them to another directory and edit the copies. This is so that its clear when you are using modified rules and not the standard ones.

Some specific notes on the format:

• Some rule files have dependencies on other files. For example: units depend on advances specified in the techs file.
• Units have a field, "roles", which is like "flags", but determines which units are used in various circumstances of the game (rather than intrinsic properties of the unit). See comments in common/unit.h
• Properties of units and advances are now fairly well generalized.
• Properties of buildings are still rather inflexible.

Check the ruleset forum for asking questions.

The ruleset collection files

A Ruleset consists of a collection of configuration files. The components of the ruleset collection are:

game       nations       governments    buildings
cities     units         techs          terrain 
effects    styles        script.lua

... more details will follow soon.

The anatomy of a game ruleset file

game.ruleset

Three optional fields are not used in default game.ruleset

[tileset]
prefered="fantasy"

[soundset]
prefered="freesounds"

[musicset]
prefered="mqtx"

tileset.prefered will instruct clients to use given tileset with these rulesets. Currently only gtk-clients supports this, other clients ignore it. Use this field only if your ruleset really requires tileset with some special tags. If only standard tags are used, user should be free to choose any of the tilesets providing them.

soundset.prefered will instruct clients to use given soundset with these rulesets. Currently only gtk-clients supports this, other clients ignore it. Use this field only if your ruleset really requires soundset with some special tags. If only standard tags are used, user should be free to choose any of the soundsets providing them. New in freeciv 2.5

musicset.prefered will instruct clients to use given musicset with these rulesets. Currently only gtk-clients supports this, other clients ignore it. Use this field only if your ruleset really requires musicset with some special tags. If only standard tags are used, user should be free to choose any of the musicsets providing them. New in freeciv 2.6

The anatomy of a styles ruleset file

styles.ruleset

Styles.ruleset is a New in freeciv 2.6.

The anatomy of a nations ruleset file

nations.ruleset

This is documented in documentation on nations.

The anatomy of a governments ruleset file

governments.ruleset

Attribute		Example Content	Explanation
name	=	_("Monarchy")	name of this government form as seen by user
reqs	=	{ "type", "name", "range" "tech", "Monarchy", "Player" }	requirements for this government (see README.effects)
graphic	=	"gov.monarchy"	tag specifing preferred graphic (see small.spec)
graphic_alt	=	"-"	alternate graphics tag if preferred is not found
ai_better	=	"Communism"	AI will not consider this government for use if the government listed here is available
rule_male_title	=	_("King %s")	Default ruler titles for the government. Note that some nations can have specific ruler titles. %s will be replaced at running time by a player name.  i  %s is required only since Freeciv 2.3. Before, player names were always appended to the ruler title.
rule_female_title	=	_("Queen %s")
helptext	=	_("\ Under Monarchy, a king or queen serves as a hereditary figurehead for your government. \n\n Monarchy suffers the same small amount of corruption that the Republic does.")	optional help text string; should escape all raw newlines so that xgettext parsing works

The anatomy of a buildings ruleset file

buildings.ruleset

The following table shows you all the attributes a building should provide to characterise it comprehesively. The first three columns of a table row form one single line inside the building ruleset file.

Attribute		Example Content	Explanation
name	=	_("Airport")	The name of the building as seen by the user.
genus	=	"Improvement"	one of: "GreatWonder", "SmallWonder", "Improvement", "Special".
reqs	=	{ "type", "name", "range" "Tech", "Radio", "Player" }	Requirements to build the building (see effects.ruleset and README.effects for help on requirements).
graphic	=	"b.airport"	Icon of improvement (used in city dialog).
graphic_alt	=	"-"	Alternate icon of improvement.
obsolete_by	=	"None"	Advance which makes building obsolete. Special value "None" means does not become obsolete.
build_cost	=	120	Production shields required to build.
upkeep	=	3	Monetary upkeep value.
sabotage	=	100	Percent chance of diplomat sabotage being successful.
flags	=	"VisibleByOthers"	Special flag strings. Others are "SaveSmallWonder" or "Gold".
helptext	=	_("\Allows a city to produce veteran air units. Also, damaged air units\ which stay in town for one full turn without moving are completely\ restored.\ \n\n\ Two cities with Airports can airlift one unit per turn. \ Airlifting instantly transports the unit from one city to another\ and will use all of the unit's movement points. A unit must have\ some movement points left to be airlifted.\ ")	The help text shown in the Freeciv help viewer.
sound	=	"b_airport"
sound_alt	=	"b_generic"

The anatomy of a cities ruleset file

cities.ruleset

The anatomy of a units ruleset file

The units.ruleset file contains all the information about unit types in the game. In addition to unit type entries there is some generic information about how units gain veterancy and how it affects them. Starting from Freeciv version 2.2 there are also unit class entries. Each unit type belongs to some unit class.

Configurable Unit Type Flags

Configurable Unit Type Flags are available starting from version 2.2

[flags]
; Names for custom unit type flags.
names = "Airbase"
; Airbase - can build airbases. See airbase definition in terrain.ruleset

This is list of custom unit type flags this ruleset uses. Custom unit type flags have no internal meaning to Freeciv, but ruleset can give them to units and have unit with such flag as requirement for effects or base building. Default ruleset has one such flag, Airbase. Workers and Engineers have Airbase flag and building Airbase requires it.

Veteran System

Veteran system entries are quite well documented in default ruleset.

Note that individual unit types can have "NoVeteran" flag preventing it from becoming veteran no matter what generic veteran system definitions say. In default ruleset Settlers, Workers and Engineers all have "NoVeteran" flag, so changing veteran_work_raise_chance affects nothing.

Unit Classes

Unit classes are new concept in version 2.2

There can be maximum of 32 different unit classes. Do not add them without proper consideration if separate class is really needed. Considering all the cross-referencing from other ruleset files, big number of different unit class can prove difficult to maintain. For example typical effects.ruleset has effects with UnitClass requirements. If you want same effect to affect several classes, you need to provide separate effect for each.

[unitclass_sea]
name          = _("Sea")
move_type     = "Sea"
min_speed     = 2
hp_loss_pct   = 0
hut_behavior  = "Normal"
flags         = "TerrainSpeed", "DamageSlows"

Possible values for move_type are "Land", "Sea", "Both" and "Air". The Terrain.ruleset defines exact limitations where units of this class can move, but move_type must be compatible with that. "Land" units cannot move at any oceanic terrain. "Sea" units can move only at oceanic terrains. "Air" units still have some special rules that makes them different from "Both". In theory you can have "Both" units that terrain.ruleset restricts to land terrains only, but you should not do that. AI does not use "Both" units. In default ruleset, Helicopters are "Both" units.

Some units are slowed down when damaged. No matter how much damage they have, speed never drops below min_speed. Neither do terrain slow units below min_speed.

Some units lose hitpoints when ever they end turn and are not in city, native base, or transport. hp_loss_pct tells how many percents of units total hitpoints is lost each turn. In default ruleset helicopters have non-zero hp_loss_pct.

hut_behavior controls what happens when unit enters tile with hut (minor tribe village). "Normal" means that hut disappears with random effect. "Nothing" means that nothing happens, hut even remains for other units to come. "Frighten" means that hut just disappear without any other effects. In default ruleset airplanes and missiles "Frighten"

Unit Class Flags

• TerrainSpeed - Unit is not moving at constant speed, but terrain affects it. This includes effects from roads and railroads. In default ruleset all but flying units have this flag.

• TerrainDefense - Units gain defense bonus from terrain.

• DamageSlows - Unit is slowed down when damaged. In default ruleset land and sea units have this flag and flying units do not.

• CanOccupyCity - Units of this class can occupy empty enemy cities. Note that particular unit type must be also military unit in order to occupy cities. In default ruleset land units and helicopters have this flag.

• Missile - Unit disappears after it has attacked even if it was victorious. In default ruleset missiles have this flag

• RoadNative - Even if particular base terrain is listed as non-native for this unit class, tiles with road are still considered native. That is, units can move anywhere where is road. In default ruleset we have no such units as all land units can move at all land terrains anyway. Removed in 2.5 Add native_to unit classes to terrain.ruleset road definitions instead.

• RiverNative - Even if particular base terrain is listed as non-native for this unit class, tiles with river are still considered native. That is, units can move anywhere where is river.

• BuildAnywhere - Units can be built even if city is located in non-native terrain for unit. In default ruleset land units have this flag so theoretical ocean cities can build them. Most definitely sea units do not have this flag.

• Unreachable - By default other units cannot attack units of this class. Only those unit types listing this class in its targets can attack. In default ruleset airplanes and missiles have this flag and Fighters list them as targets.

• CollectRansom - When unit of this class kills lone barbarian leader, player gains money. In default ruleset land units and helicopters have this flag.

• ZOC - Units of this class are subject to Zone of Control rules. There is also unit type flag IgZOC that can be used to override this. In default ruleset land units class has this flag, but some individual unit types override it with IgZOC.

• CanFortify - Units of this class can fortify in land squares. In default ruleset land units have this flag, flying units cannot fortify even when over land.

• CanPillage - Units of this class can destroy tile improvements. In default ruleset land units have this flag.

• DoesntOccupyTile - Even if enemy unit of this class is on tile, cities can still work it. In default ruleset air and missile units have this flag.

• AttackNonNative - New in 2.5 Unit can attack units on non-native tiles. Unit type flag "Only_Native_Attack" can override this.

• AttFromNonNative - New in 2.5 Unit can attack from non-native tile. Unit can be in such a tile in transport or in city. In default ruleset sea units have this flag so they can attack out from harbour cities. Unit type flag Marines works the same way, so use it if you want only some units of the class to be able to attack from non-native tiles.

Unit Types

[unit_warriors]
name          = _("Warriors")
class         = "Land"
tech_req      = "None"
obsolete_by   = "Pikemen"
graphic       = "u.warriors"
graphic_alt   = "-"
sound_move    = "m_warriors"
sound_move_alt = "m_generic"
sound_fight   = "f_warriors"
sound_fight_alt = "f_generic"
build_cost    = 10
pop_cost      = 0
attack        = 1
defense       = 1
hitpoints     = 10
firepower     = 1
move_rate     = 1
vision_radius_sq = 2
transport_cap = 0
fuel          = 0
uk_happy      = 1
uk_shield     = 1
uk_food       = 0
uk_gold       = 0
flags         = ""
roles         = "DefendOk", "FirstBuild"
helptext      = _("\
This unit may be built from the start of the game.  It is the\
 weakest unit.\
")

class refers to unit class this unit type belongs to. In 2.2 this is one of the classes defined earlier in the units.ruleset. In 2.1 this is one of the predefined classes: "Missile", "Land", "Sea", "Helicopter", "Air" or "Nuclear".

tech_req is name of the tech that is required in order to build this unit. These are defined in Techs.ruleset. Special value "None" means that unit can be built without knowing any tech.

impr_req  required city improvement, name from buildings.ruleset

obsolete_by is name of the another unit type to which this unit type upgrades to.

convert_to is name of another unit type that this unit can be converted to. New in 2.3

convert_time is number of movement points it takes to convert to convert_to unit. New in 2.5

graphic is graphic tag for this unit. Tileset should provide graphics for matching this tag.

graphic_alt is used as fallback tag if primary tag is not found from tileset.

sound_move, sound_move_alt, sound_fight and sound_fight_alt Sound tags similar to graphic tags.

build_cost is how much production is needed in order to build this unit.

pop_cost is how much city size will shrink once unit is finished. In default ruleset only Settlers have population cost.

attack is attack strength of unit.

defense is defense strength of unit.

hitpoints is number of hitpoints units of this type have when they are in full health.

firepower is unit firepower.

move_rate is unit speed. Here it is in full move points, not in 1/3 points.

vision_radius_sq is how far unit sees. This is given as vision_radius_square in order to be able to see circular areas instead of square area.

transport_cap tells how many other units this unit type can transport.

cargo is new optional field in 2.2, applicable only for units that have transport_cap > 0. It is list of different unit classes this unit type can transport. In default ruleset Carrier has cargo = "Air", "Missile", "Helicopter". In 2.1 unit type flags define what other units unit can transport.

fuel is number of turns that unit can live without refueling. Value 0 means that unit never needs to refuel. Value 1 means that unit needs to refuel every turn or to crash. Value other than zero should be given only to air units, it does not work correctly with other kind of units.

uk_happy is how much unit causes unhappiness when aggressive.

uk_shield is unit upkeep in shields / turn.

uk_food is unit upkeep in food / turn.

uk_gold is unit upkeep in gold / turn.

city_size is new optional field in 2.2. Cities built by this unit will initially be of given size. Default is 1.

targets is new optional field in 2.2. This is list of unit classes unit type can attack against even if those classes have "Unreachable" flag set. All unit types can attack classes without "Unreachable" flag even if class is not mentioned in targets.

helptext is shown in inline help in addition to automatically generated help.

Unit Type Flags

• TradeRoute - Unit can establish trade routes

• HelpWonder - Unit can be disbanded in city building Wonder to get full unit production cost towards finishing wonder

• IgZOC - Ignores Zone of Control restrictions even if unit class has ZOC flag

• NonMil - Can enforce martial law. Can occupy empty enemy cities, if unit class is capable to that. In 2.1, units of classes Land and Helicopter can occupy. In 2.2, unit class must have flag CanOccupy.

• IgTer - Regardless of terrain, move speed is at least same as would be using roads. Takes advantage of railroads.

• OneAttack - Unit can attack only once in a turn even if its move_rate is more than one.

• Pikemen - Unit gets double defense power against units flagged as Horse.

• Horse - Units flagged as Pikemen get double defense against these units.

• IgWall - Defender's Defend_Bonus effects are ignored when this unit attacks. In default rules only buildings City Walls and Great Wall give Defend_Bonus effect against Land units. Units of other classes ignore those effects and so do Land units with IgWall.

• FieldUnit - Unit is considered aggressive - causing unhappiness - even if it's within home borders (and inside cities when server setting 'happyborders' is off)

• AEGIS - Unit defensepower is multiplied by 5 when attacker is air unit. In 2.1 units from classes Air, Helicopter, Missile or Nuclear are considered air units. In 2.2, units with unit class flag AirUnit are considered air units.

• Marines - Unit can attack directly from non-native terrain. Typically this means that unit is in transport.

• Partial_Invis - Other players can see this unit only if they have unit or city center in adjacent tile.

• Settlers - Unit can irrigate, mine and build roads and railroads (when tech is known). In 2.1 they also can build Fortresses. In 2.2 this is controlled by base definitions in terrain.ruleset.

• Diplomat - Can establish embassies, steal random technologies, bribe enemy units, start revolution in enemy city, sabotage production, investigate cities. If unit does not have also Spy flag, it is always destroyed after mission.

• Trireme - Unit should stay adjacent to Land squares. In 2.1 unit can move away from coast, but might be lost if ends turn not adjacent to land. In 2.2 unit cannot move away from land at all.

• Nuclear - Can only be built when Enable_Nuke effect is active. When this unit attacks, all units (including friendly ones) within 3x3 square area are destroyed. Size of the attacked city is halved. Attack might cause fallout to surrounding squares.

• Spy - This flag works correctly only if unit has also Diplomat flag. Can poison water, select what technology to steal, select what to sabotage, sabotage enemy units. This unit might survive mission.

• Transform - Unit can transform terrain as specified in terrain.ruleset

• Paratroopers - Unit can paradrop to native terrain. Paradrop can be initiated from city or base. In 2.1 paradrop is possible from Airbase. In 2.2 paradrop is possible from base with flag ParadropFrom.

• Airbase - In 2.1 means that unit can build airbases. In 2.2 has no hardcoded meaning. Default rules mark Settlers, Worker and Engineer unit with this flag and base Airbase has building requirement UnitFlag Airbase

• Cities - Can found new city. Unit is destroyed in the process.

• No_Land_Attack - This flag affects Sea moving units only. Usually they can attack non-native terrains (shore bombardment), but units with this flag cannot. Replaced with Only_Native_Attack in 2.5

• Only_Native_Attack - This can be used to override AttackNonNative unit class flag for specific unit types. Units with this flag cannot attack against units on non-native tiles. New in 2.5

• AddToCity - Unit can inrease city size by population cost. Unit is destroyed in the process. City size cannot be increased if city is already larger than limit defined in cities.ruleset

• Fanatic - If effect Fanatics is active for player, units of this type have no upkeep cost. (According to some documentation, effect needs to be active in order to build these units. Looking at the source code this seems not to be true)

• GameLoss - If player loses unit of this type, he loses whole game.

• Unique - Player can have only one unit of this type at a time.

• Unbribable - Unit cannot be bribed.

• Undisbandable - Player cannot disband this unit.

• SuperSpy - This unit always wins against regular Diplomat and Spy units.

• NoHome - Unit has no home city assigned. This means that no city is paying upkeep for it and it cannot be killed by conquering its home city.

• NoVeteran - Unit cannot gain veteran levels. It is always in the lowest defined level.

• Bombarder - Unit uses bombard attack.

• CityBuster - Unit's firepower is doubled when it attacks against city

• NoBuild - Unit cannot be built in cities. These units can only be available from start, appear from huts, appear as barbarians, or be created via scenario scripting.

• BadWallAttacker - If defender has Defend_Bonus effect when this unit attacks, firepower is considered to be 1.

• BadCityDefender - When this unit is defender against attack to city, attacker firepower is doubled and this unit is considered to have firepower of one. Default rules use this flag for all ships. Note that native/non-native terrain does not affect defense capabilities.

• Helicopter New in 2.2 When units flagged as Fighter attack this unit, defender's firepower is considered to be 1 and defense value is halved.

• AirUnit - New in 2.2

• Fighter - Good at attacking against helicopters. In 2.1 units of class Helicopter are considered helicopters. In 2.2 units with unit type flag Helicopter are considered helicopters. In 2.1 Fighter is also able to attack against air units (similar to listing air units class in targets in 2.2)

• BarbarianOnly - New in 2.2 - Unit can be built only by barbarian players. For other players this is similar to NoBuild

• Missile - Removed in 2.2 - Unit is destroyed after it attacks even if it is victorious. In 2.2 this is unit class flag.

• Carrier - Removed in 2.2 - Unit can transport units of classes Air, Missile, Helicopter and Nuclear, and no Land units. Unit is Land unit transport if it does not have this flag or Missile_Carrier flag. In 2.2 this implementation is replaced by unit type field cargo.

• Missile_Carrier - Removed in 2.2 - Unit can transport units of classes Missile and Nuclear, but no others. See also Carrier.

• Shield2Gold - New in 2.2 - unit upkeep can be switch from shield upkeep to gold upkeep

Unit Type Roles

Unit type can have multiple roles it fits in to.

"FirstBuild"

"Explorer"

"Hut"

"HutTech"

"Partisan"

"DefendOk"

"DefendGood"

"AttackFast"

"AttackStrong"

"FerryBoat"

"Barbarian"

"BarbarianTech"

"BarbarianBoat"

"BarbarianBuild"

"BarbarianBuildTech"

"BarbarianLeader"

"BarbarianSea"

"BarbarianSeaTech"

"Cities"

"Settlers"

"GameLoss"

"Diplomat"

"Hunter"

The anatomy of a techs ruleset file

techs.ruleset

[advance_astronomy]
name     = _("Astronomy")
req1     = "Mysticism"
req2     = "Mathematics"
flags    = ""
graphic     = "a.astronomy"
graphic_alt = "-"

name is user visible name for technology

req1 and req2 are parent technologies that must be known before this one can be researched. These can have special value None or Never

root_req is another tech required before this one can be reasearched. This is usually used to provide different technology trees for different nations. Make one technology to root_req itself so nobody can gain that technology in the game, and give that technology to some nation in nation.ruleset init_tech-list.

flags is list of special flags for technology

graphic is graphic tag for technology icon. This is sent to client and client should find the tag from tileset files.

graphic_alt is fallback tag in case primary tag is not found from tileset in use.

helptext is extra helptext for technology to be shown in help-browser.

bonus_text is displayed to player if (s)he is first one to research this technology. This is applicable only if technology has Bonus_Tech-flag

cost is used if tech_cost_style in game.ruleset has been set to 3. This is research cost of the technology.

Technology flags

Bonus_Tech - First player to research this technology will get free extra tech.

Bridge - Knowledge of this tech allows Settler-type units to build bridges over rivers.

Railroad - Knowledge of this tech allows Settler-type units to build Railroads. Removed in 2.5

Farmland - Knowledge of this tech allows Settler-type units to build Farmland. Removed in 2.6

Population_Pollution_Inc - Knowledge of this tech increases pollution caused by population.

Build_Airborne - This is hint for AI. This tech allows building air units.

The anatomy of a terrain ruleset file

Terrain.ruleset
has descriptions of generic terrain options, terrain types, resources, since 2.2 military bases, since 2.5 roads, and since 2.6 extras. In earlier versions military bases; fortress and airbase, roads; road, railroad, river, other extras; irrigation, farmland, mine, pollution, fallout, hut are completely hardcoded.

General

[options]
may_road = TRUE         ; FALSE means no, TRUE means yes
may_irrigate = TRUE     ; FALSE means no, TRUE means yes
may_mine = TRUE         ; FALSE means no, TRUE means yes
may_transform = TRUE    ; FALSE means no, TRUE means yes

Options tell what terrain alterations are possible for Settler-type units. Terrain transformation, road building over rivers, and second irrigation (Farmland), can have additional in-game requirements.

[parameters]

ocean_reclaim_requirement = 30
land_channel_requirement = 10
lake_max_size = 14
ocean_resources = FALSE
river_move_mode=1
river_defense_bonus=50
river_trade_incr=1
river_help_text=_("\
Any terrain type (except Ocean) may have a River on it.  A River adds 1\
 trade to the resources produced by that tile.  It also increases a tile's\
 defense factor by 50%.  Finally, land units may move along a River (but\
 not diagonally); movement along a River costs only 1/3 of a movement point.\
\n\n\
Roads and railroads can only be built on River squares if your\
 civilization has learned Bridge Building technology.\
")
fortress_defense_bonus=100
road_superhighway_trade_bonus=50
rail_food_bonus=0
rail_shield_bonus=50
rail_trade_bonus=0
pollution_food_penalty=50
pollution_shield_penalty=50
pollution_trade_penalty=50
fallout_food_penalty=50
fallout_shield_penalty=50
fallout_trade_penalty=50

Parameters are well documented in the classic ruleset.

Terrains

[terrain_forest]
name                 = _("Forest")
graphic              = "forest"
graphic_alt          = "-"
identifier           = "f"
movement_cost        = 2
defense_bonus        = 50
food                 = 1
shield               = 2
trade                = 0
resources            = "resource_pheasant", "resource_silk"
road_trade_incr      = 0
base_time            = 1
road_time            = 4
irrigation_result    = "terrain_plains"
irrigation_food_incr = 0
irrigation_time      = 5
mining_result        = "terrain_forest"
mining_shield_incr   = 0
mining_time          = 15
transform_result     = "terrain_grassland"
transform_time       = 24
clean_pollution_time = 3
clean_fallout_time   = 3
warmer_wetter_result = "terrain_jungle"
warmer_drier_result  = "terrain_desert"
cooler_wetter_result = "no"
cooler_drier_result  = "no"
native_to            = "Land", "Air", "Missile", "Helicopter"
flags                = "Starter", "CanHaveRiver"
property_dry         = 30
property_foliage     = 50
property_temperate   = 50
helptext             = _("\
Forests are densely wooded, making agriculture somewhat\
 problematic.\
")

name - User visible name of the terrain

graphic - Graphics tag for terrain. Client will search correct graphics from tileset based on this tag.

graphic_alt - Fallback graphics tag in case tileset has no graphics for main tag.

identifier - One letter identifier used in savegames. Must be unique, and cannot be '?'.

movement_cost - How much movement points units moving on that terrain will need for single move. This affects only those unit classes which have flag TerrainSpeed

defense_bonus - Bonus to defense value of the units standing on this terrain

food,shield,trade - How much food, production and trade citizen working on this tile would produce.

resources - List of resources that can appear on this terrain. Resources are defined later in terrain.ruleset.

road_trade_incr - How much more trade citizen working on this terrain will produce, if tile has road.

base_time - New in 2.5 How many movement points it will cost for Settler to build base to this terrain. This applies to any base type that has base type specific build_time set to 0.

road_time - How many movement points it will cost for Settler to build road on this terrain. Since 2.5: This applies to any road type that has road type specific build_time set to 0.

irrigation_result - Terrain that will result from irrigating this one. If the result is either terrain itself or "yes", irrigation builds real irrigation and later farmland on tile. If the result is "no", irrigation is not at all possible.

irrigation_food_incr - How much more food citizen working on this terrain will produce, if tile has irrigation.

irrigation_time - How many movement points it will cost for Settler to irrigate this terrain.

mining_result, mining_shield_incr, mining_time - These work like irrigation fields above, but for mining.

transform_result - Terrain that will result from transforming this one.

transform_time - How many movement points it will cost for Settler to transform this terrain.

rail_time - How many movement points it will cost for Settler to build railroad on this terrain. This assumes tile already has road. Removed in 2.5

clean_pollution_time - How many movement points it will cost for Settler to clean pollution from this terrain.

clean_fallout_time - How many movement points it will cost for Settler to clean fallout from this terrain.

warmer_wetter_result, warmer_drier_result, cooler_wetter_result, cooler_drier_result - These give terrain types that will result when global warming or nuclear winter change terrain.

native_to - List of unit classes that can natively exist in this terrain. Units cannot enter terrain that is not native to them, except inside some kind of transport. New in 2.2

flags - Terrain type flags. These are listed below.

property_mountainous, property_green, property_foliage, property_tropical, property_temperate, property_cold, property_frozen, property_wet, property_dry, property_ocean_depth - Percentage of how much of given property terrain has. This is mainly used to determine terrain placement when map is generated.

helptext - Helptext for user, visible on client help browser.

Terrain flags

NoBarbs - Barbarian units never appear in this terrain. This doesn't mean they cannot move to this tile once born.

NoCities - Cities cannot be built or found from huts on this terrain.

NoPollution - Pollution never appears on this terrain.

Starter - This terrain is possible starting position for players.

Oceanic - Terrain belongs to oceanic terrains class. This has big impact on how terrain is handled and what rules apply to it. For most part, these effects are still hardcoded.

FreshWater - Map generator will use this terrain type for small bodies of water. New in 2.2

Resources

[resource_wheat]
name        = _("Wheat")
graphic     = "ts.wheat"
graphic_alt = "-"
identifier  = "j"
food        = 2

name - User visible name of the resource

graphic - Graphics tag for base. Client will search correct graphics from tileset based on this tag.

graphic_alt - Fallback graphics tag in case tileset has no graphics for main tag.

identifier - One letter identifier used in savegames. Must be unique.

food,shield,trade - How much additional resources citizen working on tile will get, if this kind of resource is on tile.

Base types

Configurable base types are new feature in 2.2

[base_airbase]
name         = _("Airbase")
graphic      = "base.airbase"
graphic_alt  = "-"
activity_gfx = "unit.airbase"
reqs         =
    { "type", "name", "range"
      "Tech", "Radio", "Player"
      "TerrainClass", "Land", "Local"
      "UnitFlag", "Airbase", "Local"
    }
gui_type     = "Airbase"
build_time   = 3
native_to    = "Air", "Helicopter", "Missile"
flags        = "NoStackDeath", "DiplomatDefense", "ParadropFrom"

name - User visible name of the base

graphic - Graphics tag for base. Client will search correct graphics from tileset based on this tag.

graphic_alt - Fallback graphics tag in case tileset has no graphics for main tag.

activity_gfx - Graphics tag for unit activity. This is icon shown over unit when it's building this kind of base.

buildable - Whether player can ever build bases of this type. Defaults to TRUE. Bases of this type can still be added from editor.

pillageable - Whether player can ever pillage bases of this type. Defaults to TRUE.

reqs - Requirements for building this kind of base. See effects.ruleset for description of requirements description.

gui_type - Whether client should handle this base as "Fortress" or "Airbase". For instance, this affects which keys are used ot order unit to build this kind of base.

build_time - How many move points it will cost for Settler to build this kind of base. Since 2.5: Value of 0 means that terrain specific base_time is used instead.

defense_bonus - Percent added to defense

border_sq - Base will claim land ownership up to this radius, -1 to disable

conflicts - List of other bases that cannot be on the same tile. Bases with non-zero border_sq automatically conflict with each other.

native_to - Unit classes that can safely stay in tile with this base. Units in native base do not need fuel even if they otherwise would. Only those units for which base is native, are considered to be inside base.

flags - Base flags. Described below.

Base flags

NoAggressive - Units inside base are not causing unhappiness in their homecity. Base must be within 3 squares from friendly city for this effect to be active.

NoStackDeath - Units inside base do not die all at once, when one of them is killed.

DiplomatDefense - Diplomats inside base will get bonus to diplomatic defense.

ParadropFrom - Paradrop units can initiate paradrop from within this base.

NativeTile - Units inside consider base tile native regardless of terrain.

Road types

Configurable road types are new feature in 2.5

[road_road]
name         = _("Road")
reqs           =
    { "type", "name", "range"
      "UnitFlag", "Settlers", "Local"
    }
move_cost    = 1
build_time   = 0
food_bonus   = 0
shield_bonus = 0
trade_bonus  = 0
native_to    = "Land"

name - User visible name of the road

reqs - List of requirements for building road

move_cost - How many movement points it takes to travel via this road. Value of 3 indicates one full movement point.

build_time - How many move points it will cost for Settler to build this kind of road. Value of 0 means that terrain specific road_time is used instead.

food_bonus, shield_bonus, trade_bonus - Percent added to output of tiles with this road.

native_to - Unit classes that consider tile with this road native regardless of terrain.

flags - Road flags. Described below

Road flags

NativeTile - Units on this road consider tile native regardless of terrain.

The anatomy of an effects ruleset file

The effects.ruleset file contains all effects in play in a Freeciv scenario. They have the following form (this is perhaps the most complicated example I could find):

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

The text in the brackets is the entry name, which just has to be unique, but is otherwise not used. The name field tells Freeciv which effect 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. Lastly there is the nreqs table which is the opposite of the reqs field, these are conditions which prevent the effect from taking place. Any one of the nreq conditions will prevent the effect from taking effect.

Value is integer amount parameter for many effects (must be in the range -32767 to 32767).

Requirement range may be one of: "None", "Local", "CAdjacent" (Cardinally Adjacent) New in 2.4, "Adjacent", "City", "Continent", "Player", "Alliance" New in 2.6, "Team" New in 2.6, "Traderoute" New in 2.6, "World". Some requirement types may only work at certain ranges. In particular, at present, "Continent" effects can affect only cities and units in cities.

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

A requirement may have a negated field, and if this is 'TRUE', the requirement is negated. Beginning from 2.6 negated is replaced with present field, defaulting to 'TRUE', but if 'FALSE' requirement must not be fulfilled.

A requirement type is the type of the requirement and can be one of "None" (default), "Tech", "TechFlag" (New in 2.5), "Gov", "Building", "Extra" (New in 2.6), "ExtraFlag" (New in 2.6), "Special" (Replaced by "Extra" in 2.6), "Base" (New in 2.2, Replaced by "Extra" in 2.6) , "BaseFlag" (New in 2.6), "Road" (New in 2.5, Replaced by "Extra" in 2.6), "RoadFlag" (New in 2.6), "Resource" (New in 2.5, Replaced by "Extra" in 3.0), "Terrain", "UnitType", "UnitFlag", "UnitClass", "UnitClassFlag" (New in 2.?), "Nation", "Nationality" (New in 2.5), "OutputType", "MinSize", "MinCulture" (New in 2.6), "AI" (New in 2.2), "TerrainClass" (New in 2.2), "TerrainFlag" (New in 2.5), "TerrainAlter" (New in 2.?), "Achievement" (New in 2.6), "CityTile" (New in 2.?), "MinYear" (New in 2.?), "DiplRel" (New in 2.6), "Style" (New in 2.6), "UnitState" (New in 2.6), "MinMoveFrags" (New in 2.6), "BuildingGenus" (New in 3.0) and "MinTechs" (New in 3.0). MinSize is the minimum size of a city required. AI is ai player difficulty level. TerrainClass is either "Land" or "Oceanic". UnitState is "Transported", "Transporting" (New in 3.0), "OnDomesticTile" (New in 3.0), "OnLivableTile" or "HasHomeCity" (New in 3.0).

The following table shows you all the effect types the Freeciv game engine provides.

Effect type	Value range	Explanation
Tech_Parasite		Gain any advance known already by amount number of other players. 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).
Airlift		Allow airlift to/from a city. Starting from 2.2 amount of units can airlift each turn.
Any_Government		Allow instant government changes.
Capital_City		The city with this effect is the capital city.
Enable_Nuke		Allows the production of nuclear weapons.
Enable_Space		Allows the production of space components.
Specialist_Output		Specify what outputs a specialist is producing. Should be used with an OutputType requirement.
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_Add_Tile		Add amount to each worked tile.
Output_Inc_Tile		Add amount to each worked tile that already has at least 1 output.
Output_Per_Tile		Increase tile output by amount percent.
Output_Waste_Pct		Reduce waste by amount percent.
Force_Content		Make amount unhappy citizens content. Applied after martial law and unit penalties.
Give_Imm_Tech		Give amount techs immediately.
Growth_Food		Food left after cities grow or shrink is amount percent of the capacity of the city's foodbox. This also affects the 'aqueductloss' penalty.
Have_Contacts  i  New in 3.0.		Provides contact with all the other players.
Have_Embassies		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)
Make_Content		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 amountper unit of unhappy citizens caused by units outside of a city content.
Make_Happy		Make amount citizens happy.
No_Anarchy		No period of anarchy between government changes. (This also neuters the Has_Senate effect.)
No_Sink_Deep		Triremes no longer sink when on dangerous seas.
Nuke_Proof		City is nuke proof.
Pollu_Pop_Pct		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.
Reveal_Cities		Immediately make all cities known.
Reveal_Map		Immediately make entire map known.
Incite_Cost_Pct		Increases revolt cost by amount percent.
Unit_Bribe_Cost_Pct  i  New in 2.6.		Increases unit bribe cost by amount percent.
Size_Adj		Increase maximum size of a city by amount.
Size_Unlimit		Make the size of a city unlimited.
Health_Pct  i  New in 2.2.		Reduces possibility of illness (plague) in a city by amount percent. This has no effect in rulesets which do not have plague enabled.
SS_Structural, SS_Component and 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.
Stealings_Ignore  i  New in 3.0.		When determining how difficult it is to steal a tech from enemy, AMOUNT previous times tech has been stolen from the city is ignored.
Move_Bonus		Add amount movement to units. Use UnitClass' requirement with range of 'Local' to give it a specific class of units only.
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.
Veteran_Build		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		Increases the chance of units of this type becoming veteran after combat by amount percent.
HP_Regen		Units that do not move recover amount percentage of their full hitpoints per turn.
City_Vision_Radius_Sq		Increase city vision radius in squared distance by amount tiles.
Unit_Vision_Radius_Sq		Increase unit vision radius in squared distance by amount tiles.
Defend_Bonus		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.
No_Incite  i  Replaced with the Incite City action in 2.6		City cannot be incited.
Gain_AI_Love		Gain amount points of "AI love" with AI(s).
Slow_Down_Timeline		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.
Civil_War_Chance		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.
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.
Empire_Size_Base  i  New in 2.2.		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.
Empire_Size_Step		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.
Max_Rates		The maximum setting for each tax rate is amount.
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.
Rapture_Grow		Can rapture grow cities.
Unbribable_Units  i  Replaced with the Bribe Unit action in 2.6		Units cannot be bribed.
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.
Revolution_Unhappiness  i  New in 2.6		If a city is in revolt for more than value turns, government falls.
Has_Senate		Has a senate that prevents declarations of war in most cases.
Inspire_Partisans		Partisan units (defined in units.ruleset) may spring up when this player's cities are taken.
Happiness_To_Gold		Make all Make_Content and Force_Content effects instead generate gold.
Fanatics		Units with "Fanatics" flag incur no upkeep.
No_Diplomacy		Cannot use any diplomacy.
Not_Tech_Source  i  New in 2.5		Tech cannot be received from this player by any means.
Trade_Revenue_Bonus		Trade revenue is multiplied by pow(2, amount/1000). The amount value is taken from the caravan's home city.
Traderoute_Pct  i  New in 2.6		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.
Unhappy_Factor		Multiply unhappy unit upkeep by amount.
Upkeep_Factor		Multiply unit upkeep by amount.
Unit_Upkeep_Free_Per_City		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.
Output_Waste		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_Penalty_Tile		When a tile yields more output than amount, it gets a penalty of -1.
Output_Inc_Tile_Celebrate		Tiles get amount extra output when city working them is celebrating.
City_Unhappy_Size  i  New in 2.2.		Each citizen after amount of citizens are unhappy instead of content.
Turn_Years  i  New in 2.2.		Calendar advances amount years each turn unless Slow_Down_Timeline effects override this.
Turn_Fragments  i  New in 2.6.		Calendar advances amount fragments each turn, in addition to years advanced by Turn_Years.
Upgrade_Price_Pct  i  New in 2.2.		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.
Tech_Cost_Factor  i  New in 2.2.		Multiplier for research cost.
Shield2Gold_Factor  i  New in 2.2.		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.
Tile_Workable  i  New in 2.2.		If value != 0, city can work target tile.
Visible_Walls  i  New since 2.1.0-beta3		Positive amount only instructs clients to use wall graphics for city. Since 2.6: Exact amount tells wall set to draw
Migration_Pct  i  New in 2.2		Increase the calculated migration score for the a city by amount in percent.
City_Radius_Sq  i  New in 2.3		Increase the squared city radius by amount. Currently, this can only usefully have "MinSize", "Building", or "Tech" requirements.
City_Build_Slots  i  New in 2.3		Increase the number of units with no population cost a city can build in a turn by amount. The required shields must be available.
Tech_Upkeep_Free  i  New in 2.3		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.
City_Image  i  New in 2.4		The index for the city image of the given city style. Allows to align the city image with the city radii.
Irrig_Possible  i  New in 2.4		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.
Transform_Possible  i  New in 2.5		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.
Mining_Possible  i  New in 2.5		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.
Irrig_TF_Possible  i  New in 2.5		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.
Mining_TF_Possible  i  New in 2.5		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.
Irrigation_Pct  i  New in 2.6		This effect controls how much of the terrain specific irrigation bonus applies.
Mining_Pct  i  New in 2.6		This effect controls how much of the terrain specific mining bonus applies.
Output_Tile_Punish_Pct  i  New in 2.6		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.
Max_Trade_Routes  i  New in 2.5		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.
Gov_Center  i  New in 2.5		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.
Enemy_Citizen_Unhappy_Pct  i  New in 2.5		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.
Victory  i  New in 2.6		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.
Performance  i  New in 2.6		Value of this effect is how much Performance-type culture the city is producing. Performance is not persistent culture, but affects only current turn.
History  i  New in 2.6		Value of this effect is how much cumulative History-type culture the city is producing.
National_Performance  i  New in 2.6		Value of this effect is how much Performance-type culture the nation is producing in addition to that produced by individual cities.
National_History  i  New in 2.6		Value of this effect is how much cumulative History-type culture the city is producing in addition to that produced by individual cities.

ai_effects.ruleset
script.lua

... more details will follow soon. Typically an effects.ruleset contains *include default/ai_effects.ruleset as cheat sheet for AIs.

How to introduce your ruleset collection

... more details will follow soon.

How to create a new ruleset - step by step

These instructions are for a Unix or Linux installation. These are quick and dirty instructions; it is better to store successive versions of yor ruleset in a suitable development area, then install them in the Freeciv data directory when they are ready, but such complexities are outside the scope of this note.

• Decide on a name for your new ruleset. This should be a single word. For example, seawolf.
• Locate the Freeciv data directory. For example, on my Debian GNU/Linux computer this is /usr/share/games/freeciv. That directory will have a sub directory called default and a file named default.serv.
• Copy the content of that default sub directory to a new directory that has the same name as yor ruleset, and is in the Freeciv data directory. For example, if creating the seawolf ruleset on my Debian GNU/Linux computer, this would create files such as /usr/share/games/freeciv/seawolf/buildings.ruleset and /usr/share/games/freeciv/seawolf/cities.ruleset.
• Copy the default.serv script to create a new file in the Freeciv data directory, but with the name of yor ruleset instead of 'default'. For example, /usr/share/games/freeciv/seawolf.serv.
• Add a 'rulesetdir' command to the end of that script to select your ruleset. For example, rulesetdir seawolf
• You have now created a new ruleset, with your chosen name, having the same rules as the default ruleset.
• Your ruleset should now appear in the menu of available rulesets, if you are using the client to start a local server. You will probably have to restart your client first, however.
• Examine and modify the files in your new ruleset directory, and the .serv script if necessary, to implement your changes to the rules.

Alternatively, copy the files to your ~/.freeciv directory, instead of /usr/share/games/freeciv/ (creating, for example, ~/.freeciv/seawolf/buildings.ruleset).

That has the advantage that you will not have to login in as the root user to create the ruleset, but the new ruleset will not be available to other users of your computer.

How to test your ruleset for errors

Use the command prompt and navigate to the freeciv server, e.g.:

cd /opt/bin/freeciv-2.1.9

Run the freeciv server, e.g.:

FREECIV-SERVER

Define the ruleset file, e.g.:

rules alien

The server will then display any errors or warnings.

See also

• Historic rulesets tutorial

Template:UpdateNavbox