Skip to content

Commit 94ce9a5

Browse files
ianfabianfab
committed
Merge remote-tracking branch 'fairy/master' into tools
2 parents cc2139d + 7f7eac1 commit 94ce9a5

24 files changed

+622
-479
lines changed

‎.gitattributes‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
README.md merge=ours

‎.github/copilot-instructions.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# Fairy-Stockfish Development Guide
2+
3+
## Repository Overview
4+
5+
**Fairy-Stockfish** is a chess variant engine derived from Stockfish, designed to support numerous chess variants and protocols. Written primarily in C++17, it includes Python and JavaScript bindings for library use.
6+
7+
**Repository Statistics:**
8+
- **Languages:** C++17 (primary), Python, JavaScript, Shell scripts
9+
- **Architecture:** Multi-protocol chess engine (UCI, UCCI, USI, XBoard/CECP)
10+
- **Target Platforms:** Windows, Linux, macOS, Android, WebAssembly
11+
- **Supported Variants:** 90+ chess variants including regional, historical, and modern variants
12+
13+
## Build System & Requirements
14+
15+
### Prerequisites
16+
- **Compiler:** GCC, Clang, or MSVC with C++17 support
17+
- **Build Tool:** GNU Make (required for C++ engine)
18+
- **Python:** 3.7+ (for Python bindings)
19+
- **Node.js:** (for JavaScript bindings)
20+
- **Additional Tools:** expect utility (for testing)
21+
22+
### Core Build Process
23+
24+
Note: Run engine and test commands from the `src/` directory unless specified otherwise.
25+
26+
#### Basic Build Commands
27+
```bash
28+
# Standard release build (recommended for most users)
29+
make -j2 ARCH=x86-64 build
30+
31+
# Debug build (for development)
32+
make -j2 ARCH=x86-64 debug=yes build
33+
34+
# All variants including ones with large boards (up to 12x10) and large branching factor (all)
35+
make -j2 ARCH=x86-64 largeboards=yes all=yes build
36+
```
37+
38+
### Python Bindings (pyffish)
39+
```bash
40+
# Build Python bindings (from repository root)
41+
python3 setup.py install
42+
43+
# Alternative: Install from PyPI
44+
pip install pyffish
45+
```
46+
47+
### JavaScript Bindings (ffish.js)
48+
Also see the `tests/js/README.md`.
49+
```bash
50+
cd src/
51+
52+
# Build JavaScript bindings (requires emscripten)
53+
make -f Makefile_js build
54+
55+
# Alternative: Install from npm
56+
npm install ffish
57+
```
58+
59+
## Testing & Validation
60+
61+
All test commands below assume the current directory is `src/`.
62+
63+
### Core Engine Tests
64+
```bash
65+
# Basic functionality test
66+
./stockfish bench
67+
68+
# Variant-specific benchmarks
69+
./stockfish bench xiangqi
70+
./stockfish bench shogi
71+
./stockfish bench capablanca
72+
73+
# Validate variants configuration
74+
./stockfish check variants.ini
75+
```
76+
77+
### Comprehensive Test Suite
78+
```bash
79+
# Protocol compliance tests
80+
../tests/protocol.sh
81+
82+
# Move generation validation
83+
../tests/perft.sh all
84+
../tests/perft.sh chess # Chess only
85+
../tests/perft.sh largeboard # Large board variants only
86+
87+
# Regression testing
88+
../tests/regression.sh
89+
90+
# Reproducible search test
91+
../tests/reprosearch.sh
92+
93+
# Build signature verification
94+
../tests/signature.sh
95+
```
96+
97+
98+
## Project Architecture
99+
100+
### Directory Structure
101+
```
102+
src/ # Core C++ engine source
103+
tests/ # Test scripts and data
104+
.github/workflows/ # CI/CD configurations
105+
```
106+
107+
### Configuration Files
108+
- **`src/variants.ini`**: Defines examples for configuration of chess variants
109+
- **`setup.py`**: Python package build configuration
110+
- **`tests/js/package.json`**: JavaScript bindings configuration
111+
112+
### Key Source Files in `src/`
113+
- **`variant.h`**: Variant rule properties
114+
- **`variant.cpp`**: Variant-specific game rules
115+
- **`variant.ini`**: Variant rule configuration examples and documentation of variant properties
116+
- **`position.h`**: Position representation
117+
- **`position.cpp`**: Board logic
118+
- **`movegen.cpp`**: Move generation logic
119+
- **`parser.cpp`**: Variant rule configuration parsing
120+
- **`piece.cpp`**: Piece type definitions and behavior
121+
- **`pyffish.cpp`**: Python bindings
122+
- **`ffishjs.cpp`**: JavaScript bindings
123+
124+
## Continuous Integration
125+
126+
### GitHub Actions Workflows
127+
- **`fairy.yml`**: Core engine testing (perft, protocols, variants)
128+
- **`stockfish.yml`**: Standard Stockfish compatibility tests
129+
- **`release.yml`**: Binary releases for multiple platforms
130+
- **`wheels.yml`**: Python package builds
131+
- **`ffishjs.yml`**: JavaScript binding builds
132+
133+
## Common Development Patterns
134+
135+
### Making Engine Changes
136+
1. **Always test basic functionality:** `./stockfish bench` after changes
137+
2. **Validate variant compatibility:** `./stockfish check variants.ini`
138+
3. **Run relevant tests:** `../tests/perft.sh all` for move generation changes
139+
140+
### Adding New Configurable Variants
141+
1. **Edit `src/variants.ini`**: Add variant configuration
142+
2. **Test parsing:** `./stockfish check variants.ini`
143+
144+
### Relevant websites for researching chess variant rules
145+
- [Chess Variants on Wikipedia](https://en.wikipedia.org/wiki/List_of_chess_variants)
146+
- [Chess Variants Wiki](https://www.chessvariants.com/)
147+
- [Variant Chess on BoardGameGeek](https://boardgamegeek.com/boardgamefamily/4024/traditional-games-chess)
148+
- [PyChess Variants](https://www.pychess.org/variants)
149+
- [Ludii](https://ludii.games/library.php)
150+
- [Lichess.org Variants](https://lichess.org/variant)
151+
- [Greenchess](https://greenchess.net/variants.php)
152+
- [Chess Variants on Chess.com](https://www.chess.com/variants)
153+
154+
### Development Best Practices
155+
* Make sure to only stage and commit changes that were changed as part of the task, do not simply add all changes.
156+
* Keep changes minimal and focused on the task at hand.
157+
* After applying changes make sure that all places related to the task have been identified.
158+
* Stay consistent with the existing code style and conventions.

‎.github/workflows/ffishjs.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ jobs:
3131
version: ${{env.EM_VERSION}}
3232
actions-cache-folder: ${{env.EM_CACHE_FOLDER}}
3333
- name: Use Node.js ${{ matrix.node-version }}
34-
uses: actions/setup-node@v4
34+
uses: actions/setup-node@v5
3535
with:
3636
node-version: ${{ matrix.node-version }}
3737
- name: Build ffishjs
@@ -65,7 +65,7 @@ jobs:
6565
version: ${{env.EM_VERSION}}
6666
actions-cache-folder: ${{env.EM_CACHE_FOLDER}}
6767
- name: Use Node.js ${{ matrix.node-version }}
68-
uses: actions/setup-node@v4
68+
uses: actions/setup-node@v5
6969
with:
7070
node-version: ${{ matrix.node-version }}
7171
- name: Build ffish.js ES6/ES2015 module

‎.github/workflows/wheels.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,13 +14,13 @@ jobs:
1414
runs-on: ${{ matrix.os }}
1515
strategy:
1616
matrix:
17-
os: [ubuntu-24.04, windows-2019, macos-13]
17+
os: [ubuntu-24.04, windows-2022, macos-13]
1818

1919
steps:
2020
- uses: actions/checkout@v5
2121

2222
# Used to host cibuildwheel
23-
- uses: actions/setup-python@v5
23+
- uses: actions/setup-python@v6
2424

2525
- name: Install cibuildwheel
2626
run: python -m pip install cibuildwheel==2.22.0
@@ -44,7 +44,7 @@ jobs:
4444
runs-on: ubuntu-24.04
4545
steps:
4646
- uses: actions/checkout@v5
47-
- uses: actions/setup-python@v5
47+
- uses: actions/setup-python@v6
4848
with:
4949
python-version: '3.9'
5050

‎.gitignore‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
# Ignore binaries in src/ that have no extension
2+
/src/*
3+
!/src/*.*
4+
!/src/*/
5+
16
# Files from build
27
**/*.o
38
**/*.s
@@ -24,6 +29,14 @@ ffish.js
2429
venv
2530
*.so
2631
pyffish.egg-info
32+
__pycache__
33+
*.pyc
34+
35+
# test artifacts
36+
tests/*.exp
37+
src/*.log
38+
src/*.epd
39+
src/*.txt
2740

2841
# IDEs
2942
.vscode

0 commit comments

Comments
 (0)