Editing Terrain

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 terrain ruleset file

…/data/classic/terrain.ruleset

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.

[control]
flags = {"name", "helptxt"
    _("Oil"), _("Has Oil Well instead of Mine.")
}
extraflags = "name", "helptxt"
}

Custom flags for terrains and (since 2.6) extras, with autogenerated help text lines.

Before v.2.5, section [options] told what terrain alterations are possible for Settler-type units. In modern game versions, all requirements for it are handled elsewhere. There also were hardcoded parameters for some terrain alterations that are moved to corresponding sections now.

[parameters]
ocean_reclaim_requirement = 30
land_channel_requirement = 10
thaw_requirement=0;   since 2.6
freeze_requirement=0; since 2.6
lake_max_size = 14
ocean_resources = FALSE
min_start_native_area=0        ; since 2.5
move_fragments=3               ; since 2.5
igter_cost=1                   ; since 2.5
pythagorean_diagonal=FALSE     ; since 2.6
ui_name_base_fortress=; since 2.6, override for "Build Type A Base" in the menu
ui_name_base_airbase=; since 2.6, override for "Build Type B Base" in the menu
pollution_food_penalty=50
pollution_shield_penalty=50
pollution_trade_penalty=50
fallout_food_penalty=50
fallout_shield_penalty=50
fallout_trade_penalty=50; other output types may be penalized as well

Parameters are well documented in the classic/terrain.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.

Brief description of map generator

Freeciv is proud of having cool and flexible system of random map generations. There are several types of island generators available that are fed with a random seed separate from the main PRNG random seed and several geographical parameters that influence the probability of getting certain terrain type with certain specials in a certain place.

The function called at the game start is map_fractal_generate() from server/generator/mapgen.[ch]. It firstly converts the geographical settings into terrain predefined macro-type percentages (see adjust_terrain_param(), they are mountain, forest, jungle, river, swamp and desert_pct). Next, it initializes the first approximation of temperature map (there are four actual temperature levels - tropical, temperate, cold and frozen; here, the selection is based on world's temperature settings and map colatitude that is produced from tile's coordinates due to the topology). Then, it applies the height map that makes continents, mountines and all this way; if one generator fails (that happens, check the output), it tries another one. The moment when the rivers are generated depends on the generator but they flow to the ocean from non-frozen terrains, mainly by lowlands.

Most terrains are finally selected by pick_terrain() function from server/generator/mapgen_utils.[ch]. This function is called many times three parameters each of which may refer to some one of the ruleset terrain parameters that are described in property_* fields: one that is proportional to the probability of getting this particular terrain among others possible, one avoided (must be 0) and one preferred (must be greater than 0). If no fit terrains are found, it drops some parameters (first preferred, then avoided, then target) to return just any generatable terrain.

Temperature comes from latitude (15% more temperate at shoreline), moisture from oceanic tiles around, mountainous/oceanic from the mapgen-dependent height pattern. Mountainous terrains are more green in hot regions. Foliage is counted towards forest and jungle counters (estimated forest+jungle percentage is ("wetness" server setting × 40 + 700) × some adjusting factor).

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

New flags since 2.6:

NotGenerated - Map generator never places this terrain type. It can be added from editor only, or by ingame events (lua scripting) NoZoc - Units on this terrain are not generating or subject to zoc NoFortify - Units cannot fortify on this terrain Frozen - Frozen/polar terrain. For water tiles, Frozen terrain is generated near poles. Conversion between frozen and unfrozen can be controlled with thaw_requirement/freeze_requirement, and Frozen terrain is shown differently on the overview map.

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.