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