Metadata-Version: 2.4
Name: xiangqilab
Version: 1.2.0
Summary: A fully local Xiangqi desktop app
Author-email: "Dongsheng \"Homer\" Xing" <homer.hsing@gmail.com>
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://gitlab.com/xiangqilab/xiangqilab
Keywords: xiangqi,chinese-chess
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: End Users/Desktop
Classifier: Topic :: Games/Entertainment :: Board Games
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Xiangqi Lab

[![Python](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-AGPL--3.0-orange.svg)](LICENSE)

**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 |
|---------|--------------------|
| <img src="screenshots/macos/en_US/main.png" height="300" alt="Main Interface (EN)"> | <img src="screenshots/macos/zh_CN/main.png" height="300" alt="Main Interface (zh_CN)"> |

### Game Editor

| English | Simplified Chinese |
|---------|--------------------|
| <img src="screenshots/macos/en_US/editor.png" height="300" alt="Game Editor - Initial Position (EN)"> | <img src="screenshots/macos/zh_CN/editor.png" height="300" alt="Game Editor - Initial Position (zh_CN)"> |

### AI Analysis (with external engine)
| English | Simplified Chinese |
|---------|--------------------|
| <img src="screenshots/macos/en_US/ai.png" height="300" alt="AI Analyzer (EN)"> | <img src="screenshots/macos/zh_CN/ai.png" height="300" alt="AI Analyzer (zh_CN)"> |

---

## Install Xiangqi Lab

### Prerequisites

- Python 3.13 (or higher) with Tkinter

### Windows

**Recommended (easiest):**

<a href="https://get.microsoft.com/installer/download/9p7dfbskpqb4?referrer=appbadge" target="_self" >
	<img src="https://get.microsoft.com/images/en-us%20dark.svg" width="200"/>
</a>

**Alternative (advanced):** Install from source.

- Install Python with Tkinter
- Install Git
- Install Xiangqi Lab from source and Launch
  ```bash
  git clone https://gitlab.com/xiangqilab/xiangqilab.git
  cd xiangqilab
  ./install.bat
  ./run.bat
  ```

### MacOS

- Install [Homebrew](https://brew.sh/) first
- Install Python with Tkinter
  ```bash
  brew install python-tk
  ```
- Install Xiangqi Lab from source and Launch
  ```bash
  git clone https://gitlab.com/xiangqilab/xiangqilab.git
  cd xiangqilab
  ./install.sh
  ./run.sh
  ```

### Ubuntu

[![Xiangqi Lab is on Snap Store](https://snapcraft.io/en/dark/install.svg)](https://snapcraft.io/xiangqilab)

### Arch Linux

- Install Xiangqi Lab from AUR and Launch
  ```bash
  paru -S xiangqilab  # or use "yay"
  xiangqilab
  ```

### Other Linux Distributions

- Install Xiangqi Lab from source and Launch
  ```bash
  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](https://github.com/fairy-stockfish/Fairy-Stockfish-NNUE/releases)
  - **Pikafish**
    - [Pikafish Releases](https://github.com/official-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](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!
