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, experimental; see Position Analysis)
• 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)
• Deck tree organization - Drag-and-drop positions into named decks and subdecks; tree syncs with Anki via AnkiConnect (automatic on startup)
• 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-<version>.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
     • Drop files directly onto a deck in the deck tree to import into that deck
3. Organize into decks - Use the deck tree on the left to create named decks/subdecks and drag positions between them. Decks stay expanded or collapsed as you leave them across imports; use the expand/collapse-all buttons above the tree, or right-click a deck to expand or collapse its subdecks. The tree syncs with Anki via AnkiConnect (automatic on startup, or manually via File → Sync Decks from Anki, Ctrl+Shift+D).
4. Configure settings - Choose color scheme, board orientation, and export method (Ctrl+,)
5. 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+Shift+D - Sync decks from Anki
• Ctrl+Shift+O - Open collection
• Ctrl+Shift+S - Save collection
• 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.
  • ⚠ Experimental: likely to fail on setups different from those tested. If it doesn't work for you, fall back to GNU Backgammon and send diagnostic logs (Help → Send Diagnostic Logs).
  • Supports XG 2.10 and 2.19, with auto-detected menu commands across English, German, French, Spanish, Japanese, Greek, and Russian Windows.

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

Studying Without Anki

File → Export to Trainer... saves the loaded positions as a study pack (.json) for the AnkiGammon trainer, which runs in the browser on a computer or phone with no Anki and no account. Open the trainer, choose the file, and study: it asks for the best move or cube action, shows the analysis, and schedules reviews with FSRS. Everything stays on that device. On a phone, add the trainer to the Home Screen first, then send the file to the phone and open it from there. The trainer also opens AnkiGammon .apkg decks and the community decks.

File → Study in Trainer skips the file on this computer: it opens the trainer in your browser and hands it the loaded positions directly. The positions go from AnkiGammon to the browser on this computer and nowhere else. Chrome, Edge and Firefox work; the first time, allow the browser to reach devices on your local network if it asks. Safari can't connect, so AnkiGammon offers to save the file instead.

Collection Files

A collection file saves the positions currently loaded in AnkiGammon, so you can rebuild your cards later for a new AnkiGammon version, new settings, or after new rollouts in XG.

• File → Save Collection... (Ctrl+Shift+S) writes the loaded positions to a .json file. Positions imported from a file are saved as a link to that file, with the import filters you used and the deck each position is in. Other positions (pasted analysis or position IDs) are saved whole.
• File → Open Collection... (Ctrl+Shift+O) replaces the loaded positions after a warning. It re-imports each file with its filters and puts every position back into its saved deck. Then export to Anki: existing cards are updated in place and keep their review history.

Notes:

• XG files (.xg, .xgp) keep the analysis and rollouts saved in them. Match files (.mat, .sgf) are analyzed again by the engine.
• Positions you moved between decks or deleted stay that way. If a file's analysis changed, positions that now fall under the error threshold are reported as not found, and newly qualifying positions are left out.
• Files stored next to or below the collection file are saved with relative paths, so you can move the folder as a whole.
• The position list is cleared after each export by default, so save the collection before exporting (or turn off "Clear position list after export" in Settings).

The Re-render cards only mode of File → Regenerate Cards in Anki also keeps rollouts, because it reuses the analysis stored in each card. Use a collection when you want to pick up new analysis from your source files.

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, with a click to switch the cells between error costs and the No-Double / Double-Take cubeful equities. In match play an "Unlimited" row under the matrix shows the same position as an unlimited game (no beavers), so you can compare the match action with the unlimited one; click "no Jacoby · Jacoby" on the row to switch the Jacoby rule (if enabled)
• Move score matrix showing top moves at different match contexts (if enabled)
• Cube position spoiler — a collapsed section revealing how the best move changes when the cube is centered, owned by you, or owned by your opponent; only shown when the best move actually differs (if enabled)

On wide screens (1200px and up) the card back automatically lays the answer, your notes, and the analysis table out beside the board, so everything is visible without scrolling; on narrow screens the classic stacked layout is used. Cards exported before this feature keep the stacked layout until re-exported or regenerated ("Regenerate cards" via AnkiConnect).

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, experimental)
• 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, experimental)
• XG Analysis Level: Set XG depth (Very Quick → Extensive, default: World Class)
• Score Matrix: Generate cube decision matrix for all match scores, plus an unlimited-game reference for match positions, without and with the Jacoby rule (two extra analyses per card, one for redoubles; no beavers) (optional, time-consuming)
• Score Matrix Max Size: Cap the matrix size in points to save time on long matches; with "Auto" it uses the match length, or a 7-point view for unlimited (money) games
• Move Score Matrix: Generate move analysis at different match contexts - Neutral, DMP, Gammon-Save, Gammon-Go (optional, time-consuming)
• Analyze Checker Plays at All Cube Positions: Re-analyze each checker play with the cube centered, owned by the player, and owned by the opponent (3 extra analyses per position). A collapsed spoiler is added to the card back only when the best move differs between cube positions. Owned-cube variants use a 2-cube unless the cube is already owned. Works for match play and unlimited games; skipped in Crawford games and 1-point matches where the cube is dead (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.