uct/plugin.h

   1 #ifndef PACHI_UCT_PLUGIN_H
   2 #define PACHI_UCT_PLUGIN_H
   3
   4 /* This is the public API for external Pachi UCT plugins. */
   5 /* Unlike the rest of Pachi, this file is available for anyone for
   6  * unrestricted use and distribution. The plugin interface is not
   7  * restricted by the terms of GPL and plugins may have any arbitrary
   8  * licence conditions and do not need to be GPL or open-source at all. */
   9
  10 /* Contrast this with <uct/plugins.h>, which is internal Pachi API
  11  * for calling all loaded modules. */
  12
  13 /* In order to compile your plugin, pass cc an -I parameter pointing
  14  * at the root Pachi sources directory and include this file - it should
  15  * pull in everything else neccessary. */
  16
  17 /* No API stability guarantees can be made at this point. The board
  18  * structure and UCT tree in particular _are_ likely to change again. */
  19
  20 #include <assert.h> // we use assertions a lot, even in .h files
  21
  22 #include "stone.h" // stones and their colors
  23 #include "move.h" // coordinates and (coordinate, stone) pairs ("moves")
  24 #include "board.h" // the goban structure and basic interface
  25 #include "uct/prior.h" // the UCT tree prior values assignment
  26 #include "uct/tree.h" // the UCT minimax tree and node structures
  27
  28
  29 /* This function is called at the time a new game is started (more precisely,
  30  * when clear_board GTP command is received; board size is already known and
  31  * the board structure is initialized, but komi is not known yet), with
  32  * argument string passed on Pachi's commandline. The pointer the function
  33  * returns is assumed to be the plugin's context and will be passed to all
  34  * subsequent functions called within the game.
  35  *
  36  * The seed is a random seed in the range of 0..65335. If the plugin will use
  37  * fast_random() from Pachi's <random.h>, this should be ignored; otherwise,
  38  * if the plugin is using a random generator, it should be seeded with this
  39  * value so that Pachi would play the same game with the same random seed.
  40  *
  41  * When the game finishes and new game is started, the current context is
  42  * deinitialized and the init function is called again. The game is monotonic;
  43  * no moves are undone when made (in case of undo, the game is cancelled and
  44  * re-played from beginning). */
  45 void *pachi_plugin_init(char *args, struct board *b, int seed);
  46
  47 /* This function is called when priors are to be assigned to all leaves
  48  * of a given node. Usually, the leaves have been freshly expanded (but in
  49  * theory, this may be also a delayed bias). Eqex is a recommendation on how
  50  * many simulations should the prior information be worth.
  51  *
  52  * The function should evaluate the board situation when in tree node @node
  53  * and save evaluation of various coordinates to @map. The @map structure
  54  * contains a lot of useful information; map->b is the board in the @node
  55  * situation, map->to_play is who is to play, map->consider is bool array
  56  * describing which coordinates are worth evaluating at all and map->distances
  57  * are pre-computed Common Fate Graph distances from the last move. To record
  58  * priors, use add_prior_value(). See <uct/prior.h> for details and the
  59  * <uct/prior.c> for the default prior evaluation functions. */
  60 void pachi_plugin_prior(void *data, struct tree_node *node, struct prior_map *map, int eqex);
  61
  62 /* This function is called when the game has ended and the context needs
  63  * to be deinitialized. */
  64 void pachi_plugin_done(void *data);
  65
  66 #endif