chess_z

# chess_z chess_z هو إطار برمجي للشطرنج الصيني مطبق بلغة C، وينصب التركيز الحالي على نواة القواعد وحدود ربط الذكاء الاصطناعي. ## الميزات الرئيسية - **تمثيل لوحة البتات**: لوحة من 90 مربعًا ممثلة بلوحتي بتات `uint64_t` مزدوجتين، ولكل نوع قطعة من كل جانب bitboard مستقل. - **مصفوفة البريد**: صيانة متزامنة لمصفوفة البريد `board[90]` لتسهيل توليد القواعد والتصحيح. - **دعم كامل للقواعد**: يدعم الوضعية الابتدائية، قراءة وكتابة FEN، تنفيذ النقلات، توليد النقلات القانونية، كشف الكش، وperft. - **واجهة تكييف الذكاء الاصطناعي**: توفر `XqEngineAdapter`، ويمكن لاحقًا ربط دوال بحث/تقييم خارجية لشطرنج صيني. - **محرك مبسط مدمج**: يتضمن تقييمًا صغيرًا للمواد وحركية النقلات القانونية + بحث negamax، ويُستخدم أساسًا لاختبار دخان الإطار. ## هيكل المجلدات ```text include/xiangqi/bitboard.h عمليات لوحة البتات الأساسية include/xiangqi/types.h الأنواع الأساسية، القطع، النقلات include/xiangqi/position.h تمثيل الوضعية، FEN، تنفيذ النقلات include/xiangqi/movegen.h النقلات شبه القانونية/القانونية، كشف الكش، perft include/xiangqi/engine.h واجهة تكييف محرك الذكاء الاصطناعي 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 وبدون حد زمني، وهو مناسب كمدخل غير تفاعلي لتحليل الأداء. ## ربط الذكاء الاصطناعي يمكن للذكاء الاصطناعي الخارجي إعادة استخدام طبقة القواعد مباشرة: ```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 صفوف من الأسود إلى الأحمر، باستخدام الأحرف الكبيرة للأحمر والأحرف الصغيرة للأسود.