Frequently Asked Questions (FAQ)
What is the purpose of blunderDB?
blunderDB lets you build a personalised database of positions. Its strength is that it assumes no classification a priori. Users are free to query positions with great flexibility by combining criteria of their choosing (race, structure, cube, score, back checkers, checkers in the zone, win/gammon/backgammon chances, …).
Another convenient use of blunderDB is the creation of reference position catalogs. With the ability to tag positions, users can organize all their reference positions in a structured way using a single file. I hope that blunderDB facilitates the sharing of positions between players.
What motivated the creation of blunderDB?
I used to store interesting positions or blunders in various folders. However, I ran into trouble finding positions by criteria not initially anticipated by my choice of thematic categories. For example, if positions were sorted by game type (race, holding game, blitz, backgame, …), how do you retrieve every position at a given score, or at a given cube level? Lastly, some old positions tended to fall into oblivion. I wanted a tool that aggregates all my positions and does not presuppose a priori thematic categories, and then lets me ask questions of the database. With this flexible approach, new filters can be added without breaking the organisation of positions. This kind of software is quite common in chess, such as ChessBase.
Should I create different databases for different categories of positions?
Barring well-identified reasons, it is essential not to split positions across separate databases, at the risk of not being able to relate them in future searches. blunderDB’s philosophy is not to presuppose position categories a priori and to let users query them flexibly. When positions were encountered under particular conditions or for specific reasons, it can be worth storing them in distinct databases. For example, one might build separate position databases for:
reference positions,
blunders from live tournaments,
blunders from online play.
How to merge multiple databases?
If you have several blunderDB databases you want to bring together, use the Merge a database button (CTRL-SHIFT-I):
Open the main database (the one that will receive the positions)
Click Merge a database in the toolbar
Pick the database to merge
blunderDB merges the positions
During the merge, blunderDB avoids duplicates: a position already present is not duplicated, and the analyses from different engines coexist instead of overwriting each other (see Import: what is written, what never is).
Note
It is recommended to make a backup copy of your main database before importing another database.
Which match file formats are supported?
blunderDB supports the following match formats:
eXtreme Gammon (XG): .xg files, with complete move analysis, cube decisions, played moves, and multi-engine support. .xgp files for importing individual positions with analysis.
GNUbg: .sgf files (Smart Game Format), with analysis.
Jellyfish: .mat and .txt files.
BGBlitz: .bgf files and text positions.
Import can be done via a single file, multiple selection, recursive folder, paste from clipboard, or drag and drop.
blunderDB automatically detects duplicates and prevents importing a match already present in the database.
Can I import the matches I played online?
Yes, by a detour: Backgammon Studio (Heroes), Backgammon Galaxy and GammonSpace all three produce files eXtreme Gammon can read — Studio even ships an integration pack that drops into the XG folder. Those matches therefore reach blunderDB through the existing .xg path, with no dedicated reader needed.
Note
Exactly what survives that detour — analyses, roll luck, marks, comments — has not been measured: it would take a match exported from each of the three platforms. If you have one and something is lost on import, open an issue with the file: the measurement is what will decide whether a reader of their own is needed, not a guess.
The older text formats GNU Backgammon already reads — .sgg (GridGammon), .tmg, .gam, Snowie’s .txt — are in the same case: going through GNU Backgammon makes them importable today.
Can I synchronise my database across several machines?
A blunderDB database is a single file. That makes backup and copying trivial, and it settles the answer:
Dropbox, Syncthing, iCloud, OneDrive: these work, on one condition — do not open the database on both sides at once. They synchronise files, not concurrent writes: two instances writing in parallel produce a conflict the service resolves by keeping one version and renaming the other. blunderDB takes a write lock on the open file, which protects one machine, but no lock crosses a synchronisation service.
Several machines at the same time: this is what
servemode answers (see Headless mode (server)). A daemon holds the database, the machines connect to it, and there is only ever one writer.Two databases that have diverged: they are merged rather than synchronised — see “How do I merge several databases?” above. Deduplication by Zobrist hash does the work: shared positions are not duplicated and their analyses and comments are combined. It is a merge, not a reconciliation: nothing is deleted on one side because the other deleted it.
Do I need eXtreme Gammon to use blunderDB?
No. blunderDB also reads GNUbg, BGBlitz and Jellyfish files, and its embedded evaluator (gammonNet) analyses any position without depending on third-party software — see “What is the built-in evaluator worth?” below. An XG import does, however, bring the most complete analysis (plays, cube decisions, flags, roll luck): it is the format the statistics draw on most richly.
I already use eXtreme Gammon: what use is blunderDB to me?
blunderDB does not replay your matches, it brings them together. Three concrete differences:
aggregating into a single file matches coming from XG, GNUbg, BGBlitz and Jellyfish, deduplicated position by position;
searching by checker structure and by error: “the takes at this score where I lost more than 50 millipoints” is written as a single command line (see List of commands);
reviewing the positions kept, by spaced repetition, in Anki decks (see Anki Panel).
Your XG analyses remain XG’s: blunderDB imports them as they are and never recomputes them (see Import: what is written, what never is).
Are XG rollouts imported? Does blunderDB do rollouts?
No, in both directions. From an XG analysis, the import keeps the level label (“3-ply”, “XG Roller++”, “Book”), the equities, the errors and the probabilities; it does not open the .xg file’s rollout data, and therefore keeps neither the number of trials nor the standard deviation. An XG analysis pasted as text, on the other hand, keeps its label literally, “Rollout” included. The embedded evaluator, for its part, does not do rollouts: it answers with a search up to 0 or 2 rolls ahead.
What has been measured of the built-in evaluator, and what has not?
A measurement is published, on the Eval panel’s evaluated regime: 4000 money race decisions, compared against the exact bearoff table — 93.4% verdict agreement (3735/4000), but only 61.1% within 1% of the take point against 94.4% beyond 20%; average winning-probability gap 0.85%, maximum 8.30%. What is not measured: the cube verdict at a match score and contact positions, for which no figure is published. The details of the assumptions are in Methodology and assumptions of the Eval panel.
What is a collection?
A collection is a custom grouping of positions. Unlike a filter search which is dynamic, a collection is a fixed set of positions manually chosen by the user. Collections allow, for example, grouping reference positions for a particular topic.
What is EPC?
EPC (Effective Pip Count) is a more accurate measure than the simple pip count for evaluating bearoff positions. blunderDB’s Eval panel uses a 6-point bearoff table identical to GNUbg’s, computed on the machine on first launch, and computes in real time the EPC, average number of rolls, standard deviation, pip count, and wastage.
On pure bearoff positions, the panel also shows the winning probability of the player on roll and, when the position is covered by a two-sided database (TS-06-06 table computed on first launch, or extended TS-06-11 table computed from the Bearoff tab of the configuration), the exact money cube verdict. Outside that domain, the probability is estimated with its error margin and the verdict is deliberately not shown. See the manual section “Methodology and assumptions of the Eval panel” for the details of the assumptions.
What is the built-in evaluator (gammonNet) worth?
gammonNet is a neural network trained by a third party (see Credits), ported to Go and compiled into blunderDB: no external software, no network connection. It plays the role of XG or GNUbg for positions that were not imported — search up to 0 or 2 rolls ahead, cube decisions per Janowski and blunderDB’s match equity table, honouring the match score. It is neither the only nor necessarily the best engine on the market: it is the one that works offline, without an account or subscription, on the position you are looking at. Nothing stops you from also importing XG or GNUbg analyses where they exist — the two sources coexist, and a column shows the origin of each analysis. See the “Eval Panel” section and “Methodology and assumptions of the Eval panel” in the manual.
What that is worth, in figures. On the bear-off positions the embedded exact table covers — the only place an oracle exists — gammonNet at 2-ply gives the same cube verdict in 93.4 % of cases, and the disagreement concentrates exactly at the take point (61 % agreement within 1 % of the take point, 94 % beyond 10 %): that is where two legitimate methods diverge most on a close decision, not a diffuse error. The detail and the method are in “Methodology and assumptions of the Eval panel”.
For the same question asked of your library rather than of a reference corpus, blunderdb analyze --compare compares the embedded engine with the analyses that came in your XG or GNUbg files — agreement on the best answer, cost of the disagreements, breakdown by game phase — writing nothing.
What is the difference between PR and the Snowie Error Rate?
PR (Performance Rating) is the average equity error per counted decision, multiplied by 500 as eXtreme Gammon and GNUbg do; the lower it is, the better you are playing. The Snowie Error Rate reports that same average against the number of plays rather than the number of decisions — a longer match therefore does not mechanically worsen the SER. blunderDB shows both in the Stats panel, aligned with eXtreme Gammon’s and GNUbg’s conventions (see Annex: Statistics model — XG / gnuBG / blunderDB alignment for the counting rules in detail).
Does blunderDB have a command-line interface?
Yes, blunderDB has a command-line interface (CLI) that allows performing without a graphical interface operations such as creating databases, importing matches, exporting, searching positions, displaying statistics, etc. Refer to the CLI documentation for more details.
Does blunderDB offer a server mode?
Yes, an optional “headless” mode: the same binary, launched with serve, exposes blunderDB’s engine over HTTP + JSON behind an authenticating reverse proxy (blunderDB itself performs no authentication). It can run on SQLite or on multi-tenant PostgreSQL, and is used to drive blunderDB from your own scripts or a homegrown application, over HTTP + JSON — there is no web interface —, or to share a database between several players. The normal use remains the desktop application; see Headless mode (server) for the details (including the ready-to-use Docker image) and the “Deploying server mode behind a proxy” tutorial in the user guide.
Can I modify, copy, share blunderDB?
Yes, absolutely. blunderDB is licensed under the MIT license.
Where is my data stored?
On your disk, in the .db file you chose when creating the database: no account, no server, no synchronisation by default. The desktop application opens that file directly; only the optional server mode (see above) runs blunderDB remotely, and in that case you are the one hosting that server.
Can I share a database with another player?
Yes: a blunderDB database is a plain file, so copying or sending it is enough. To distribute a database to a third party, two optional mechanisms, chosen at export time, turn it into a controlled release rather than a plain copy: an origin watermark signs the file with your issuer identity (unforgeable, readable in the Metadata panel or via blunderdb info, and never recording anything on the recipient’s side), and password protection produces an encrypted .dbx file. See Handing out a database: origin and password in the manual.
What data format does blunderDB use?
The database is a simple SQLite file. In the absence of blunderDB, it can thus be opened with any SQLite file editor.
What were the design principles of blunderDB?
I wanted an interface that stays approachable, but designed above all for advanced, sustained use, where one moves from position to position and from search to search. The command line, opened by pressing the SPACE bar, and the keyboard shortcuts serve that use, without being mandatory.
I also wanted blunderDB to be lightweight, self-contained, installation-free and available on different platforms, hence my choice of the Go language and the Svelte library. For serialising the database, the file format had to be cross-platform and suited to holding a database. The SQLite file format seemed the obvious fit.
I was also keen that a database should remain a single file, one that can be copied, backed up or sent to another player.
Finally, blunderDB is no longer limited to the desktop application: the same binary provides a command-line interface and an optional server mode, which can rely on PostgreSQL for multi-user deployments. The normal way to use it nevertheless remains the desktop application. See Command Line Interface (CLI) and Headless mode (server).
What is the software architecture of blunderDB?
The backend is coded in Go. It is responsible for all operations on the SQLite database that stores the positions.
The frontend is coded in Svelte. It is responsible for rendering the graphical interface and the Backgammon board.
The application is encapsulated with Wails, enabling the production of native desktop applications for Windows, Linux and macOS.
The database is managed by SQLite.
The optional server mode can rely on PostgreSQL instead of SQLite for multi-user deployments.
The embedded evaluator (gammonNet, MIT) is a neural network ported to Go and compiled into blunderDB: it evaluates any position offline, without XG or GNUbg. See “What is the built-in evaluator worth?” below.
For more information, see the blunderDB GitHub repository.
Which platforms does blunderDB run on?
blunderDB runs on Windows, Linux and Mac.
Where does the blunderDB icon come from?
The blunderDB icon is the “goggling” emoticon from the SMirC series.
How to save the state of the current database?
The database is updated immediately upon validation of the request. No explicit saving operation is necessary.