Nations | Editing Rulesets | Editing tilesets | Themes | Sounds | Event Scripting
Rulesets and modpacks forum | Art and tilesets forum

Back to Game Mods page | Talk:Game Mods

---

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.

Contents 1 Overview of Editing a Nationset 2 The nation ruleset file 2.1 The anatomy of a nation ruleset file 2.2 How to introduce your nation ruleset file 2.2.1 Changes related to game playing 2.2.2 Changes related to software development 2.3 Further posibilities for nation definition 3 The nation flag image file 3.1 Flag Guidelines 3.2 Flag Specifics 3.3 How to introduce your nation flag image file 3.3.1 Changes related to game playing 3.3.2 Changes related to software development 4 Testing Nation Rulesets 5 Nations Mini-FAQ 5.1 In what order should I list cities in Nation ruleset files? 5.2 What nations can be added to Freeciv proper? 5.3 What about relative geographical positions of cities?

Overview of Editing a NationsetEdit

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 rulesets file and a flag in the tilesets.

i 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 nation ruleset fileEdit

This file contains all the attributes of the nation you want to define. See the aztec.ruleset file for a introducing example and feel free to examine the other nations files. It may help to copy one of them over and edit it.

i Your newly created file should be located under data/nation/<nationname>.ruleset.

i The file name should be the same as the name of the nation inside the ruleset file.

The anatomy of a nation ruleset fileEdit

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
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" "Pietro Tribuno", "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 Leader names should be in the native language as much as possible. Check if you are not using Anglicized or Latinized names and try to be consistent in orthography. i Since Freeciv 2.3.
leader	=	"Enrico Dandolo", "Giustiniano Participazio", "Pietro Tribuno", ...	A collection of leader names associated to the nation. These are used as proposal to the human player for nation customization during game start. i Leader names should be in the native language as much as possible. Check if you are not using Anglicized or Latinized names and try to be consistent in orthography. i This field is no more supported since Freeciv 2.3. Use leaders field instead.
leader_sex	=	"Male", "Male", "Male" ...	Here you define the sex of the leaders numerated above. The sequence of the list follows the leader name list. i This field is no more supported since Freeciv 2.3. Use leaders field 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", "Eraclea", "Aquiłeja", ...	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.

How to introduce your nation ruleset fileEdit

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 playingEdit

data/default/nations.ruleset

This lists all nation files and is read by the game engine on startup. A existing nation file which didn't get introduced in here will never apear in your game. Add your nation (nation/<nationname>.ruleset) to this list.

Changes related to software developmentEdit

data/nation/Makefile.am

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.

po/POTFILES.in

Here 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 definitionEdit

data/scenario/*

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.

The nation flag image fileEdit

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. One good place to look is the Open Clip Art Library. Other good sources for nation flag data are the Wikimedia Commons and Flagspot.

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 the CREDITS file) to discuss your ideas for changes.

i Remember that 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.

Flag GuidelinesEdit

Here are a few guidelines for flags:

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

i Please note that Freeciv no longer uses XPM files. As of Freeciv 2.1 all flags are stored in SVG (Scalable Vector Graphics) format. PNG is the preferred form for graphics, and flags should be made exclusively in SVG. Inkscape is a good SVG editor.

Flag SpecificsEdit

To add a flag you'll have to edit the following files:

data/flags/<nationname>.svg

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 SVG file is not used in Freeciv 2.0 but all the other steps for adding flags are the same.

i 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
data/flags/<nationname>-shield.png

These are the flag images that are used by Freeciv. They are rendered automatically from the SVG file. The conversion program is not included in Freeciv 2.0 so you should download the development version which does have it. Once this file has been created it can be used with older versions of Freeciv as well. To run the conversion program you will need to install Inkscape, ImageMagick, and (optionally) pngquant. Once these are installed change to the data/flags directory and run ./convert_png <nationname>.svg.

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.

i 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 fileEdit

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 playingEdit

data/nations/<nationname>.ruleset

Here you should have already referenced your image file via the 'flag=<nationname>' attribute.

Changes related to software developmentEdit

data/flags/Makefile.am

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 append it two more times since there are separate lists for your nations shild image file and the image source file (the svg file).

Testing Nation RulesetsEdit

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.

Nations Mini-FAQEdit

These address a few problems and questions about adding nations.

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

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: http://thread.gmane.org/gmane.games.freeciv.devel/69121

There is even a perl script available to do the job in the same thread: http://article.gmane.org/gmane.games.freeciv.devel/5978

What nations can be added to Freeciv proper?Edit

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.

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.

i 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?Edit

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.