chess_z

# chess_z chess_z는 C 언어로 구현된 중국 장기 소프트웨어 프레임워크로, 현재는 규칙 코어와 AI 연결 경계에 중점을 두고 있습니다. ## 주요 특징 - **비트보드 표현**: 90칸 보드는 이중 `uint64_t` 비트보드로 표현되며, 각 진영의 각 기물 유형마다 독립적인 bitboard를 가집니다. - **메일박스 배열**: `board[90]` 메일박스 배열을 동기화하여 유지 관리하므로 규칙 생성과 디버깅이 용이합니다. - **완전한 규칙 지원**: 초기局面, FEN 읽기/쓰기, 수 두기, 합법 수 생성, 장군 감지 및 perft를 지원합니다. - **AI 어댑터 인터페이스**: `XqEngineAdapter`를 제공하여 이후 외부 장기 AI 탐색/평가 함수를 연결할 수 있습니다. - **내장 간단 엔진**: 매우 작은 기물 가치와 합법 수 기동성 평가 + negamax 탐색을 포함하며, 주로 프레임워크 스모크 테스트에 사용됩니다. ## 디렉터리 구조 ```text include/xiangqi/bitboard.h 비트보드 기본 연산 include/xiangqi/types.h 기본 유형, 기물, 수 include/xiangqi/position.h 局面 표현, FEN, 수 두기 include/xiangqi/movegen.h 유사 합법/합법 수, 장군 감지, perft include/xiangqi/engine.h AI 엔진 어댑터 인터페이스 src/ 핵심 구현 examples/cli.c 예제 명령줄 진입점 stats/generate_positions.c 무작위 합법局面 생성 진입점 stats/search_positions.c 일괄局面 탐색 진입점 stats/random_fen/ 무작위局面 FEN 데이터 stats/data/ 성능 분석 결과 tests/test_core.c 기본 규칙 테스트 ``` ## 빌드 CMake 사용을 권장합니다: ```sh cmake -S . -B build cmake --build build ctest --test-dir build ``` 로컬에 GCC만 있다면 직접 테스트를 컴파일할 수도 있습니다: ```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 ``` 대화형 인간 대 기계 예제 컴파일: ```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 ``` 예제 진입점의 기본 설정은 "당신이 홍方을, 내장 간단 엔진이 흑方을 맡는" 것입니다. 입력 형식은 `시작점+도착점`이며, 파일은 `a..i`, 행 번호는 `0..9`를 사용합니다. 예: ```text b2b9 ``` 사용 가능한 명령: ```text moves 현재 모든 합법 수 출력 fen 현재 FEN 출력 help 도움말 출력 quit 종료 ``` ## 무작위局面 생성과 일괄 탐색 빌드 후 먼저 재현 가능한 무작위 합법局面 세트를 생성한 다음, 내장 엔진이 하나씩 탐색하도록 할 수 있습니다: ```sh ./build/xiangqi_generate_positions ./build/xiangqi_search_positions ``` 두 프로그램은 기본적으로 `stats/random_fen/random_positions.fen`을 사용하며, 둘 다 동일한 파일 경로를 지정할 수도 있습니다: ```sh ./build/xiangqi_generate_positions build/profile_positions.fen ./build/xiangqi_search_positions build/profile_positions.fen ``` 생성기는 고정 무작위 시드를 사용하여 초기局面에서 `0..100`보를 무작위로 두어 총 100개의局面을 출력하며, 각 줄에 FEN 하나씩 기록합니다. 탐색 프로그램은 파일을 순차적으로 한 번 읽고, 최대 깊이 6, 시간 제한 없음 설정으로 각局面에 대해 한 수를 탐색하므로 성능 분석을 위한 비대화형 진입점으로 적합합니다. ## AI 연결 외부 AI는 규칙 계층을 직접 재사용할 수 있습니다: ```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]); /* next에서 탐색 또는 평가 수행 */ } ``` `XqEngineAdapter`를 통해 사용자 정의 탐색을 연결할 수도 있습니다: ```c static bool my_search(const XqPosition *pos, unsigned depth, XqMove *best, void *user) { (void)user; /* 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); ``` ## 좌표 규약 - `file` 범위는 `0..8`, `rank` 범위는 `0..9`입니다. - 홍方의 최하단 행은 `rank = 0`, 흑方의 최하단 행은 `rank = 9`입니다. - `xq_square_make(file, rank)`는 좌표를 `rank * 9 + file`로 매핑합니다. - FEN은 흑方부터 홍方까지 10행으로 작성하며, 대문자는 홍方, 소문자는 흑方을 나타냅니다.