🌟 Overview
A comprehensive Xiangqi platform featuring AI gameplay, board recognition, and extensive puzzle libraries. Built with modern web technologies and fully functional offline.
Key Highlights:
- 🤖 Local AI engine powered by Pikafish
- 📸 Open-source board recognition system (physical boards + screenshots)
- 📚 7,300+ puzzles covering openings, endgames, and classical positions
- 📱 Complete offline support via PWA
- ⚖️ Intelligent rule enforcement (checkmate, stalemate, perpetual check/chase detection)
Features
Game Modes
- ♟️ Two-Player Mode - Local or online play
- 🤖 AI Opponent - Multiple difficulty levels (PC & Android)
- ⏱️ Chess Clock - Tournament-style time controls
- 🧠 Game Review - Deep AI analysis of completed games (PC only)
- 📊 Position Analysis - Real-time move suggestions (PC & Android)
- 📚 Puzzle Library - 7,300+ curated positions:
- Opening patterns (~200 puzzles)
- Classical endgames (366 puzzles)
- Complex tactical positions (183 puzzles)
- Fundamental checkmate patterns
- Historical game studies
Board Recognition System
Industry-first open-source implementation for Xiangqi board recognition.
Two Recognition Modes
1. Physical Board Recognition
- Supports wooden, paper, and various physical boards
- Automatic perspective correction (handles camera angles)
- Intelligent coordinate mapping
- Best results with light-colored pieces
2. Digital Screenshot Recognition
- Optimized for digital board interfaces
- Dual-model architecture: Detection + Classification
- Automatic side (red/black) identification
- No perspective correction needed
Model Files
| Model |
Purpose |
File |
| Online Detection |
Locate piece positions |
online_xiangqi_piece_detector.onnx |
| Online Classification |
Identify piece types |
online_xiangqi_classifier.onnx |
| Physical Board |
Unified physical board recognition |
Entity_chess_recognition_model.onnx |
Usage Example
const recognizer = new ChessRecognizer();
recognizer.uploadImage(imageFile);
recognizer.markCorners([topLeft, topRight, bottomRight, bottomLeft]);
recognizer.markCenterPawn(centerPosition);
const fenCode = await recognizer.recognize();
console.log(fenCode);
💡 See source code for detailed API documentation
Intelligent Rule System
Automatic detection of:
- ✅ Checkmate and stalemate
- ✅ Draw by insufficient material
- ✅ Draw by repetition
- ✅ Perpetual check/chase detection
- 📜 Based on ROC Xiangqi Rules (2024 revision)
Most positions are correctly adjudicated automatically. In edge cases, players should apply official rules manually.
Utilities
- 🔄 Undo Move - Take back moves
- 💾 Save/Load Positions - Store and retrieve games
- ⚙️ Position Editor - Create custom legal positions
- 🎨 Customization - 5 board themes + 5 piece styles
| Feature |
PC (Win/Mac/Linux) |
Android |
iOS |
| Two-Player |
✅ |
✅ |
✅ |
| Chess Clock |
✅ |
✅ |
✅ |
| AI Opponent |
✅ |
✅ |
❌* |
| AI Analysis |
✅ |
✅ |
❌* |
| Game Review |
✅ |
❌** |
❌* |
| Board Recognition |
✅ |
✅ |
✅ |
* iOS: WebAssembly local computation limitations
** Mobile: Insufficient CPU for deep analysis
Quick Start
Online Play
Visit: https://android-xiangqi-offline.netlify.app/
Local Development
# Clone repository
git clone https://github.com/dffge552/xiangqi-pwa-offline.git
# Navigate to directory
cd xiangqi-pwa-offline
# Install dependencies (if applicable)
npm install
# Start development server
npm start
Requirements: Modern browser (Chrome 90+, Firefox 88+, Safari 14+)
Technical Stack
- Frontend: Vanilla JavaScript (ES6+), HTML5, CSS3
- AI Engine: Pikafish (WebAssembly)
- Computer Vision: ONNX Runtime (custom-trained models)
- PWA: Service Worker + Workbox
- Storage: LocalStorage / IndexedDB
AI Engine
Powered by Pikafish, an open-source Xiangqi engine:
- 🔓 Free and open source
- ⚡ Continuously updated with strong playing strength
- 🚀 Multi-threaded parallel computation
- 📖 Widely used in Xiangqi education
Resources:
Documentation
Project Motivation
Hi, I’m a high school sophomore who developed Xiangqi Arena initially as a school project, but mainly driven by my passion for Chinese Chess.
Existing Xiangqi software often suffers from either overly complex interfaces or lack of modern features. I combined my programming skills to create a platform that’s both professional and accessible.
The core mission is improving players’ skills through AI analysis, game review, and diverse practice modes. I hope to nurture talented Xiangqi players and bring honor to Taiwan’s Xiangqi community!
Contributing
Contributions are welcome!
How to Contribute
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature)
- Commit your changes (
git commit -m 'Add some AmazingFeature')
- Push to the branch (
git push origin feature/AmazingFeature)
- Open a Pull Request
Especially Welcome
- 🧠 AI Model Improvements - Enhance recognition accuracy
- 🌍 Internationalization - Translate interface text
- 🎨 UI/UX Enhancements - Improve user experience
- 📚 Puzzle Expansion - Add more practice positions
- 🐛 Bug Fixes - Report and fix issues
License
This project is licensed under the MIT License.
You are free to:
- ✅ Use commercially
- ✅ Modify
- ✅ Distribute
- ✅ Use privately
- ✅ Copy and integrate into other projects
Only requirement:
- ⭐ Attribution required
- 📄 Preserve copyright notice
Attribution Example
This project uses the board recognition system from "Xiangqi Arena"
Author: dffge552
Source: https://github.com/dffge552/xiangqi-pwa-offline
Other Projects
Acknowledgments
Puzzle Sources
Recommended Learning Resources
- 从寬象棋
- Additional resources available in-game
Star History
If this project helps you, please give it a ⭐ star!
Crafted with Care · Shared Openly · Growing Together
Made with ❤️ by dffge552
评论