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 5. Using default AI as part of new AI module
  10 6. Callback interface ChangeLog
  11
  12
  13 1. Default build
  14 ----------------
  15
  16 By default Freeciv is built with just one, "classic", AI type
  17 statically built in, and with no support for dynamic AI modules.
  18 Classic AI is always used for all players, effectively hiding the
  19 fact that AI module interface even exist.
  20
  21
  22 2. Using freeciv built with AI-modules support
  23 ----------------------------------------------
  24
  25 Some modules might be statically linked to freeciv server, and those
  26 are always available. If freeciv is built with also dynamic modules
  27 support enabled, one can load additional AI modules to server with
  28 commandline option "--LoadAI <modulename>"
  29 Whether module is statically linked or dynamically loaded, new AI players
  30 that use that module can be created by giving "create" command AI type as
  31 second parameter
  32 > create Leonidas classic
  33
  34 Players created any other way, such as by aifill will get the AI type
  35 that has been made the default freeciv build time.
  36
  37 Information "list" command shows includes player's AI type:
  38 > list
  39 Leonidas [#ff0000]: Team 0, user Unassigned
  40   AI, classic, difficulty level Easy
  41
  42
  43 3. Building freeciv with AI-modules support
  44 -------------------------------------------
  45
  46 There's three configure options controlling AI-modules support to be
  47 built in to freeciv.
  48
  49 To statically link some of the supplied AI modules to freeciv,
  50 use --enable-ai-static=<comma,separated,list>. Default value for this
  51 is just "classic". Order of the modules is important in that first of
  52 the modules will be the default AI type used for all the players for whom
  53 it's not explicitly set.
  54
  55 To support dynamically loading additional modules, use
  56 --enable-aimodules. It requires that also --enable-shared has been used,
  57 which may not work on all platforms.
  58 Special value --enable-aimodules=experimental makes freeciv also to build
  59 all the modules in its source tree as dynamically loadable AI modules.
  60
  61 In case you want to use some dynamically loadable module as the default
  62 AI type instead of first type listed for --enable-ai-static, you can
  63 explicitly set the default type with --with-default-ai=<type>.
  64
  65 Dynamic AI modules are expected in their correct installation location
  66 unless one has configured with --enable-debug which allows freeciv
  67 server to look for supplied modules from build directory too. Otherwise you
  68 cannot use dynamic modules from the freeciv build dir, but you need
  69 to "make install" freeciv to install them to correct location.
  70
  71
  72 4. Coding new dynamic AI module
  73 -------------------------------
  74
  75 Dynamic AI module to be loaded with "--LoadAI <modulename>" needs to contain
  76 two functions.
  77
  78 const char *fc_ai_<modulename>_capstr(void)
  79   This needs to return capability string of the module. This is used to
  80   check if module is compatible with the version of freeciv one tries to
  81   load it into. Current freeciv's capstr is in common/ai.h macro FC_AI_MOD_CAPSTR.
  82
  83
  84 bool fc_ai_<modulename>_setup(struct ai_type *ai)
  85   This function is called for AI module to setup itself. Most importantly
  86   it should setup callback table ai->funcs so that its other functions
  87   get called, and fill ai->name so that it can be referred to in creation of
  88   new players.
  89   Callback table, with comments when each callback gets called, is defined
  90   in common/ai.h
  91
  92 For "--LoadAI <modulename>" to find the AI module, it must reside in ${libdir}/fcai/
  93 (/usr/lib/fcai by default) under name fc_ai_<modulename>.so
  94
  95
  96 5. Using default AI as part of new AI module
  97 --------------------------------------------
  98
  99 Default AI here refers to specific code module that any AI module can use, not to any
 100 one AI module. Classic AI module is just a thin wrapper around it, and also Threaded AI
 101 uses it.
 102
 103 Almost all functions in default AI API take pointer to current AI type as parameter.
 104 This is used for accessing memory associated with the correct AI type from the structures
 105 having such AI type specific data.
 106
 107 If a AI type wants to add its own data associated with some code structure, it needs
 108 to make sure data needed by default AI is in the beginning of the allocated data blocks.
 109 For example, see threaded AI: tai_player_alloc(), tai_player_free(), and struct tai_plr.
 110
 111 Default AI code is usually built in freeciv only if some AI type using it has been built;
 112 either 'classic' or 'threaded'. If no such ai type has been built, you can still force
 113 it in for custom ai types to use by passing configure option --with-ai-lib
 114
 115
 116 6. Callback interface ChangeLog
 117 -------------------------------
 118
 119 New in Freeciv 3.1:
 120 -------------------
 121 - Added 'tile_info', called when tile has changed
 122
 123
 124 New in Freeciv 3.0:
 125 -------------------
 126 - Added 'private' pointer for ai module to store data of its own
 127 - Added 'module_close', called when server quits
 128 - Added 'player_console', called when user enter aicmd
 129 - Added 'city_created', 'city_destroyed', 'unit_created', and 'unit_destroyed'
 130   They are like 'city_alloc', 'city_free', 'unit_alloc', and 'unit_free' but called
 131   for real cities and units only, in a later phase of creation or earlier phase
 132   of destruction
 133
 134
 135 New in Freeciv 2.6:
 136 -------------------
 137 - Renamed enum danger_consideration as enum override_bool
 138 - Added restart_phase, called when AI gains control of the player whose phase is already
 139   active, for example when continuing from a saved game
 140 - Added created_by_civil_war, called for AI type of the player who got created from
 141   civil war
 142 - Added "created" player parameter to split_by_civil_war
 143 - Added game_start, called for all AI types when game starts
 144 - "city_got" is called when the city is fully initialized, "city_lost" when city still valid
 145 - Added gov_value for giving AI control of deciding value of governments
 146 - Added player_save_relations and player_load_relations called on savegame handling for a
 147   player once per other player in game. Old player_save and player_load are called only once
 148   overall
 149 - Added want_to_explore, called for AI type of the unit owner, when it is about to autoexplore
 150 - Added currently unused 'reserved' pointers that we can populate with optional callbacks
 151   without need to change the mandatory capability of the modules