HOWTO: Add Your Own Nation to FreeCiv

FreeCiv is an amazing clone of the old Civilization games. It got stuck somewhere between Civ 2 and Civ 3 as far as the graphics are concerned, but the game play is as much fun as in the original. Plus, it’s open source and hence hackable, has a scripting interface (at least in the soon to be released version 2.4) and has built-in hackability.

Here is a quick primer on getting your very own, private nation implemented in FreeCiv. Once you are done, you can play as your favorite city, sports team, state, or whatever grouping you like. Want a battle between the Romulans and the Klingons? No problem!

First, a list of the things you’ll need:

• an image of the flag of your nation
• a list of “city” names (don’t have to be actual city names) and their respective geographies (are they near the ocean, on hills, etc.)
• a list of “rulers”; again, these are just names that are offered (in this case for rulers of your nation)
• a list of “titles” which are the titles given to your rulers under different regimes

Next, you have to find the location of your FreeCiv installation and the user data directory. The installation directory is most easily found by searching for the file, “nations.ruleset” on your computer. It would be in a directory called “default” under the installation directory. You need this directory because you will base the files of your specific nation on those in this directory.

The user data directory is the place where FreeCiv looks for user modifications, and it’s a little harder to find. In general, it’s where FreeCiv stores the temporary save files, so an easy way to find it is to start a new game and save it (Ctrl+S once the map is in view). Once you have done that, look on your computer for files named “freeciv-*-sav.*” They should be in a directory named “saves” under the user data directory. [Note: if things don’t work, the user data directory may be a versioned directory under the user data directory. For instance, the FreeCiv 2.4 beta stores its files under the subdirectory 2.4]

Once you have the valid user data directory, create subdirectories named: flags, misc, nation, default. Copy the file nations.ruleset to the default directory.

Choose a nation that you want to use as a starting point for your own. It doesn’t really matter which one you use, you could take the smallest file for quick editing, or the largest for the best examples. I chose the Californians (a real “nation” in FreeCiv) and the example below is based on that. Starting from the installation directory, copy the files:

• nation/californian.ruleset
• misc/flags.spec
• misc/flags-large.spec
• misc/shields.spec
• misc/shields-large.spec

They all go to their respective subdirectories in the user data directory.

Now we create the different versions of the flag. We need two sizes (regular and large) and two locations (cities and units, or flags and shields). That’s the easy part, as long as you know how to rescale an image. I used ImageMagick’s convert utility for the purpose, since it is reliable and easy to use. You will need the following resolutions:

• small flag: 29×20 (base.png)
• large flag: 44×30 (base-large.png)
• small shield: 14×14 (base-shield.png)
• large shield: 19×19 (base-shield-large.png)

Theoretically, you can name the four images whatever you’d like (since you’ll have to edit other files to include the correct names). Practically, you should use the names added in parenthesis after the resolution. (Don’t forget to replace the “base” with the name of your nation.)

The flags all go into the flags subdirectory of the user data directory. If you are using convert, your original flag is named download.jpg, and your nation is the foosbars, then you would issue these commands:

convert -resize 29×20\! download.jpg flags/foosbars.png

convert -resize 44×30\! download.jpg flags/foosbars-large.png

convert -resize 14×14\! download.jpg flags/foosbars-shield.png

convert -resize 19×19\! download.jpg flags/foosbars-shield-large.png

Next, we need to edit the existing files. Let’s start with the easy ones. Take default/nations.ruleset. The only thing you want to add there is a line at the very end. Copy the line above, insert it (so it’s present twice) and edit the name of the nation on your new line to the name of your nation. Instead of *include “nations/zulu.ruleset” as the last line, mine has *include “nations/foosbars.ruleset”.

Next, you do the same thing in the four files in the misc directory. Copy the last line, so that it’s there twice in a row, and edit the name of the nation (zulu) in the second copy to the name of your nation. Be careful, since here the name shows up twice: on the left is the name of the nation’s flag (which we still have to set), on the right it’s the name of the actual file (minus the file extension).

FINALLY, the biggest chunk of work. You need to edit the nation’s ruleset. Rename the original ruleset you copied into the nation subdirectory to the name of the nation (boosbars) as stated in the nations.ruleset file. Open your favorite text editor and start hacking away. You need to (in order):

• set the section name ([nation_foosbars])
• give the nation a name (in plural form, too)
• select which groups it belongs to (the list of available groups is in nations.ruleset)
• choose a legend, which is the description shown when you select the nation (mostly optional)
• enter the names of leaders and their sex; everything after a semicolon is descriptive
• choose the titles given to rulers under different regimes – make sure you have names for all regimes you care about
• enter the name of your flag (which is what is keyed into the various flags spec files)
• choose an alternate flag, in case your flag is not available (set it to “-” dash)
• choose a city style (optional, just leave as is)
• ignore the init_ settings
• select a set of civil war nations, which is the name of the nations that your own nation will split into if there is a civil war (optional)
• give name and approximate location of cities; that’s the largest chunk of work. Enter each city name in double quotes; if you have an idea of the approximate location, add it after the name in parenthesis. For instance, if your city is San Diego, you might choose to add a line, “San Diego (ocean, hills, desert)”
  There is some meta-syntax to specify mandatory vs. optional location items, but that’s for the advanced user.

Now simply save the file and start FreeCiv. If everything went well, you should be able to select your new nation from the list of nations in the New Game window.

If that didn’t happen, there are tons of different reasons. Let’s do some debugging.

First, is your nation available by name? If you go to the All Nations tab, is it listed there, even if with the wrong flag? If it isn’t, FreeCiv may simply not have found your nations.ruleset file, which means you probably didn’t put it in the correct user data directory. Try to find it again!

If FreeCiv refuses to start at all, it’s probably because there is a syntax problem with one of the files. Maybe you forgot to close a double quote, or spelled a keyword (like include) wrong? Go back and check the syntax of each file. If all else fails, remove the nations.ruleset file from the default in the user data directory – things should turn to normal. Put it back in and remove the foosbar.ruleset file from the nations in the user data directory. If FreeCiv now starts, you can place the file back in and remove the flags files. Proceed until you find the file that causes the problem. [Note: it is useful for debugging this kind of problem to start the server stand-alone. You can add a debug flag there and it will tell you more accurately what’s wrong.]

If the nations is available just fine, but the flag comes out wrong (typically as a light blue flag with dark blue question marks, the so-called unknown flag), then one of the following might have happened:

• the name of the flag in the nation’s ruleset is wrong; the name is the argument to the flag key
• this name has to show up verbatim in the flags files – check each of them, in particular the large flag file, since that’s what’s shown in the nation selector
• the argument to the flag file is the actual name of the flag file, including directory name, but minus the file extension

I created several nations just out of the fun of it. For last year’s gay pride month (june), I created an LGBTQQ nation with the names of gayborhoods from “List of gay villages” on Wikipedia. This year, I created a San Diegan nation with the names of the city hoods in town. I am tempted to go more and more local and create a Pacific Beach nation with the names of streets as cities. Maybe I’ll create a whole set of them and finally play out La Jolla vs. Pacific Beach, the Eternal Torment!