AI Documentation

704pages on
this wiki
Add New Page
Talk1 Share



The Freeciv AI is widely recognized as being as good as or better military-wise as the AI of certain other games it is natural to compare it with. It is, however, still too easy for experienced players.

The code base used to be in a bad shape but it has gotten a lot better. The reason for this is that the developer (Syela) who in a few months put together a working AI had suddenly disappeared. His bright ideas could only be matched by his inability to name variables and to comment the code. Subsequent AI developers were not brave (or stupid?) enough to start from scratch, taking instead a small bite here and there, trying hard not to break much, to understand Syela's original design and only then to throw it away. Or perfect it.

Not all code is residing in ai/, but it is also dissolved in little chunks in the whole server/. Aside that, server/settlers.c is only AI stuff - the problem is, that most of it is used also for the auto-settlers, so we can't separate it from the server. server/gotohand.c is a left-over from the previous path-finding system which is slowly being phased out.


AI development doesn't have its own mailing list anymore. Instead, send questions to, or go to the Community Portal to read the archives or to join up.


The long-term goals for Freeciv AI development are

  • to create a challenging and fun AI for human players to defeat
  • to create an AI that can handle all the rules possibilities that Freeciv can offer


Build calculations are expressed through a structure called ai_choice. This has a variable called "want", which determines how much the AI wants whatever item is pointed to by choice->type. choice->want is

  -199   get_a_boat
  < 0    an error
  == 0   no want, nothing to do
  <= 100 normal want
   > 100 critical want, used to requisition emergency needs
   > ??? probably an error (1024 is a reasonable upper bound)
   > 200 Frequently used as a cap. When want exceeds this value,
         it is reduced to a lower number.

These are ideal numbers, your mileage while travelling through the code may vary considerably. Technology and diplomats, in particular, seem to violate these standards.

Actually, only defense units seem to follow this "standard". Attack units, quite notably, do not follow this at all. Their want frequently and easily overshadow want for other, useful, things.


Hard fact: amortize \left( benefit, delay \right) returns benefit \times \left(\frac{MORT - 1}{MORT}\right)^{delay}

Speculation: What is better, to receive 10$ annually starting in 5 years from now or 5$ annually starting from this year? How can you take inflation into account? The function amortize is meant to help you answer these questions. To achieve this, it rescales the future benefit in terms of todays money.

Suppose we have a constant rate of inflation, x percent. Then in five years time 10$ will buy as much as 10 \times \left(\frac{100}{100+x}\right)^5 will buy today. Denoting \frac{100}{100+x} by q we get the general formula, N dollars Y years from now will be worth N \times q^Y in todays money. If we will receive N every year starting Y years from now, the total amount receivable (in todays money) is \frac{N \times q^Y}{1-q} --- this is the sum of infinite geometric series. This is exactly the operation that amortize performs, the multiplication by some q < 1 raised to power Y. Note that the factor \frac{1}{1-q} does not depend on the parameters N and Y and can be ignored. The connection between MORT constant and the inflation rate x is given by \frac{MORT-1}{MORT}=q=\frac{100}{100+x}.

Thus the current value of MORT = 24 corresponds to the inflation rate (or the rate of expansion of your civ) of 4.3%

Most likely this explanation is not what the authors of amortize() had in mind, but the basic idea is correct: the value of the payoff decays exponentially with the delay.

The version of amortize used in the military code, militaryAmortize(), remains a complete mystery.


This estimation is implemented by killDesire function (which isn't perfect: multi-victim part is flawed) plus some corrections. In general,

Want = OperationProfit \times AmortizationFactor


  • AmortizationFactor is completely beyond me (but it's a function of the estimated time length of the operation).
  • OperationProfit = BattleProfit - Maintenance


  • Maintenance = (Support + UnhappinessCompensation) \times OperationTime
here unhappiness is from military unit being away from home and Support is the number of shields spent on supporting this unit per turn
  • BattleProfit = ShieldsLostByEnemy \times ProbabilityToWin - ShieldsLostByUs \times ProbabilityToLose
That is BattleProfit is a probabilistic average. It answer the question "how much better off, on average, we would be from attacking this enemy unit?"


The code dealing with choosing military units to be built and targets for them is especially messy. Here is what we've managed to decipher.

Military units are requested in military_advisor_choose_build function. It first considers the defensive units and then ventures into selection of attackers (if home is safe). There are 2 possibilities here: we just build a new attacker or we already have an attacker which was forced, for some reason, to defend. In the second case it's easy: we calculate how good the existing attacker is and if it's good, we build a defender to free it up.

Building a brand-new attacker is more complicated. Firstly, ai_choose_attacker_* functions are charged to find the first approximation to the best attacker that can be built here. This prototype attacker is selected using very simple attack_power * speed formula. Then (already in kill_something_with) we search for targets for the prototype attacker (using find_something_to_kill). Having found a target, we do the last refinement by calling process_attacker_want to look for the best attacker type to take out the target. This type will be our attacker choice. Note that the function process_attacker_want has side-effects wrt the tech selection.

Here is an example:

First ai_choose_attacker_land selects a Dragoon because it's strong and fast. Then find_something_to_kill finds a victim for the (virtual) Dragoon, an enemy Riflemen standing right next to the town. Then process_attacker_want figures out that since the enemy is right beside us, it can be taken out easier using an Artillery. It also figures that a Howitzer would do this job even better, so bumps up our desire for Robotics.

This is the idea, anyway. In practice, it is more complicated and probably less efficient.


The ferry (i.e. boats transporting land units) system of Freeciv is probably better described by statistical mechanics than by logic. Both ferries and prospective passenger (PP) move around in what looks like a random fashion, trying to get closer to each other. On average, they succeed. This behaviour has good reasons behind it, is hell to debug but means that small bugs don't affect overall picture visibly (and stay unfixed as a result).

Each turn both boats and PPs forget all about prior arrangements (unless the passenger is actually _in_ the boat). Then each will look for the closest partner, exchange cards and head towards it. This is done in a loop which goes through all units in essentially random order.

Because most units recalculate their destination every turn, ignoring prior arrangements is the only good strategy -- it means that a boat will not rely on the PP to notify it when it's not needed anymore. This is not very effective but can only be changed when the PPs behave more responsibly. See diplomat code for more responsible behaviour -- they try to check if the old target is still good before trying to find a new one.

When a boat has a passenger, it's a different story. The boat doesn't do any calculations, instead one of the passengers is given full control and it is the passenger who drives the boat.

Here are the main data fields used by the system. Value of ai.ferry in the passenger unit is:

 FERRY_NONE : means that the unit has no need of a ferry
 FERRY_WANTED : means that the unit wants a ferry
 >0 : id of it's ferry

Value of ai.passenger in the ferry unit can be either of:

 FERRY_AVAILABLE : means that the unit is a ferry and is available
 >0 : id of it's passenger

When boat-building code stabilizes, it can be seen how many free boats there are, on average, per PP. If there are more boats than PPs, it makes sense that only PPs should look for boats. If boats are few, they should be the ones choosing. This can be done both dynamically (both possibilities are coded and the appropriate is chosen every turn) and statically (after much testing only one system remains). Now they exist in parallel, although developed to a different degree.


The AI's diplomatic behaviour is current only regulated by the 'diplomacy' server setting.

In default rules, the AI starts out in NO_CONTACT mode, and proceeds to NEUTRAL on first-contact.

AI is not very trusting for NEUTRAL and PEACE modes, but once it hits ALLIANCE, this changes completely, and it will happily hand over any tech and maps it has to you. The only thing that will make the AI attack you then is if you build a spaceship.

For people who want to hack at this part of the AI code, please note

* pplayers_at_war(p1,p2) returns FALSE if p1==p2
* pplayers_non_attack(p1,p2) returns FALSE if p1==p2
* pplayers_allied(p1,p2) returns TRUE if p1==p2 
* pplayer_has_embassy(p1,p2) returns TRUE if p1==p2

i.e. we do not ever consider a player to be at war with himself, we never consider a player to have any kind of non-attack treaty with himself, and we always consider a player to have an alliance with himself.

The introduction of diplomacy is fraught with many problems. One is that it usually gains only human players, not AI players, since humans are so much smarter and know how to exploit diplomacy, while for AIs they mostly only add constraints on what it can do. Another is that it can be very difficult to write diplomacy that is useful for and not in the way of modpacks. Which means diplomacy either has to be optional, or have fine-grained controls on who can do what diplomatic deals to whom, set from rulesets. The latter is not yet well implemented.


There are currently five difficulty levels: 'novice', 'easy', 'medium', 'hard' and 'experimental'. The 'hard' level is no-holds-barred, while 'medium' has a number of handicaps. In 'easy', the AI also does random stupid things through the ai_fuzzy function. The 'experimental' level is only for coding - you can gate new code with the H_EXPERIMENTAL handicap and test 'experimental' level AIs against 'hard' level AIs. In 'novice' the AI researches slower than normal players.

Other handicaps used are:

 H_RATES, can't set its rates beyond government limits
 H_TARGETS, can't target anything it doesn't know exists
 H_HUTS, doesn't know which unseen tiles have huts on them
 H_FOG, can't see through fog of war

The other defined handicaps (in common/player.h) are not currently in use.


  • Cities don't realize units are on their way to defend it.
  • AI builds cities without regard to danger at that location.
  • AI won't build cross-country roads outside of city radii.
  • Locally_zero_minimap is not implemented when wilderness tiles change.
  • If no path to chosen victim is found, new victim should be chosen.
  • AI makes trade routes [to close/convenient cities] that tend to give only small benefits. It should try to build trade routes for its best cities (most building bonuses and least corruption) by moving caravans there and changing homecity.
  • Emergencies in two cities at once aren't handled properly.
  • Explorers will not use ferryboats to get to new lands to explore. The AI will also not build units to explore new islands, leaving huts alone.
  • AI sometimes believes that wasting a horde of weak military units to kill one enemy is profitable (PR#1340)
  • Stop building shore defense in landlocked cities with a pond adjacent.
  • Fix the AI valuation of supermarket. (It currently never builds it). See farmland_food() and ai_eval_buildings() in advdomestic.c
  • Teach the AI to coordinate the units in an attack (ok, this one is a bit big...)
  • AI builds cities very close together, so it never can get really big cities. City radius overlaps too much.
  • calculate the places where to build cities and how to improve the tiles for the specific city.
  • engineers shall do terrain transformation if useful


  • Friendly cities can be used as beachheads
  • Assess_danger should acknowledge positive feedback between multiple attackers
  • It would be nice for bodyguard and charge to meet en-route more elegantly.
  • struct choice should have a priority indicator in it. This will reduce the number of "special" want values and remove the necessity to have want capped, thus reducing confusion.
  • building cities close together is more efficient in the early game (you get to use one free tile for each city and cities don't grow so much anyways). be careful when changing this behaviour. in the early game it's usually best to have only one big city for things like colossus. in the late game each city with overlapped spaces should either become a high or low priority city, so that there are very small cities (with little buildings) and large cities (with many buildings).

Ad blocker interference detected!

Wikia is a free-to-use site that makes money from advertising. We have a modified experience for viewers using ad blockers

Wikia is not accessible if you’ve made further modifications. Remove the custom ad blocker rule(s) and the page will load as expected.

Also on Fandom

Random Wiki