blunderDB

blunderDB is a software for creating backgammon position databases. Its main strength is to provide a single place where a player can aggregate the positions he or she has encountered (online, in tournaments) and be able to review these positions by filtering them with various filters that can be arbitrarily combined. blunderDB can also be used to create catalogs of reference positions.

The present documentation is structured as follows:

• the download and installation section explains how to obtain and run blunderDB.

• the manual describes the general functioning of blunderDB and how it should be used.

• the user guide is a practical introduction for quickly using blunderDB.

• the list of commands as well as the list of keyboard shortcuts enables efficient use of blunderDB.

• the command line interface (CLI) section describes the available commands for bulk import, automation, and scripting.

• The FAQ provides answers to the most frequently asked questions.

Version history

Version	Date	Cause and/or nature of changes
0.1.0	December 31, 2024	Beta version
0.2.0	January 6, 2025	Various bug fixes. Addition of match/TP/GV tables. Added search filters (moves, cube decisions, date). Added metadata for positions. Import/export functionality between blunderDB instances. Added metadata functionality for databases. Introduction of version numbers (database and application).
0.3.0	January 27, 2025	Various bug fixes. Automatically saves the window size. Imports any comments from XG.
0.4.0	February 3, 2025	Various bug fixes. Adding an icon for blunderDB. Filter corrections. Adding macOS support.
0.5.0	February 4, 2025	Addition of new filters (mirror, non-contact, jan blot, outfield blot).
0.6.0	February 13, 2025	Add filter library. Displaying the database version in the metadata.
0.7.0	February 16, 2025	Support Japanese and German XG exports.
0.8.0	May 3, 2025	New button to hide pipcount. Button to load random position.
0.9.0	November 02, 2025	Fix filter library bug. Database import/export. Display arrows for selected moves. Keyboard shortcuts for import/export.
0.10.0	February 25, 2026	Match import from eXtreme Gammon (XG/XGP), GNUbg (SGF), Jellyfish (MAT/TXT) and BGBlitz (BGF/TXT). Match navigation: browse through moves of an imported match, with played move highlighting. Match panel: list, sort, inline editing, player swap, tournament assignment. Recursive folder import and drag & drop import. EPC (Effective Pip Count) calculator with built-in GNUbg bearoff database. Collections: custom position grouping. Tournaments: group matches by event. Save and restore session state (last search, current position). Automatic database schema migration. Multi-engine display in analysis. Player 1 error/blunder filter in searches. Database export with granular selection (matches, collections, tournaments, played moves). Match navigation button. Pipcount display in match navigation. Complete command-line interface (CLI). Automatic reopening of the last database. Improved toolbar and icons.
0.11.0	March 6, 2026	Filter to search within currently filtered positions. Add match and tournament filters. Automatic board clearing when opening the search panel.
0.12.0	March 19, 2026	Import eXtreme Gammon position files (XGP) with analysis.
0.13.0	March 28, 2026	Interface simplification: match and collection navigation is now done directly through panels. Command line integrated into the status bar. Console panel renamed to Log panel. Dedicated EPC panel in the bottom panel. Copy/paste position in the search panel. Drag and drop to reorder collections, positions within collections, and matches within tournaments. Tournament column in the match panel with inline editing. Automatic display of the analysis panel after a search.
0.14.0	March 30, 2026	Dedicated Anki panel for spaced repetition study (FSRS algorithm). Import comments from XG files.
0.15.0	March 31, 2026	Export position as PNG image to clipboard (board only via Ctrl+X, or board with analysis via Ctrl+X Ctrl+X).
0.16.0	April 18, 2026	Database schema v2.0.0: Zobrist-hashed position deduplication, denormalized filter columns, bitboard pattern pre-filter, WAL journaling. Batch import >=3x faster, filtered search <=100 ms on 10k+ positions. NOTE: DB files created with v0.16.0 cannot be opened by older versions; old DBs are auto-migrated in place (back up first).
0.17.0	April 20, 2026	Storage optimization: zlib compression of analysis data (~80% reduction), compact board encoding (~90% position state size reduction). Added 5 missing indexes for search performance. Fixed cube error search returning wrong results. Fixed EDIT mode after search returns no results. Restored search panel state when switching tabs. Removed 62 debug print statements from hot search/filter paths.
0.18.0	April 20, 2026	Major codebase refactoring: split db.go (10k lines) into 19 domain-focused files, extracted 7 service modules from App.svelte (4,888→469 lines), consolidated modal/panel stores. Full migration to Svelte 5 runes. Replaced 9 table modals with a generic DataTableModal component. Added ESLint + Prettier + vitest (125 frontend tests) with CI enforcement. WCAG 2.1 AA accessibility baseline (visible focus, ARIA roles, keyboard navigation). Upgraded Database mutex to RWMutex for better read concurrency. Complete CLI documentation (CLI_USAGE.md + Sphinx FR/EN). Rewrote README. Resolved all ESLint warnings (46→0) and Vite build warnings (6→0).
0.19.0	May 7, 2026	Added Stats panel: PR (Performance Rate), Snowie Error Rate and MWC cost (Match Winning Chance cost) indicators, filter bar (player, tournament, dates, decision type, match length), Dashboard tab with level cards / rolling PR / top blunders, Progression tab with per-tournament curve and per-match scatter plot, Errors tab with cube-action breakdown and error magnitude histogram. Interactive drill-down to positions / matches / tournaments from all indicators. Instant PR / MWC toggle. CLI command list –type stats. Alignment of PR / Snowie ER / MWC indicators with eXtremeGammon and gnuBG (0.16 equity threshold for close cubes). Fixed cube_error calculation for Double/Pass decisions. Statistics model documentation (Annex: Statistics model — XG / gnuBG / blunderDB alignment). See Stats Panel.

Table of contents

• 1. Download and Installation
• 2. Manual
  • 2.1. Introduction
  • 2.2. Main Interactions
  • 2.3. Description of the interface
  • 2.4. Browsing positions
  • 2.5. Editing positions
  • 2.6. The command line
  • 2.7. Analysis Panel
  • 2.8. Comments Panel
  • 2.9. Search Panel
  • 2.10. Collections Panel
  • 2.11. Matches Panel
  • 2.12. Tournaments Panel
  • 2.13. Stats Panel
  • 2.14. EPC Panel
  • 2.15. Anki Panel
  • 2.16. Metadata Panel
  • 2.17. Log Panel
• 3. User Guide
  • 3.1. Create a new database
  • 3.2. Open an existing database
  • 3.3. Import and merge a database
  • 3.4. Edit a position
  • 3.5. Add a position to the database
  • 3.6. Tag a position
  • 3.7. Delete a position
  • 3.8. Import a position from XG
  • 3.9. Import a match
  • 3.10. Import a folder of matches
  • 3.11. Drag and drop
  • 3.12. Navigate through a match
  • 3.13. Manage the match panel
  • 3.14. Manage collections
  • 3.15. Manage tournaments
  • 3.16. Display performance statistics
  • 3.17. Calculate the EPC
  • 3.18. Display the analysis of a position imported from XG
  • 3.19. Export a position to XG
  • 3.20. View the different positions
  • 3.21. Search for positions based on criteria
• 4. List of commands
  • 4.1. Global operations
  • 4.2. Positions and navigation
  • 4.3. Editing and search
  • 4.4. Search Filters
  • 4.5. Various commands
• 5. Keyboard shortcuts
  • 5.1. Database
  • 5.2. Position
  • 5.3. Navigation
  • 5.4. Display
  • 5.5. Actions
  • 5.6. Tools
  • 5.7. Command Line
  • 5.8. Search History Panel
  • 5.9. Filter Library Panel
  • 5.10. Analysis Panel
  • 5.11. Match Panel
  • 5.12. Anki panel (spaced repetition)
• 6. Command Line Interface (CLI)
  • 6.1. Introduction
  • 6.2. General syntax
  • 6.3. Available commands
  • 6.4. create — Create a database
  • 6.5. import — Import data
  • 6.6. export — Export data
  • 6.7. search — Search positions
  • 6.8. list — List contents
  • 6.9. match — Display a match
  • 6.10. info — Database metadata
  • 6.11. edit — Edit metadata
  • 6.12. verify — Verify integrity
  • 6.13. delete — Delete data
  • 6.14. Workflow examples
  • 6.15. Exit codes
• 7. Frequently Asked Questions (FAQ)
  • 7.1. What is the purpose of blunderDB?
  • 7.2. What motivated the creation of blunderDB?
  • 7.3. How to save the state of the current database?
  • 7.4. Should I create different databases for different categories of positions?
  • 7.5. How to merge multiple databases?
  • 7.6. Which match file formats are supported?
  • 7.7. What is a collection?
  • 7.8. What is EPC?
  • 7.9. Does blunderDB have a command-line interface?
  • 7.10. Can I modify, copy, share blunderDB?
  • 7.11. What data format does blunderDB use?
  • 7.12. What were the design principles of blunderDB?
  • 7.13. What is the software architecture of blunderDB?
  • 7.14. On which platforms does blunderDB run?
  • 7.15. Where does the blunderDB icon come from?
• 8. Annex: Advanced Filter Usage
  • 8.1. Command-line search for positions
  • 8.2. Search in Current Results
  • 8.3. Filter Library
  • 8.4. Examples
• 9. Windows Annex: False Detection of blunderDB as Malware
  • 9.1. Windows SmartScreen Warning
  • 9.2. Windows Defender Blocking
• 10. Mac Annex: Possible Blocking of blunderDB
  • 10.1. Installation of blunderDB
  • 10.2. Authorization to Run blunderDB
• 11. Annex: Database Schema
  • 11.1. Version 1.0.0
  • 11.2. Version 1.1.0
  • 11.3. Version 1.2.0
  • 11.4. Version 1.3.0
  • 11.5. Version 1.4.0
  • 11.6. Version 1.5.0
  • 11.7. Version 1.6.0
  • 11.8. Version 1.7.0
• 12. Annex: Statistics model — XG / gnuBG / blunderDB alignment
  • 12.1. Formal definitions
  • 12.2. Decisions counted in the PR denominator
  • 12.3. blunderDB ↔ XG ↔ gnuBG correspondence
  • 12.4. Validating your own figures
  • 12.5. gnuBG reference

Contact

Author: Kévin Unger <blunderdb@proton.me>. You can also find me on Heroes under the username postmanpat.

I initially developed blunderDB for my personal use to help detect patterns in my mistakes. However, it’s very rewarding to receive feedback, especially after spending a lot of time on design, coding, and debugging. So feel free to reach out to share your experiences. All (constructive) feedback is welcome.

Here are several ways to discuss:

• Join the Discord server of blunderDB: https://discord.gg/DA5PpzM9En

• Email me at blunderdb@proton.me.

• Discuss with me if we meet in a tournament.

• On GitHub.

  • Open an issue: https://github.com/kevung/blunderDB/issues

  • For bug fixes or improvement suggestions, create a pull request.

Donate

If you appreciate blunderDB and want to support its past and future developments, you can

• buy me a drink if we have the pleasure of meeting!

• make a small donation via PayPal to the address blunderdb@proton.me

Acknowledgments

I dedicate this little software to my wife Anne-Claire and our dear daughter Perrine. I would especially like to thank a few friends:

• Tristan Remille, for introducing me to backgammon with joy and kindness; for showing the way in understanding this wonderful game; and for continuing to support me despite my poor attempts to improve my play.

• Nicolas Harmand, a cheerful companion for over a decade in great adventures, and a fantastic sparring partner since he has caught the backgammon bug.