chess_z

# chess_z chess_z est un cadre logiciel pour le Xiangqi (échecs chinois) implémenté en C, dont l'objectif actuel est le cœur des règles et la frontière d'intégration de l'IA. ## Caractéristiques principales - **Représentation par bitboards** : le plateau de 90 cases utilise une représentation à double bitboard `uint64_t`, chaque type de pièce de chaque camp disposant de son propre bitboard. - **Tableau mailbox** : un tableau mailbox `board[90]` est maintenu en synchronisation, ce qui facilite la génération des règles et le débogage. - **Prise en charge complète des règles** : prise en charge de la position initiale, lecture/écriture FEN, déplacement des pièces, génération des coups légaux, détection d'échec et perft. - **Interface d'adaptation IA** : fournit `XqEngineAdapter`, permettant d'intégrer ultérieurement des fonctions externes de recherche/évaluation d'IA pour le Xiangqi. - **Moteur simple intégré** : comprend une très petite évaluation basée sur le matériel et la mobilité des coups légaux + une recherche negamax, principalement destinée aux tests de fumée du cadre. ## Structure des répertoires ```text include/xiangqi/bitboard.h opérations de base sur les bitboards include/xiangqi/types.h types de base, pièces, coups include/xiangqi/position.h représentation de la position, FEN, déplacements include/xiangqi/movegen.h coups pseudo-légaux/légaux, détection d'échec, perft include/xiangqi/engine.h interface d'adaptation du moteur IA src/ implémentation du cœur examples/cli.c point d'entrée CLI d'exemple stats/generate_positions.c point d'entrée de génération de positions légales aléatoires stats/search_positions.c point d'entrée de recherche par lots de positions stats/random_fen/ données FEN de positions aléatoires stats/data/ résultats d'analyse de performance tests/test_core.c tests des règles de base ``` ## Compilation CMake est recommandé : ```sh cmake -S . -B build cmake --build build ctest --test-dir build ``` Si seul GCC est disponible localement, il est également possible de compiler directement les tests : ```sh gcc -std=c99 -Wall -Wextra -Wpedantic -I include src/position.c src/movegen.c src/engine.c tests/test_core.c -o build/xiangqi_core_tests ./build/xiangqi_core_tests ``` Compiler l'exemple interactif homme-machine : ```sh gcc -std=c99 -Wall -Wextra -Wpedantic -I include src/position.c src/movegen.c src/engine.c examples/cli.c -o build/xiangqi_cli ./build/xiangqi_cli ``` Le point d'entrée d'exemple est par défaut « vous jouez les rouges, le moteur simple intégré joue les noirs ». Le format de saisie est `départ+arrivée`, les colonnes utilisent `a..i`, les numéros de ligne utilisent `0..9`, par exemple : ```text b2b9 ``` Commandes disponibles : ```text moves affiche tous les coups légaux actuels fen affiche la FEN actuelle help affiche l'aide quit quitter ``` ## Génération de positions aléatoires et recherche par lots Après compilation, il est possible de générer d'abord un ensemble de positions légales aléatoires reproductibles, puis de laisser le moteur intégré les rechercher une par une : ```sh ./build/xiangqi_generate_positions ./build/xiangqi_search_positions ``` Les deux programmes utilisent par défaut `stats/random_fen/random_positions.fen`, mais il est également possible de leur spécifier le même chemin de fichier : ```sh ./build/xiangqi_generate_positions build/profile_positions.fen ./build/xiangqi_search_positions build/profile_positions.fen ``` Le générateur utilise une graine aléatoire fixe, effectue une marche aléatoire de `0..100` coups depuis la position initiale et produit 100 positions, une FEN par ligne. Le programme de recherche lit le fichier une fois séquentiellement et recherche un coup pour chaque position avec une profondeur maximale de 6 et sans limite de temps, ce qui en fait un point d'entrée non interactif adapté à l'analyse de performance. ## Intégration de l'IA Une IA externe peut réutiliser directement la couche de règles : ```c XqMoveList legal; xq_generate_legal(&pos, &legal); for (int i = 0; i < legal.count; ++i) { XqPosition next = pos; xq_position_make_move(&next, legal.moves[i]); /* effectuer une recherche ou une évaluation sur next */ } ``` Il est également possible d'intégrer une recherche personnalisée via `XqEngineAdapter` : ```c static bool my_search(const XqPosition *pos, unsigned depth, XqMove *best, void *user) { (void)user; /* implémenter sa propre recherche avec xq_generate_legal / xq_position_make_move */ return false; } XqEngineAdapter engine = { .evaluate = NULL, .search = my_search, .user = NULL, }; XqMove best; XqSearchLimits limits = xq_search_limits_default(); xq_engine_find_best_move(&engine, &pos, &limits, &best); ``` ## Convention de coordonnées - `file` va de `0..8`, `rank` va de `0..9`. - La ligne de fond des rouges est `rank = 0`, celle des noirs est `rank = 9`. - `xq_square_make(file, rank)` mappe les coordonnées en `rank * 9 + file`. - La FEN s'écrit sur 10 lignes, des noirs vers les rouges, avec les majuscules pour les rouges et les minuscules pour les noirs.