Modpack UI icon

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

The anatomy of 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

; 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, appeared in version 2.2, are groups of unit types that mainly are related by similar way of movement and allocation (i.e., they can exist at the same terrains, share the same native roads and transporters, lose or not hitpoints per turn in the open etc.)

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.

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

Unit classes have move types "Land", "Sea" or "Both" (in 2.5 and earlier, these ones or "Air" were specified in "move_type" parameter, now figured out automatically and used only in unit selection dialog). The terrain.ruleset defines exact limitations where units of this class can move; "Land" units cannot move at any oceanic terrain. "Sea" units can move only at oceanic terrains.

Some units are slowed down when damaged. No matter how much damage they have, speed never drops below min_speed. Neither do any effects 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. Goes deprecated since v.3.1 (replaced with action enablers).
  • BuildAnywhere - Units can be built even if city is located in non-native terrain for unit; if all tiles around a city they are in are transformed to unsuitable ones, they are not disbanded. 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 unit types listing this class in its targets can attack them. 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.

Deprecated flags[]

  • 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.

Unit Types[]

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 move fragments. But note that it will be converted into fragments intristically. In older versions, if the result exceeds 253, the path-finding algorithm may count some moves wrongly (limit lifted to 65533 since v.2.6.1).

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; i.e., the unit with squared vision radius RSQ located at X0,Y0 can see a tile at X,Y if (X-X0)^2+(Y-Y0)^2≤RSQ. 1 means cardinally adjacent tiles, 2 means also diagonally adjacent ones. This value is additive with "Unit_Vision_Radius_Sq" effect.

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.

embarks lists unit types among the cargo that can be loaded when a transporter is out of a city or base. New in 2.???

disembarks is the same for unloading in an unprepared place. Note not being listed here does not prevent the cargo from other actions fron aboard, including attacks New in 2.???

fuel is number of turns that unit can live without refueling. To refuel, most fueled units must spend turn onset in a city or a native base. 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 Bonuses[]

You can set combat bonuses that a unit type has against units with particular unit type flags.

bonuses       =
   { "flag", "type", "value"
     "Helicopter", "DefenseDivider", 1
     "Helicopter", "Firepower1", 1

Firepower1 - when a unit with this bonus attacks, the defender's frepower is set to 1. DefenseDivider - when the unit attacks, target defense power is divided 1 + this number of times (i.e., 1 means halved). New in 3.1: you may set this effect in percentage with DefenseDividerPct.

DefenseMultiplier - when the unit defends, its defense power is multiplied 1 + this number of times (i.e., 1 means doubled). New in 3.1: you may set this effect in percentage with DefenseMultiplierPct.

New in 3.1: CityDefensePct - applied when the unit defends in a city center (multiplicative with the former), but "Defend_Bonus" effect in this case won't increase defense further.

Unit Type Flags[]

Unit type flag Introduced in v. Removed/unhardcoded in v. Meaning
TradeRoute 2.6 Unit can establish trade routes. Replaced by an action enabler in 2.6.
HelpWonder 3.0 Unit can be disbanded in city building Wonder to get full unit production cost towards finishing wonder. Replaced by an action enabler in 3.0.
HasNoZOC 2.6 Unit does not impose zone of control. Enemy units can pass freely around it.
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 or other roads faster then parameters.igter_cost from terrain.ruleset
OneAttack Unit can attack only once in a turn even if its move_rate is more than one.
Pikemen 2.5 Unit gets double defense power against units flagged as Horse. Since 2.5 combat bonuses unhardcode this.
Horse 2.5 Units flagged as Pikemen get double defense against these units. Since 2.5 combat bonuses unhardcode this.
IgWall 2.6 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. Unhardcoded in 2.6.
Cant_Fortify 2.6 Unit type can not fortify even if its class can. Before 2.6, any "Settlers" units could not do it.
FieldUnit Unit is considered aggressive - causing unhappiness - even if it's within home borders (and inside cities when server setting 'happyborders' is off)
AEGIS 2.5 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 perform diplomatic actions. If the unit does not have also Spy flag, it is always destroyed after missions (this is unhardcoded in 2.6).
Trireme 2.6 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 a terrain without "NoSafeCoast" flag. In 2.2 unit cannot move away from coasts at all.
CoastStrict 3.0
Coast 3.0 Unit can be refueled being adjacent to a safe coast tile.
Nuclear 3.0 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. Replaced by an action enabler in 3.0.
Provoking 3.0 Enemy units try to autoattack this unit even if its attacking combat strength is small.
Spy This flag works correctly only if unit has also Diplomat flag. Is stronger in a diplomatic combat and can perform or survive more diplomatic actions.
Transform 2.5 Unit can transform terrain as specified in terrain.ruleset. Since 2.5 "TF_Possible" effect is used instead.
Capturer 2.3 3.0 Unit can capture some other units. Since 3.0, an action enabler unhardcodes this.
Capturable 2.3 3.0 Unit can be captured by some other units. Since 3.0, an action enabler unhardcodes this.
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 2.1 2.2 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 2.5 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 2.5 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.
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.[1]
GameLoss If player loses unit of this type, he loses the whole game.
Unique Player can have only one unit of this type at a time.
Unbribable 3.0 Unit cannot be bribed. Unhardcoded in 3.0.
Undisbandable 3.0 Player cannot disband this unit. If the unit is upkept in shields and its home city can't pay the price, the city loses a citizen in a turn (this is unhardcoded with shield_protected flag list since 3.0). If such a unit perishes in a ship, it is teleported to a nearest owner's city if possible.
EvacuateFirst 3.0
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 level it was built.
Bombarder 3.0 Unit uses bombard attack. Replaced with an action enabler in 3.0.
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 a defender against attack to a 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 2.2 2.5 When units flagged as Fighter attack this unit, defender's firepower is considered to be 1 and defense value is halved. Since 2.5, the flag is unhardcoded.
AirUnit 2.2 2.5 Bad at attacking "AEGIS" units
Fighter 2.1 2.5 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). Since 2.5 the flag is unhardcoded.
BarbarianOnly 2.2 Unit can be built only by barbarian players. For other players this is similar to NoBuild
Missile 2.2 Unit is destroyed after it attacks even if it is victorious. In 2.2 this is unit class flag.
Carrier 2.2 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 2.2 Unit can transport units of classes Missile and Nuclear, but no others. See also Carrier.
Shield2Gold 2.2 Unit upkeep is switched from shield upkeep to gold upkeep if its owner has positive "Shield2Gold_Factor" effect that specifies the ratio; uk_gold is ignored in this case.
BeachLander 3.0 Unit can retain its movement points stepping from a non-native to a native terrain even if slow_invasions is on.
NewCityGamesOnly 3.0 Unit can't be built in scenarios where founding new cities is prevented.
CanEscape 3.0 When unit is in an attacked stack and its defender is lost, it has 50% chance to escape to a nearby tile if possible.
CanKillEscaping 3.0 Prevents "CanEscape" flag effect for units on a tile it attacks.

Unit Type Roles[]

Unit type can have multiple roles it fits in to. For starting units, first defined unit that fits the role related to a letter in "startunits" is placed unless the player can build (by player-ranged prerequisites) another non-obsolete unit of this role and either can't build the first one or it is defined later (thus in classic ruleset for "w" you get Workers and not Engineers unless you start with Explosives known). The information below is for versions 2.6 and 3.0 except pieces in italic.

"FirstBuild" - each newly founded city tries to build the best available unit with this role. A ruleset must have at least one.

"Explorer" - starting Explorer unit type ("x") mandatory in a ruleset until v.2.5. In versions around 2.5 and earlier, homed explorers at their home cities are disbanded by AI when the dummy can't find a better use of it.

"ExplorerStartUnit" (since v.2.6) - starting Explorer unit type ("x"). A ruleset must have at least one.

"Hut" - if you know techs for no available "Hut_Tech" unit type, this unit appears when a hut gives you mercenaries (softcoded in default.lua)

"HutTech" - when a hut produces a mercenary, it firstly looks for one of this role that the owner of the entered unit has a tech to build (softcoded in default.lua)

"Partisan" - placed by place_partisans() routine (the partisan placing is mostly softcoded in default.lua but you would have to place another units by your own and can't make them fortified). Only one unit type may have this flag.

"DefendOk" - starting defender unit ("d") until v.2.5. AI considers this type when gets a defender for a city.

"DefendOkStartunit" (since v.2.6) marks "d" starting unit.

"DefendGood" - starting good defending unit ("D") until v.2.5. AI considers this type when gets a defender for a city (twice more than "DefendOk") and as a bodyguard for a king.

"DefendGoodStartunit" (since v.2.6) marks "D" starting unit.

"AttackFastStartUnit" (until v.2.5: "AttackFast") - starting "a" unit.

"AttackStrongStartUnit" (until v.2.5: "AttackStrong")- starting "A" unit.

"FerryBoat" - A unit used for ferrying. A ruleset must have at least one. Must not have "Land" move type (since move types type have become implicit, that means "can move over some oceanic terrain"); also, to be successfully used, should not lose hitpoints (unless a recovery effect, e.g. from UNO wonder, compensates for it) or have fuel limitation (unless it's a coast-fueled unit). May be placed as a starting unit as "f" but then it will not be generated if it has "Sea" movement type until v.2.5. AI uses ferries to bring colonists, caravans, spies or invasion forces to another continents. Cities may hang out a flag to beckon ferries or build their own ones for these means.

"FerryStartunit" (since v.2.6) marks "f" starting unit (note, starting units are shifted to the closest possible tiles to the starting tile defined by random).

"Barbarian" - random units of this role are generated as land barbarians since game start. A ruleset must have at least one if the barbarians are not disabled at load time.

"BarbarianTech" - random units of this role are generated as land barbarians instead of starting ones since anybody knows the tech it requires.

"BarbarianBoat" - sea barbarians may appear loaded into single this unit, tech knowledge is not important. Must have transport capacity of 2 or more and be able to transport barbarian leader and all sea barbarian types (the uprising amount is limited by minimum of barbarian abundance level value and the capacity). Must not have "Land" move type. A ruleset must have at least one if the barbarians are not disabled at load time.

"BarbarianBuild" - barbarians can build these units in a city they control even if they don't have a tech for it. A ruleset must have at least one if the barbarians are not disabled at load time.

"BarbarianBuildTech" - barbarians can build these units in a city they control if any player has learned the tech. (They can build units of those two roles only and their AI selects one with the best attack value, so expect Cannons going in hordes from conquered cities since one has got Metallurgy).

"BarbarianLeader" - one such unit is generated at any barbarian uprising, if it is destroyed, the capturer may get a ransom. A ruleset must have at least one if the barbarians are not disabled at load time.

"BarbarianSea" - random units of this role are generated as sea barbarians since game start. A ruleset must have at least one if the barbarians are not disabled at load time.

"BarbarianSeaTech" - random units of this role are generated as sea barbarians since any player has learned the tech.

"CitiesStartunit" (until v.2.5: "Cities") - starting "c" unit.

"Settlers" - may perform terrain alterations (build bases or roads, irrigate, mine or transform). Starting "w" unit and mandatory for a runleset until v.2.5.

"WorkerStartunit" (since v.2.6) - starting "w" unit.

"KingStartUnit" (v.2.5: "GameLoss") - starting gameloss unit ("k"). This is the only role of starting units that (if they are on the game's starting set) is given to a nation separated in civil war, placed in a city that becomes the new nation's capital.

"DiplomatStartunit" - (until v.2.5: "Diplomat") - starting "s" unit.

"Hunter" - non-bararian AI qualifies these units as hunters suitable for destroying enemy units (diplomatic, able to transport or gameloss), maybe using missiles, if our Horsemen have no missiles, just attack or go closer to the target if it looks worthy. For cities to consider building the units for this purpose, they must have either "Land" or "Sea" movement type.

Some more about how AI manages units[]

AI (the default one) has several procedures of deciding what a specific unit does this turn. The procedures are decided in a fixed order, only the first suited one is applied:

  1. If the unit has orders (supposedly given to it by a human), AI does not manage it. Neither does it if the unit is out of moves.
  2. If the unit has flag "Diplomat" (in older versions, also "Spy"), it is used as a defensive or offensive diplomat.
  3. If the unit either has flag "Settlers" or can found new cities, it is managed by a civil manager.
  4. If the unit can perform action "Help Wonder", "Enter Marketplace" and/or "Establish Trade Route", it is managed as a caravan.
  5. If the unit has role "BarbarianLeader", it behaves as one.
  6. If the unit can paradrop, it is managed as a paratrooper.
  7. If the unit is a ferry and AI has not assigned it a hunter's task before, it is used as a ferryboat.
  8. If the unit requires fuel and is not a bodyguard/air escort of something, it is managed as an air unit (that means sometimes operating from a carrier)
  9. If the unit is losing hitpoints... AI just fails to manage it.
  10. If the unit is not a civilain, it is managed as a military unit:
    1. If it is a bodyguard/air escort, just does nothing;
    2. If it is a "Hunter" unit and the player is not barbarian, tries to hunt something; if there are still move points, hunts once again; then it may switch to the next point:
    3. Finds a military job (defend, attack, escort or recover), or autoexplores; then, if the unit survives, sentries or fortifies.
  11. Tries to autoexplore (that is a default result of some other branches if there is no primary tasks), and if nothing in available region is unexplored, just joins defensive forces.

Bodyguards/escort forces are normally selected before main AI movement, a unit that needs but has lost its bodyguard requests new one when it is processed. Units on a defensive job may do attacks, conquer cities or enter huts if they can do it this turn and it does not look too dangerous for their mission. Note also that as per v.2.6.3 AI does not know that bombardment is a special attack.

  1. 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.

See also[]

Editing Rulesets
Editing BuildingsEditing CitiesEditing EffectsEditing GameEditing Governments
Editing NationsEditing StylesEditing TechsEditing TerrainEditing Units