Research Report on the History of Computer Chinese Chess (Xiangqi) Game-Playing

Chapter 6: Getting Started Guide for Xiangqi Engine Development

6.1 Setting Up the Development Environment

Tools needed for developing a Xiangqi engine:

Compilers:

• Windows: MSVC (Visual Studio), MinGW GCC
• Linux/macOS: GCC, Clang

Development tools:

• Text editor or IDE (VS Code, CLion, etc.)
• Git version control tool
• CMake build system (optional)

Debugging tools:

• GDB (Unix) or WinDbg (Windows)
• Performance analysis tools (perf, Valgrind, etc.)

Testing tools:

• UCCI debugger
• Automated game tools (Binghe Wusi, etc.)

6.2 Development Roadmap

Recommended roadmap for developing a Xiangqi engine from scratch:

Step 1 (1-2 weeks): Implement position representation

• Design board data structure
• Implement FEN parsing and generation
• Implement move representation

Step 2 (2-3 weeks): Implement move generation

• Implement move generation for all 7 piece types
• Implement move legality checking
• Implement general facing check

Step 3 (2-3 weeks): Implement evaluation function

• Implement basic material value evaluation
• Implement positional value tables
• Implement simple piece activity evaluation

Step 4 (3-4 weeks): Implement search algorithm

• Implement Alpha-Beta search
• Implement iterative deepening
• Implement Zobrist hashing and transposition table

Step 5 (2-3 weeks): Implement UCCI protocol

• Implement basic UCCI protocol commands
• Test protocol implementation using UCCI debugger

Step 6 (1-2 weeks): Performance optimization

• Identify bottlenecks using performance analysis tools
• Optimize move generation and evaluation function
• Introduce simple pruning techniques

Step 7 (ongoing): Strength improvement

• Introduce advanced pruning such as null-move pruning, LMR, etc.
• Optimize evaluation function
• Introduce multi-threaded parallel search

6.3 Frequently Asked Questions

Q: What level of programming skill is needed for Xiangqi engine development? A: Basic knowledge of C/C++ (pointers, data structures, algorithms), and the ability to implement a moderately complex program.

Q: Can I develop an engine without basic Xiangqi knowledge? A: Yes, you can develop the engine, but designing the evaluation function requires some Xiangqi knowledge.

Q: How long does it take for an engine to reach a certain strength level? A: With full-time development, about 3-6 months to achieve an amateur beginner-level engine. Reaching professional level requires more time and continuous optimization.

Chapter 7: Reliability Engineering for Xiangqi Engines

7.1 Test Coverage and Regression Testing

Reliability assurance for Xiangqi engines:

Unit testing: Test the basic functionality of each module (position representation, move generation, evaluation function, etc.)

Integration testing: Test inter-module collaboration (search+evaluation, UCCI+search, etc.)

Regression testing: Use standard test suites to verify that each code modification does not introduce new problems

7.2 Failure Recovery Mechanisms

Xiangqi engine failure recovery:

Time overflow protection: Set a maximum time limit for search; if search does not complete within the time limit, return the current best move.

Memory overflow protection: Set a maximum memory limit for the transposition table to prevent the engine from consuming excessive system resources.

UCCI protocol exception handling: When an exception occurs in UCCI protocol communication, the engine should handle it gracefully and recover.

7.3 Logging and Monitoring

Xiangqi engine logging and monitoring:

Search log: Record key metrics for each search (search depth, node count, NPS, etc.)

Evaluation log: Record detailed information for each evaluation (evaluation value, feature values, etc.)

Error log: Record errors and exceptions during engine operation

Performance monitoring: Record performance indicators such as CPU usage and memory consumption

Chapter 8: Xiangqi Engine Development Community Guide

8.1 How to Participate in Open Source Engine Development

Process for participating in the development of open source engines like Pikafish:

1. Read project documentation: Understand the project’s goals, architecture, and development process
2. Set up the development environment: Clone the code, compile and run, familiarize yourself with the code structure
3. Start with small tasks: Fix simple bugs, add small features
4. Submit Pull Requests: Follow the project’s code standards and review process
5. Participate in community discussions: Engage in technical discussions on Issues and forums

8.2 Standards for Contributing Code

Standards to follow when contributing code:

Code style: Follow the project’s existing code style (indentation, naming, comments, etc.)

Commit messages: Write clear, meaningful commit messages

Testing requirements: Code modifications must pass all existing tests

Documentation updates: Update relevant documentation when necessary

8.3 Community Collaboration Tools

Collaboration tools used by the Xiangqi engine community:

GitHub: Code hosting, Issue tracking, Pull Request review

Fishtest: Distributed testing platform

Discord/QQ groups: Real-time communication

Forums: Long-form discussion and technical sharing

Chapter 9: Known Technical Puzzles of Xiangqi Engines

9.1 Puzzles in the Shoutan Dahui (Hand-Talk Competition) Series

There are some unsolved technical puzzles in the Xiangqi engine community:

Evaluation of certain special positions: In certain special cyclic move positions, different engines’ evaluation results vary significantly.

Boundary cases of perpetual check and perpetual chase: In extremely complex cyclic move positions, engine rule implementations may diverge.

Depth of sacrificial attacks: In certain complex sacrificial attack variations, the best moves found by different engines may be completely different.

9.2 Sources of Strength Differences Between Engines

Main sources of strength differences between different Xiangqi engines:

Evaluation function precision: NNUE evaluation vs. hand-crafted evaluation, and the quality and quantity of NNUE training data

Search efficiency: The aggressiveness of pruning strategies and the quality of move ordering

Parallel scalability: Efficiency of multi-threaded and distributed search

Opening book quality: The coverage and data accuracy of opening books

Completeness of rule implementation: The completeness of cyclic move rules and other special rule implementations

Chapter 10: Obtaining Xiangqi Engine Resources

10.1 Obtaining Open Source Engines

Channels for obtaining Xiangqi open source engines:

Pikafish:

• GitHub: github.com/official-pikafish/Pikafish
• Official website: pikafish.com
• Official forum: bbs.pikafish.org

ElephantEye:

• Website: xqbase.com
• GitHub: github.com/xqbase/eleeye

Orange:

• GitHub: github.com/danieltan1517/orange-xiangqi

10.2 Obtaining Cloud Book Resources

Methods for accessing Xiangqi cloud books:

Online query:

• Website: chessdb.cn
• API: Provides HTTP-based REST API

Client integration:

• Binghe Wusi: Built-in cloud book client
• UCCI engines: Some engines have built-in cloud book clients

10.3 Obtaining Game Resources

Channels for accessing Xiangqi game databases:

Online game databases:

• Xiangqi Yellow Pages (dpxq.com)
• China Xiangqi Master Network game library
• Dongping Xiangqi Network game library

Open source game datasets:

• Test game collections in the Pikafish project
• Public data provided by the cloud book