ankigammon 1.3.0

Convert eXtreme Gammon backgammon analysis into Anki flashcards

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
• GNU Backgammon integration - Analyze unanalyzed positions automatically
• 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 GNU Backgammon if configured in Settings (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:

• GNU Backgammon Path: Configure path to gnubg-cli executable for automatic position analysis
• Analysis Ply: Set depth (0-4, default: 3)
• 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
• 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.