CONTENTS
========

1. Default build
2. Using freeciv built with AI-modules support
3. Building freeciv with AI-modules support
4. Coding new AI module


1. Default build
----------------

By default Freeciv is built with just one, "classic", AI type
statically built in, and with no support for dynamic AI modules.
Classic AI is always used for all players, effectively hiding the
fact that AI module interface even exist.


2. Using freeciv built with AI-modules support
----------------------------------------------

Some modules might be statically linked to freeciv server, and those
are always available. If freeciv is built with also dynamic modules
support enabled, one can load additional AI modules to server with
commandline option "--LoadAI <modulename>"
Whether module is statically linked or dynamically loaded, new AI players
that use that module can be created by giving "create" command AI type as
second parameter
> create Leonidas classic

Players created any other way, such as by aifill will get the "classic"
AI type.

Information "list" command shows includes player's AI type:
> list
Leonidas [#ff0000]: Team 0, user Unassigned
  AI, classic, difficulty level Easy


3. Building freeciv with AI-modules support
-------------------------------------------

There's three configure options controlling AI-modules support to be
built in to freeciv.

To statically link some of the supplied AI modules to freeciv,
use --enable-ai-static=<comma,separated,list>. Default value for this
is just "classic".

To support dynamically loading additional modules, use
--enable-aimodules. It requires that also --enable-shared has been used,
which may not work on all platforms.
Special value --enable-aimodules=experimental makes freeciv also to build
all the modules in its source tree as dynamically loadable AI modules.

Dynamic AI modules are expected in their correct installation location
unless one has configured with --enable-debug which allows freeciv
server to look for supplied modules from build directory too. Otherwise you
cannot use dynamic modules from the freeciv build dir, but you need
to "make install" freeciv to install them to correct location.


4. Coding new dynamic AI module
-------------------------------

Dynamic AI module to be loaded with "--LoadAI <modulename>" needs to contain
two functions.

const char *fc_ai_<modulename>_capstr(void)
  This needs to return capability string of the module. This is used to
  check if module is compatible with the version of freeciv one tries to
  load it into. Current freeciv's capstr is in common/ai.h macro FC_AI_MOD_CAPSTR.

 
bool fc_ai_<modulename>_setup(struct ai_type *ai)
  This function is called for AI module to setup itself. Most importantly
  it should setup callback table ai->funcs so that its other functions
  get called, and fill ai->name so that it can be referred to in creation of
  new players.
  Callback table, with comments when each callback gets called, is defined
  in common/ai.h

For "--LoadAI <modulename>" to find the AI module, it must reside in ${libdir}/fcai/
(/usr/lib/fcai by default) under name fc_ai_<modulename>.so