AnkiGammon

A graphical application for converting backgammon positions into Anki flashcards. Analyze positions from eXtreme Gammon, OpenGammon, or GNU Backgammon and create smart study cards.

Features

• Modern GUI interface - Easy-to-use graphical application with drag-and-drop support
• Multiple input formats - XGID/OGID/GNUID position IDs, XG binary files (.xg, .xgp), match files (.mat), SGF files
• Direct XG export support - Copy/paste pre-analyzed positions from eXtreme Gammon
• File import with filtering - Drag-and-drop files with error threshold and player selection
• Dual analysis engines - Analyze positions using GNU Backgammon (cross-platform) or eXtreme Gammon (Windows)
• Automatic format detection - Paste any supported format, the app detects it automatically
• Two export methods:
  • AnkiConnect: Push directly to Anki (recommended)
  • APKG: Self-contained package for manual import
• Customizable appearance - 7 color schemes, board orientation (including random), configurable MCQ options (2-10)
• Position management - Multi-select, add notes, preview positions before export
• Automatic update notifications - Get notified when new versions are available
• Comments extraction - Automatically imports comments and notes from XG files (.xg, .xgp)

Installation

Standalone Executable (Recommended)

Download pre-built executables from GitHub Releases:

Windows:

1. Download ankigammon-windows.zip from the latest release
2. Extract the ZIP file
3. Double-click ankigammon.exe
4. Windows SmartScreen Warning: Click "More info" → "Run anyway"
   • This warning appears because the app is not code-signed
   • The application is safe and open-source

macOS:

1. Download AnkiGammon-macOS.dmg from the latest release
2. Open the DMG file
3. Drag AnkiGammon to your Applications folder
4. First time only: Right-click AnkiGammon → Open
   • If blocked, go to System Settings → Privacy & Security
   • Scroll down and click "Open Anyway"
   • Enter your password when prompted
5. After first run, you can open AnkiGammon normally

Why do I see a security warning on macOS? AnkiGammon is not code-signed because that requires a $99/year Apple Developer account. The app is open-source and safe to use.

Linux:

1. Download AnkiGammon-x86_64.AppImage from the latest release
2. Make it executable:
   • Right-click → Properties → Permissions → "Allow executing file as program"
   • Or via terminal: chmod +x AnkiGammon-x86_64.AppImage
3. Double-click to run!

Note for Ubuntu 22.04+ users: If the AppImage doesn't run, install FUSE 2:

• Ubuntu 22.04: sudo apt install libfuse2
• Ubuntu 24.04: sudo apt install libfuse2t64

Install via pip

If you have Python 3.8+ installed:

pip install ankigammon
ankigammon  # Launch the GUI

Development Install

For developers who want to run from source:

git clone https://github.com/Deinonychus999/AnkiGammon.git
cd AnkiGammon
pip install -e .  # Install in editable mode
ankigammon  # Launches the GUI

Usage

1. Launch the application:
   • Windows: Double-click ankigammon.exe
   • macOS: Open AnkiGammon from Applications folder
   • Linux: Double-click AnkiGammon-x86_64.AppImage
   • From PyPI install: Run ankigammon in terminal
2. Add positions (choose one or more methods):
   • Paste XG analysis: Press Ctrl+N, paste pre-analyzed positions from eXtreme Gammon (Ctrl+C)
   • Paste position IDs: Press Ctrl+N, paste XGID/OGID/GNUID strings (requires GNU Backgammon for analysis)
   • Import files: Press Ctrl+O or drag-and-drop files (.xg, .xgp, .mat, .sgf, .txt)
     • For match files: Choose error threshold and which player's mistakes to import
3. Configure settings - Choose color scheme, board orientation, and export method (Ctrl+,)
4. Generate cards - Click "Generate Cards" (Ctrl+E) to create Anki flashcards

Keyboard Shortcuts

• Ctrl+N - Add positions
• Ctrl+O - Import file
• Ctrl+E - Export cards
• Ctrl+, - Settings
• Ctrl+Q - Quit
• Delete/Backspace - Remove selected positions

Position Analysis

Unanalyzed positions (position IDs, match files, SGF files) can be analyzed using one of two engines:

• GNU Backgammon — Open-source CLI tool, works on Windows/macOS/Linux
• eXtreme Gammon — Commercial software via UI automation, Windows only

Configure your preferred engine in Settings → Analysis (see Customization Options below).

Supported Formats

AnkiGammon supports multiple input formats with automatic detection:

XG Text Export (Pre-Analyzed)

Import pre-analyzed positions directly from eXtreme Gammon:

1. In eXtreme Gammon, analyze a position
2. Press Ctrl+C to copy the full analysis
3. Paste into AnkiGammon's input area

Position ID Formats (Unanalyzed)

Position IDs encode positions without move analysis. Configure GNU Backgammon in Settings to enable automatic analysis.

• XGID (eXtreme Gammon ID) - 26-character position string + metadata fields

  • Example: XGID=---BBBBAAA---Ac-bbccbAA-A-:1:1:-1:63:4:3:0:5:8

• OGID (OpenGammon Position ID) - Base-26 position encoding with colon-separated fields

  • Example: cccccggggg:ddddiiiiii:N0N:63:W:IW:4:3:7:1:15

• GNUID (GNU Backgammon ID) - Compact Base64 format (PositionID:MatchID)

  • Example: 4HPwATDgc/ABMA:8IhuACAACAAE

All formats fully support position encoding, cube state, dice, and match metadata.

File Formats

• XG Binary files (.xg, .xgp) - eXtreme Gammon match and position files (includes pre-analysis from XG)
• Match files (.mat, .txt) - GNU Backgammon match exports (requires GNU Backgammon for analysis)
• SGF files (.sgf) - Smart Game Format for backgammon (requires GNU Backgammon for analysis)

Import via Ctrl+O or drag-and-drop directly onto the window.

Format Detection

The application automatically detects which format you're using. Just paste your position and AnkiGammon will handle it:

• XGID: Detected by XGID= prefix
• OGID: Detected by base-26 pattern with colons
• GNUID: Detected by base64 pattern

You can mix formats in the same input - each position can use a different format!

Export Methods

AnkiConnect (Recommended)

Push cards directly to running Anki through the GUI:

• Install AnkiConnect addon
• Keep Anki running while generating cards
• Cards appear instantly in your deck

APKG

Generate a package file for manual import:

• Select "APKG" in Settings
• Import into Anki: File → Import → Select the .apkg file
• Useful for offline card generation

Regenerating Cards

Both export methods support updating existing cards when you change settings (color scheme, board orientation, etc.):

• Cards are matched by their XGID position identifier
• Re-exporting updates the card content while preserving your Anki review history
• Useful for applying new color schemes or enabling features like move score matrices

Card Format

Each position becomes one Anki card:

Front:

• Board image showing the position
• Metadata: player on roll, dice, score, cube, match length
• Multiple choice: Candidate moves (configurable 2-10, labeled A-J, shuffled)
• Optional text move descriptions

Back:

• Position image and metadata
• MCQ feedback showing if your answer was correct, close, or incorrect
• Ranked table of moves with equity, error, and winning chances
• Interactive move visualization - click any move to see the resulting position
• Cubeful/cubeless equity toggle
• Source position ID with copy button for easy sharing
• Source attribution (analysis source and ply level)
• Explanation (if added)
• Score matrix showing optimal cube actions across all match scores (if enabled)
• Move score matrix showing top moves at different match contexts (if enabled)

Customization Options

Open Settings with Ctrl+, to configure:

Appearance:

• Color Schemes: Choose from 7 built-in themes (Classic, Forest, Ocean, Desert, Sunset, Midnight, Monochrome)
• Board Orientation: Counter-clockwise (default), Clockwise, or Random (varies per card)
• Score Format: Display match scores as absolute (e.g., "3-2") or away (e.g., "4-away, 5-away")
• Show Pip Count: Toggle pip count display on the board
• Swap Checker Colors: Play as the other side by swapping checker colors

Card Options:

• Show Move Options: Toggle multiple-choice options on card front
• Move Preview: Preview the resulting position before submitting your answer
• Interactive Moves: Enable/disable animated move visualization on card back
• Number of MCQ Options: Configure how many moves to display (2-10, default: 5)

Export:

• Deck Name: Customize your Anki deck name
• Export Method: Choose between AnkiConnect or APKG output
• Use Subdecks: Split checker and cube decisions into separate subdecks
• Clear After Export: Automatically clear the position list after successful export

Analysis:

• Analysis Engine: Choose between GNU Backgammon (cross-platform) or eXtreme Gammon (Windows only)
• GNU Backgammon Path: Configure path to gnubg-cli executable
• Analysis Ply: Set GnuBG depth (0-4, default: 3)
• eXtreme Gammon Path: Configure path to eXtremeGammon2.exe (Windows only)
• XG Analysis Level: Set XG depth (Very Quick → Extensive, default: World Class)
• Score Matrix: Generate cube decision matrix for all match scores (optional, time-consuming)
• Move Score Matrix: Generate move analysis at different match contexts - Neutral, DMP, Gammon-Save, Gammon-Go (optional, time-consuming)

Troubleshooting

"Cannot connect to Anki-Connect"

• Install AnkiConnect addon: https://ankiweb.net/shared/info/2055492159
• Make sure Anki is running
• Check firewall isn't blocking localhost:8765

"No decisions found in input"

• Ensure input includes position ID lines (XGID, OGID, or GNUID format)
• Copy the full analyzed position from XG (press Ctrl+C)

Application won't start

• Windows: Click "More info" → "Run anyway" if SmartScreen blocks the app
• macOS: Right-click → Open on first run, or go to System Settings → Privacy & Security → "Open Anyway"
• Linux: Make the AppImage executable with chmod +x AnkiGammon-x86_64.AppImage
• Linux (Ubuntu 22.04+): Install FUSE 2 with sudo apt install libfuse2 or sudo apt install libfuse2t64 (Ubuntu 24.04)
• Linux (running from source): If you get ImportError: libxkbcommon.so.0, install Qt dependencies with sudo apt install libxkbcommon0 libxcb1

For Developers

Building the Executable

Quick Build:

Windows:

build_executable.bat

macOS/Linux:

chmod +x build_executable.sh
./build_executable.sh

The executable will be in the dist/ folder.

Manual Build (if script doesn't work):

Windows:

# Install PyInstaller
pip install pyinstaller

# Clean previous builds
rmdir /s /q build dist

# Build
pyinstaller ankigammon.spec

macOS/Linux:

# Install PyInstaller
pip3 install pyinstaller

# Clean previous builds
rm -rf build dist

# Build
pyinstaller ankigammon.spec

# Remove quarantine attribute (macOS only)
xattr -cr dist/ankigammon

Testing the Build

Windows:

# Test the GUI launches
cd dist
ankigammon.exe

macOS/Linux:

# Test the GUI launches
cd dist
./ankigammon

Settings Storage

User preferences (color scheme, deck name, board orientation, etc.) are automatically saved to:

• Windows: C:\Users\YourName\.ankigammon\config.json
• macOS: ~/.ankigammon/config.json
• Linux: ~/.ankigammon/config.json

Settings persist across application restarts, even when using the standalone executable.

Troubleshooting Build Issues

Missing modules in executable:

• Add the module to hiddenimports in ankigammon.spec
• Or try: pyinstaller --collect-all ankigammon ankigammon.spec

macOS code signing:

• Remove quarantine for local testing: xattr -cr dist/ankigammon

Requirements

• Python 3.8+ (for development install only)
• Dependencies automatically installed via pip install .: genanki, requests, PySide6, qtawesome, pywinauto/pyautogui (Windows only, for XG integration)
• For standalone executable: No requirements - Python and all dependencies are bundled

License

AnkiGammon is licensed under the MIT License. See LICENSE for details.

For third-party licenses and attributions, see THIRD-PARTY-LICENSES.md.