chess_z

# chess_z chess_z é uma estrutura de software de xadrez chinês implementada em C, com foco atual no núcleo de regras e na fronteira de integração de IA. ## Principais características - **Representação por bitboards**: o tabuleiro de 90 casas usa bitboards duplos `uint64_t`, com um bitboard independente para cada tipo de peça de cada lado. - **Array de mailbox**: mantém de forma sincronizada o array `board[90]`, facilitando a geração de regras e a depuração. - **Suporte completo às regras**: suporta posição inicial, leitura/escrita de FEN, execução de movimentos, geração de movimentos legais, detecção de xeque e perft. - **Interface de adaptação de IA**: fornece `XqEngineAdapter`, permitindo conectar posteriormente funções externas de busca/avaliação de xadrez. - **Motor simples embutido**: inclui uma avaliação pequena baseada em material e mobilidade de movimentos legais + busca negamax, usada principalmente para testes de fumaça da estrutura. ## Estrutura de diretórios ```text include/xiangqi/bitboard.h operações básicas de bitboard include/xiangqi/types.h tipos básicos, peças, movimentos include/xiangqi/position.h representação de posição, FEN, execução de movimentos include/xiangqi/movegen.h movimentos pseudo-legais/legais, detecção de xeque, perft include/xiangqi/engine.h interface de adaptação do motor de IA src/ implementação principal examples/cli.c exemplo de entrada por linha de comando stats/generate_positions.c entrada para geração de posições legais aleatórias stats/search_positions.c entrada para busca em lote de posições stats/random_fen/ dados FEN de posições aleatórias stats/data/ resultados de análise de desempenho tests/test_core.c testes básicos de regras ``` ## Compilação Recomenda-se usar CMake: ```sh cmake -S . -B build cmake --build build ctest --test-dir build ``` Se a máquina tiver apenas GCC, também é possível compilar os testes diretamente: ```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 ``` Compilar o exemplo interativo humano-máquina: ```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 ``` O exemplo padrão é "você joga com as vermelhas, o motor simples embutido joga com as pretas". O formato de entrada é `origem+destino`, com colunas `a..i` e linhas `0..9`, por exemplo: ```text b2b9 ``` Comandos disponíveis: ```text moves imprime todos os movimentos legais atuais fen imprime o FEN atual help imprime ajuda quit sai ``` ## Geração de posições aleatórias e busca em lote Após a compilação, é possível primeiro gerar um conjunto reproduzível de posições legais aleatórias e, em seguida, fazer o motor embutido buscar uma a uma: ```sh ./build/xiangqi_generate_positions ./build/xiangqi_search_positions ``` Os dois programas usam por padrão `stats/random_fen/random_positions.fen`, mas também é possível especificar o mesmo caminho de arquivo para ambos: ```sh ./build/xiangqi_generate_positions build/profile_positions.fen ./build/xiangqi_search_positions build/profile_positions.fen ``` O gerador usa uma semente aleatória fixa, faz movimentos aleatórios de `0..100` passos a partir da posição inicial e produz 100 posições, uma FEN por linha. O programa de busca lê o arquivo uma vez em sequência e busca um movimento para cada posição com profundidade máxima 6 e sem limite de tempo, sendo adequado como entrada não interativa para análise de desempenho. ## Integração de IA Uma IA externa pode reutilizar diretamente a camada de regras: ```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]); /* fazer busca ou avaliação em next */ } ``` Também é possível conectar uma busca personalizada por meio de `XqEngineAdapter`: ```c static bool my_search(const XqPosition *pos, unsigned depth, XqMove *best, void *user) { (void)user; /* use xq_generate_legal / xq_position_make_move para implementar sua própria busca */ 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); ``` ## Convenções de coordenadas - `file` varia de `0..8`, `rank` varia de `0..9`. - A linha de fundo das vermelhas é `rank = 0`, a linha de fundo das pretas é `rank = 9`. - `xq_square_make(file, rank)` mapeia as coordenadas para `rank * 9 + file`. - A FEN é escrita em 10 linhas, das pretas para as vermelhas, usando maiúsculas para as vermelhas e minúsculas para as pretas.