common/ai.h

   1 /***********************************************************************
   2  Freeciv - Copyright (C) 1996 - A Kjeldberg, L Gregersen, P Unold
   3    This program is free software; you can redistribute it and/or modify
   4    it under the terms of the GNU General Public License as published by
   5    the Free Software Foundation; either version 2, or (at your option)
   6    any later version.
   7
   8    This program is distributed in the hope that it will be useful,
   9    but WITHOUT ANY WARRANTY; without even the implied warranty of
  10    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11    GNU General Public License for more details.
  12 ***********************************************************************/
  13 #ifndef FC__AI_H
  14 #define FC__AI_H
  15
  16 #ifdef __cplusplus
  17 extern "C" {
  18 #endif /* __cplusplus */
  19
  20 /* common */
  21 #include "fc_types.h" /* MAX_LEN_NAME */
  22
  23 /* Update this capability string when ever there is changes to ai_type
  24  * structure below. When changing mandatory capability part, check that
  25  * there's enough reserved_xx pointers in the end of the structure for
  26  * taking to use without need to bump mandatory capability again. */
  27 #define FC_AI_MOD_CAPSTR "+Freeciv-3.1-ai-module-2017.Jan.13"
  28
  29 /* Timers for all AI activities. Define it to get statistics about the AI. */
  30 #ifdef FREECIV_DEBUG
  31 #  undef DEBUG_AITIMERS
  32 #endif /* FREECIV_DEBUG */
  33
  34 struct Treaty;
  35 struct player;
  36 struct adv_choice;
  37 struct city;
  38 struct unit;
  39 struct tile;
  40 struct settlermap;
  41 struct pf_path;
  42 struct section_file;
  43 struct adv_data;
  44
  45 enum incident_type {
  46   INCIDENT_DIPLOMAT = 0, INCIDENT_WAR, INCIDENT_PILLAGE,
  47   INCIDENT_NUCLEAR, INCIDENT_NUCLEAR_NOT_TARGET,
  48   INCIDENT_NUCLEAR_SELF, INCIDENT_LAST
  49 };
  50
  51 struct ai_type
  52 {
  53   char name[MAX_LEN_NAME];
  54
  55   void *private;
  56
  57   struct {
  58     /* Called for every AI type when game starts. Game is not necessarily new one,
  59        it can also be an old game loaded from a savegame. */
  60     void (*game_start)(void);
  61
  62     /* Called for every AI type when game has ended. */
  63     void (*game_free)(void);
  64
  65     /* Called for every AI type when new player is added to game. */
  66     void (*player_alloc)(struct player *pplayer);
  67
  68     /* Called for every AI type when player is freed from game. */
  69     void (*player_free)(struct player *pplayer);
  70
  71     /* Called for every AI type for each player in game when game saved. */
  72     void (*player_save)(struct player *pplayer, struct section_file *file,
  73                         int plrno);
  74
  75     /* Called for every AI type for each player in game when game loaded. */
  76     void (*player_load)(struct player *pplayer, const struct section_file *file,
  77                         int plrno);
  78
  79     /* Called for every AI type for each player in game when game saved,
  80      * with each other player as parameter.
  81      * In practice it's good to use player_save_relations when you
  82      * want to add entries to "player%d.ai%d", but player_iterate() inside
  83      * player_save is better otherwise. The difference is in how clean
  84      * structure the produced savegame will have. */
  85     void (*player_save_relations)(struct player *pplayer, struct player *other,
  86                                   struct section_file *file, int plrno);
  87
  88     /* Called for every AI type for each player in game when game loaded,
  89      * with each other player as parameter. */
  90     void (*player_load_relations)(struct player *pplayer, struct player *other,
  91                                   const struct section_file *file, int plrno);
  92
  93     /* AI console. */
  94     void (*player_console)(struct player *pplayer, const char *cmd);
  95
  96     /* Called for AI type that gains control of player. */
  97     void (*gained_control)(struct player *pplayer);
  98
  99     /* Called for AI type that loses control of player. */
 100     void (*lost_control)(struct player *pplayer);
 101
 102     /* Called for AI type of the player who gets split to two. */
 103     void (*split_by_civil_war)(struct player *original, struct player *created);
 104
 105    /* Called for AI type of the player who got created from the split. */
 106     void (*created_by_civil_war)(struct player *original, struct player *created);
 107
 108     /* Called for player AI type when player phase begins. This is in the
 109      * beginning of phase setup. See also first_activities. */
 110     void (*phase_begin)(struct player *pplayer, bool new_phase);
 111
 112     /* Called for player AI type when player phase ends. */
 113     void (*phase_finished)(struct player *pplayer);
 114
 115     /* Called for every AI type when new city is added to game. */
 116     void (*city_alloc)(struct city *pcity);
 117
 118     /* Called for every AI type when city is removed from game. */
 119     void (*city_free)(struct city *pcity);
 120
 121     /* Called for player AI type when player gains control of city. */
 122     void (*city_got)(struct player *pplayer, struct city *pcity);
 123
 124     /* Called for player AI type when player loses control of city. */
 125     void (*city_lost)(struct player *pplayer, struct city *pcity);
 126
 127     /* Called for every AI type for each city in game when game saved. */
 128     void (*city_save)(struct section_file *file, const struct city *pcity,
 129                       const char *citystr);
 130
 131     /* Called for every AI type for each city in game when game loaded. */
 132     void (*city_load)(const struct section_file *file, struct city *pcity,
 133                       const char *citystr);
 134
 135     /* Called for player AI type when building advisor has chosen something
 136      * to be built in a city. This can override that decision. */
 137     void (*choose_building)(struct city *pcity, struct adv_choice *choice);
 138
 139     /* Called for player AI when building advisor prepares to make decisions. */
 140     void (*build_adv_prepare)(struct player *pplayer, struct adv_data *adv);
 141
 142     /* Called for every AI type when building advisor is first initialized
 143      * for the turn. */
 144     void (*build_adv_init)(struct player *pplayer);
 145
 146     /* Called for player AI when building advisor should set wants for buildings.
 147      * Without this implemented in AI type building advisor does not adjust wants
 148      * at all. */
 149     void (*build_adv_adjust_want)(struct player *pplayer, struct city *wonder_city);
 150
 151     /* Called for player AI when evaluating governments. */
 152     void (*gov_value)(struct player *pplayer, struct government *gov,
 153                       adv_want *val, bool *override);
 154
 155     /* Called for every AI type when unit ruleset has been loaded. */
 156     void (*units_ruleset_init)(void);
 157
 158     /* Called for every AI type before unit ruleset gets reloaded. */
 159     void (*units_ruleset_close)(void);
 160
 161     /* Called for every AI type when new unit is added to game. */
 162     void (*unit_alloc)(struct unit *punit);
 163
 164     /* Called for every AI type when unit is removed from game. */
 165     void (*unit_free)(struct unit *punit);
 166
 167     /* Called for player AI type when player gains control of unit. */
 168     void (*unit_got)(struct unit *punit);
 169
 170     /* Called for player AI type when unit changes type. */
 171     void (*unit_transformed)(struct unit *punit, struct unit_type *old_type);
 172
 173     /* Called for player AI type when player loses control of unit. */
 174     void (*unit_lost)(struct unit *punit);
 175
 176     /* Called for unit owner AI type for each unit when turn ends. */
 177     void (*unit_turn_end)(struct unit *punit);
 178
 179     /* Called for unit owner AI type when advisors goto moves unit. */
 180     void (*unit_move)(struct unit *punit, struct tile *ptile,
 181                       struct pf_path *path, int step);
 182
 183     /* Called for unit owner AI type when new advisor task is set for unit. */
 184     void (*unit_task)(struct unit *punit, enum adv_unit_task task,
 185                       struct tile *ptile);
 186
 187     /* Called for every AI type for each unit in game when game saved. */
 188     void (*unit_save)(struct section_file *file, const struct unit *punit,
 189                       const char *unitstr);
 190
 191     /* Called for every AI type for each unit in game when game loaded. */
 192     void (*unit_load)(const struct section_file *file, struct unit *punit,
 193                       const char *unitstr);
 194
 195     /* Called for player AI type when autosettlers have been handled for the turn. */
 196     void (*settler_reset)(struct player *pplayer);
 197
 198     /* Called for player AI type when autosettlers should find new work. */
 199     void (*settler_run)(struct player *pplayer, struct unit *punit,
 200                         struct settlermap *state);
 201
 202     /* Called for player AI type for each autosettler still working.
 203        Cancelling current work there will result in settler_run() call. */
 204     void (*settler_cont)(struct player *pplayer, struct unit *punit,
 205                          struct settlermap *state);
 206
 207     /* Called for player AI type when unit wants to autoexplore towards a tile. */
 208     void (*want_to_explore)(struct unit *punit, struct tile *target,
 209                             enum override_bool *allow);
 210
 211     /* Called for player AI type in the beginning of player phase.
 212      * Unlike with phase_begin, everything is set up for phase already. */
 213     void (*first_activities)(struct player *pplayer);
 214
 215     /* Called for player AI when player phase is already active when AI gains control. */
 216     void (*restart_phase)(struct player *pplayer);
 217
 218     /* Called for player AI type in the beginning of player phase. Not for barbarian
 219      * players. */
 220     void (*diplomacy_actions)(struct player *pplayer);
 221
 222     /* Called for player AI type in the end of player phase. */
 223     void (*last_activities)(struct player *pplayer);
 224
 225     /* Called for player AI type when diplomatic treaty requires evaluation. */
 226     void (*treaty_evaluate)(struct player *pplayer, struct player *aplayer,
 227                             struct Treaty *ptreaty);
 228
 229     /* Called for player AI type when diplomatic treaty has been accepted
 230      * by both parties. */
 231     void (*treaty_accepted)(struct player *pplayer, struct player *aplayer,
 232                             struct Treaty *ptreaty);
 233
 234     /* Called for player AI type when first contact with another player has been
 235      * established. Note that when contact is between two AI players, callback
 236      * might be already called for the other party, so you can't assume
 237      * relations to be all-pristine when this gets called. */
 238     void (*first_contact)(struct player *pplayer, struct player *aplayer);
 239
 240     /* Called for player AI type of the victim when someone does some violation
 241      * against him/her. */
 242     void (*incident)(enum incident_type type, struct player *violator,
 243                      struct player *victim);
 244
 245     /* Called for player AI type of city owner when logging requires city debug
 246      * information. */
 247     void (*log_fragment_city)(char *buffer, int buflength, const struct city *pcity);
 248
 249     /* Called for player AI type of unit owner when logging requires unit debug
 250      * information. */
 251     void (*log_fragment_unit)(char *buffer, int buflength, const struct unit *punit);
 252
 253     /* Called for player AI type to decide if another player is dangerous. */
 254     void (*consider_plr_dangerous)(struct player *plr1, struct player *plr2,
 255                                    enum override_bool *result);
 256
 257     /* Called for player AI type to decide if it's dangerous for unit to enter tile. */
 258     void (*consider_tile_dangerous)(struct tile *ptile, struct unit *punit,
 259                                     enum override_bool *result);
 260
 261     /* Called for player AI to decide if city can be chosen to act as wonder city
 262      * for building advisor. */
 263     void (*consider_wonder_city)(struct city *pcity, bool *result);
 264
 265     /* Called for player AI type with short internval */
 266     void (*refresh)(struct player *pplayer);
 267
 268     /* Called for every AI type when tile has changed */
 269     void (*tile_info)(struct tile *ptile);
 270
 271     /* These are here reserving space for future optional callbacks.
 272      * This way we don't need to change the mandatory capability of the AI module
 273      * interface when adding such callbacks, but existing modules just have these
 274      * set to NULL. Optional capability should be set when taking one of these to use,
 275      * so that new modules know if the server is going to call these or is it too old
 276      * version to do so.
 277      * When mandatory capability then changes again, please add new reservations to
 278      * replace those taken to use. */
 279     void (*reserved_01)(void);
 280     void (*reserved_02)(void);
 281     void (*reserved_03)(void);
 282     void (*reserved_04)(void);
 283     void (*reserved_05)(void);
 284   } funcs;
 285 };
 286
 287 struct ai_type *ai_type_alloc(void);
 288 void ai_type_dealloc(void);
 289 struct ai_type *get_ai_type(int id);
 290 int ai_type_number(const struct ai_type *ai);
 291 void init_ai(struct ai_type *ai);
 292 int ai_type_get_count(void);
 293 const char *ai_name(const struct ai_type *ai);
 294
 295 struct ai_type *ai_type_by_name(const char *search);
 296 const char *ai_type_name_or_fallback(const char *orig_name);
 297
 298 #ifdef DEBUG_AITIMERS
 299 void ai_timer_init(void);
 300 void ai_timer_free(void);
 301 void ai_timer_start(const struct ai_type *ai);
 302 void ai_timer_stop(const struct ai_type *ai);
 303 void ai_timer_player_start(const struct player *pplayer);
 304 void ai_timer_player_stop(const struct player *pplayer);
 305 #else
 306 #define ai_timer_init(...) (void) 0
 307 #define ai_timer_free(...) (void) 0
 308 #define ai_timer_start(...) (void) 0
 309 #define ai_timer_stop(...) (void) 0
 310 #define ai_timer_player_start(...) (void) 0
 311 #define ai_timer_player_stop(...) (void) 0
 312 #endif /* DEBUG_AITIMERS */
 313
 314 #define ai_type_iterate(NAME_ai)                        \
 315   do {                                                  \
 316     int _aii_;                                          \
 317     int _aitotal_ = ai_type_get_count();                \
 318     for (_aii_ = 0; _aii_ < _aitotal_ ; _aii_++) {      \
 319       struct ai_type *NAME_ai = get_ai_type(_aii_);
 320
 321 #define ai_type_iterate_end \
 322     }                       \
 323   } while (FALSE);
 324
 325 /* FIXME: This should also check if player is ai controlled */
 326 #define CALL_PLR_AI_FUNC(_func, _player, ...)                           \
 327   do {                                                                  \
 328     struct player *_plr_ = _player; /* _player expanded just once */    \
 329     if (_plr_ && _plr_->ai && _plr_->ai->funcs._func) {                 \
 330       ai_timer_player_start(_plr_);                                     \
 331       _plr_->ai->funcs._func( __VA_ARGS__ );                            \
 332       ai_timer_player_stop(_plr_);                                      \
 333     }                                                                   \
 334   } while (FALSE)
 335
 336 #define CALL_FUNC_EACH_AI(_func, ...)           \
 337   do {                                          \
 338     ai_type_iterate(_ait_) {                    \
 339       if (_ait_->funcs._func) {                 \
 340         ai_timer_start(_ait_);                  \
 341         _ait_->funcs._func( __VA_ARGS__ );      \
 342         ai_timer_stop(_ait_);                   \
 343       }                                         \
 344     } ai_type_iterate_end;                      \
 345   } while (FALSE)
 346
 347 #ifdef __cplusplus
 348 }
 349 #endif /* __cplusplus */
 350
 351 #endif  /* FC__AI_H */