Modpack UI icon

This page describes (though not fully) the contents of a nation ruleset. It is intended as developer reference, and for people wanting to create/compile alternative nation files for Freeciv.

Nations.ruleset has some global definitions and section for each nation. Default ruleset is split to several files which use include-directive to combine themselves to single ruleset. Freeciv up to 2.4 had files in two levels. There's main nations.ruleset, and, included from it, ruleset for each nation. Starting from freeciv 2.5 there's three levels: nations.ruleset has just global definitions and it includes nationlist.ruleset, which has just list of include directives for individual nations. In ruleset of your own, you may want to replace main nations.ruleset only, including default nationlist.ruleset from it. Or you can provide also your own nation list that is subset of default one. Or you may even have individual nations defined yourself.

See also …/doc/README.nations in the Freeciv distribution.

Overview of Editing a Nationset[]

The purpose of the nationsets is to provide a flexible and detailed but not hard-coded way to describe the nations available within Freeciv games. This enables everyone to create add-ons to conveniently introduce additional nations for Freeciv. A nation consists of a nation ruleset file and a flag in the tileset.

The nationname bit used below is to be replaced with the nations name (duh). Please don't use whitespaces and special characters. Underlines are OK though.

The main nations.ruleset file[]

default_government = "Despotism"
warn_city_style    = 1

compatibility.default_government  tells what is the starting government of those nations that do not have it explicitly set in their own definition.

compatibility.warn_city_style  controls whether ruleset loading should give warnings about nations that have unknown city style. All such nations will use default city style regardless if the loading gave warnings or not. This setting is useful if you want to include default nation definitions, but have your own cities.ruleset that doesn't contain all the city styles that default nations are defined to use.

Also default values for AI traits are defined in main nations.ruleset. That's documented in traits.

The individual nation ruleset files[]

This file contains all the attributes of the nation you want to define. See the …/data/nation/aztec.ruleset file for an example, or examine other …/data/nation/ files. Your newly created file should be located under …/data/nation/nationname.ruleset, and the file name should be the same as the name of the nation inside the ruleset file.

The anatomy of a nation ruleset file[]

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

Attribute Example Content Explanation
translation_domain = "freeciv" FIXME: Maybe only for core nations.
 i  Since Freeciv 2.5.
name = _("Venetian") The name of the nation, an adjective.
plural = _("?plural:Venetians") The plural form of the nations name, a noun.
groups = "Medieval", "Early Modern", "European" These groups are used to categorize the playable nations in the Freeciv client. It facilitates the outline of nation selection.
legend = _("The Republic of Venice emerged from the shadows of history\
when refugees from barbarian marauders gathered on the safety of the\
islands of a lagoon in northeast Italy. Originally a loyal subject ...")
A summary of this nation shown by the Freeciv client. Possible topics are historical, geological, religious and other particular information about the nation.
leaders = "name", "sex"
"Enrico Dandolo", "Male"

"Giustiniano Participazio", "Male"

A collection of leader names associated to the nation. These are used as proposal to the human player for nation customization during game start. The sex of the leaders is either "Male" or "Female".
 i  Since Freeciv 2.3.
leader = "Enrico Dandolo", "Giustiniano Participazio" …  i  Not more supported since Freeciv 2.3, use leaders instead.
leader_sex = "Male", "Male" …  i  Not more supported since Freeciv 2.3, use leaders instead.
flag = "venice" This is the reference to the flag image file. Hence it has to be named after the image file.
flag_alt = "-" Another reference to a flag image file. This is used as fallback position if the primary flag file was not found and is usually empty.
city_style = "Classical" Here you can define which city images package will be used to visualize the cities for this nation. This attribute is only relevant when the nation gets used for computer players.
ruler_titles = { "government", "male_title", "female_title";
"Despotism", _("Condottiere %s"), _("Condottiera %s")
"Fundamentalism", _("Patriarch %s"), _("Matriarch %s")


This enumeration of ruler titles helps to adjust the leaders prefix depending on the currently used government of a civilization. %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.

init_techs = "" This list sums up the technologies one nation brings into game. The techs will be available to the nation directly after beginning. This is left empty for default rulesets.
init_buildings = "" This list sums up the buildings one nation brings into game. The buildings can be built by the nation directly after beginning. This is left empty for default rulesets.
init_government = "Despotism" This is a single value attribute. A valid value would be one of the global defined governments. This is always Despotism for default rulesets.
init_units = "" This list sums up the units one nation brings into game. The units can be built by the nation directly after beginning. This is left empty for default rulesets.
conflicts_with = "roman", "italian" Specifies one or more nations that should be avoided in the same game (for instance, the AI will prefer not to pick a nation conflicting with one already in the game). This is optional and should only be used when necessary; reasons for conflicting nations could be either that they represent the same people in different eras (e.g., Aztec and Mexican), or that the two nations' flags are too similar (e.g., Irish and Italian). Adding this to one nation works in both directions.
civilwar_nations = "cypriot", "italian", "croatian" Here you can give a list of references to other nation files. These nations will be used if a nation is split due to civil war, and their cities will be used if this nation's cities run out.
cities = "Venesia",


This list sums up the cities one nation used during their 'historical' evolvement. The city names are used as proposals to the human player for naming newly created cities. Just like the leader names it is preferred to use names in the nation's native language.
is_playable = FALSE Required for barbarians, FALSE was 0 before Freeciv 2.5.
barbarian_type = "Land" Only required for barbarians: "Land", "Sea", or "LandAndSea".
 i  Since Freeciv 2.2, Freeciv 2.1 had is_barbarian=1.

How to introduce your nation ruleset file[]

There are several files where you will have to unveil the existence of your nations ruleset file before you are able to choose it inside a Freeciv game. Since these files will have to be edited before your nation can be included in the main distribution it will have to be done anyway. But unless you know what you're doing you shouldn't need to worry about this. If you're not capable to apply the needed changes feel free to submit your creations and help will be on the way for the remaining steps.

If you want to try it on your own just add a reference to your nation ruleset file to the lists in the following files:

Changes related to game playing:
 i  This was data/default/nations.ruleset up to version 2.4.5
  • /data/default/nationlist.ruleset
    This lists all nation files and is read by the game engine on startup. An existing nation file which didn't get introduced in here will never appear in your game. Add your nation (nation/nationname.ruleset) to this list.
Changes related to software development:
  • /data/nation/
    is a list of all Freeciv project related files. This file tells the project build machinery which files to pack into installable (and executable, of course) Freeciv packages. Lookup the already enumerated nation ruleset files and append yours. The file could be automatically created, see …/data/nation/
  • /translations/nations/
    is yet another list of nations files; the reference in here will be used for translating purposes. Add your nation (data/nation/nationname.ruleset) to it.

Further posibilities for nation definition[]

 i  This was data/scenario/* up to version 2.3.5

In this folder you can deposit scenario files. These files help to adjust further options for game play.

  • You are able to define a scenario map to play on.
  • You can add starting position for your nation on that scenario map.
  • You can define the amount of resources available at game start.
  • …and many more things.

To personalize a nation ruleset without SVG skills all you need is a text editor supporting UTF-8 (or its proper subset US-ASCII in simple cases), copy and paste the annotated native.ruleset to data/nations/native.ruleset, optionally rename and edit it as you see fit, and reference the result in …/data/default/nationlist.ruleset.

The nation flag image file[]

A new nation needs a new flag. You should provide a unique flag for your nation. It may help to copy one of the other flag files over to be able to start a nations development. But using a flag that is already used by another nation in the game is only acceptable as contribution if there are profound reasons existent.

If you are creating a real-world nation you can probably find a Free or public domain flag that can be used. Good places to look are the Open Clip Art Library, Wikimedia Commons, and Flags of the World.

We also welcome improvements to existing flags. Many of our existing flags come from the Open Clip Art Library (formerly the Sodipodi clipart collection), and some of them are less than perfect. One common problem is that the colors are wrong. If you fix a flag for a real nation be sure to cite your source so we can be sure it's accurate. If you want to add or improve a flag for a fantasy nation, this is also welcome.

We recommend you first contact the original author of the flag (see …/data/misc/flags.spec artists) to discuss your ideas for changes. The SVG versions of all flags shipped with Freeciv are now also available here in the Flags Catalogue, with not yet fixed invalid SVG in Category:Broken SVG.

Any flags we add must be licenced under the GPL and should be attributed to their original author, so make a note of where you found the flag, what its licence is, and who made it. Note that the GNU Free Documentation License is not compatible with GNU GPL v2. See Freeciv:Copyrights, Help:Image_copyright_tags and Help:Copying_from_Wikipedia for more information.

Flags should be rectangles, since an outline is added to them automatically. Flags often come in multiple aspect ratios. A 3:2 ratio looks best for Freeciv; and all current flags use this ratio. Other common ratios are 2:1, 1:1, or 4:3. To add a flag you'll have to edit the following files:

  • This is your nations flag image file in SVG format. This is not used directly by Freeciv but is rendered into PNG files (at various resolutions for different tilesets). The nationname should preferably be a geographical name rather than an ethnonym (e.g. Venice instead of Venetian) although currently some flags do not follow this.
  • /data/flags/nationname.png (29×20)
  • /data/flags/nationname-shield.png (14×14)
  • /data/flags/nationname-large.png (44×30)
  • /data/flags/nationname-shield-large.png (19×19)
    These are the flag images that are used by Freeciv. They are rendered from the SVG file with a converter of your choice. For the shields you can use …/data/flags/mask.png and …/data/flags/mask-large.png. On some platforms you can use the bash-script …/data/flags/convert_png for this job, cf. draft.
  • /data/misc/flags.spec
    This file has a reference to the flag PNG graphic. The "tag" here must match the flag tag you put in the nation.ruleset file (usually f.nationname, and the "file" should point to the PNG image at flags/nationname.png. Don't forget to add the flag's creator's name to the credits.
  • /data/misc/shields.spec
    Just like flags.spec, this file must include a reference to the flag PNG graphic. The only difference is that the file should point to the "shield" graphic, flags/nationname-shield.png.
  • /data/misc/flags-large.spec
  • /data/misc/shields-large.spec
    Ditto for the large flags and shields.

Changes to the .spec files can be submitted as a patch (created using diff -ruN). Even though the

  • .spec files may need to be changed, please include them in the diff -- this should be easier for you, and it provides a convenient place for us to grab the sprite name. See the section on How to Contribute for more instructions.

How to introduce your nation flag image file[]

There are two files where you will have to unveil the existence of your nations image file. Add your nation flag file to the following files:

Changes related to game playing:
  • Here you should have already referenced your image file via the flag=nationname attribute.
Changes related to software development:
  • /data/flags/
    This file tells the project build machinery which files to pack into executable Freeciv installation packages. Perceive the already enumerated nation flag files and append yours. You will have to add it five times (flag, flag-large, shield, shield-large, and SVG).

Nations Mini-FAQ[]

These address a few problems and questions about adding nations.

In what order should I list cities in Nation ruleset files?[]

Usually the cities are ordered by either population size, age or a combination of both. The first city is often the nation's capital. A discussion of city ordering appears in the freeciv-dev archive, there is even a perl script available to do the job in the same thread.

What nations can be added to Freeciv proper?[]

Freeciv includes modern, historical and imaginary nations. Modern nations are existing (independent) states, historical nations existed in past times but have ceased to exist, and imaginary nations are those that are products of the fantasy of a book writer. See also …/doc/README.nations in the Freeciv distribution for details of policy.

If you want to have a new nation added to Freeciv proper, write a ruleset file while following the guidelines below and then draw a 3:2 flag image in svg (vector) format. Ruleset and flag image put together is known as a nationset. Submit the nationset in a patch ticket at the Freeciv project at Gna. The nations maintainer will review the nationset against Freeciv project standards and commit it to the development branch if accepted.

Non-imaginary nations should be countries that are currently independent or that have been independent in the past. The game includes a small number of nations that have never been independent but that are significantly different from the mainstream ethnicity in their country (e.g. Québécois). Provinces, states or other sub-national entities with neither a history as an independent nation nor a significant ethnic distinction are not included in Freeciv (examples of nations that have been rejected are the Pennsylvanians, the Murcians and the Paulistas).

A modern nation must be restricted to its current territory today; you should leave out any cities not on this territory. The reason for this is, we don't want Freeciv to be used as a political vehicle for discussions about the borders or independence of nations and avoid trouble with other ruleset authors.

Choosing leader names is not that restricted, but there should be a strong historical relation to the nation you create. Try to include some female leaders if possible.

Keep in mind that inclusion (or omission) of a leader does not imply a moral judgment. To prevent political discussions Freeciv does not prohibit the inclusion of leaders of questionable reputation. Several nations include dictators or other mass murderers amongst their leaders. The ground for inclusion should be importance, not moral character. Nevertheless, it is recommended to balance 'good' and 'evil' leaders.

Both leader and city names should be in the nation's language and in original orthography. There is some leeway here, if the language of the government is different from the one spoken by the population you can use either language. Make sure you are not using English or Latinized names if English or Latin is not the native language nor the language of the government (e.g. Konstantinoupolis rather than Constantinople). Try to be consistent in orthography and transliteration.

Imaginary nations are usually based on mythology, folklore or supranational organizations. Keep in mind that imaginary nations that are subject to copyright can not be included in the game.

What about relative geographical positions of cities?[]

Cities are not given in their relative geographical positions. However there is a feature in Freeciv that supports city placement according to the geological environment where it is founded. You are able to add some attributes to each city name, such as hills, forest, river. A leading exclamation mark ! expresses the absence of that type of geological environment.

The syntax looks like this:

"Mannheim (grassland, forest, river, !ocean)",
"Bonn (plains, forest, river)",

For the sake of human readability, one city per line is appropriate.

Testing Nation Rulesets[]

Here are a few tips on how to test your nation rulesets for errors.

  • Run the server separately to check for errors: On the command line, do freeciv-server or ./ser in the source dir if you build Freeciv yourself. Note any errors and correct your ruleset accordingly.
  • Run the server in verbose mode: freeciv-server -d 3 or ./ser -d 3 - this will output non-fatal errors such as typos in nation or terrain references.
  • Run the server in very verbose mode: First configure with --enable-debug, then run freeciv-server -d 4:ruleset.c or ./ser -d 4:ruleset.c.