chess_z

# chess_z chess_z is a Chinese chess software framework implemented in C, currently focused on the rules core and AI integration boundaries. ## Main Features - **Bitboard representation**: The 90-square board is represented using dual `uint64_t` bitboards, with independent bitboards for each piece type on each side. - **Mailbox array**: A `board[90]` mailbox array is maintained synchronously for convenient rule generation and debugging. - **Complete rule support**: Supports the initial position, FEN reading and writing, making moves, legal move generation, check detection, and perft. - **AI adapter interface**: Provides `XqEngineAdapter`, allowing external Chinese chess AI search/evaluation functions to be integrated later. - **Built-in simple engine**: Includes a very small material and legal-move mobility evaluation plus negamax search, mainly used for framework smoke testing. ## Directory Structure ```text include/xiangqi/bitboard.h Basic bitboard operations include/xiangqi/types.h Basic types, pieces, moves include/xiangqi/position.h Position representation, FEN, making moves include/xiangqi/movegen.h Pseudo-legal/legal moves, check detection, perft include/xiangqi/engine.h AI engine adapter interface src/ Core implementation examples/cli.c Example command-line entry point stats/generate_positions.c Random legal position generation entry point stats/search_positions.c Batch position search entry point stats/random_fen/ Random position FEN data stats/data/ Performance analysis results tests/test_core.c Basic rules tests ``` ## Building CMake is recommended: ```sh cmake -S . -B build cmake --build build ctest --test-dir build ``` If only GCC is available locally, the tests can also be compiled directly: ```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 ``` Compile the interactive human-vs-engine example: ```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 ``` The example entry point defaults to "you play red, and the built-in simple engine plays black." The input format is `start square + end square`, with files using `a..i` and ranks using `0..9`, for example: ```text b2b9 ``` Available commands: ```text moves Print all current legal moves fen Print the current FEN help Print help quit Exit ``` ## Random Position Generation and Batch Search After building, you can first generate a reproducible set of random legal positions and then have the built-in engine search them one by one: ```sh ./build/xiangqi_generate_positions ./build/xiangqi_search_positions ``` Both programs use `stats/random_fen/random_positions.fen` by default, and the same file path can also be specified for both: ```sh ./build/xiangqi_generate_positions build/profile_positions.fen ./build/xiangqi_search_positions build/profile_positions.fen ``` The generator uses a fixed random seed, makes random moves from the initial position for `0..100` plies, and outputs 100 positions, one FEN per line. The search program reads the file once sequentially and searches one move for each position with a maximum depth of 6 and no time limit, making it suitable as a non-interactive entry point for performance analysis. ## AI Integration External AI can directly reuse the rules layer: ```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]); /* Perform search or evaluation on next */ } ``` Custom search can also be integrated through `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 to implement your own search */ 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); ``` ## Coordinate Conventions - `file` ranges from `0..8`, and `rank` ranges from `0..9`. - Red's back rank is `rank = 0`, and Black's back rank is `rank = 9`. - `xq_square_make(file, rank)` maps coordinates to `rank * 9 + file`. - FEN is written as 10 rows from Black to Red, using uppercase for Red pieces and lowercase for Black pieces.