Xiangqi Lab

A fully local Xiangqi desktop app

---

Features

• 100% Local & Private — No internet required, no accounts, no data collection. Everything (AI + saved games) runs and stays on your computer.
• Fully Open Source — Licensed under AGPL-3.0 with an additional clause prohibiting use of the code for training AI models.
• Extremely Lightweight — Built with Python and only the built-in Tkinter GUI library.
• Cross-Platform — Works on Windows, macOS, and Linux.
• Multiple Play Modes (requires external engine):
  • Player vs AI
  • AI vs AI
  • AI move suggestions
• Easy Navigation — Easily switch between the main line and AI-generated variations.
• Powerful Game Editor — Create and edit your own scenarios.
• Compatible with strong engines — Supports Fairy-Stockfish and Pikafish (you must download the engine + neural network separately).

Xiangqi Lab is designed for study, practice, and experimentation. It is not intended for cheating in online games. Please respect fair play.

---

Screenshots

Xiangqi Lab is multilingual:

English • Simplified Chinese • Traditional Chinese • Vietnamese • Malay

Main Interface

English	Simplified Chinese

Game Editor

English	Simplified Chinese

AI Analysis (with external engine)

English	Simplified Chinese

---

Install Xiangqi Lab

Prerequisites

• Python 3.13 (or higher) with Tkinter

Windows

Recommended (easiest):

Alternative (advanced): Install from source.

• Install Python with Tkinter
• Install Git
• Install Xiangqi Lab from source and Launch

  git clone https://gitlab.com/xiangqilab/xiangqilab.git
  cd xiangqilab
  ./install.bat
  ./run.bat
  

MacOS

• Install Homebrew first
• Install Python with Tkinter

  brew install python-tk
  

• Install Xiangqi Lab from source and Launch

  git clone https://gitlab.com/xiangqilab/xiangqilab.git
  cd xiangqilab
  ./install.sh
  ./run.sh
  

Ubuntu

Arch Linux

• Install Xiangqi Lab from AUR and Launch

  paru -S xiangqilab  # or use "yay"
  xiangqilab
  

Other Linux Distributions

• Install Xiangqi Lab from source and Launch

  git clone https://gitlab.com/xiangqilab/xiangqilab.git
  cd xiangqilab
  ./install.sh
  ./run.sh
  

---

Engine Setup (One-time only)

Xiangqi Lab requires a separate Xiangqi engine. We recommend Fairy-Stockfish or Pikafish.

1. Download an Engine

• Fairy-Stockfish
  • Fairy-Stockfish Xiangqi releases
• Pikafish
  • Pikafish Releases

2. Launch Xiangqi Lab
3. Open AI Settings
   • Click the "AI Settings" button in the main window.
4. Configure Paths
   • AI Engine: Select the downloaded engine executable
   • Neural Network: Select the .nnue file
5. Test the Engine
   • Click the "Test Engine" button
6. Save the Settings
   • Press the "Save" button.

---

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-or-later).

Additional restriction: Use of this project's source code for training any AI or machine learning models is strictly prohibited.

See the LICENSE file for full details.

---

Contributing

Contributions are welcome! Feel free to:

• Open issues for bugs or feature requests
• Submit pull requests
• Provide ideas

---

Enjoy playing Xiangqi!