Interface engine.h et programme engine-cli
engine.h expose initialisation, coups légaux, classement des coups, évaluation et décision de videau, avec Position ID et Match ID, sans type gnubg ; erreurs par code de retour. engine-cli l'interroge et répond en JSON (bestmove, moves, legal, cube, eval ; option --ply). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Pierre MARTIN
co-authored by
Claude Opus 5.5
Claude Opus 5.5
parent
42bfb6506d
commit
da5fa71ff8
@@ -0,0 +1,155 @@
|
||||
/*
|
||||
* 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_status;
|
||||
|
||||
#define ENGINE_MAX_PLY 4
|
||||
|
||||
/* 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
|
||||
};
|
||||
|
||||
/* 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 */
|
||||
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 */
|
||||
const char *decision; /* décision de gnubg, en anglais : « no_double_take »,
|
||||
* « double_take », « double_pass »,
|
||||
* « too_good_pass », « not_available »… */
|
||||
} engine_cube;
|
||||
|
||||
/* 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);
|
||||
|
||||
/*
|
||||
* 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. Comme dans
|
||||
* gnubg, les coups écartés par les filtres gardent l'évaluation du niveau
|
||||
* inférieur (voir leur champ ply).
|
||||
*/
|
||||
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);
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
||||
#endif /* USTAGAMMON_ENGINE_H */
|
||||
Reference in New Issue
Block a user