doc/README.AI_modules

   1
   2 CONTENTS
   3 ========
   4
   5 1. Default build
   6 2. Using freeciv built with AI-modules support
   7 3. Building freeciv with AI-modules support
   8 4. Coding new AI module
   9
  10
  11 1. Default build
  12 ----------------
  13
  14 By default Freeciv is built with just one, "classic", AI type
  15 statically built in, and with no support for dynamic AI modules.
  16 Classic AI is always used for all players, effectively hiding the
  17 fact that AI module interface even exist.
  18
  19
  20 2. Using freeciv built with AI-modules support
  21 ----------------------------------------------
  22
  23 Some modules might be statically linked to freeciv server, and those
  24 are always available. If freeciv is built with also dynamic modules
  25 support enabled, one can load additional AI modules to server with
  26 commandline option "--LoadAI <modulename>"
  27 Whether module is statically linked or dynamically loaded, new AI players
  28 that use that module can be created by giving "create" command AI type as
  29 second parameter
  30 > create Leonidas classic
  31
  32 Players created any other way, such as by aifill will get the AI type
  33 that has been made the default freeciv build time.
  34
  35 Information "list" command shows includes player's AI type:
  36 > list
  37 Leonidas [#ff0000]: Team 0, user Unassigned
  38   AI, classic, difficulty level Easy
  39
  40
  41 3. Building freeciv with AI-modules support
  42 -------------------------------------------
  43
  44 There's three configure options controlling AI-modules support to be
  45 built in to freeciv.
  46
  47 To statically link some of the supplied AI modules to freeciv,
  48 use --enable-ai-static=<comma,separated,list>. Default value for this
  49 is just "classic". Order of the modules is important in that first of
  50 the modules will be the default AI type used for all the players for whom
  51 it's not explicitly set.
  52
  53 To support dynamically loading additional modules, use
  54 --enable-aimodules. It requires that also --enable-shared has been used,
  55 which may not work on all platforms.
  56 Special value --enable-aimodules=experimental makes freeciv also to build
  57 all the modules in its source tree as dynamically loadable AI modules.
  58
  59 In case you want to use some dynamically loadable module as the default
  60 AI type instead of first type listed for --enable-ai-static, you can
  61 explicitly set the default type with --with-default-ai=<type>.
  62
  63 Dynamic AI modules are expected in their correct installation location
  64 unless one has configured with --enable-debug which allows freeciv
  65 server to look for supplied modules from build directory too. Otherwise you
  66 cannot use dynamic modules from the freeciv build dir, but you need
  67 to "make install" freeciv to install them to correct location.
  68
  69
  70 4. Coding new dynamic AI module
  71 -------------------------------
  72
  73 Dynamic AI module to be loaded with "--LoadAI <modulename>" needs to contain
  74 two functions.
  75
  76 const char *fc_ai_<modulename>_capstr(void)
  77   This needs to return capability string of the module. This is used to
  78   check if module is compatible with the version of freeciv one tries to
  79   load it into. Current freeciv's capstr is in common/ai.h macro FC_AI_MOD_CAPSTR.
  80
  81
  82 bool fc_ai_<modulename>_setup(struct ai_type *ai)
  83   This function is called for AI module to setup itself. Most importantly
  84   it should setup callback table ai->funcs so that its other functions
  85   get called, and fill ai->name so that it can be referred to in creation of
  86   new players.
  87   Callback table, with comments when each callback gets called, is defined
  88   in common/ai.h
  89
  90 For "--LoadAI <modulename>" to find the AI module, it must reside in ${libdir}/fcai/
  91 (/usr/lib/fcai by default) under name fc_ai_<modulename>.so