This is the manual for Freeciv 1.13, the manual for the most recent version is found at Game Manual.

Back to main manuals page | Talk:Game Manual

The Freeciv client program is your window into the world of Freeciv. It is through this application that you will be able to play your game or simply watch other people's on-line game. Through its main window you will view your empire and the surrounding regions, direct the movement of your legions, and command the workings of your cities. In Freeciv, you are the near-absolute immortal ruler of your empire, but you can only control what you can observe and know to order.
The client is the doorway from your throne room to the rest of the world.

This document reflects the Freeciv client programs for the 1.13.0 GTK+1.2 build. The general concepts involved, and many of the windows, willl also help in using other clients.

 i  Info about this manual

  • The words Click or Click on throughout this manual mean a single click with the left mouse button (LMB).
  • Buttons (in the client) or keys on the keyboard are pictured like this: Connect or ESC
  • Menu entries (File- or RMB-menus) in the client are shown like this: File

A Tutorial Introduction to the Client[]

In this section you will start a solitaire game of Freeciv and learn the basic concepts of controlling your race. All of this document assumes that Freeciv is installed in its default directories, and that the executables are in your PATH.

There are at present five versions of the client. Historically oldest client, named xaw, uses the Athena widget set that comes with the X window system. There is also a native Amiga client (MUI) and a native Windows client (Win32). The default client is built on the GTK+-2.0 widget set and is called gtk2. An older client for GTK+-1.2 ("gtk1") is still present in 2.0, but it isn't recommended to use it. There are other ports in various states of progress. We will be using the "gtk1" client for this tutorial. The only significant difference between "gtk1" and "gtk2" is that "gtk2" has an easy interface for starting and loading games. You can skip next chapter (Starting Up) if you are using the "gtk2" client.

Starting Up[]

Though this is the client tutorial, we must always start up a server to play the game. In an xterm or other window, start the server and give it some parameters:

       % civserver
       This is the server for Freeciv version 1.13.0
       You can learn a lot about Freeciv at
       2: Now accepting new client connections.
       For introductory help, type 'help'.
       > set aifill 7

That parameter will provide six computer-controlled players after you start (more precisely: it will add artificial intelligence players to the game until the total reaches seven; since there is one of you, this will provide you with six opponents). Leave that running for now, go to another xterm, and type

       % civclient &

This will start up the client (in the background) and will bring up the Main Window and the Connection Dialog.

The Connection Dialog[]

Freeciv Server Selection.

As the window's title indicates, this dialog enables a connection to be made to a running server. Name is important since this name is associated with the nation you're playing. If you are playing from a loaded savegame or connecting to a multiplayer game, you use this field to indicate which nation to play with. In general, it can be anything (it defaults to your username), and you must remember it, be told what it is, or look in the savegame if you have access to it. However, players created initially as AI will have their username be the same as the nation's leader name.

The other tab in the dialog lists the games registered with the Metaserver. This is described in more detail here.

All this is FYI. For now, if you're starting a new game, just choose the default. The second and third fields specify the server that your client is connecting to. If you started the civserver in another window as above and you have your /etc/hosts set up correctly (i.e. localhost points to your machine), then everything should be fine. If the server is on a different machine, you must specify the hostname or IP address and possibly the port number that the server is running on (a server command line option sets this, but defaults to 5555).

'Click on Connect'. If you look over at your server window, you should see something like:

       2: Connection request from bob from
       2: bob has client version 1.13.0
       2: bob has joined as player bob.

Now on the server command line, type:

       > start

which will start your game.

Select a Nation[]

Immediately after the server starts a new game, you are presented with the dialog that allows you to choose a nation and leader. Click on a nation's toggle button to select a nation. If any nations are grayed out, it means that other (human) players have already selected that nation. After you've made your selection, use the drop-down box to select a leader name and/or enter one of your choosing. Select your preferred gender, and then the initial city style you want. This option selects kind of sprite you want to indicate a city on the map. Click OK and we're on our way.

Choose nation

Which Nation Will You Be?

A Look at the Main Window[]

Now the main client window will be filled in with the world as you know it. One of the first things you should do, however, is click and hold on the Help menu button in the menu bar; you will see a wealth of topics for which there is online help. There is online help for essentially all of the game's concepts and features. Browse through the other menus to get an idea of the other dialogs available to you. More detailed information about the other dialogs will be presented later. The main parts of the client window are: the Map, the Overview Map, the Sidebar, and the Output Window and Chatline.

Main window begingame

Freeciv Main Window.

The Map[]

Canvas closeup
Freeciv Main Map.

The upper right is a scrollable map of the world around your initial units. The default world is 80 squares across and 50 squares high, but this viewport only shows a subset of these. Simply expand your window to see more of the map. Each square you see filled in contains a representation of the terrain in that portion of the world's surface.

It is possible to move around the world to view a different part. This can be done by either clicking on the scrollbars ( as you normally do in a program) or by using the keyboard shortcuts( remember to have the freeciv screen active before using the keyboard shortcuts). You can also center the map by clicking on the map.You can also set auto center on units which can be found in menu game options.This would auto center the map on the current active unit. You can also center the map view on a particular city, this is done by using the find city option in the kingdom menu or the keyboard shortcut (Ctrl+f).

The flashing square in the middle is alternating between the terrain of that square and the icon of the currently active unit. The terrain types which you see should be a sample of those in the world; in the picture your initial units are on a Grassland square, with Plains squares just to the south, east, and southeast of your units, and one north of the middle of the river. Just to the north of your units is a River square, with two more Rivers to its east. Off to the far southeast is a Tundra square. Surrounding your coast to the west is a number of Ocean squares. Your map may vary, but the same features will be available.

Many map squares have special resources; in this case, there is one. The Plains square just to the east of the units has a Horses symbol; such a square has higher food productivity than an ordinary Plains square. How can you tell what the squares contain if you aren't familiar with the symbols? Put the cursor over the square, and press and hold the middle mouse button; you will see a tiny window saying something like "Terrain: Plains (Horses)". Do the same in the square with your units; you will get a line describing its terrain, another identifying the unit on the top of the stack there, and another giving the unit's critical statistics (attack, defense, firepower, and hit points).

But first, note that much of the map is black, apart from the 21 squares in the center. These are squares of which you know nothing; you will not see what is in them until you have a unit close enough to report on them. What of the world beyond your 11x8 viewport? Move your cursor to the horizontal scrollbar below the map, and single left click. This shifts the map one square to the left, exposing more black squares on the right. A single right click will shift the map one square to the right. A single middle mouse click on the scrollbar will jump the map to that relative position on the entire world map. The vertical scroll bar adjusts the map height similarly. Or, instead of using the scrollbar, you can simply point to a square on the map and use a single right click; the map will be recentered around that spot. At present, there is little to see.

Find your way back to where your units are. A shortcut for this is the c key, which will move the map to place the active unit in the center of the map. This and other shortcut keys you will use a lot. We'll leave the units for later.

The Overview Map[]

Freeciv Overview Map.

In the top left corner of the client window is an area which is mostly black, with some colored squares within. This is a map of the entire world, in a resolution so small that individual terrain squares are indistinguishable. It has a yellow dot flashing in time with your current unit. At this point it has no value, other than showing that the starting location is at the far south of the "middle" of the world.

Once you have a world-spanning empire it will come in handy. On the real Earth map, if you have the detail map showing Europe, for instance, you would need many scroll clicks to adjust it to look at South America. But one click on the corresponding place in the overview map will shift the detail map to centered on the selected position.

Cities and units are shown on the overview map as colored dots. Moving units will move the dot on the overview map. Cities that have been destroyed will not be shown on the overview map. All units and cities can be shown by building a certain wonder. See wonders for more information on this.


Sidebar labeled
Sidebar Summary.

Below the overview map is what I'll call the sidebar. The sidebar gives immediate access to some important information and controls without opening dialogs. The various parts of the sidebar are numbered and a synopsis of those parts is found below:

1. Sidebar detach button
Just drag and drop the sidebar to detach it to where you wish it to be.
2. Game state indicators
There are four symbols here. The first is the science researched level; the brighter the bulb, the closer you are to achieving your current advance. The second is the global warming sun indicator; this gets progressively larger and redder as land squares are polluted, indicating the risk of a global warming event. The third is the nuclear winter snowflake, which grows with the amount of nuclear waste on the land, indicating the risk of nuclear winter. The final symbol is the government icon, which represents which government type your nation is running.
3. Tax rates indicators/controls
This shows 10 figures representing the division of your trade points between luxuries, research, and taxes. The default rates are no luxuries, 50% research, and 50% taxes, so what you see are pictures for five researchers and five tax collectors. If you reduced taxes to 40% and increased luxuries to 10%, the pictures would show one entertainer, five researchers, and four tax collectors. Let's change things to do research a bit faster. There is no need for taxes at this point. There are two ways to change the distribution of effort in your empire. One is through the "Game" menu item called "Rates". The other is through this icon bar.
Click on the first tax collector. That will change it to an entertainer, and move it to the far left of the line (since it always shows entertainers, then scientists, then tax collectors).
Click on that far-left entertainer, and it becomes a scientist. You can also look at the information box above and see the new percentages give as text.
What if you try to exceed the maximum amount of research (or any other choice) allowed for in the rules? Try it:
Click on another tax collector to make it an entertainer, then click on the new entertainer. The icon doesn't change, and you get an error at the bottom of the window: "Game: Science rate exceeds the max rate for Despotism." This is how you get errors returned from the server; your client tried to make the change, but the server rejected it.
Change a scientist into a tax collector, and you can change the entertainer back into a scientist.
4. Game information
This is a display of the total population of your civilization, the year it is in the game (years increment in 50 years a turn, until 1000BC, then 25 years per turn etc), the amount of gold you have in the treasury and the levels of tax, luxuries, and science you have set (another representation of the information in section 3).
5. Timeout indicator
This is the timeout indicator; if the timeout option has been set, this will show the amount of time you have left to complete your turn, otherwise it will show "off". The amount can be changed by using the server command for this. If playing over the internet, who ever is hosting the game will have control over this, and you can ask them to change the timeout by asking them in the player chat window.
6. Turn done button
This is the turn done button; press this at the end of your turn, or set Auto Turn Done which will do auto turn for you once you make you last move. You can find this option in the Game menu. You may see this button flash, this means that all other players have finished their turns and are waiting on you to finish your turn. When you press the turn done button it will gray out until the start of the next turn. When the game ends the turn done button stops working.
7. Active unit state
This part gives the type of unit whose move it is (or the unit you have selected for moving), its homecity (if any), the number of moves you have left for that unit and what kind of terrain it is on.
8. Active (focused) unit
This is the unit which is being moved (unit details can be found above).
9. Other units on the active unit's tile
This is the list of of the units that are occupying the same square as the active unit, or are present in the same town.
10. More units indicator
This shows that there are more units on this square than can be shown in the space. Click this and you will be shown the other units.

Message Output Window and Chatline[]


Message Area and Chatline.

Near the bottom of the window, below the unit icons, is a large rectangular area with messages. It contains all messages sent to you from the server (Note: you can filter which messages you'd like to receive, see Message Options). It has a scrollbar to allow you to scroll back to see older messages than those which fit in the window.

At the very bottom is a single line. This is the multiplayer "chat" line, to communicate with other players (tip: to send a private message just to one player, type playername: hi! or type .hi all! to send a message to your allies). You can also send commands to the server through an IRC-like interface. For example, typing /help will give you return the help listing in the Output window. More detailed explanation of the chatline can be found in the reference section.

Message Options[]

You can control which messages you receive from the server in the Output Window beneath the main window, the Messages Window, and via popups. The word city means that the message setting is a message that would concern a city.The word civ means that the message concerns your whole civilization.The first two options " City: Buildings unavailable item" and " City: Captured/Destroyed" are currently set to "Pop". This means any messages concerning this would appear in a new popup message each time.You can easly change this by clicking "Out" which would then give the same messages but this time they would appear in the output window which is under the main map.Clicking "Mes" would set the messages to appear in the message window which ( unlike the popup message window ) can display more than one message.

Message options

Message Options.

Local Options[]

Local options

Local Options.

There are several miscellaneous options controlling aspects of the client that can be found in the Game menu.

Local Option: Solid unit background color This displays units with a solid background color and the map square that the unit may be on is not shown.

Local Option: Sound bell at new turn Sounds a bell at the start of each new turn.

Local Option: Smooth unit moves and Local Option: Smooth unit moves steps These settings deal with Graphic display of units and can be tweaked to the users liking. The smooth unit moves makes the units move more smoothly-and you can either make it "jump" from one map square to another map square or make a transition in more steps. Just click to change the number setting.

Local Option: Combat animations Combat animations will show battles animated. If you wish to turn off this option just unclick this option.

Local Option: Popup dialog in AI mode Clicking this on or off will effect what is displayed if you switch to AI mode. No messages will be displayed at anytime if its turned off while the computer plays for you.

Local Option: Manual Turn Done in AI mode Turns on or off manual turn done when you have set AI mode on.AI plays your turn, but stops and waits on you pressing turn done button if its set on.

Local Option: Auto center in Units and Local option Auto Center on Combat This will set the main map to be centered on the current active unit, so that at the end of moving a unit the map will then be refreshed and display the next unit to be moved (if any). When a battle occurs the auto center on combat will take you to view this if you have this set to on.

Local Option: Focus on Awakened Units When units are sentried, they awake if an enemy unit comes near. This option would take you to the unit when it awakes.

Local Option: Draw Diagonal Roads/Rails The game has an option of drawing straight lines for roads and rails or use the more aesthetically pleasing diagonal line for roads and rails.

Local Option: Concise city Production Gives more concise city information.

Local Option: End turn when done moving If you wish to make the game end your turn after your last move automatically rather than having to click turn done every turn, then turn this option on.

Local Option: Use ALT/Meta for accelerators (GTK only) Option for GTK users with accelerators. This won't work on other systems.

Beginning Your Exploration[]

Here we will play a turn or two to get acquainted with the client. If you want to follow along with something very similar to this tutorial, download this savegame to your home directory, and instead of starting the civserver as before, instead do:

       % civserver -f ~/client-tut.sav.gz 

and then start your client normally except that you should use "bob" as the user name.


By default, you start the game with 3 units: an explorer and two settlers (though this can be changed with server option "startunits").

In this game you start up in a location right next to the ocean with a fish tile near. In the continent you see that there are some grassland and plains, which one of those has a river.

When you want to know which is the output of a tile you have point that tile with the mouse and issue a middle button click - or a press the two buttons at the same time -.

Since units stack on a tile, you can either use the sidebar - or press w - to cycle through the units, or click on the unit stack to bring up the Unit Selection Dialog.

When the unit popup dialog comes active you must select a unit to operate with it. This is a modal dialog so whether you select a unit or cancel it.

Click the explorer icon (the top unit) in the Unit Selection Dialog, to put it in focus. The unit stack on the map should now be blinking with the explorer on top of the stack. Press either the 8 or the Up key on your keyboard to move the explorer to the north.

With the numeric keypad you can command the movement of your units. (You can also use the Goto command to order a unit to move to a destination tile. To do so, select the unit, press g on the keyboard and the point the tile with the mouse and make a click on the tile. The unit will go there automatically.)

Now move the explorer pressing 8 and 9 on the keypad. This will capture a hut. The huts are minor tribe villages that can give technology, gold, cities, etc... Be aware because there can be hordes of barbarians...

Now the explorer has no moves left, the next unit becomes active.

Issue 3 with the first settler and 7 with the second. I will see a tile with a whale in it. The whale and fish tiles are the best ones to found a city around them.

Now, the turn is over. All your units has moved. The press the end turn button on the sidebar.

We can now do a bit of exploring with the explorer to make a few more reconnaissance of the terrain.

Now click on the explorer to make it active. Press 9, 9 and 6. You will make contact with other civilization.

In the next turn the unit of the other civilization will disappear. That's because you only see enemy units and terrain modifications that are in sight of your units or cities or allied ones. This is the fog of war. It can be controlled by a server option.

You are competing against other players. So the other civilizations or nations are likely to declare war on you really soon, so you'd better protect your cities. To protect your cities you must build defenders and attackers, and also keep producing settlers to expand your empire and take ownership of the land before your opponents.

With the lower right settler, build a road. This will give trade to your city, as soon as the city start using this tile to produce. You must build some infrastructure in your cities to make them grow and connect your empire.

Founding your Capital City[]

The spot for the active settler looks like a good spot for your first city.

This is a good place to settler your city because is near an special - see the Terrain page for a description of all the possible types. This special tiles gives to your cities more food, trade or shields than the normal ones. A suitable place to create a city or your capital is one with 1 or more specials nearby. Normally you'll want to find good spots for your first cities because this will give you some advantage against your neighbors. Try to found your first cities near whales or fish.

Take a look at the menu button marked Orders; that menu lists commands relevant to the selected unit. Press and hold the left mouse button on the Orders button; you will see a list of menu options pop up. Some of them will be grayed out; they aren't available to the selected type of unit, or aren't available for the terrain it is in, or are otherwise not appropriate. One of the available options is Build City. Notice that next to the name is the shortcut b; you could have done this by just pressing the b key.

Move the cursor down to the Build City line and release the mouse button. You will get a dialog asking how you want to name the city; it will already have a default name, taken from a list of built-in names of cities suitable for that race. You can certainly change the name if you so desire. Click OK. The dialog box and the unit will disappear, and in its place on the map will appear a new city. At the same time the city window will appear, so that you can give your first commands to the new city.

A Look at Your City[]

To give you a better idea of what you can do and see in the city dialog, a large city is displayed, one that would take many turns to grow. This window is one which you'll see quite often, so it's important you understand what you can do with it.

Once you take your actions on the current city, you can circle through all the cities thanks to the prev/next city buttons, or close the window. This buttons are on the bottom of the city window.

Overview Page[]

Citydlg overview freeciv113 gtk

City Overview.

In this city there are 8 citizens, 1 of them is happy (the one at left) and the rest are content. All of them are working the land as you can see in the city map.

All the tiles have an indicator - e.g. 2/1/2 - showing the resources that generate its assigned citizen. Normally it's preferable to have your population keep working the land. However, sometimes the cities revolt and then you have to edit the city map to remove a worker and convert it into an elvis. You do that clicking on the tile in the city map, this will toggle its state. A citizen can be working the land, or can be turned into an elvis - generate luxuries to keep people content or happy; a taxman - generate more money; or a scientist - which, obviously, generates more science.

The normal way to arrange the worked city tiles is to click into the city center. This will run the default placement routine of citizens.

In the City Info frame you have what your city is producing. It's indicated the resources a city produce: food, production and trade. And below you have gold, luxury and science mainly diverted from trade. Also under you have the granary stock, and the corruption and pollution of your city.

In the supported units frame you have the units that depend upon the resources of that city. This units can consume shields(production) and food. This indicated in the frame by a shield or wheat icon side by side the unit. More information on Government.

The present units frame lists the units located in the city right now. Note that you can move your units around and can be in another city or place. To circle thought all the units you must click on the > or < buttons.

On the right of the screen you have the item the city is producing. Note that you can buy that item or change for another with the buttons in the frame. Also note that changing from a unit to a building or a wonder, or vice versa, will mean losing half of the shields accumulated. The information present in the frame is: your are producing Pyramids (a Wonder), you have 6 out of 200 and it will last 65 turns.

To change your current production you must press the button Change on the production frame. This will bring up a dialog with all the available items. Also, if you press the buy button, it will pop up a dialog for confirmation purposes.

Right below the production frame you have all the buildings and improvements in the city. If you want to sell one of them just select it with a click and press the sell button. Or, alternatively, you can double click an item to sell it.

You will notice that nearly all of this information is inside a tab of the window. So you can click on the tabs to bring other information visible. This tabs are described in the next sections...

Units Page[]

Citydlg units freeciv 113

Units Tab.

The Units page gives the same sort of information that the quick units reference on the overview page does, but more units are displayed, and there are two multiple unit commands you can give here.

Like in the overview window tab, there are two frame with the supported and present units in the city. As in the overview tab, the supported units show with icons the resources they consume - two wheat (for 2 food) and one shield for each settler, one shield only for phalanx and horseman -.

On the right corner of each frame there are two buttons to scroll through the units.

When you select a unit - click on it - there will appear a list of options to do some actions on that unit. You can also do this on the overview tab.

Below the present units frame there are three buttons, which perform useful actions.

Worklists Page[]

Citydlg worklists freeciv113 gtk

Worklist Tab.

A worklist is a list with buildings, units or wonders to be produced by a city. As you see in the snapshot the first element is the Pyramids, which is the one being produced. The others will be build once the Pyramids Wonder is build.

Those items programmed for building are in the current worklist. The available items to be selected are in the other list of the tab. Once you discover the right technologies you will be able to build new buildings, units or wonders.

On both list, there is a column named info, which informs you of the capabilities of a unit type. It stands for Attack/Defense/Move.

Obviously the current list can be manipulated at will. To add an item before another on the current list, just select it and double click the desired item on the available list. To add a last item just unselect the item on the current list and double click the item in the available list. To delete an item of the current worklist just double click it.

Be aware that you can lose half of the cumulated shields if you change the currently build type for another type. When you're building a unit, you can change the production to another unit without losing any shield, but if you change it for a building or a wonder, you will lose half the shields.

Happiness Page[]

Each citizen of a city can be unhappy, content or happy. As the cities grow unhappy citizens will appear, and you must convert them to content. A city will fall into disorder if unhappy workers are more than happy ones.

Also, you can make a city happy if you give its citizens lots of luxuries. You can't do that building Wonders or Buildings, you must sacrifice trade and taxes into luxuries. You must give him luxuries modifying the rate indicators/controls in the sidebar of the main window.

One fast way to resolve a revolt in a city is to use the default routine for managing citizens. You can click the city center of the city in the overview tab of the city window, as documented before.

The Citizen Management Agent Page[]

<essay here: all that is cma including adding and deleting presets>

The Citizen Management Agent (CMA) helps you manage your cities. It deploys the available workers on the free tiles around the city to achieve maximal city output. It also changes workers to scientists, taxmen, or entertainers, if appropriate. And the CMA has another astonishing ability: whenever possible, it keeps your cities content.

There are various means to tell the CMA what kind of output you would like. Open the city window and click on the CMA tab. There are two kinds of sliders: On the left, you can set a Minimal Surplus for each kind of production; e.g. Gold = +3 means the city earns 3 gold more than it needs to upkeep its improvements. On the right, the sliders let you define by how much you prefer one kind of production to another; setting science to 3 means you prefer a single bulb to three shields (or gold, trade,...). You can set different factors for each kind of production, according to your needs.

If you set up some Minimal Surpluses which are impossible to fulfill, the CMA can't be activated. Whenever the CMA can't fulfill its task in the ongoing game, it passes back control to you. So you'd better not define too high a surplus; instead, use factors to achieve your goals.

The Celebrate checkbox lets your city - celebrate. This will work only with a high luxury rate. See help about 'Happiness'.

Clicking on 'Control city' puts the city under control of the CMA, 'Release city' passes control back to you.

For ease of use, you can save your slider setting as a preset with a name. Click on 'add preset' and enter a name for your setting. You can use this preset in every city by just clicking on its name. Also, you can control your setting from within the city report, in the CMA column. And you can change it from there (use 'change' --> 'CMA'), if you have saved it as a preset.

Use 'Game' --> 'Save Settings' to store your presets permanently.

But beware! If you use the CMA for some of your cities, you will encounter some difficulties with managing cities nearby, by hand. It's best to manage all cities on an island either by hand or by CMA. Read more hints, some background information, and some preset examples in the file README.cma, included with Freeciv.

Citizen Management Agent (CMA) detailed[]

The CMA is a rather new tool built into the GTK+ client of Freeciv version 1.12.1. It is designed to help you manage your cities, i.e. deploy the workers on the available tiles around (or make them scientists, taxmen, or even entertainers), to get the most out of the city. You can switch the CMA on or off at any time for any city, but there are some handicaps (explained below), if you have CMA'd and non-CMA'd cities nearby. In any case you need an actual 1.12.1 or above server; the CMA won't run with server version 1.12.0.

The heart of CMA is an optimizing algorithm, that tries to deploy the workers of a city in such a way, that a user-defined goal is achieved as much as possible. You know probably, there is already a kind of optimizing, when you open a city, and click on the center tile (the city symbol) of the mini map. This optimization tries to maximize mostly the science output; but it doesn't care about disorder.

The new City Management Agent goes far beyond this old form of optimizing. First, it performs this task every time anything changes with the city. If the city grows or shrinks, troops go in or out, tiles get irrigation or mining, or are occupied by an enemy, the CMA becomes active. Second, it supports all kinds of optimizing, like production (shields), gold, science, or luxury. Third, it gives the player a fine-grained control over this, with the possibility of setting constraints for any kind of city output. The latter includes the constraint of celebration, which makes it very easy to let your cities grow, even in harder times. The forth, and probably most valuable thing in war times, is that is keeps your cities content, preventing them from revolt.


You can set up the CMA for a city by opening the city window and clicking on the CMA tab. On the left side, you can choose a preset for a specified goal, on the right side you can specify more complex goals by moving the sliders. You can choose a preset at first, and then modify it. Once you have created a new setting, you can add a preset name for it. This is not required, but very useful, since you can watch and even change the city's setting from within the city report, if it is given a name. Don't forget to save settings (in the Game menu), when you've created new presets.

The sliders are of two kinds: the rightmost sliders are factors, which gauges how much one product is worth compared to the others (e.g how much shields are worth with respect to everything else). The leftmost sliders are constraints: you can command the city not to lose food, e.g. by setting the surplus constraint to zero; and you can allow the city to lose gold by setting the gold surplus to -3 e.g., and urge them to make at least 5 shields per round by setting the production surplus to 5. The most powerful constraint, though, is the Celebrate constraint, which makes the city celebrate at once (which usually takes effect the round after you change it).

It is obvious that the CMA can't fulfill all these constraints in every case. Whenever the constraints can't be fulfilled, the CMA quits its service for that city, giving a message: "The agent can't fulfill the requirements for Berlin. Passing back control." You then have the choice of either managing the city on your own (which has some drawbacks, see below), or open that city and change the surplus requirements so that they can be fulfilled.

When you have made a setup for a city, you need to click on "Control city" to switch on the CMA. If this button's text is greyed, either the CMA is already active, or the task is impossible. In the latter case you see dashes instead of numbers in the results block. If you ever want to switch off the CMA deliberately, click "Release city".

Advanced Usage[]

There is not much experience using the CMA yet, but some common remarks may be helpful. Usually the goal(s) of your cities depend on the phase your game is in, whether you want to spread widely, grow quickly, research advanced techs or wage war. You may want to set up a high factor for science to research, or a high shields factor to produce units. The highest factor available is 25, that means: if the shields factor is set to 25, and other to 1, the CMA prefers a single shield over 25 gold (or trade also). This is pretty much because money can buy units too. That also means that the CMA is indifferent about producing gold, science, luxury, and food; but when you wage war, you usually prefer gold or luxury. So it's probably a good idea to set a second (or even third) preference for the city's output, e.g. gold factor 5. That still prefers 1 shield over 5 gold (and 1 gold over 5 food or anything else).

Constraints aren't useful in all cases. If you want a high income, it's probably better to set the gold factor to 25, than to set a minimal surplus of 5 or so. Because a big city can make more gold than a small one, you'd end up setting a different surplus for each city.

However, if the shields surplus of a city is below zero, it cannot support all of its units any more. You will lose some of the units the city supports. If the food surplus is negative, the city will starve and eventually (when the granary is empty) shrink. This may be intended, but if the city supports any settlers, you will lose them before the city shrinks. Constraints can also have a warning function.

Which constraints can be fulfilled depends widely on the global science, tax, and luxury rates. E.g. a gold surplus >= 0 is easier to fulfill with a higher tax rate than a lower one. You should always consider to change these rates, when you going to change the CMA settings for the most of your cities.

Hint: To avoid accidentally releasing your cities, when you change the rates, it is best to do so from within the tax dialog rather than from the rates display in the main window.


The CMA is a very powerful tool, which not only releases you from the micromanagement of your cities, but gives you more performance than you have ever seen (well, for most players).

There are some drawbacks, though. Once you've switched on the CMA, it grabs any good tile it can get. So you encounter very hard times trying to manage a city nearby a CMA-controlled one. This is true for the city window and the main map worker's interface as well. If you want to have CMA-controlled and "handmade" cities, they probably should be on different islands.

There are several situations where the CMA can't fulfill the requirements just temporarily, e.g. when you move a ship from one city to another, or when an enemy walks through your country. The CMA passes back control in these cases, and you have to re-enable it manually. A general approach to prevent this might be, to set the minimal surpluses as low as possible (-20). Of course you must be careful with the food and shield surpluses.

While the CMA does a really good job for a single city, no tile will ever be released for the good of another city. Also, the CMA'd cities are computed in a more random order; the results may depend on it and change, when a recalculation is done (when tax changes e.g.). So, no guarantee is given that the overall results are always optimal.

see README.cma for details

Last updated: 9 Jan 2002

The Trade Routes Page[]

This page shows the established trade routes this city has, the cities they connect to and the amount of trade bonus the city gets from each individual trade route, each turn. This amount is raw-trade, and corruption has yet to be calculated over it.

Trade routes can be established between cities once the technology Trade has been researched, or more precisely, once you can build Caravans or Freights. Each Caravan, and later Freight, is a civilian unit (0 offensive power) that can be moved onto cities and thereby establish a trade route, provided the distance between that city and the home city of the caravan is great enough. The destination city can be anyone's, moving into an neutral or enemy city being possible (think: black-market trade route). Upon entering the city a Caravan will automatically try to create a trade route. If the destination city is yours or your ally's, then you will be asked if you want to create the trade route or move along. If you are inside a city and want to establish a trade route (without moving out of the city and back), pressing r (make trade route) will open the question dialog.

You cannot establish a trade route between cities that are less than 8 tiles (Manhattan distance) away from each other.

These trade routes will give a lasting bonus to trade in the trading cities.

Additionally, upon creation of the route, you will get a one time bonus reward in gold and research. If the trade route created is already in use, the caravan will 'go to the marketplace' and give you the bonus gold and science (no further changes to the trade route).

Caravans or freights can also be used to help build your own wonders, in which case an extra option is given in the question dialog, given upon creation of the trade route. This is better than disbanding your caravan to help with construction of wonders.

Each city has a maximum of 4 trade routes that it can manage. These can be between cities in your own empire or of any other player. Trading with another player means that you will have to share the profit, while when trading with yourself, you will reap the profits for the two cities but will also suffer a trade penalty (trade is reduced by half, so it cancels out in the end). If a fifth trade route is created and it is better than previous ones, it can replace an old trade route. Likewise if one of the two trading cities finds a better trading partner (one that gives more trade revenue) then the route between these two cities will disappear.

The trade bonus is calculated as a function of the total amount of trade that the two trading cities generate (not counting other trade routes). So the more trade 2 cities generate, the bigger the trade bonus. If the trade bonus that a trade route would generate is less than 1 than no trade route can be generated. Trading between two cities on separate continents doubles the trade bonus. Trading between foreign cities (of two different nations) also doubles the trade bonus. These two bonuses are cumulative. The one-time reward you get for establishing a trade route is not only a function of the total amount of trade generated, but also the distance between the 2 cities.

Thus, the more trade 2 cities generate, the further away they are and the more exotic they are from each other, the bigger the reward.

The Misc. Settings Page[]

In this tab there is a new citizens frame which it's main goal is to instruct the server to set the new citizens as entertainers/scientist/taxman.

There is a frame about the auto-attack code in the server. It's advisable to not use it because it does not work quite well.

In the city frame there are two options. A button to rename the city, and a check box to allow you to disband the city at size 1 if that city produces a settler. It's main purpose is to allow you to remove a badly placed city - if you don't check this, the server will not produce the settler and issue a message.

There is an <next-time-open> frame which lets you decide which tab of the city window will be open by default.

For now, click on the Close dialog button.

A Reference of the Client Features[]

Reference of the Windows[]

Connect Window[]

While we already discussed the Connection Dialogue, in section 1.1 above, there some additional facts worth mentioning. The default host name of localhost connects only to a server running on your own computer; to join a multiplayer game on another computer you will need to enter its IP address or hostname. The Name field specifies the name by which you identify yourself to the server operator; for an initial connection to a game it may as well be your ordinary name or user name (e.g., david), but if you are reconnecting to an existing game it needs to be the the ruler name of the empire ("Caesar").

The Connect button will make the connection to the server. The Metaserver button will open the Metaserver Window.

Metaserver Window[]

<review this text>

This window, which can be opened by pressing the Metaserver button of the Connect Window, displays the status information of Freeciv servers all over the Internet. By clicking on a server's line you can enter its address and port number into your Connect Window. Press the Update button to request a fresh server list from the metaserver.

Main Window[]

The main window is described at length in the tutorial, but there are a few elements that were not covered at that time.

At the very bottom of the window there is a chat area where you can chat with the other players. To send a private message just to one player, type this:

playername: hi!

<paragraph here: chatline and sending server commands (permissions)>

<paragraph here: viewing options>

City Dialog[]

The City dialog is covered in detail in the tutorial

The Rates Dialog[]

The rates dialog shows you the current division of your trade into taxes, luxuries, and science. You may use this to adjust your rates, up to the limit allowed by your government type. Use single left clicks either to the left or the right of the scrollbar or grab the scrollbar to move it. Reducing the rate a step increases some other rate a step, and likewise when you increase one rate. You may set the Lock button on any rate which you don't want this automatic adjustment to change.

The Cities Report[]

This is opened by selecting City Report from the main window's Reports pull-down menu, or by pressing the F1 key. It displays a one-line summary for each of your cities. The "State" field shows whether the morale of your city is "Rapture", "Peace", or "Disorder" (in this example, Mediolanum is in Disorder). The "Workers" field shows a count of the happy, content, and unhappy workers (Mediolanum and Neapolis have unhappy workers, though Neapolis probably has an entertainer). For any cities with specialists, the number of entertainers, scientists, and tax collectors are shown. The "Surplus" field is the surplus counts in food, production, and trade; a glance at this will warn you of cities with negative net food supply. The "Economy" field is the trade division into gold, luxuries, and science; many cities have negative gold because taxes are low. If there are trade routes or pollution, they are shown in other columns. The "Food Stock" column shows the contents and size of the food store. The building or unit under construction is shown last, with its production points already complete, target production points, and "Buy" cost.

The Center button centers the map on the city. The Popup button opens the City Dialog for that city. The Buy button is the same as pressing the Buy button on the selected city's window. The Change button is the same as pressing the Change button on the selected city's window; this means that you see a list of buildings or units, and must select one. The Refresh button requests that the server update the data in the list. The Configure button opens a window to configure this window. It allows you to regulate which of the possible columns are shown, or to what level of conciseness.

Players Dialog[]

The Players window is opened from the main window menu. It shows all of the players in the game by ruler name and empire name; an asterisk beginning a ruler name indicates that it is an AI. Players will show up here even if you have not seen them within the game. If you have an embassy with that race, that column will have an X and the Intelligence and Meet buttons will activate those windows. The State column indicates whether, with regard to the current turn, that player is still moving or is done. Players currently connected by clients have their IP address listed; those not connected show how many turns they have been offline. The Intelligence button opens the Intelligence Window. The Meet button opens the Meeting Window.


This is brought up by selecting Economy from the Reports menu on the main window menu bar. It gives a summary of the empire-wide income and outflow of money. First it lists all of the types of buildings you have built, their count and their maintenance costs. Then it summarizes your tax income from all cities and your total building costs. The Sell Obsolete button goes through every city and sells the selected type of building, but only if the building is obsolete (for instance, an ancient Barracks becomes obsolete once you develop Gunpowder) or superseded by a Wonder of the World (as the Pyramids makes your Granaries unnecessary). The Sell All button sells all of that type of building, obsolete or not.


This is brought up by selecting Units from the Records pull-down menu on your main window. It lists how many of each type of unit you have, and also highlights with an asterisk which units are obsolete and can thus be upgraded (in the example, the Legion, Musketeers, and Galleon). The Upgrade button offers you the chance to upgrade some or all of the selected unit types for a price, if units of those types are present in a city. Upgrading is possible for many units when the ability to make the better unit has been discovered (for instance, Settlers may be upgraded to Engineers once Explosives have been discovered). You might check this to be sure you don't have forgotten and left some of your cities guarded by ancient units in the modern age; for instance, that Legion is a waste of support with Armor units around.

Wonders of the World Report[]

This shows all of the Wonders of the world including those being built.

Top Five Cities[]

This shows the five greatest cities in the world. It's ranked by wonders, then by city size

The Messages Window[]

Double-clicking on city messages in this window will pop up the city dialog for that city.

<sentences here: finish explanation>


This is brought up from the main window menu bar. It lists several empire-wide statistics, and gives you a ranking by which your empire compares with the other empires.

Help Window[]

The help window is selected by choosing any of the entries under the Help pull-down menu on the main window. There is help available in many categories, from units and buildings to concepts such as combat and happiness. Regardless of which category you select, the left edge scrollbar lists all of the help which is available, in all categories. Click on a unit name, building name, form of government, or whatever your interest is, to bring up its help page. The help pages themselves may contain scrolled data, as the example above does (note the scroll bar). Help pages for units and buildings list their critical statistics and technological prerequisites.

The help pages for buildings, units, and civilization advances include a map of the advances required to produce the item. Note that in this example, Transport requires Magnetism, which is displayed in red because you don't have that technology and aren't close enough to have it listed as an option for research; it is 15 research steps away from what you have researched already. Its predecessors are Physics and Iron Working; Physics is at least 13 steps in the future, but Iron Working is only one research step away, and indeed is marked yellow to say that it can be researched right now. The advances Bronze Working and Warrior Code have already been discovered.

You may use this interactively to plan your research. One of the prerequisites for Physics is Navigation; the graph shows that it is 9 steps away, but doesn't show what you need to get to it. A click on the Navigation box redisplays the window to expand its prerequisites. If showing the earlier advances would exceed the space in the window, the later ones are pushed off to the right; to get them back, click again on an intermediate advance (such as Navigation); its prerequisites will disappear, leaving room for those displaced.

Intelligence Report[]

This is opened from the Intelligence button on the Players window, but is only available for civilizations for which you have established an embassy (one of the functions of a Diplomat). It shows some useful data about the civilization, mostly about the state of its technology. Note the asterisk with Monotheism; that is an advancement that the other race has and you don't, and might be something you want to bargain for.

Meeting Dialog[]

The Meeting Window comes up from the Meet button of the Players window; recall that this is only available between human players, as the AI players don't do diplomacy. It automatically comes up for both players involved in the meeting, and both will then use his or her window to negotiate a treaty. The left column of the window has buttons with which the window user may offer gifts to the other player; the right column has buttons to request gifts from the other player. The center contains all of the clauses so far offered by either player.

Let's suppose the Romans want to make a few offers and see what happens. Each of the blue buttons is a menu. Caesar might start with the Maps menu and select the option to give the entire worldmap as known to him, then select the Advances menu, which pops up all of the advances that the Romans have and the English don't; in this case he offers Map Making. The box in the center on both player's windows now shows these two clauses.

Elizabeth has the chance to examine the Roman generosity and come up with a counter-offer. She could accept the gift as it is by pressing Accept treaty, but the Romans would probably not accept it as is and would demand changes. They could do so by using their right-side buttons to add clauses offering English assets to Rome. She will make some offers of her own instead, using the Advances and Cities buttons to offer Masonry and Birmingham.

Caesar can see that the English are overcome with his magnificence, and will try to see how far he can go. Selecting the first line of the treaty clauses and clicking on Erase clause, the Roman offer of the world map disappears from both player's windows.

Elizabeth could use the right buttons to add clauses of Roman gifts, or could delete clauses from the treaty, or end the meeting entirely. Instead, she clicks on Accept treaty, which causes the "English view" red thumbs-down symbol to change to a green thumbs-up symbol on both windows.

Caesar sees an entirely acceptable treaty, and clicks on Accept treaty also. The meeting window disappears from the view of both players, and the server will implement the transfers given in the treaty. They will both immediately see in their message lists messages informing them of the changes that took place.

Notes on diplomacy at version 1.14.2: (update this when next version comes up)

Sometimes this may not come clear, but here is a list of a couple commands that are quite useful, however not clearly documented anywhere easy to find:

- Opening your "players" dialog and selecting one (human) player that got one of your embassies then pressing m on your keyboard allows you to start a meeting.

- Also in the "players" dialog, you can drop your current diplomacy state (from alliance to peace, from peace to neutral and from neutral to war) by pressing c. This drops the selected player's diplomatic state.


<paragraph here: researching/goal/steps>

Also note the Help button. Checking this will give you a help window on any advancement on which you click in the lower list, and also on any advancement you select in the Researching or Goal drop-down boxes.

Global Worklists[]

A player may use the "Edit worklists" window to create, edit, and delete global worklists. As of version 1.11.4, a player may create up to 16 global worklists. Global worklists are intended to save time managing cities: instead of creating many identical city worklists, the player may create one global worklist and copy it to each city.

Spaceship Dialog[]

This shows the spaceship under construction and its statistics. Of particular interest is the success probability.

Main Menubar Options[]

The main client window has four menu buttons in a row along the top of the window. They each deal with different aspects of user interface.

Game Menu[]

This menu deals with empire-wide game controls and user interface controls.

Local Options
Local options control the behaviour of the freeciv client (but not messages). Options include:
  • "Solid unit background color", when set, uses a solid color to identify each race's units, instead of the default background containing a national flag.
  • "Sound bell at new turn", when set, rings the bell when the new turn begins. This may be useful in multiplayer games with a timeout set, since you may be away from the computer waiting for others to move.
  • "Smooth unit moves", defaulted to Yes, gives to unit moves a bit more of the feel of moving pieces on a board. Instead of just having the unit disappear and reappear in a new place, it is shown for an instant part way in between the old and new positions.
  • "Popup dialogs in AI mode", defaulted to No, allows messages to pop up in the client when the race is being controlled by an AI.
  • "Manual Turn Done in AI mode", defaulted to Yes, enables the Turn Done button when the AI has finished its work. This allows you to control the race in addition to having the AI make the moves.
  • "Auto Center on Units", defaulted to Yes, makes the main window automatically center on the unit when a new unit is activated.
  • "Focus on Awakened Units", defaulted to Yes, controls units that have awakened out of Sentry. When set, such units become active automatically.
  • "Draw Diagonal Roads/Rails", defaulted to Yes, shows small roads between squares in a diagonal relationship which both have roads. This is simply a visual effect, not a game issue of what squares have roads.
  • "Center map when Popup city," defaulted to Yes, positions the map to place a city in the center when its window is displayed.
Message Options
Messages can appear in the output window, the message window, an individual pop-up window, or can be ignored.
Save Settings
This menuitem causes the local and message options to be written to a ./civclientrc file.
This opens the Players Window.
This opens this turn's messages window, which contains the urgent messages from the server.
Server options initial and ongoing
These open read-only windows listing the server's game options. For descriptions of the server game options see the server documentation, especially the server's online documentation via the "explain" command. These are to allow you to find out what the rules are in this universe.
Export log
This writes the current game log out to the file civgame.log in the current directory. The material written is what appears in the main window's scrollable message list.
Clear log
This clears the main window's scrollable output list. This may be necessary if you find the window's content has become so long that it is difficult to scroll.
Disconnect from the current server. Frees the socket. The connect window will appear.
Exits the game.

Kingdom Menu[]

Tax Rates
This opens the Rates Window.
Find City
This is to help when you have a large empire and have forgotten where one of your cities is. A window will open giving a list of all of the cities whose names you could know, whether yours or of other empires. Click on a name and the map will center on that city. Click on Center and the window will close, leaving the map on that city. Click on Cancel and the window will close, leaving the map where it was before Find City was selected.
This menuitem allows the player to edit global worklists using the Edit worklists window.
This allows you to start a revolution, which eventually will allow you to change your form of government.

View Menu[]

These control map display settings.

Map Grid
Toggles on or off the grid on the map.
City names
Toggles the display of city names.
City productions
Toggles the display of city production targets under each city's icon.
Center view
Centers the map on the currently selected unit.

Orders Menu[]

These give orders to the currently selected unit. Many of them are straightforward orders whose effects are described further in the Game Manual. Some, however, are more complicated:

Auto Settler
This tells the game to assign AI control to the selected worker unit (Settlers, Workers, or Engineers). Thereafter it will do what AI player's Settlers do as far as building roads, irrigating, for the purpose of improving the area around the Settler's city.
This marks a unit, if it is in a city, as operating under that city's auto-attack options; see the City Options Window. When so enabled, when a designated enemy unit comes close to the city, such units will leave the city, attack the enemy, and return to the city.
This tells the game to assign AI control to the selected unit as an exploration unit. Thereafter it will search the map and uncover new territory in the manner of AI players. If a unit can do no more exploring, it will abort this order.
Go to
This tells a unit to take a predetermined route to a specified destination and then await further orders. The mouse pointer will change and a line will join the unit's position with the cursor position; this is the route that the unit will take. Click on the destination to confirm the order. Waypoints (points which the unit must go through en route) can be specified by moving the cursor to the point and pressing the Goto key (usually G).
Similar to the Go to order, except that upon reaching its destination, the unit will return to its starting point by the best route and start again, until interrupted. Again, waypoints can be set by repeatedly pressing the Patrol key (usually Q).
Connect with Road/Rail/Irrigation
Orders worker units to create road/rail/irrigation on every tile along the specified route. Waypoints can be set as for "Go to" using the shortcut keys.
Explode Nuclear
Orders a Nuclear unit to explode. A Nuclear will explode when it enters an enemy city, but this order will cause it to explode in open terrain.

Reports Menu[]

Each of these brings up the corresponding report window; most of these were shown in the windows section.

The most useful report: City report brings up the city window. The shortcut key (F1) is worth remembering.
The units menu item pops up the units window. The only useful thing here is the Upgrade button - used to upgrade obsolete units.
Brings up the Economy window.
Shows the science window.
Wonders of the World
Pops up the Wonders of the World window.
Top Five Cities
Pops up the Top Five Cities window.
Pops up the Demographics window.
Pops up the spaceship window.

Help Menu[]

The online help contains information on all areas of the game system, buildings, units, concepts, etc.

Customizing the Client[]

The client can be customized in many ways to reflect your tastes for its user interface. The game system, rules, units, and such are not controlled by the client and are beyond customization at the client level; they are defined by the server. But many issues dealing with graphics features can be changed.

Alternate Graphics Tilesets[]

The graphics used for Freeciv are defined in XPM (X Pixmap) files in the distribution; there are separate files for terrain squares, units, roads, the small symbols used on various windows, and the spaceship elements. The default tilesets are a set of 45x45 tiles by Ralf Engels. Other tilesets exist which are different both in style and in size; many people prefer using 30x30 tiles to fit more of the map on the screen (17 across and 11 high).

The Freeciv distribution comes with one alternate tileset, a 30x30 tileset, which was the standard tileset in Freeciv 1.7.2. By default, it is stored in the directory /usr/local/share/freeciv/classic, so you may use it with the -tiles classic option added to your invocation of the client. Additional popular tilesets have been contributed to the Freeciv effort, and can be found in [1]. You would typically download and unpack them into a new directory in /usr/local/share/freeciv for general use.

X Resources and Command Options[]

A great many features of the Xaw client are defined as X resources, and as such may be set by you; this is not the case with the GTK client. Typically, you would add such definitions to your .Xdefaults file, or whatever file you use to customize your X environment. All Xaw client Freeciv resources start with the name Freeciv, so to change your customary player name (as shown in the table below), you would add Freeciv*player: Honorius to your file of X settings.

All Xaw client command line options are available with either one or two hyphens before the name (that is, -name and --name yield the same effect). The GTK client requires two hyphens. All but two of the command line options are also X resources (for the Xaw client only). The two exceptions are -help (which lists the command line options) and -version (which displays the Freeciv client version).

X Resource Command line Results
log -log Defines the name of a log file to be produced as the client operates. The amount of information logged is controlled by the debug resource.
name -name The player name you wish to use; this is copied into the Connect Window for you.
server -server The Internet address (e.g., or name (e.g., at which the Freeciv server is to be found; this is copied into the Connect Window.
port -port The port number on the server system at which the Freeciv server is to be found; this is copied into the Connect Window.
debug -debug Sets the level of debugging information logged, a number from 0 to 2. Zero logs fatal errors; 1 additionally logs warning errors; 2 additionally logs normal debugging messages.
tileset Provides the directory name of an alternate tileset to be used for graphics. This should be a name relative to the base of the Freeciv data area, by default /usr/local/share/freeciv.

Those are the X resources which a typical user might wish to modify. The Xaw client, however, uses the X resource system to control vast amounts of the user interface's presentation, such as the color of every field, the ways in which the fields of a window are linked together, and the words on each button. You can find the default settings for all of these resources in the file /usr/local/share/freeciv/Freeciv. If you wished to, for instance, you could change the Turn Done button with the line

Freeciv*turndonebutton.label: Next Turn

in your X resources file.

Files and Environment Variables[]

The client depends on certain files to initialize itself. The standard distribution places these files in /usr/local/share/freeciv, and the code is compiled to use that directory. The files used from the Freeciv directory are:

The default X resources for Xaw client
The database of help data used for the Help menu.
The directory containing the graphics files required:
the map terrain tiles
the unit symbols
roads of various sorts
small graphics for various windows
spaceship components
treaty agreement graphics

The environment variable FREECIV_DATADIR, if specified, gives the full path of an alternate directory.

The environment variable HOME is used to find the user's home directory. The file .civclientrc is ready from and written to in that directory.