pierre/Ustagammon
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Activity
Files
091cb4a8b01fe3c47da0efb19a313c7eec4e2e1d
Ustagammon/engine/include/engine.h
T

421 lines
19 KiB
C
Raw Blame History

/*
* engine.h -- interface C du moteur de backgammon d'Ustagammon.
*
* Copyright (C) 2026 les auteurs d'Ustagammon.
* Licence : GPLv3 ou ultérieure (voir LICENSE).
*
* Le moteur est le cœur de GNU Backgammon (engine/gnubg/), seule autorité
* pour les règles, les coups, le videau et les évaluations. Cette interface
* n'expose aucun type de gnubg.
*
* Positions : une position est décrite par deux identifiants de gnubg,
* - le Position ID (14 caractères), qui code le plateau du point de vue du
* joueur au trait ;
* - le Match ID (12 caractères), qui code le reste : longueur du match (0 en
* partie libre), score, videau et son propriétaire, joueur au trait,
* Crawford, Jacoby. Les dés éventuellement codés dans le Match ID sont
* ignorés : les dés sont passés à part.
*
* Niveaux (« ply ») : réglages prédéfinis de gnubg, sans bruit, de 0
* (évaluation statique du réseau) à 4. gnubg compte les plis à partir de 0.
*
* Équités : toujours du point de vue du joueur au trait, normalisées pour
* un videau de 1. En match, gnubg convertit les chances de gain du match en
* équité normalisée, comme il l'affiche par défaut.
*
* Probabilités, dans l'ordre de gnubg : gain, gain gammon, gain backgammon,
* perte gammon, perte backgammon (les gammons incluent les backgammons).
*
* Contraintes : une seule instance du moteur (état global de gnubg) et des
* appels sérialisés, jamais concurrents. Toutes les fonctions renvoient un
* code engine_status ; aucune ne termine le programme pour une erreur
* d'utilisation.
*/
#ifndef USTAGAMMON_ENGINE_H
#define USTAGAMMON_ENGINE_H
#ifdef __cplusplus
extern "C" {
#endif
typedef enum {
ENGINE_OK = 0,
ENGINE_ERROR_NOT_INITIALISED, /* engine_init n'a pas réussi */
ENGINE_ERROR_DATA, /* données absentes ou invalides */
ENGINE_ERROR_POSITION_ID, /* Position ID invalide */
ENGINE_ERROR_MATCH_ID, /* Match ID invalide */
ENGINE_ERROR_DICE, /* dés hors de 1..6 */
ENGINE_ERROR_PLY, /* niveau hors de 0..ENGINE_MAX_PLY */
ENGINE_ERROR_TOO_MANY_MOVES, /* tableau de coups trop petit */
ENGINE_ERROR_INTERNAL, /* échec signalé par gnubg */
ENGINE_ERROR_LEVEL, /* niveau de jeu inconnu */
ENGINE_ERROR_MOVE, /* coup joué absent des coups légaux */
ENGINE_ERROR_CUBE_ACTION /* décision de videau inconnue */
} engine_status;
#define ENGINE_MAX_PLY 4
/*
* Niveaux de jeu de l'ordinateur : les réglages prédéfinis de gnubg, dans
* l'ordre de son tableau aecSettings (engine/gnubg/eval.c, l. 305-328, noms
* de aszSettings). Les quatre premiers évaluent à 0 pli et ajoutent un
* bruit (rNoise, écart type en équité) qui fait commettre des erreurs ; ce
* bruit est « déterministe » (fDeterministic) : il est tiré d'un hachage MD5
* de la position (Noise, eval.c l. 2241), donc la même position donne
* toujours le même coup. Les suivants sont sans bruit, de 0 à 4 plis, avec
* le filtre de coups « Normal » (aiSettingsMoveFilter, eval.c l. 331).
*
* Les anciennes versions de gnubg nommaient « expert » le niveau 0 pli et
* « world class » (champion du monde) le niveau 2 plis.
*/
typedef enum {
ENGINE_LEVEL_BEGINNER = 0, /* « beginner » : 0 pli, bruit 0,060 */
ENGINE_LEVEL_CASUAL, /* « casual play » : 0 pli, bruit 0,050 */
ENGINE_LEVEL_INTERMEDIATE, /* « intermediate » : 0 pli, bruit 0,040 */
ENGINE_LEVEL_ADVANCED, /* « advanced » : 0 pli, bruit 0,015 */
ENGINE_LEVEL_0PLY, /* « 0ply » (ancien « expert ») */
ENGINE_LEVEL_1PLY, /* « 1ply » */
ENGINE_LEVEL_2PLY, /* « 2ply » (ancien « world class ») */
ENGINE_LEVEL_3PLY, /* « 3ply » */
ENGINE_LEVEL_4PLY, /* « 4ply » */
ENGINE_LEVEL_COUNT
} engine_level;
/* Réglages d'un niveau, tels que gnubg les définit. */
typedef struct {
const char *name; /* identifiant : « beginner », « casual »,
* « intermediate », « advanced », « 0ply »… « 4ply » */
int plies; /* profondeur, en plis de gnubg */
float noise; /* écart type du bruit (0 : aucun) */
int deterministic; /* bruit tiré de la position, reproductible */
int prune; /* élagage des réponses (gnubg : à partir d'1 pli) */
} engine_level_settings;
/*
* Appréciation d'un coup ou d'une décision de videau : seuils de gnubg sur
* l'équité perdue, normalisée pour un videau de 1 (arSkillLevel dans
* gnubg.c l. 280-285 et Skill dans analysis.c l. 288). Une perte
* strictement plus grande que le seuil fait passer à la catégorie.
*/
#define ENGINE_SKILL_DOUBTFUL_THRESHOLD 0.03f /* douteux */
#define ENGINE_SKILL_BAD_THRESHOLD 0.06f /* mauvais */
#define ENGINE_SKILL_VERY_BAD_THRESHOLD 0.12f /* très mauvais */
typedef enum {
ENGINE_SKILL_NONE = 0, /* rien à signaler */
ENGINE_SKILL_DOUBTFUL, /* douteux */
ENGINE_SKILL_BAD, /* mauvais */
ENGINE_SKILL_VERY_BAD /* très mauvais */
} engine_skill;
/*
* Chance d'un jet : seuils de gnubg sur l'équité gagnée ou perdue par
* rapport à la moyenne des jets (arLuckLevel dans gnubg.c l. 274-279 et Luck
* dans analysis.c l. 272). Un écart strictement plus grand que le seuil
* fait passer à la catégorie.
*/
#define ENGINE_LUCK_THRESHOLD 0.3f /* chanceux, malchanceux */
#define ENGINE_LUCK_VERY_THRESHOLD 0.6f /* très chanceux, très malchanceux */
typedef enum {
ENGINE_LUCK_VERY_UNLUCKY = 0, /* très malchanceux */
ENGINE_LUCK_UNLUCKY, /* malchanceux */
ENGINE_LUCK_NONE, /* ordinaire */
ENGINE_LUCK_LUCKY, /* chanceux */
ENGINE_LUCK_VERY_LUCKY /* très chanceux */
} engine_luck_rating;
/* Décision de videau prise par un joueur. Les deux premières sont celles
* du joueur au trait, les deux dernières sa réponse par l'adversaire. */
typedef enum {
ENGINE_CUBE_ACTION_NO_DOUBLE = 0,
ENGINE_CUBE_ACTION_DOUBLE,
ENGINE_CUBE_ACTION_TAKE,
ENGINE_CUBE_ACTION_PASS
} engine_cube_action;
/* Nombre maximal de coups légaux pour un jet (MAX_MOVES de gnubg). */
#define ENGINE_MAX_MOVES 3060
/* Indices du tableau probabilities. */
enum {
ENGINE_WIN = 0,
ENGINE_WIN_GAMMON,
ENGINE_WIN_BACKGAMMON,
ENGINE_LOSE_GAMMON,
ENGINE_LOSE_BACKGAMMON,
ENGINE_NUM_PROBABILITIES
};
/*
* Demi-coup : un pion déplacé d'une case avec un seul dé. Les cases sont
* numérotées du point de vue du joueur qui joue, comme dans la notation de
* gnubg : 1 à 24, 25 pour la barre, 0 pour la sortie.
*/
#define ENGINE_BAR 25
#define ENGINE_OFF 0
typedef struct {
int from;
int to;
} engine_half_move;
/* Un coup complet utilise au plus quatre dés (un double). */
#define ENGINE_MAX_HALF_MOVES 4
/* Un coup, avec son évaluation quand il a été classé. */
typedef struct {
char notation[32]; /* notation de gnubg, ex. « 8/5 6/5 » */
char position_id[16]; /* Position ID après le coup, plateau vu du
* joueur qui vient de jouer */
engine_half_move half_moves[ENGINE_MAX_HALF_MOVES];
int half_move_count; /* demi-coups du coup, dans un ordre jouable */
int ply; /* niveau de l'évaluation (-1 : non évalué) */
float probabilities[ENGINE_NUM_PROBABILITIES];
float equity; /* équité de classement (avec videau) */
} engine_move;
/* Évaluation d'une position, joueur au trait avant de lancer les dés. */
typedef struct {
float probabilities[ENGINE_NUM_PROBABILITIES];
float cubeless_equity; /* équité sans videau */
float cubeful_equity; /* équité avec videau */
} engine_evaluation;
/* Décision de videau du joueur au trait, avant de lancer les dés. */
typedef struct {
float probabilities[ENGINE_NUM_PROBABILITIES];
float no_double; /* équité si pas de double */
float double_take; /* équité si double et prend */
float double_pass; /* équité si double et passe */
float optimal; /* équité après les meilleures décisions des deux
* joueurs */
const char *decision; /* nom de la décision dans l'énumération
* cubedecision de gnubg : « NODOUBLE_TAKE »,
* « DOUBLE_TAKE », « DOUBLE_PASS »,
* « TOOGOOD_PASS », « NOT_AVAILABLE »… */
const char *decision_text; /* libellé anglais de gnubg, ex. « Double, take » */
int available; /* le joueur au trait a le droit de doubler */
int should_double; /* gnubg recommande de doubler : décision
* DOUBLE_TAKE, DOUBLE_PASS, DOUBLE_BEAVER,
* REDOUBLE_TAKE ou REDOUBLE_PASS (un double
* « facultatif » n'est pas recommandé) */
int should_take; /* s'il double, l'adversaire doit prendre :
* prendre lui coûte moins que passer
* (double_take <= double_pass) */
} engine_cube;
/* Analyse d'un coup joué, comme l'analyse de partie de gnubg. */
typedef struct {
int move_count; /* nombre de coups légaux (0 : aucun coup
* possible, rien d'autre n'est rempli) */
int rank; /* rang du coup joué dans le classement, à
* partir de 1 */
engine_move played; /* le coup joué, évalué */
engine_move best; /* le meilleur coup, évalué */
float equity_loss; /* équité du coup joué moins celle du meilleur :
* 0 ou négative */
engine_skill skill; /* appréciation de gnubg pour cette perte */
} engine_move_analysis;
/* Analyse d'une décision de videau, comme l'analyse de partie de gnubg. */
typedef struct {
int analysed; /* gnubg analyse cette décision ; sinon (videau
* inaccessible, position de départ…), perte
* nulle et cube non rempli */
engine_cube cube; /* la décision de videau du joueur au trait */
float equity_loss; /* équité perdue par celui qui décide, du point
* de vue de celui-ci, normalisée pour un videau
* de 1 : 0 ou négative */
engine_skill skill; /* appréciation de gnubg pour cette perte */
} engine_cube_analysis;
/* Chance d'un jet, comme l'analyse de partie de gnubg. */
typedef struct {
float luck; /* équité gagnée (positive) ou perdue par ce jet
* par rapport à la moyenne des jets, du point
* de vue du joueur au trait */
engine_luck_rating rating;
} engine_luck;
/* Un camp sur le plateau, vu de lui-même (sa case 1 est la plus proche de
* la sortie). */
typedef struct {
int points[24]; /* pions sur les cases 1 à 24 (indices 0 à 23) */
int bar; /* pions sur la barre */
int off; /* pions sortis */
int pip_count; /* compte de points */
} engine_side;
/* Plateau décodé d'un Position ID. */
typedef struct {
engine_side on_roll; /* le joueur au trait */
engine_side opponent; /* son adversaire */
char swapped_position_id[16]; /* la même position vue de l'adversaire */
} engine_board;
/* Fin de partie. */
typedef struct {
int over; /* la partie est finie */
int winner; /* 0 : le joueur au trait, 1 : son adversaire */
int kind; /* 1 : simple, 2 : gammon, 3 : backgammon */
int points; /* points gagnés : kind fois la valeur du videau,
* mais 1 fois en partie libre avec la règle
* Jacoby quand le videau n'a pas bougé */
} engine_result;
/* Où en est un coup saisi demi-coup par demi-coup. */
typedef struct {
int valid; /* les demi-coups commencent un coup légal */
int complete; /* ils forment à eux seuls un coup légal */
char position_id[16]; /* si valid : position après ces demi-coups, vue
* du joueur qui joue ; sinon chaîne vide */
} engine_half_moves_check;
/* Description lisible d'un Match ID décodé. */
typedef struct {
int match_length; /* 0 : partie libre (money game) */
int score[2];
int cube_value;
int cube_owner; /* -1 : videau au centre ; sinon 0 ou 1 */
int player_on_roll; /* 0 ou 1 */
int crawford; /* partie Crawford en cours */
int jacoby; /* règle Jacoby (partie libre) */
} engine_match;
/*
* Charge les données du moteur depuis data_dir : gnubg.wd (réseaux),
* gnubg_os0.bd et gnubg_ts0.bd (fins de partie), Kazaross-XG2.xml (table
* d'équité de match). À appeler une fois avant toute autre fonction.
*/
engine_status engine_init(const char *data_dir);
/* Libère les ressources. Le moteur ne peut pas être réinitialisé ensuite. */
void engine_shutdown(void);
/* Message d'erreur en français pour un code de retour. */
const char *engine_status_message(engine_status status);
/* Décode un Match ID. */
engine_status engine_decode_match(const char *match_id, engine_match *match);
/*
* Code un Match ID (12 caractères et le zéro final), sans dés ni double en
* cours. cube_value : puissance de 2 de 1 à 4096 ; cube_owner : -1, 0 ou 1.
*/
engine_status engine_encode_match(const engine_match *match, char match_id[13]);
/* Décode un Position ID en plateau. */
engine_status engine_decode_position(const char *position_id, engine_board *board);
/* La partie est-elle finie dans cette position, et combien rapporte-t-elle ? */
engine_status engine_game_result(const char *position_id, const char *match_id,
engine_result *result);
/*
* Vérifie des demi-coups saisis un par un (count de 0 à
* ENGINE_MAX_HALF_MOVES), avec le jet die1, die2 : chacun doit être permis
* par les règles, et l'ensemble doit pouvoir se compléter en un des coups
* légaux d'engine_legal_moves. Des demi-coups refusés ne sont pas une erreur :
* check->valid vaut alors 0.
*/
engine_status engine_check_half_moves(const char *position_id, int die1, int die2,
const engine_half_move *half_moves, int count,
engine_half_moves_check *check);
/*
* Coups légaux pour une position et un jet (die1, die2 dans 1..6), sans
* évaluation (ply vaut -1). moves doit pouvoir contenir max_moves coups ;
* ENGINE_MAX_MOVES suffit toujours. *count reçoit le nombre de coups (0 si
* le joueur ne peut pas jouer).
*/
engine_status engine_legal_moves(const char *position_id, const char *match_id,
int die1, int die2,
engine_move *moves, int max_moves, int *count);
/*
* Coups légaux classés du meilleur au moins bon, au niveau ply, exactement
* comme la commande « hint » de gnubg (filtre de coups « Normal »). Les coups
* écartés par les filtres gardent l'évaluation du niveau inférieur (voir
* leur champ ply) et sont classés après ceux évalués plus profondément.
*/
engine_status engine_best_moves(const char *position_id, const char *match_id,
int die1, int die2, int ply,
engine_move *moves, int max_moves, int *count);
/* Évaluation d'une position au niveau ply. */
engine_status engine_evaluate(const char *position_id, const char *match_id,
int ply, engine_evaluation *evaluation);
/* Décision de videau au niveau ply. */
engine_status engine_cube_decision(const char *position_id, const char *match_id,
int ply, engine_cube *cube);
/* ------------------------------------------------------ Niveaux de jeu */
/* Réglages d'un niveau (engine_level). */
engine_status engine_level_settings_of(int level, engine_level_settings *settings);
/* Le niveau qui porte ce nom, ou ENGINE_ERROR_LEVEL. */
engine_status engine_level_from_name(const char *name, int *level);
/*
* Coups légaux classés comme les classe l'ordinateur de gnubg quand il joue
* à ce niveau (ComputerTurn dans play.c : FindnSaveBestMoves sans analyse
* ni seuil, filtre « Normal », puis RefreshMoveList) ; il joue le premier.
* Les équités incluent le bruit du niveau.
*/
engine_status engine_level_best_moves(const char *position_id, const char *match_id,
int die1, int die2, int level,
engine_move *moves, int max_moves, int *count);
/* Décision de videau évaluée avec les réglages de ce niveau, bruit compris. */
engine_status engine_level_cube_decision(const char *position_id, const char *match_id,
int level, engine_cube *cube);
/* ------------------------------------------------------------- Analyse */
/* Appréciation de gnubg pour une perte d'équité (0 ou négative). */
engine_skill engine_skill_of(float equity_loss);
/* Catégorie de chance de gnubg pour une chance de jet. */
engine_luck_rating engine_luck_rating_of(float luck);
/*
* Analyse le coup joué par le joueur au trait avec le jet die1, die2, au
* niveau ply, comme l'analyse de partie de gnubg (AnalyzeMove dans
* analysis.c : FindnSaveBestMoves avec le coup joué, seuil « douteux »,
* filtre « Normal », sans RefreshMoveList). played_position_id est la
* position après le coup, vue du joueur qui vient de le jouer (champ
* position_id d'engine_move). ENGINE_ERROR_MOVE si ce n'est pas un coup
* légal ; si aucun coup n'est possible, move_count vaut 0.
*/
engine_status engine_analyse_move(const char *position_id, const char *match_id,
int die1, int die2, const char *played_position_id, int ply,
engine_move_analysis *analysis);
/*
* Analyse une décision de videau au niveau ply, comme l'analyse de partie de
* gnubg (AnalyzeMove, cas MOVE_NORMAL, MOVE_DOUBLE, MOVE_TAKE et
* MOVE_DROP). La position et le Match ID sont ceux du joueur au trait, qui
* double ou non ; pour TAKE et PASS, la perte est celle de son adversaire.
*/
engine_status engine_analyse_cube(const char *position_id, const char *match_id, int ply,
engine_cube_action action, engine_cube_analysis *analysis);
/*
* Chance du jet die1, die2 pour le joueur au trait, comme l'analyse de
* partie de gnubg (LuckAnalysis dans analysis.c : meilleur coup de chaque
* jet à 0 pli, avec videau ; à la position de départ, le premier jet ne
* peut pas être un double).
*/
engine_status engine_luck_of(const char *position_id, const char *match_id,
int die1, int die2, engine_luck *luck);
#ifdef __cplusplus
}
#endif
#endif /* USTAGAMMON_ENGINE_H */
Reference in New Issue View Git Blame Copy Permalink