Manual
Introduction
blunderDB is software for creating backgammon position databases. Its main strength is to provide a single place to aggregate positions that a player has encountered (online, in tournaments) and to be able to re-study these positions by filtering them according to various arbitrarily combinable filters. blunderDB can also be used to create catalogs of reference positions.
Positions are stored in a database represented by a .db file. The desktop application opens this file directly, never a network address: server mode (Headless mode (server)) is another mode of the same binary, and moving from one to the other means exporting or migrating the database, not pointing the application at a URL.
Main Interactions
The main interactions possible with blunderDB are:
add a new position,
modify an existing position,
copy the board image to the clipboard (PNG) via CTRL-X, or with the full analysis via CTRL-X CTRL-X,
delete an existing position,
search for one or more positions,
import matches from various sources (XG, GNUbg, BGBlitz, Jellyfish), including comments from XG files,
navigate through the moves of an imported match,
organize positions into collections,
organize matches into tournaments.
The user can freely tag positions and annotate them with comments.
Description of the interface
The interface of blunderDB is composed, from top to bottom, of:
[top] the toolbar, which gathers all the main operations that can be performed on the database,
[in the middle] the main display area, which allows for displaying or editing backgammon positions,
[at the bottom] the status bar, which provides various information about the database or the current position, and integrates the command line.
Panels can be displayed to:
display the analysis data associated with the current position from eXtreme Gammon (XG), GNUbg, or BGBlitz,
display, add, or modify comments,
search and filter positions using combinable criteria,
display and manage position collections (collections panel),
display the list of imported matches and navigate through the moves of a match (match panel),
display and manage tournaments (tournaments panel),
display performance statistics (Stats panel),
compute the EPC (Effective Pip Count) of a bearoff position (Eval panel),
study positions with spaced repetition (Anki panel),
display the database metadata (metadata panel).
Modal windows can be displayed to:
display the blunderDB help,
display the catalogue of guided tours (see Guided tours and sample database),
configure database export settings,
configure blunderDB, in particular the interface language (see Configuration).
The main display area provides the user with:
a board to display or edit a backgammon position,
the level and owner of the cube,
the pip count of each player,
the score of each player,
the dice to play. If no values are shown on the dice, the position of the dice indicates which player is on roll and that the position is a cube decision. When the cube decision is a response to a double (take/pass), the offered cube is shown in the centre of the board, at the offered value.
The clipboard is the everyday gesture; saving is the other need — the illustration for an article, a forum post, a lesson. SVG is offered because the board is one: it is the form that survives being enlarged, the one you put in a document without blurring it. PNG derives from it, as does the clipboard copy: one rendering, three destinations, so none of them can drift from the others. This menu does not appear in the Eval panel or in the Search panel, where the right button already places the other colour’s checkers. See Bringing a position into the Eval panel for bringing a position into the Eval panel.
The status bar is structured from left to right with the following information:
the command line, accessible by pressing the SPACE key,
an informational message related to an operation performed by the user,
the index of the current position, followed by the number of positions in the current library (or move/game info when navigating a match),
the library counter — “412 positions · 38 blunders · 5 matches” — where every number opens what it counts: the positions, the
E>search prepared in the command line at the library’s threshold, or the match list. A figure you cannot follow is a decoration. The blunder threshold is the library’s own, set in the Library tab of the settings and shared with the statistics: two thresholds would make the same word mean two things. The counter promises exactly what the link opens, including for a position played several ways, which is worth its largest cost.
Note
In the case of positions resulting from a user search, the number of positions indicated in the status bar corresponds to the number of filtered positions.
The Anki tab carries a badge when cards are due, across every deck. That figure is the reason to open the tab; it has no business behind it. Zero shows nothing: a badge saying “0” is noise.
The log command opens the activity log: the last two hundred lines of the log file, a button to copy them — what it takes to attach a report to a bug — and another to open the folder holding them. The log is neither filtered nor reformatted: a log you tidy up is a log you can no longer quote.
The grid command opens the contact sheet: the browsed list — search results, library, collection — as a grid of mini-boards, drawn like the board, in pages of twenty-four. It opens on the page of the current position, whose thumbnail is outlined; a click or ENTER on a thumbnail opens its position on the board and closes the sheet, and it can be browsed entirely from the keyboard (see Contact sheet). It does not open in edit mode or in a match, which is browsed by its moves.
In the search history of the Search panel, each token of a saved command shows as a named chip — No Contact, Move Error — rather than a bare token. The exact command stays in the tooltip, since that is what gets re-run; and a token blunderDB does not recognise shows as it is rather than translated to the nearest thing.
View Tabs
Below the toolbar, a tab bar lets you work with several views in parallel. Each view is an independent workspace that keeps its own position list, the index of the current position, the displayed position, the analysis and the selected move, the active panel, the comment being edited, as well as the navigation context within a match. This makes it possible, for example, to keep a search open in one view while browsing a match in another.
Create a view: click the + button of the tab bar or press CTRL-T. The new view starts as a copy of the current view.
Close a view: click the cross on the tab or press CTRL-W. The last view cannot be closed.
Switch view: click a tab, press CTRL-PageUp / CTRL-PageDown (or SHIFT-J / SHIFT-K) to move to the previous / next view, or CTRL-1 to CTRL-9 to jump directly to the n-th view.
Rename a view: double-click the tab, type the new name and confirm with ENTER.
Views are saved with the database session state and restored when it is reopened.
Configuration
The settings button (gear icon) in the toolbar, to the left of the help button, opens blunderDB’s settings window. It is organised in seven tabs:
Interface — language, display scale, panel position;
Colours — the board’s colours;
Library — what belongs to the open database: the error and blunder thresholds, compaction and repair, described below;
Bearoff — the bearoff tables used by the Eval panel;
gammonNet — the settings of the embedded evaluator, described below;
Watched folder — the automatic import of matches arriving in a folder, described below;
Issuer identity — the key that signs your watermarks, described in Handing out a database: origin and password.
The Interface tab starts with a theme: follow the system, light, dark, high contrast or printable. The theme sets the interface colours and proposes a board palette — a dark interface around a light board is not a dark theme, it is half of one, since the board occupies most of the window.
You keep the last word, and the mechanism guarantees it rather than promising it: the Colours tab still sets the board directly, and a colour chosen after the theme is yours. At start-up only the interface tokens are applied, never the board palette — the one you set is already loaded, and rewriting it at every launch would erase your work one session at a time. See ADR-0038.
Follow the system is the default: it obeys the desktop’s light/dark preference, including when it changes mid-session. A tool does not impose its light or its dark on a desktop that has already decided.
The Interface tab also lets you choose the language among English, French, German, Italian, Spanish, Finnish, Japanese, Greek and Russian. The whole interface (toolbar, panels, messages, help) is translated into the selected language. The language choice is saved and kept from one session to the next.
The Library tab gathers what belongs to the open file rather than to the machine. It is empty as long as no database is open, and it says so.
It carries first the two thresholds that decide the whole application’s vocabulary: a decision is an error as soon as its cost reaches the error threshold, and that error is a blunder as soon as it reaches the blunder threshold. Every blunder is an error, so the first threshold cannot exceed the second, and blunderDB refuses the inverted pair. The values are entered in equity — “0.080” — the unit of every table; the command line, for its part, speaks millipoints, so the 0.080 threshold is written E>80 in a search.
These thresholds follow the file, not the computer: the same database counts the same blunders wherever it is opened, blunderdb info displays them, and blunderdb edit --error-threshold / --blunder-threshold sets them. They do not travel in an export: a threshold is a reading habit, not a fact of the positions.
Three presets are offered in one click, each under the name of the program that drew that line: blunderDB (0.050 / 0.100), XG (0.020 / 0.080) and gnubg (0.040 / 0.080). By default, a library reads 0.050 and 0.100.
What they change, on screen: the blunder count of the status bar’s counter and the search its link prepares, the “Errors” and “Blunders” columns of the statistics and of the players table, the marks on the moves in a match’s detail pane (Matches Panel), and the list of positions blunderDB offers to review after an import.
The same tab also offers a Compact database button, which reclaims the disk space left behind by deletions (matches, tournaments, purges): the database never shrinks by itself when data is deleted, that compaction has to be requested explicitly. The operation can take a while on a large database and temporarily needs about twice its size in free disk space (blunderDB refuses to start rather than risk an interrupted compaction); a confirmation is therefore asked before it runs. The result — the space gained, in megabytes — is then shown in the status bar. The same operation is available on the command line through blunderdb vacuum (see Command Line Interface (CLI)).
The Open the log folder button just below it opens the folder holding the application log — useful for attaching details to a bug report, especially when blunderDB was started from a shortcut or a double-click, with no terminal attached to show anything.
The Check for updates at startup checkbox, off by default, queries the GitHub repository’s releases page once per launch and shows a message in the status bar when a newer version is available — never a window that gets in the way. This check stays automatically disabled on an installation that came through a package manager (Flatpak, Homebrew, a distribution package…): that channel is the one handling updates then, not blunderDB itself.
Two settings govern the ranking of neighbouring positions (the like token, see Search Panel): the number of neighbours returned, and the maximum distance beyond which a position stops being one. That distance is zero by default, that is, no ceiling: the scale depends on the game phase, and a value chosen here would read as a measurement. The like<12 token imposes its own for one search, without touching the setting.
The Board colours tab lets you customise the board’s colours. Each element has its own colour picker: the background, the border, the light and dark points, player 1’s and player 2’s checkers, the dice, the dice pips and the cube. The Reset button restores all the default colours. Like the language, the chosen colours are kept across sessions.
The Bearoff tab manages the Eval panel’s bearoff tables (see Eval Panel). They are neither embedded in the executable nor downloaded: blunderDB computes them on the machine that uses them, and the result is identical byte for byte to what gnubg produces — the SHA-256 fingerprint is checked before a table is accepted.
The two ordinary tables (TS-06-06 for the cube verdict, OS-06 for the EPC) are computed on first launch, in the background and without asking: about six seconds on one core, during which the application is used normally. The Eval panel mentions it only if a position is placed there that needs a table which is not ready yet.
The tab shows the active domain and its origin, the state of the one-sided table the EPC reads, the folder where all this lives, and the list of the tables present with their size and their verdict. Each row can be deleted individually, after confirmation.
Verified or unverified. A verified table has exactly the bytes gnubg produces for its domain: its SHA-256 fingerprint is recorded in blunderDB and was found again. The fingerprints recorded for one-sided tables (OS-06 to OS-10) are the ones produced by GNUbg 1.08’s makebearoff tool. An unverified table is well formed but its domain has no recorded fingerprint — nothing is held against it, simply nobody has compared it to the reference. A corrupt table contradicts itself and is never read; it is recomputed.
Computing a wider table. The domain is picked from a list of two families, together with the number of cores to give it (by default all but one, so the machine stays usable):
exact cube (two-sided), from TS-06-06 to TS-06-15: widens the domain where the winning probability and the cube verdict are read rather than estimated;
EPC beyond the home board (one-sided), from OS-06 to OS-10: widens how far from home a chequer may stand without the EPC block going silent. This sweep reads only positions smaller than the one it is computing, so it is sequential by construction and the core count buys it nothing — the picker says so by greying out.
Before anything starts, the tab states three figures for the chosen domain: the size on disk, the memory needed during the computation, and the time it should take on this machine. The last one starts as an estimate and becomes a measurement: every run wide enough records its own speed and keeps it. A domain the available memory cannot hold is offered greyed out, with the reason — “it would need 24 GB, 12 are left” is an answer, an absent row would not be.
As an order of magnitude, on a sixteen-thread machine: TS-06-09 weighs 191 MB and takes about ten seconds, TS-06-11 weighs 1.2 GB and a few minutes, TS-06-13 exceeds what most machines can hold in memory. On the one-sided side, on one core: OS-07 weighs 4.9 MB and takes 17 s, OS-08 15 MB and 1 min 20, OS-10 117 MB and half an hour.
Pause and resume. During the computation, the progress shows the measured remaining time and two distinct buttons: Pause and Cancel. Pausing writes the state of the computation beside the table; running it again continues where it stopped instead of starting over. Cancelling keeps nothing. Closing the configuration window interrupts nothing — the computation carries on in the background.
A paused computation is found again at the next launch, named and quantified (“TS-06-09 interrupted at 43%”), with Resume and Delete. Nothing restarts on its own: the user is the one who asked it to stop.
The tab finally allows pointing to an external two-sided .bd file, for example a database produced by gnubg itself: the table with the widest domain wins.
The Library tab finally carries Repair the analyses: the analysis columns that search and statistics query are a projection of the stored analyses, which stay intact. A fault in the projection is therefore repairable without re-importing anything. It is explicit and never automatic — rewriting someone’s analysis columns on the mere act of opening their database is not something a tool should do behind their back. The same blunderdb repair is available on the command line.
The gammonNet tab configures the embedded evaluator (see ADR-0011). Two search depths can be set there, named and kept separately — lowering one never changes the other:
Display depth — the interactive comfort while editing the board; never written to the database.
Analysis depth — what the post-import analysis batch writes into a position’s Analysis.
Both default to 2-ply, the canonical configuration. The tab also offers pruning (k=12 by default) and the number of candidate moves shown (10 by default), as well as an auto-analyze after import box which, once ticked, checks after every import whether positions with no analysis at all remain (neither gammonNet, nor XG, nor GNUbg, nor BGBlitz — the rule is “an evaluation only fills a hole”, never a replacement) and, if so, starts a gammonNet analysis in the background at the configured analysis depth. An Analyze now button re-runs the same catch-up manually, useful for a library built before this feature existed.
A second button, Re-analyze stale positions, covers the opposite case: a position already analyzed by gammonNet, but whose stored analysis was written by an engine version older than the one currently running, or at a depth different from the analysis depth configured above, is flagged there as stale and re-evaluated. A position that also carries an XG, GNUbg or BGBlitz analysis is never touched by this button, whatever its gammonNet content — ADR-0013’s protection remains unconditional. The count shown next to each button (positions with no analysis, stale positions) is purely informational; the batch recomputes its own list when it starts.
Both batches are bounded, visible and cancellable, never a silent daemon: their progress (positions analysed / total) and a cancel button appear in the status bar for their whole duration, and disappear once finished in favor of a message summarizing the result — how many positions were analyzed, how many were refused (a position gammonNet declines to evaluate, such as a match score beyond its MET’s range, which is never a failure) and how many failed (retried, unchanged, on the next run). Closing the application during either loses nothing: each analyzed position is written as it goes, and the next run resumes exactly where the analysis stopped, with no journal to keep.
A match imported without an analysis now gets a Performance Rating. That is the case of a match played online, or of a Jellyfish .mat file, that nobody ran through XG: blunderDB knew its positions and the moves played, but no analysis said what they were worth. Once the batch has run, the move actually played is compared with gammonNet’s ranking and the gap feeds the PR, the error rate, the worst decisions and every other indicator, exactly as for a match analysed by XG. The comparison invents nothing: the played move comes from the match’s own move table, written at import whether or not the file carried an analysis.
A database analysed with a version older than this one does not need to be re-evaluated: blunderdb repair recomputes the columns from the analyses and the moves already stored and gives those matches their PR back (see repair).
One honest caveat: a position is identified by its structure, so a position met twice — played well once and badly the other time — carries only one gap, that of its first recorded occurrence. This is not specific to this computation: an XG library has exactly the same shape.
Watched folder
The Watched folder tab asks blunderDB to look at a folder while it runs and import each match file that appears in it. Play a session in eXtreme Gammon, come back to blunderDB, and find the matches already there.
Nothing is guessed. Until a folder is named there is no watch: blunderDB does not start reading a directory because it supposed where your matches live. The Suggest button looks at the usual places on this machine and offers one only if it really exists; otherwise it says so, and naming the folder is up to you.
Three things are worth knowing before ticking the box:
Only files that appear are imported. Whatever the folder already holds when the watch starts is recorded as known and left alone: pointing a watch at four years of matches must not import all of them. To import what is there, use the folder import, which exists for that — and the two compose very well, the import first, the watch after.
A file is imported only once its size has settled. A match another program is writing grows from one glance to the next; importing it half-written would give a parse error nobody can act on. blunderDB therefore waits to see the same file unchanged twice.
The import is silent. You were studying a position when your matches arrived: taking the screen back from you would be the worst possible moment. The import runs without a window, and the status bar shows a strip giving the count of matches imported, skipped (duplicates) and failed, with a button that opens the full report if you want it. Everything else is identical to a manual import: same duplicates detected, same import batch, same automatic analysis if it is on.
The default interval is ten seconds; the floor is two. The folder is not walked recursively: a watched folder is where a tool drops its matches, not a tree to crawl. An unmounted network share does not stop the watch, nor does it make its contents pass for new when it comes back.
The same watch exists on the command line, with blunderdb import --type batch --dir <folder> --watch (see Command Line Interface (CLI)): it is the form a server, a scheduled task or a script can use.
The configuration window also provides interface display settings. An interface scale slider lets you enlarge or shrink all interface elements, which is useful on high-density screens or to improve readability. A panel position menu sets where the panels (search, matches, analysis) appear relative to the board: bottom, side or automatic (the side is then chosen on wide screens to make better use of the available space). Like the other settings, these choices are kept from one session to the next.
Guided tours and sample database
To make getting started easier, blunderDB offers guided tours of the interface. The tour catalogue opens from the toolbar or with the tour command (alias tutorial). Seven tours are available: a general tour of the interface, and tours dedicated to searching positions, reviewing matches, reviewing tournaments, the Eval panel, Anki review and statistics. Each tour highlights the relevant interface elements, step by step, opens the panel it talks about along the way, and can be replayed at any time. On first launch, the general tour is offered automatically.
The demo command loads a sample database that lets you explore the tool’s features without importing your own games: three matches (two of them grouped in a tournament) analysed by eXtreme Gammon, BGBlitz and gammonNet, three thematic collections, tagged comments (#blunder, #cube) and an Anki deck with its review log. The players, the tournament and the venue are fictional. The guided tours rely on this database when no database is open.
Editing positions
Pressing the TAB key opens the search panel and allows editing a position on the board to add it to the database or to define a position structure to search for. The distribution of checkers, the cube, the score, and the turn can be modified using the mouse (see Edit a position).
Tip
Refer to Keyboard shortcuts for available shortcuts.
The command line
The command line, integrated into the status bar, allows you to perform all the functionalities of blunderDB available in the graphical interface: general operations on the database, position navigation, displaying analysis and/or comments, searching for positions based on filters… After getting familiar with the interface, it is recommended to gradually use the command line for a powerful and smooth use of blunderDB, especially for position search functionalities.
To open the command line, press the SPACE key. To submit a query and close the command line, press the ENTER key.
blunderDB executes the queries sent by the user as long as they are valid and immediately modifies the state of the database if necessary. There are no explicit save actions required from the user.
Tip
Refer to list of commands for the list of available commands in the command line.
The command palette
The command palette (CTRL-SHIFT-P) finds, by an approximate name, what you no longer know where to look for: a command of the command line, a tab, a filter of the library or a match. The letters typed must appear in order, not necessarily next to each other, regardless of case and accents: “cbmtx” finds the cube matrix, “lyon” the matches of a tournament in Lyon.
The arrows choose, ENTER runs, ESC closes. A command runs as if it had been typed; s and ss open the command line to write the filters in it; a filter runs as from a double-click in the library; a match opens as from a double-click in the Matches panel.
Analysis Panel
The Analysis panel (CTRL-L) displays the analysis data for the current position, imported from eXtreme Gammon (XG), GNUbg, or BGBlitz. It shows the best alternatives (checker moves or cube decisions) with their equity values and corresponding errors. The d key toggles between checker and cube analysis. During match navigation, the actually played move is highlighted in the list of alternatives. Press CTRL-L or run the list command to show or hide the panel.
Under the tables, a sentence sometimes says what the played decision cost and why: “You lose 120 mMWC: the move played leaves three blots where 13/7 8/7 leaves only one.” It comes from six measurable rules — exposure, a home point made or missed, gammon chances given up, a safety that costs more than it earns, and the two directions of a cube error (doubling too late or too early, taking too loose or passing too tight).
The rule that matters is silence: the sentence appears only when a rule applies confidently, and on an error past the threshold from which the engines agree it is one. The rest of the time there is no sentence — no empty frame, no “we do not know”. A wrong explanation costs more than none: it teaches something inaccurate.
When a position has been judged by several engines, a strip at the top of the panel puts them side by side: one line per engine, with its depth and its answer — the cube verdict, or its own best move. It says first whether they agree, and it is the disagreement that justifies it: “XG says double, take; gammonNet says no double” reads at a glance, where two tables had to be compared diagonally.
An engine’s best move is the best of that engine: the candidate list is sorted by equity across all engines, so its first entry is nobody’s best move in particular.
The strip appears only when there really are several engines, and it exists in this panel alone: the Eval panel presents one decision, the embedded engine’s (ADR-0017), and a comparison would have no place there.
Moves are written as they read on the board, here as in the Eval panel: the least advanced checker moves first, and a checker that chains several dice is written only once — a 64 played with the same checker reads 24/14, and 24/14* if it hits on arrival. The detail of the chain only reappears when it says something more: a hit on the way keeps its intermediate point, 24/18* 18/14, without which the hit on the 18 would vanish from the notation.
An imported analysis’ equity follows the same rule as the Eval panel: the column states its own referential, “Equity (money)” or “Equity (match)” depending on the score of the analysed position, never a plain “Equity” silent on the scale. The Jacoby and Beaver rules active on a money-game position are also shown, in badges under the cube decision table.
Comments Panel
The Comments panel (CTRL-P) shows, adds and edits the comments attached to the current position. A position may carry several: all of them are shown, most recent first. Comments imported from XG files are automatically attached to the matching positions. Press CTRL-P or run the comment command to show or hide the panel.
Every comment that came out of a file carries a provenance badge (XG, GNU BG, BGF, or imported when the provenance was never recorded). Comments you wrote carry none: that is the ordinary case, and marking every line would be noise. Editing an imported comment makes it yours: after the edit, the sentence is yours.
That distinction shows elsewhere: deleting a match no longer destroys a position you had written on. A note lifted from the source file does still go with the match that brought it in.
The trash
Deleting a position, a collection or a comment goes through a trash: the delete does happen, but a copy of what disappears is kept for thirty days. The trash command opens the window that lists them, each with Restore and Delete.
A restored position comes back with its analysis and its comments — giving it back bare would be a restore in name only. It does not come back under its old number: the original row no longer exists, and blunderDB re-saves it by its fingerprint, which guarantees it never creates a duplicate but gives it a new identifier. A collection comes back with its list; the positions it held were never deleted — a collection is a view over them.
Anything older than thirty days is dropped by the vacuum command, never on opening a database: not running vacuum is keeping everything.
Note
The trash does not travel. An export does not carry it, and deleting a match puts nothing in it: the orphan purge that follows a match deletion is automatic housekeeping, not a user’s gesture — see the retention rule in Matches Panel.
Search Panel
The Search panel (CTRL-F or TAB) filters positions using freely combinable criteria: checker structure, cube decision type, error magnitude, dates, tags, etc. The TAB key simultaneously opens the search panel and the position editor, allowing a checker structure to be defined directly on the board.
The Search panel: numeric filters, checker structure on the board, At least / Except tabs.
To search among the positions on screen, use the ss command followed by filters (e.g.: ss nc, ss E>40). ss searches the list on screen: the results of the previous search, the open collection or the positions of the match under review, whether the command is typed directly or from the search panel (TAB). The panel’s Search in current results checkbox follows the same rule. In a collection and in a match, s is refused: it would search the whole library and replace the list on screen.
The results of an ss search run from a collection or a match are left with Esc, in a single press as soon as neither a field nor the focused panel has something to close (a move selected in the analysis, for example): blunderDB returns to the whole collection, or to the match on the move studied, and to the position left. This way back follows ss only: s, run from the search panel opened on a collection or a match, searches the whole library, and Esc no longer returns to the list left.
The panel offers an explicit control over the decision type searched for: Indifferent (no filter), Checker (checker decisions) or Cube (cube decisions). When Cube is selected, a second list specifies the sub-type: All, Double / No double (the player on roll has to decide whether to double) or Take / Pass (response to an opponent’s double). The control is synchronised with the board: editing the dice or the cube on the board updates the decision type, and vice versa. In Take / Pass mode, the cube is shown in the centre of the board at the offered value; that value remains editable.
The game phase — opening, middlegame, race, bearoff — is a label blunderDB computes from the board alone. It is never editable, and is searchable through the command line’s ph: token (ph:race, repeatable: ph:race ph:bearoff). Three of its four boundaries are the ones GNU Backgammon uses to route its networks; the fourth, where the opening stops, is a blunderDB convention: a position is still in the opening as long as neither side has moved more than four checkers off its starting points, nothing has been borne off and nothing is on the bar.
Note
The label is recomputed by the blunderdb repair command. On a database opened for the first time with this version, it is computed once, at that opening. A database whose phases were never computed returns nothing for ph: — nothing, rather than a wrong answer.
The like token ranks instead of narrowing: its presence orders the result by ascending distance to a target position — like the current one, like42 the one with index 42 — and the other tokens narrow the set it ranks, so that s like42 E>80 reads “the neighbours of 42 where I went wrong”. The distance is a transport distance in checker-pips, the amount of checker movement separating two positions, seen from the player on roll.
A neighbour is the same problem, not the same drawing: the ranking is taken inside the target’s class — the same kind of decision, the same regime (money or match) for a cube decision, and a match other than its own, since the positions surrounding it in its own game are its closest structures without ever being its neighbours. Dice, score and cube value stay outside the class; the ordinary tokens narrow on them when wanted. like42* widens the class to every kind of decision and to both regimes, never to the target’s match; like<12 drops anything beyond twelve checker-pips. A ranking that finds nothing returns an empty list and says so, rather than ten unrelated positions.
In edit mode, s like takes the drawn board as its target: you draw roughly the position you remember, you launch, and the library answers — where the search by structure demands the exact drawing. The board is then read as a position and not as a pattern: a point left empty counts as checkers borne off, which is exact for a real position and skews the computation for a drawing left half done.
Every neighbour carries its distance under the analysis tables, together with the position it is close to. That is what makes it possible to judge whether one is looking at a neighbour or at a coincidence, and it is the reason the ceiling exists. The ranking is also launched without going through the command line: CTRL-SHIFT-L, or the Neighbouring positions entry of the board’s context menu.
The n token counts encounters: n>3 keeps the positions more than three moves reach, across every match. That is a different question from “what did I get wrong” — a position met twenty times and played correctly nineteen is still the one to know cold. The count is of moves, not matches: the same position twice in one match counts twice, because those were two decisions.
The plan of play is a second derived label, beside the phase, and it answers the question a bundle of saved filters cannot ask: “show me my errors in a holding game”. Token gt:, repeatable (gt:holding gt:mutualholding), from the point of view of the player on roll — the plan the decision was being made in.
The ten recognised plans, in the order the rules exhaust them, from the most specific to the most general:
race— the rearmost checkers of both sides have crossed: no contact is possible any more. GNU Backgammon’s boundary.bearin— the player on roll is bearing in while the opponent still holds an anchor in their home board.crunch— the player on roll has at most six checkers outside their points 1 and 2. GNU Backgammon’s rule, its author’s threshold.backgame— two or more anchors in the opponent’s home board.acepoint— a single anchor, on the opponent’s ace point, at least twenty pips behind.blitz— three or more home points made, and the opponent on the bar or with a blot to hit in that home board.primevprime— both sides hold a prime of at least four points, and each has a checker trapped behind the other’s.mutualholding— both sides hold a high anchor.holding— the player on roll holds a high anchor, the opponent does not.contact— contact, and none of the plans above. The opening lands here.
Three of these rules are GNU Backgammon’s own and are sourced; the others are blunderDB conventions. The backgammon literature describes the plans of play without putting numbers on their boundaries, and no inter-classifier agreement has been published for this problem. The unsourced thresholds — three home points for a blitz, four points for a prime, twenty pips behind for an ace-point game — are therefore stated here rather than hidden in the code, and they are versioned: change them, run blunderdb repair, and the whole database is relabelled.
Note
One label is kept per position, that of the player on roll. A derived label is never editable, never exported as a truth, and a database whose plans have never been computed returns nothing for gt: — as for ph:.
The Flagged filter keeps the positions you flagged in the software the match came from. Only eXtreme Gammon produces this information, recorded move by move in the .xg file; blunderDB reads it on import and keeps it. A flagged cube decision yields two flagged positions, the double and the take/pass, blunderDB splitting in two what the source file records as a single decision.
Note
Flagging is not retroactive: matches already in the database do not carry this information, since it exists only in the source files. Simply import the relevant .xg file again — the import detects the duplicate and adds nothing but the flags, leaving existing comments and analyses untouched. A flag can neither be set nor removed from within blunderDB: for a temporary working list, use a collection instead.
The Comment filter queries the comments attached to positions in three exclusive modes. contains text searches for one or more words in the comment text (input field, words separated by ;, at least one must match); has a comment keeps any position carrying a comment, whatever its content; no comment keeps, on the contrary, the positions that are not annotated — useful, combined with an error or date filter, to draw up the list of what remains to be commented.
Note
Comments imported from a match file (XG, GNUbg) count as comments. To keep only your own, add the co:user token on the command line (co:xg, co:gnubg, co:bgf and co:unknown name the other provenances). Comments attached to a match or a tournament are not concerned either way: they annotate the match or the tournament, not its positions.
The Matches & Tournaments filter is backed by a shared picker (a modal window) instead of typed numeric IDs: two checkbox lists, one for matches and one for tournaments, each text-filterable (player, date, event for matches; name, date, location for tournaments), with All / None buttons that act only on the currently filtered subset. Checking a tournament automatically checks (and greys out) its member matches in the match list, making visible the fact that a tournament is equivalent to the set of its matches.
The search panel has three tabs along its left edge: Search (the filters), History and Saved. The History tab lists past searches with their date and command: a click selects a search and displays the associated position on the board, a double-click re-runs it. Each entry can be saved to the filter library (bookmark icon, by giving the filter a name) or deleted. The Saved tab contains the filter library: double-click a saved filter to re-run the corresponding search (see Annex: Advanced Filter Usage). The history command (alias hi) opens the search panel.
The star of a library filter pins it. Pinned filters show as chips at the top of the panel, whichever tab is open, numbered in library order: a click on a chip runs the filter, and ALT-1 … ALT-9 run the pinned filter of that rank from any screen in NORMAL or EDIT mode, without opening the panel. The filter then asks the same question as the double-click, checker structure included. The pin belongs to the database: it follows a renamed filter, disappears with a deleted one and does not travel with an export of the library.
A replayed search keeps its ranking: s like42 ranks against position 42, and s like against the board saved with the search — the one being browsed or drawn. An entry that kept no board is not replayed against the one on screen, and the status bar says so.
Tip
Refer to list of commands for the list of available filters.
Collections Panel
The Collections panel: name, number of positions, description, last modified.
The Collections panel (CTRL-B) manages collections of positions. Collections can be created, renamed and deleted. Positions can be added to them or removed (Del key, confirmation asked). Double-click a collection to browse its positions with the LEFT and RIGHT keys. The ss command searches among the positions of the open collection; Esc then returns to the collection (see Search Panel). The order of the collections, and of the positions within a collection, can be changed by drag and drop. Press CTRL-B or run the collection command to show or hide the panel.
Import: what is written, what never is
Importing a match, a position or another database adds what is missing; it does not replace what is already there.
A position is never duplicated. It is its identity — checkers, cube, dice, score — that recognises it, never the file it came from: the same position met in two matches stays a single row.
One analysis per engine. eXtreme Gammon, GNUbg, BGBlitz and the embedded evaluator coexist on the same position, and the Analysis panel shows where each one came from. Importing one never erases another.
An imported analysis is never recomputed. blunderDB stores it as-is, with its level label (“3-ply”, “XG Roller++”, “Book”), its equities, its errors, its probabilities and the roll’s luck. The rule is “an evaluation only fills a gap”: automatic analysis after import only visits positions with no analysis at all, and Re-analyze stale positions leaves untouched any position carrying an imported analysis (see Configuration).
Reimporting the same file rewrites nothing. The match is recognised as already present; only the flags set in the originating software are added, without touching comments or analyses.
What blunderDB never writes: a recomputed luck value — it is read from the source file, or stays unknown — and a rollout, whose data it neither opens from a
.xgfile nor knows how to produce.
A collection can be living: its content is no longer a hand-made list but the result of a search, re-evaluated every time it is opened. The ◇ button at the head of the collection makes it living with the last search run; ◈ says it already is, and the same button gives it back its list. Nothing is destroyed by making it living: the positions it held are still there when you go back.
A living collection whose query carries a token this version no longer knows refuses to open, and says so, rather than returning the whole database. That is the one failure a saved filter must not have: widening in silence.
Matches Panel
The Matches panel (CTRL-Tab) lists imported matches. Double-click a match (or press ENTER) to navigate through its moves. The m command resumes navigation in the last visited match.
The user can:
browse through the moves of a match using the LEFT and RIGHT keys,
switch between games using the PageUp and PageDown keys,
display the move analysis (checker and cube) by pressing CTRL-L,
toggle between checker move and cube analysis with the d key,
see the actually played move highlighted in the analysis,
search among the positions of the match with the
sscommand (e.g.:ss E>80); Esc then returns to the move studied (see Search Panel).
The last visited position in each match is saved and restored automatically. Press CTRL-Tab or run the match command to show or hide the panel.
A row’s ⊕ button enriches that match from a file. There is nothing new behind it: re-importing the same match in another format already enriches it in place — the canonical hash recognises that it is the same match, and the analyses and comments of the second file complete the first. What the button adds is that it can be found: nobody guesses that an import is also an enrichment. The report that follows says which of the two happened — “enriched: 1” rather than “imported: 1”.
Each match can be exported as a Jellyfish .mat transcript via the ⬇ button in the match list or the .mat button of the match sheet.
Clicking a match opens its detail pane. Its Transcript tab lists the moves game by game, and clicking a move takes the review there. Every move carries its severity: ? for an error, ?? for a blunder, a coloured rule in the row’s margin, and the move’s cost in equity when hovering over the mark. The thresholds are the database’s own (Configuration), the ones the statistics count with. A move is judged as it was played: the same position played twice in the match receives two judgements. A move the analysis does not score carries no mark.
Each game’s header counts its marks, whether the game is expanded or not: you can see without opening it which game holds the blunders.
The Merge players button in the panel toolbar opens a window listing all the player names in the database with their number of matches: select the spelling variants of the same player, choose the canonical name to keep, then merge. Useful to unify per-player statistics when the same player appears under several names.
When a match is open, an information bar appears above the board: it recalls the players involved (player 1 versus player 2) as well as the match context (event, location, round, date and match length, when this information is available). This bar is also shown outside match mode: when a studied position (from a search, a collection or a direct access) comes from one or several matches, it indicates its provenance — the first match concerned and, where applicable, a “+N” badge listing the others on hover. A position imported on its own, which no match references, shows nothing.
When opening a database that contains matches, the Matches panel is shown right away and the review starts directly on the first position, so you can begin navigating immediately.
Note
A database can be opened for writing by only one window at a time. If you open a database already open in another blunderDB window, it opens read-only: navigation, search and analysis remain possible, but any modification is disabled and the title bar shows “[read-only]”.
Tip
Refer to Keyboard shortcuts for available shortcuts.
Transcription Panel
The Transcription panel (CTRL-SHIFT-T, transcribe or tr command) is where a match one has in front of one — a score sheet, a video recording — is typed in and turned into a match of the library. What is typed is a draft: it lives in the database, it closes and reopens, and it enters neither the statistics nor the searches until it has been saved as a match.
The panel opens on the library’s list of drafts: last modified, players, match length, number of actions, and the match already produced (# followed by its id) or the words “no match”. A click opens a draft, and the Drafts button in the bar comes back to the list. The New transcription button unfolds the creation form.
The list is walked from the keyboard too: DOWN and UP (or j and k) move the highlight, ENTER opens the highlighted draft, n unfolds the form. The first draft is highlighted on opening and it is the most recently modified one: picking up yesterday’s work therefore takes two keys, CTRL-SHIFT-T then ENTER.
The form asks for one thing only: the match length. The value 0 means a money session and brings up the Jacoby and Beaver boxes. The field opens on the length of the last modified draft, or on 7 when the database holds none. Player names are not asked for: the draft names the sides Player 1 and Player 2, and the list shows “Unnamed”.
Everything derived from what has been typed — the match length (or “Money”), the score, the Crawford mention when the current game is one, the game number, the state of the cube — its value, centred or in the name of whoever owns it — and the side on roll — is shown in the match bar, above the board: that is where the eye already is when one wonders who is on roll. The expected action is spelled out in the status bar: “Kévin’s dice”, “Alice’s answer to the double”, “roll again”.
The draft bar, at the top of the panel, carries only the gestures that take the draft out of itself, the two undo arrows and the orientation of the board.
Player 1 stays at the bottom of the board, whoever is on roll. A match being transcribed is a game unfolding: the roll changes hands at every half-move, and following it would flip the board from one turn to the next — the checkers just looked at would move to the top and the eye would make the journey again at every roll. Who is on roll is read from the dice, which change sides. The ⇅ button of the bar flips the board and shows player 2 at the bottom; it does not modify the draft, and the display comes back the right way up when the draft is closed. Not to be confused with the Swap players button of the Metadata pane, which swaps the two players in the document itself.
The Metadata button on the bar unfolds the draft’s header, at any time: the names of the two players — autocompleted from the players in the database —, the event, the location, the round, the date (today by default), the transcriber (the database’s user by default) and the tournament the match will be attached to when it is saved. No field is required: a draft with no names saves and exports all the same, with empty headers. The Swap the players button exchanges the two names, gives every action to the opposite camp and turns the board around: it is the same match, read from the other side.
The match length is changed in that same pane, at any time: the score, the Crawford game and the referential — money play when the length is 0, and the Jacoby and Beaver boxes then appear — are recomputed from one end of the draft to the other, and the actions recorded after the match was won are marked "past the end" without a single one being removed. The length is part of a position’s identity: after a save, changing it and saving again writes brand-new positions, to be analysed, and the old ones disappear as soon as nothing holds them any more.
Below the bar, the draft occupies three regions: the mouse-target palette, the candidate plays and the transcript. They are laid out according to the width of the panel. In a wide panel — the bottom dock — the three sit side by side, the palette on the left. In a medium panel, the candidates take the top and the transcript comes beside the roll triangle, in the room the triangle leaves to its right. In a narrow panel the three follow one another: candidates, palette, transcript — the triangle and the transcript do not fit side by side there without cutting the transcript’s second column off, and widening the dock by a few dozen pixels is enough to bring them together. In every case the rule is the same: nothing comes between the two roll boxes and the first candidate row, and at least five candidates can be read without scrolling anything.
The palette shows the two dice as they are entered; a click on them clears the roll, like BACKSPACE. A game opens with one die from each side: the higher one starts and plays both dice without having to enter them again; a tie is recorded as it stands and another opening is expected.
As soon as the second die falls, every legal play of the roll is listed, ranked by the built-in engine, the first preselected and its arrows drawn on the board. The list gives the play, its equity and its error against the best one: transcribing means recognising the play one saw, not judging it — the Evaluation panel is there for that. This ranking is an evaluation: it is shown, it is never written to the library. When the engine is unavailable the plays are listed unranked and the list says so at its head.
The wheel selects the next or previous candidate, over the list as well as over the board: the eye stays on the board and the arrows scroll past, which recognises a play faster than reading its notation. A click on a row selects it, a double-click validates it.
The triangle of the twenty-one rolls sits under the two roll cells, beside the keyboard and not in its place: two digits remain twice as fast as a click, and the triangle is there for whoever transcribes with a hand on the mouse. One cell per roll, never two: 3-1 and 1-3 are the same roll.
A move played on the board spares you reading the dice. As long as no die has been entered, a click on a checker then on its destination — or a drag from one to the other — plays the move on the board, constrained to the legal plays; the destinations the chosen checker offers light up. The two dice follow from the steps: playing 13/7 then 8/7 says 6-1 without a digit having been typed, and the action is recorded as soon as the move is complete. Backspace undoes the last step, a digit abandons the move and goes back to entering the dice, and a double-click off the board starts it again. When several rolls make the same move — a bear-off several dice cover, a die that cannot be played — nothing is recorded and the triangle leaves only those rolls clickable: the roll is never guessed in place of the person watching the game.
With both dice entered, the board plays too, constrained to the legal plays of that roll — at the end of the document as on an action being reviewed, whose dice the cursor has loaded. Each step played keeps in the list only the candidates that contain it, the first of them preselected: this is the gesture for a move far down the list, where walking down to the twelfth candidate costs thirteen keys. A complete legal move is recorded at once, with the dice as they were typed; on an action being reviewed, it replaces it.
An illegal move is transcribed as it was played, with no button and no change of mode. With the dice entered, a drag that no legal play offers puts the checker down where it is released — even from a point no legal play leaves from, provided it holds a checker of the side on roll. The move then leaves the rules: the rest is played freely, by click as by drag, the candidate list gives way to a line that says so, and nothing is recorded before ENTER, which writes the dice entered, the steps and the board reached. Backspace undoes the last step; undoing the only step outside the rules brings the list back. Without dice entered, the drag stays constrained: an illegal move does not say which roll produced it.
The move can also be typed on the keyboard, in the transcript. A double-click on the cell of a move — or of a dance, of an unrecorded move — turns it into a field, prefilled with its notation. Only the move is typed there, 13/7 8/7*, bar/22 or 6/off: the dice are those of the cell. ENTER records it in place of the move written, ESCAPE closes the cell without writing anything, and a text that names no move leaves the field open. The dashed cell of the entry in progress opens the same way, as soon as both its dice are entered.
A move entered by the free drag or by notation that happens to be legal stays an ordinary move — the comparison is made on the board reached, never on where the gesture came from; otherwise it is marked “illegal move” in the transcript, and the .mat export warns before writing the file, without ever refusing.
On the dice line, the Double, Take, Pass, Resign row takes the four cube gestures to the mouse: they are, with the two dice, the five possible answers to a single question — what did the side on roll do? It says whose turn it is: the side on roll announces — double, resign — or the other side answers — take, pass; never all four at once, and a button whose gesture would answer nothing stays off. The keyboard, for its part, never refuses anything: a button that is off is a target one does not offer, not a forbidden gesture. “Resign” records nothing yet: the row becomes the three levels — single, gammon, backgammon — and “Cancel”, which doubles the ESCAPE key. The cube drawn on the board is the second target of these gestures: a click on it offers a double. Facing an offer it does not answer — take and pass are two symmetric answers and live together in the row, one click each.
The status bar says what the draft expects, in a word: the dance recorded on its own, the tie to roll again, the answer expected to a double, the level expected after a resignation, the correction in place, the move “to review” whose roll has changed. It also answers there the gestures that have nothing to do — “nothing to undo”, “no action under the cursor” — for a second and a half. The inconsistency an action left behind it is flagged at the head of the transcript instead, where the offending cell is.
A game ends with a pass, with a resignation or by bearing off the fifteenth checker (single, gammon or backgammon, multiplied by the value of the cube). The score, the Crawford game and the end of the match then appear in the match bar, and the opening of the next game is expected.
A game’s score is the one the previous games give, unless it was declared otherwise at the table. A double-click on the score in a game’s header, in the transcript, turns it into a prefilled field: type the score the game was played at — 3-2, 3–2 or 3 2 —, ENTER records it, ESCAPE closes the field without writing anything, and a field emptied then confirmed goes back to the derived score. The game is played at that score: the Crawford game, the end of the match and the following games follow from it, and both the saved match and the .mat file carry it. A score that differs from the derived one is marked, the tooltip gives the derived one, and the game’s opening carries the inconsistency “inconsistent declared score”. In money play there is no score to declare.
The transcript occupies the right half of the panel: one column per player, one row per turn, the cube action and the end of the game in the column of whoever acted. The cursor’s cell is framed; moving the cursor brings the board back to the position of the action aimed at and lists its candidates, with the play that was recorded selected. An inconsistency (illegal move, double turn, impossible cube action, action past the end of the match, inconsistent dice, unrecorded move, inconsistent declared score) decorates its cell and is named in a tooltip. The unrecorded move is the case of a .mat file read back: gnubg writes ??? there when it did not keep the play, the roll is known and the play is not, and putting the cursor on that cell offers the plays of that roll to fill it in. A double turn leaves an empty cell, framed in dashes, in the column of the side whose turn is missing: the cursor stops there, a click takes it there, and that is where the missing turn is typed — a deleted decision, for instance. Games fold away; the cursor’s is open.
What is being typed is drawn in the transcript, in dashes, in the exact place where it will be written: the dice as they come in, the notation of the play as soon as it is selected, and in the column of the side the action belongs to. A correction covers the cell it replaces, an insertion opens a cell between its two neighbours, a fresh entry appears at the bottom of the game in progress. Nothing is written into the draft before the validation; what is read and what the document will say never diverge.
Correcting is typing on the cell you are on. With the cursor on an action, a digit starts its roll again in place, and the four cube gestures count as corrections too: on a pass, t — or the Take button — writes a take in place of the pass, with no need to delete it and then insert. The game then takes its course again: a cell opens just after the take, on the doubler’s side, and the rest of the game is typed there as usual, inserted in front of the opening of the next game, until the game ends. The same keys fill the cell an insertion has just opened: i then d inserts a double in front of the action aimed at.
Going back to the last action is going back to where the transcription is being written. A digit typed on it still corrects its roll, but once that roll has been typed again, the next digit validates it and opens the following decision; ENTER validates it likewise. The following decisions are then added after it, as the first time.
Typing the two dice again on a game’s opening cell decides once more who starts: player 1’s die is typed first, player 2’s next, and the higher one wins — the big die first, the turn goes to player 1, at the bottom of the board; the small die first, it goes to player 2, at the top. The validation is immediate on the second die, as for a fresh opening. The game’s first checker play follows the new winner and changes column with it: its side had not been chosen, it was proposed by the opening — the winner of the roll plays both dice without typing them again. It is the only action that correcting an opening moves: the rest of the game keeps its sides, and a play already given to the other player with s is not taken back.
An insertion in the middle of the document goes on inserting: the validation opens an empty cell after it, and the next action is inserted in its turn instead of overwriting the one that follows. That is what makes it possible to catch up the whole end of a game — a pass that should have been a take — without losing what has already been typed of the next game. The end of the game, or moving the cursor, puts an end to the insertion: the cursor then lands on the next opening.
Del (or x) removes the decision being edited and steps back onto the previous one, ready to be corrected: on a written cell, the action disappears; on an open insertion or a roll typed at the end of the document, it is the entry that is abandoned. Pressing Del repeatedly thus goes back up the transcript, erasing as it goes. The actions that follow keep their side, and the double turn a deletion leaves is marked without the cursor being brought back to it.
A right click on a cell opens the corrections of that action — insert before, insert after, delete, change side — and brings the cursor onto it on the way; these are the same gestures as the i, a, x and s keys, and the browser menu is suppressed only there. They have no buttons elsewhere: a button acting on “the action under the cursor” would aim at a cell one may not see, where the right click names its own.
The draft bar carries the gestures that take the draft out of itself. “Create the match” (CTRL-ENTER) writes it into the library, and then becomes “Update match #n”: the match is replaced under the same id, and the analysis of the new positions only starts at once, with its progress and its cancellation in the status bar. Beside it, the bar says where that match stands — no match, up to date, or behind the draft. It says nothing about the safety of the draft itself: it is written to the library after every action, there is nothing to watch.
“.mat text” opens the Jellyfish file as it would be written, in a window wide enough for its columns to stay aligned, with a button to copy it. “Export .mat” writes that same file to disk. “Close the draft” deletes it after confirmation; a match already created stays in the library, for good. The two arrows ↶ and ↷ undo and redo, like CTRL-Z and CTRL-SHIFT-Z.
If the analysis of a transcribed match was interrupted — the application closed while the batch was running — the status bar says so the next time the database is opened and offers to finish it. Nothing is kept about that interruption: the offer comes back for as long as positions remain to be analysed, and the batch that restarts covers only that match, never the whole library.
A draft carrying inconsistencies is saved all the same, after a warning: nothing is refused. An illegal move is exported as it was played, with the warning that gnubg and XG will flag it (“Invalid move”) and diverge from there.
The Matches panel recalls every draft in progress above the list of matches: the “Draft in progress” line opens the Transcription tab.
Tip
Refer to Keyboard shortcuts for available shortcuts.
Tournaments Panel
The Tournaments panel: one tournament per row, number of matches, reference player’s PR.
The Tournaments panel (CTRL-Y) groups matches into tournaments for organised tracking and per-event statistical analysis. Tournaments can be created, renamed, and deleted; matches can be assigned to them. Stats panel statistics can be filtered by tournament. Press CTRL-Y to show or hide the panel.
Tournaments fill themselves at import time. XG, GnuBG and BGF files name their event; when a new match is imported, blunderDB files it under the tournament of that name, creating it if it does not exist yet. The tournament’s date and location are left empty — this panel is where they are filled in. A match already in the database is never refiled: re-importing its file does not undo what was arranged by hand.
The PR column of each tournament shows the PR of the reference player — that is, the player appearing in the greatest number of the tournament’s matches (in case of a tie, the one who made the most decisions). The PR therefore does not mix your play with your opponents’: for your own tournaments, it reflects your performance alone. The reference player’s name appears in a tooltip when hovering over the value.
Directing a tournament
blunderDB can direct a tournament, not merely file it away. The directing is carried by the Nicomaque engine, by Nicolas Harmand: it holds the format, the pairings, the brackets and the standings; blunderDB gives it an interface and keeps its matches. The ⓘ button on the panel’s bar recalls that credit and leads to the engine’s repository and documentation.
A directed tournament is chosen in the Tournaments Panel panel (CTRL-Y, direct command): open a tournament, then Direct this tournament. A tournament already directed shows its state beside its name and the button becomes Open. While a direction is open, the main area shows the tournament in place of the board — blunderDB’s only exception to that rule; switching to any other tab brings the board back.
A direction has three states: in preparation while no match has been launched, under way afterwards, closed once the standings are frozen. Reopening a closed tournament is possible, and asks for confirmation: the final standings stop being final.
Everything decided is written into a journal, and nothing else is. The standings, the brackets, the proposals and the warnings are replayed from that journal at every open: a power cut costs nothing, and a correction never erases what happened — it is added to it.
The Directing page
This is where the director spends most of their time. From top to bottom: the engine’s warnings, which stay visible and never block anything; the table grid, whose header carries the Print the sheet button for the pairings; the last decision; the proposal queue; and the free players. The grid comes before the queue: a long queue never pushes it off the screen.
A proposed round can be announced before it is launched: Upcoming round…, next to Print the sheet, asks for the date and time to print (“Monday 21/09, 8 pm”) and prints the sheet of the pairings in the queue, marked “announced”. Nothing is launched or written to the log: the round is launched on the day, at its time. A pairing waiting for a free table carries a dash instead of the table number.
At the top of the tournament view, the clock strip fits on one line: the time, the time elapsed since the first launched match, the matches played and running, the observed pace in minutes per point against the planned pace, the slow matches, the next break and the estimated end. The estimated end is the engine’s forecast: it replays the log, finishes the tournament fifteen times at the planned pace, and the strip gives the median, pushed past the declared breaks. A night that is not declared as a break therefore counts as play. A time that is not today’s carries its day.
From the second day on, the elapsed time gives way to the day of play (the day of the first launched match is day 1) and to the playing time: the time during which at least one match was running, without the nights or the gaps when no table was playing. A closed tournament has no clock strip any more.
A proposal is confirmed with one click on Launch. Launch all confirms, in two clicks, the proposals that have a table, after showing their list; Confirm sits at the head of that list. Pairings without a table stay in the queue, marked “no free table”: in rounds mode, a round stays open until all its players are engaged in it. “Ignore for now” writes nothing: the engine is deterministic, and the proposal comes back identical at the next call. Pair by hand is offered at all times — the engine proposes, the director decides.
A match paired by hand without a table number takes the first free table. If the room is full, it is started anyway and its cell appears at the end of the grid, “no table”, until it is moved to a table.
A proposal may carry a remark from the engine: no free table, or a match expected to end during a break. It stays launchable in both cases. When a phase runs in micro-rounds, the queue shows the time left before the next batch; at the deadline the proposals appear by themselves, and nothing launches on its own.
The result card
A click on a busy table opens the match’s card. It shows two large targets: the names of the two players. Clicking the one who won records the result — two clicks in all, table included. The winner is the only thing required; the score is free, either one, both or neither.
The card’s ⋯ button unfolds what is rarely used: the forfeit, a free remark (“ran out of time”, “retired because of…”), moving the match to another table, and cancelling it.
A typing mistake seen at once is taken back in two clicks below the grid: Correct the last decision, then the right winner (CTRL-Z opens the same take-back). An older correction is made from the history.
The players
The Players tab enters, corrects and withdraws. The entry field keeps the focus and empties after each name: twenty players are entered from the keyboard alone. Autocompletion offers the players of the database; choosing one fixes the exact spelling their matches carry and pre-fills their rating with their PR.
The directory gathers the entrants of every directed tournament of the database, de-duplicated by name, with the club and the rating of their last entry. It is never stored: deleting a direction takes its entrants out of it. Taking the entrants of a previous tournament is one click, whatever their number; the directory is copied as CSV or saved to a file (Save…), and reads back pasted.
A doubles event enters pairs: the Pair box adds the partner’s name, club and rating. The pair plays under the name “A / B”, which its matches carry too; its rating is the mean of the two, and a value typed in Pair rating replaces it. The directory keeps the two persons, never the pair.
Before Enter them, the preview of a pasted CSV lists the unreadable lines — no name, no separator when the other lines have one, a rating that is not a number — and the duplicates, within the paste or with a player already entered. A duplicate is not entered unless its box is ticked.
A latecomer arriving after the draw takes a free bye if the bracket still offers one, and the interface writes beside the field where they will enter before it is validated. With no free place, they are entered all the same and the view says which phase they will enter. No draw already made is ever redone.
A withdrawal happens now or after their current match, depending on whether the player leaves at once or finishes what they are playing.
A player missing a round does not need to be withdrawn: Mark absent, on their row, opens a small form under their name — until a time (pre-filled with the next hour), or, when the current phase is a round-by-round Swiss, until round with its number. The engine then simply stops pairing them, but their rank, lives and place in the bracket stay whatever they have earned — an absence is not a forfeit. Return, on their row, lifts the absence in one click, before or after the declared deadline.
Correcting the entry of a withdrawn player — their name, club, rating — leaves them withdrawn. Their return is a gesture of its own: Reinstate, on their line. They are paired again, with the results and lives they had when they left; the matches lost by forfeit at their withdrawal stay lost.
Brackets, slots, standings, history
The Brackets tab draws the brackets and, for a Swiss, the lives table. A match already played carries its result there; a match the engine complains about is marked in place.
The Slots tab links the tournament to the library. Every match of the tournament is a slot, which can be filled in two ways: transcribing the match on the spot (Transcription Panel), or attaching a match already imported. Nothing is attached by inference: a coincidence of names is a suggestion to accept, a partial match is not even suggested, and if the file of an attached match contradicts the recorded result, the disagreement is shown without being resolved — during a tournament, the director’s word stands.
The Standings tab shows the current standings, section by section, with each player’s record (wins–losses) and the prizes when a prize fund is set. Two tied players share the place and the prize. A withdrawn player keeps the rank their run earned, marked “withdrawn” with their record or the point in the bracket where they stopped. Close the tournament freezes the final standings. The standings are copied as CSV, in the language of the interface, or saved to a file: Save… opens the system dialog on a proposed name, the tournament followed by the word “standings” and today’s date, and the file holds exactly the copied CSV. On the command line, blunderdb tournament standings writes the same CSV.
Closing with no match under way is one click. With matches under way, the Standings say how many and wait for a second click in place: closing freezes the standings without them, and their result can no longer be entered. Reopen is confirmed the same way; the final standings then stop being final, and the reopening stays in the log.
The History tab is the journal in plain words: one line per decision, in order, filterable by player or by match. It is what a director re-reads after a dispute, and it is where an older decision is corrected or annotated.
Correct, on a result’s line, opens below it the same take-back as the last decision: click the right winner, with the score if needed. The original result stays in its place in the log, the correction is added to it, and the standings take it into account at once.
The settings
The Settings tab opens on named formats: six club tournaments ready to use, the first of which is recommended. Choosing one is enough to begin; the fields stay editable afterwards.
Set here: the phases and their match length, the lengths round by round of a bracket (“15, 13, 11” reads from the last round backwards), the number of tables, the planned pace in minutes per point (8 by default; the clock strip and the estimated end start from it), the breaks of the day, the prize fund (entry fee, the club’s retention, a scale per section) and the display folder.
A bracket has three boxes: Consolation (its losers play a second bracket, a separate section in the standings), Reconciliation (the consolation winner plays the main bracket winner; the box only appears with the consolation) and Recharge (in double elimination, the main bracket winner must be beaten twice; the box only appears with the reconciliation). A consolation has standings of its own only with a prize scale: as long as the Consolation section’s scale is empty, the Settings say so. A Pools phase is set by the size of its pools (4 by default) and the number of qualifiers per pool (2 by default).
The settings stay reachable during a tournament: lowering the switch at 22:00 to finish earlier, adding a consolation on the Saturday evening, as long as the bracket has not been drawn. What is then frozen is greyed out with its reason: the format of an opened phase, the number of lives it has handed out and, once a phase is drawn, its pool size and number of qualifiers. Saving during a tournament first shows the list of what will change, and asks for confirmation. What the engine refuses appears there with its reason, and nothing is saved: that is the case for the consolation, the reconciliation or the recharge of a bracket already drawn.
A table with a broken board is declared in Tables out of service: its numbers, separated by commas (“7, 12”). The engine no longer assigns it, and the grid shows it as out of service; lowering the number of tables would remove the last one, not the broken one. If a match is under way on a table taken out of service, the list of what will change says so and names a free table to move it to, from the match card.
Seeding is an option, off by default: the engine’s study concludes “no protected seeds”, which is the current culture of backgammon. Switched on, players are placed by rating.
The shared room
Several events played in the same room — a main event, a speed, doubles — are grouped in a Rencontre, at the bottom of the Settings: Create and attach… opens the room with its number of tables, Attach… adds a directed event to it. Attaching first shows what will change: the event’s tables become the room’s. Detach from the rencontre gives the event back to itself, with its log and its tables; Delete the rencontre moves it to the trash and detaches its events without deleting any.
In a Rencontre, no event proposes a table where another is playing: the grid shows those tables as in use, with the event’s name, and a pairing with no free table waits. A table out of service is ticked once, in the Rencontre, and applies to every event; the number of tables, the tables out of service and the breaks changed in one event’s Settings apply to the room as well, and the list of what will change names the other events.
Opening the Direction of an event in a Rencontre opens the others too: a tab per event appears at the top of the Direction, each with its summary — pending proposals, matches under way, an alert if there is one. Switching events is a click on its tab, with no confirmation; the event left behind does not close and replays nothing, it stays exactly as it was left. A tournament outside a Rencontre has only one event: no tab to show.
One person may play several events of the Rencontre: two Participants with the same name are the same person, and for a doubles pair each of its two members counts. While they play in one event, the others do not propose them, and their Waiting list says where they play: “playing in main, table 4”. Pairing by hand is still allowed: the match starts, and its cell in the grid carries the same note.
The hall display
A tournament is watched. Choosing a display folder in the Settings is enough once and for all: blunderDB rewrites a standalone HTML page there at every event, and the page reloads itself. It opens offline, on a second screen or projected, and loads no outside resource. Open in the browser shows it at once.
The pairing sheet goes on the welcome desk: one click on Print the sheet opens the system’s print dialog. One line per match — the two players, the length, the table, two empty boxes for the score — and a round of thirty-two players fits on one A4 page.
A Rencontre has its own output folder, chosen once in its Settings panel with the same Choose folder button: blunderDB writes index.html there, the room’s wall page — one line per table, whichever tournament occupies it, with each tournament’s announced rounds and a link to its own page — and each attached tournament writes its own into a subfolder. A gesture in any tournament of the Rencontre regenerates the wall page; an attached tournament’s own folder is kept but ignored as long as it stays in the Rencontre.
Outside the interface, the blunderdb tournament sub-command reads a directed tournament without a graphical interface: list, verify, standings, page and export; page --rencontre writes a Rencontre’s wall page instead of a single tournament’s page. See Command Line Interface (CLI).
Stats Panel
Introduction
The Stats panel lets you analyse your play level and track your progress over time using the positions imported in the database. It computes and displays PR (Performance Rating) and MWC cost (Match Winning Chance cost) for all positions or a filtered subset.
The Stats panel is especially useful for:
gauging your level against the level bands (World Class, Expert, Advanced…) using the global PR;
tracking your progress tournament by tournament or match by match using the Progression tab charts;
identifying your weak spots: the Errors tab shows the breakdown between checker plays and cube decisions, and the distribution of error magnitudes;
compare the players in the database with one another, one row per player, through the Players tab — useful for following an entire competition;
navigating directly to the relevant positions by clicking any indicator (drill-down).
Opening the panel
To open the Stats panel:
Press CTRL-D.
Type the
statsorstcommand in the command line.
Note
The panel refreshes automatically whenever the filter is changed. It does not recalculate statistics on a simple PR ↔ MWC toggle: both metrics are computed simultaneously by the backend.
Filter bar
The filter bar at the top of the panel restricts the computation to a subset of positions.
Player perspective
The Player drop-down filters statistics to the analysed player. blunderDB automatically selects the player whose name appears most often in the database — changeable at any time.
Tip
Changing the player does not cause any data loss; simply re-select the previous player in the list.
Available filters
Tournament(s) — restrict to one or more tournaments. Multiple tournaments can be selected simultaneously.
Dates — time range (From … To). If only the start date is set, more recent positions are included.
Decision type — All / Checker plays / Cube decisions.
Match length — restrict to specific match lengths (1, 3, 5, 7, 9, 11, 13, 15, 21 points). Multiple lengths can be combined.
A Reset button clears all filters (except the auto-detected player).
Note
Filters are saved in the blunderDB configuration (config.yaml) and restored on the next launch.
PR / MWC toggle
The PR / MWC button at the top of the panel toggles the metric displayed across all tabs.
PR (Performance Rating)
The average equity error per counted decision, multiplied by 500 as eXtreme Gammon and GNUbg do: a PR of 5.0 is worth 0.010 of lost equity per decision, i.e. 10 millipoints (mpt). The exact counting rule — which decisions enter the denominator, how the score is converted — is the one in Annex: Statistics model — XG / gnuBG / blunderDB alignment.
The level bands the panel draws behind the progress curve are an indicative marker specific to blunderDB: no publication is authoritative on these thresholds. The upper bound of each band is exclusive: a PR of 4 is Advanced, not Expert.
Level
PR
World Class
< 2
Expert
2 – 4
Advanced
4 – 6
Intermediate
6 – 9
Casual
9 – 12
Beginner
≥ 12
MWC cost (Match Winning Chance cost)
Cumulative match winning probability lost due to errors, over the full filtered dataset. Computed using the Kazaross-XG2 MET embedded in blunderDB.
Caution
MWC cost does not apply to money-game positions (with no match stake). Those positions are excluded from the MWC computation. MWC values depend on the MET used; they are not directly comparable across software using different METs.
The PR ↔ MWC toggle is instant: no backend recalculation is performed.
The HTML report
The HTML report button in the panel’s header produces a self-contained document: a single file, with no external image, no remote stylesheet, no script. The diagrams are inline SVG, drawn by the same renderer as the board on screen, with your palette. It opens in any browser, travels by e-mail, and prints to PDF from the browser itself — which avoids embedding a PDF generator to produce what everybody already has.
It carries the current scope’s figures (positions, matches, counted decisions, global, checker and cube PR), then the ten most expensive decisions, each with its diagram, its cost, the match it comes from and the best move when an analysis gives one.
The report carries the Stats panel’s current filter. A report that does not state its scope is a report whose figures mean nothing: set the filter — a tournament, a date range, a player — before producing it.
Dashboard tab
The Dashboard tab gives a summary view of key indicators.
The Dashboard tab: global PR, checker PR, cube PR.
Level cards
Three cards display the PR (or MWC) for:
PR Global — all decisions (checker + cube);
PR Checker — checker plays only;
PR Cube — cube decisions only.
Clicking a card loads the positions in the corresponding subset into the analysis panel (drill-down).
Note
The total number of decisions is shown at the bottom of each card on hover.
Rolling PR over last N decisions
A row of PR (or MWC) values computed over the last N decisions (N = 5, 10, 50, 100, 250, 500, 1000) lets you measure the recent trend. Greyed values correspond to an N larger than the number of available decisions.
Clicking a value loads the corresponding last N positions.
Top blunders
The list of the 10 worst errors (or MWC cost), sorted by descending magnitude. Clicking a row loads the relevant position in the analysis panel.
Progression tab
The Progression tab shows how your level evolves over time.
At the top of the tab, a goal: “PR < 5 within twelve weeks”. A target, a deadline, and a trend that says where you are heading — nothing more. A goal that started grading, congratulating or reminding would be a different feature, not this one.
The Suggest button proposes a target from your current level: the lower bound of the band you are in, that is, the entry into the next one. Proposing “a bit better” would be anchored to nothing; proposing a band says something — going from intermediate to advanced can be seen and told.
The trend is a least-squares fit over your matches’ PR, projected to the deadline. It refuses to speak below three matches: drawing a line between two points would be a claim that cannot be held. And the sentence says so every time — a trend is not a prediction.
The goal is stored in the database’s metadata, not in the configuration: it is about that library, so it follows the file rather than the machine. No schema change: metadata is already a key/value table, readable by blunderdb info as by the daemon.
Tournament line chart
A line chart displays the PR (or MWC) for each tournament (X axis: tournament order, Y axis: metric value). Colour bands materialise the level thresholds.
Clicking a point on the chart opens a context menu with two options:
Open tournament — opens the tournament in the Tournaments panel.
Open positions — loads all positions from the tournament into the analysis panel.
Match scatter plot
A scatter plot represents each match (X axis: date, Y axis: PR or MWC). Point size is proportional to the number of decisions in the match.
Clicking a point opens a context menu:
Open match — opens the match in the Matches panel.
Open positions — loads all positions from the match into the analysis panel.
Errors tab
The Errors tab breaks down error sources.
The Errors tab: PR breakdown by cube action.
Breakdown by cube action
A bar chart displays the PR (or MWC) for each type of cube decision: NoDouble, DoubleTake, DoublePass, TooGood. Each bar also shows the number of decisions and the blunder rate in a tooltip.
Clicking a bar loads the positions matching that cube action, only those with an error (drill-down).
Direction of cube errors
The breakdown above says how much cube decisions cost; this table says in which direction they go wrong.
A cube position carries two decisions taken by two different players, presented here as two rows:
Offer — the player holding the cube doubles or does not. Their errors are the missed doubles (a double was called for) and the premature doubles (it was not).
Answer — the player being offered the cube takes or passes. Their errors are the wrong passes (a correct take was passed) and the wrong takes (a correct pass was taken).
The two rows are deliberately kept apart: a player can perfectly well double late and take loosely, and a single figure would call that “balanced” while losing both halves of the information.
Each cell shows the number of decisions; the tooltip gives the cumulated equity lost. Clicking a cell loads the matching positions. A cell at zero is not clickable.
Note
This table counts decisions, it passes no judgement. At what gap a tendency deserves to be named depends on the sample size and on a point of reference, neither of which the engine holds.
Checker / Cube comparison
A comparison chart places checker plays and cube decisions side by side. Clicking a bar loads the positions in the subset with an error.
Error magnitude histogram
A histogram distributes errors by magnitude in millipoints (mpt, buckets: 0–5, 5–10, 10–25, 25–50, 50–100, ≥ 100). Clicking a bar loads the positions in the bucket.
Breakdowns tab
The Breakdowns tab slices the same decisions the global figures count along four axes. None of them redefines what counts as a decision: that would be a second PR wearing the same name.
By game phase — opening, middlegame, race, bearoff. This is what answers “my PR in the race versus my PR in contact”. The label is computed from the board (see Search Panel); a database whose phases were never computed files everything under Unclassified, and
blunderdb repairfills it in.By plan of play — race, blitz, holding, backgame, prime vs prime… This is the breakdown the classifier exists for: “where do I lose the most?”, plan by plan. The same derived label as the phase, the same caveats, and
blunderdb repairfills it the same way.By tag — the
#wordwritten in the comments. A position may carry several: these rows do not sum to the total, and the panel says so under the table. A tag labels; it does not partition.By score — both sides’ away score, read from the side of the player on roll, that is from the side of whoever is deciding. The Money row is money play. A cell with fewer than ten decisions is greyed with its count still visible rather than hidden: too few to read, but the omission stays auditable.
Note
The Crawford game is not distinguished: blunderDB does not record that flag on a position. The practical effect is small — a Crawford game has no cube decision at all — but the omission is real and is better written down than left to be guessed.
Study and real play
The command blunderdb list --type study --days 30 puts three numbers side by side, plan of play by plan of play: how many distinct positions were revised over the period, what the PR was before it, what the PR is since.
Three numbers, and no fourth. There is no gain column and no arrow, because nothing here controls for anything: the player may have met stronger opponents, changed format, or simply played more races this month. The rapprochement is the reader’s; a column announcing an effect would claim a causality these data do not carry. The numbers themselves are exact.
Reviews are counted as distinct positions: a card revised four times in the month is one position studied, and counting the repetitions would make a month of cramming look like a month of coverage. The PR’s decisions, on the other hand, are all counted — each was taken once. A PR resting on fewer than ten decisions shows —, with its sample visible beside it.
Players tab
The four previous tabs describe one player; the Players tab compares them all. It shows one row per player in the database, which answers the need of an organiser following a whole competition rather than one player.
The Players tab: one row per player, sortable by any column.
Columns, in order:
Column |
Meaning |
|---|---|
Player |
The name as it appears in the matches. A player recorded under two spellings therefore shows up on two rows; use the player merge to bring them together. |
Matches |
Number of matches played within the retained period. |
W–L |
Wins and losses. An unfinished match (truncated log, resignation) counts as neither: W + L can therefore be lower than the number of matches. |
Decisions |
Number of counted decisions — the PR’s denominator. This is the column that says what the neighbouring rates are worth: a PR computed over twelve decisions means nothing. |
PR |
Overall Performance Rating. |
Checker PR, Cube PR |
The PR split by decision type. |
Snowie |
Snowie Error Rate (see Annex: Statistics model — XG / gnuBG / blunderDB alignment). |
Blunders |
Number of errors reaching the library’s blunder threshold (0.100 EMG by default). |
Luck |
Average luck per roll, in millipoints (mpt), signed: positive if the dice were favourable. |
Use:
Sort — click a column header. The table opens sorted by ascending PR, best player first. Players for whom nothing was measured stay at the bottom whichever way the sort goes: a zero for lack of data is not a perfect performance.
Open a player’s detail — click a row. The player is selected in the filter bar and the display switches to the Dashboard tab.
Narrow the period — the date, tournament and match-length filters apply as usual, which makes it possible to bound the table to the dates of a competition.
Compare two players — tick the box in the first column on two rows. A block appears above the table and sets their figures face to face; ticking a third player replaces the older of the two. The box does not select the row: ticking compares, clicking opens the detail.
In that block, only the rates get a verdict, and the better of the two is set in bold. Three figures never get one, and it is worth saying why. Luck is not a quality: a luckier player is not a better one. Matches, record and decisions say what the rates are worth, but putting them in competition would let whoever simply played more win. The blunder count does not compare raw — twelve out of a thousand decisions beat ten out of a hundred — so the block adds a Blunders / 100 dec. line, which does compare, and leaves the count beside it as context.
A tie is not a win: it is set in bold on neither side. A rate with nothing behind it shows as “—” and decides nothing.
Note
In this tab, the Player list and the decision type choice are disabled: the table shows every player, and already splits checker and cube decisions into separate columns.
Important
A dash (”—”) marks a value that was never measured, not to be confused with zero. That is notably the case of the Luck column for any match imported before schema version 2.15.0: luck was not stored back then, and nothing allows it to be reconstructed afterwards — the source files must be re-imported. Formats that do not carry it (BGF, Jellyfish .mat) never will.
Aggregation rule
Important
The PR of a tournament (or any subset) is computed using the sum/sum rule — never as an average of individual match PRs.
Formula:
Example: a player plays two matches in a tournament —
Match A: 10 decisions, 0.100 of lost equity → PR = 5.0
Match B: 90 decisions, 0.540 of lost equity → PR = 3.0
Naive average of PRs: (5.0 + 3.0) / 2 = 4.0 (incorrect)
Sum/sum rule: 500 × 0.640 / (10 + 90) = 3.2 (correct)
The sum/sum rule is the only one that handles varying match lengths correctly (a 21-point match carries more weight than a 1-point match).
MWC: limitations
MWC cost is computed from the Kazaross-XG2 MET, the de facto reference table in competitive backgammon. Results are not directly comparable with software using other METs. It is the same table, read through the same entry point, that the embedded evaluator uses for its cube decisions at a match score: the statistics and the engine cannot diverge on this. It gives its own values up to 25 points to go on each side; beyond that, it is extended by a Zadeh table computed the same way as GNUbg’s, up to 64.
Money-game positions (with no match score) are excluded from the MWC computation. If your database contains many money-game positions, the MWC cost may be underestimated or unavailable.
The MWC cost is cumulative over the full filtered dataset — not a per-decision indicator. It measures the total impact of your errors on your winning chances.
Eval Panel
The Eval panel (CTRL-E) evaluates live whatever position sits on the board; on a bearoff position it specialises and additionally computes the EPC (Effective Pip Count). It is opened by pressing CTRL-E, by clicking the Eval tab in the lower panel, or by running the eval command; epc, its former name, opens it too. The panel was called EPC, then Bearoff, before becoming Eval — so this is where to look for what an earlier version called the Bearoff panel, the name now only naming the tab that configures the bearoff tables.
The panel always shows the single decision the position on the board calls for — never two at once — and the facts that go with it. Each quantity is read in the axis that suits it rather than in a single imposed axis: the winning, gammon and backgammon probabilities and the cubeless equity of each player, computed before the roll, are read per player (bottom, top, then Δ), to the left of the cube decision, when no dice are showing. Facts and decision stay side by side: the cube decision never drops below the figures that justify it, whatever the interface language and the position on the board. As soon as dice are showing, these same before the roll values change axis: they are read on roll, at the head of the candidate-move list, as an italic before the roll row — not one more candidate move, a reference against which to read each move. The gap between that row and a move contains the luck of the roll, never the merit of the move, and so it carries no error column. On a pure bearoff position, a second table, still per player and always present, dice showing or not, carries the EPC, the pip count, the wastage, the average number of rolls and the standard deviation; these five columns never migrate. The two tables are stacked and share the same column grid: same edges, same column guides, a single column of dots — they read as one two-storey object. The Add to database button, the regime badge, the engine attribution (the depth of the last evaluation appears there too) and the Challenge box form a separate strip, right-aligned above the tables.
Only the candidate-move list scrolls — the before the roll row, too, stays pinned above it; the rest of the panel (facts, badge, cube decision) always remains visible, with no particular adjustment of the panel size.
The facts table and the decision are computed by gammonNet, embedded, without XG or gnubg. The computation follows the position without ever freezing the interface: a 0-ply depth is displayed immediately on every gesture, then, after half a second of stillness, a deeper evaluation (2 plies by default, adjustable in the gammonNet tab of the settings) replaces it in the background — any new gesture cancels that background computation. The depth shown in the badge strip, or inside the regime badge on a race position, is always the one that actually produced the figure shown, never the one requested; it is not repeated on every row, since a live evaluation shares the same depth for all moves. The equity of the candidate moves and of the cube decision follows the score of the position: in money game it is expressed in points, at a match score in normalised equity — the same scale as XG and GNU Backgammon, where winning the value of the current cube is worth +1 and losing it −1 — never mixed in the same table. The column header states it explicitly rather than leaving the scale to guess: “Equity (money)” in money game, “Equity (match)” at a match score. It accounts for the live cube: the search values every terminal position through the cube model (Janowski, measured efficiency) in the position’s cube state, the way XG and GNU Backgammon do in cubeful evaluation. This is what makes the gammon-go and gammon-save effects visible at the score — at 4-away/2-away, the player behind plays 8/2 6/2 on an opening 6-4 because an early double will give the gammon the value of the match, something a cubeless evaluation cannot see. The before the roll row, by contrast, stays a cubeless equity: it is a fact about the position, not a decision. The evaluation is never stored: it is a computation, not an analysis. Clicking a candidate move shows it on the board as arrows, exactly as in the Analysis panel. The discreet ? button, in the badge strip, leads to the gammonNet engine repository; the full attribution (Strehl network, gammonNet configuration) appears in the Acknowledgments of the help.
The Add to database button, at the head of the badge strip, stores the position on the board in the database; CTRL-S, the w command and the Save Position toolbar button do the same. Only the position is written, never the evaluation shown; if gammonNet automatic analysis is enabled, its batch starts afterwards, as after an import. The status bar announces the position’s number, including when it was already in the database: it is then marked as individually imported, and the Individually Imported filter (s i) finds it. The panel stays open on the same board, which remains a scratch board: you can move a checker and add the variation, and leaving the panel brings you back to what you were studying. The button is disabled while no database is open, or while the position cannot be saved (for example the panel’s starting position, where the top player has borne off all their checkers); its tooltip gives the reason.
The user edits the checker position over the whole board, exactly as in edit mode: left click places a checker of the bottom player, right click a checker of the top player. The second table, the race one, only appears when the resulting position is a pure bearoff (all checkers of both players in their home board); on any other position, only the table of the four common columns (win, gammon, backgammon, cubeless) responds, and the decision bears on the checkers or on a generic cube depending on whether dice are showing.
In each facts table, one row per player — identified by its coloured dot, the black player always at the bottom. The first carries, as long as no dice are showing, the player’s win, gammon and backgammon (probabilities, without the % sign) and cubeless equity; the second, on a bearoff position and dice showing or not, the EPC, the pip count, the wastage (difference between the EPC and the pip count), the average number of rolls and the standard deviation. When both players have values to compare, a Δ row gives the signed differences (bottom − top: negative when the black player is ahead). Outside a race position, showing dice therefore makes the facts tables themselves disappear: the four columns they carried have just changed axis, on roll, at the head of the move list.
The cube decision always has the same shape, whatever the origin of the figures — exact table, evaluated regime or ordinary gammonNet evaluation: one row per option, in the order no double, double/take, double/pass, with its equity in the position’s frame of reference and its gap to the best option. The order never changes, unlike the move list: the three options have names, so it is the name one reads, not the rank. The best one is recognised by its highlighting and by its gap cell left empty. When the cube has already been turned, the options read no redouble, redouble/take, redouble/pass.
A last row gives the verdict. It takes four values: no double, double, take, double, pass and too good to double, the last when playing the position on is worth more than cashing the point: doubling would then be a mistake for the opposite reason to that of a plain no double. It is also the only place where the panel says there is no verdict, rather than suggesting a computation in progress:
no decision — the regime is not entitled to one; the cube verdict is never estimated (see the estimated badge);
not evaluable at this score — the engine refuses the position, typically a score beyond the horizon of the match equity table, i.e. a side with more than 64 points to go;
opponent owns the cube and cube dead (Crawford) — the cube cannot be turned. The equities remain displayed, for information, but no option carries a gap: an error is what a choice costs, and there is no choice.
In money game, the Jacoby and Beaver rules active on the position appear under the cube table, in small badges next to the verdict they change: the no double verdict of a position under the Jacoby rule is not the same computation as without it, and nothing else on screen said so.
A third badge, Max cube, appears when the source identifier caps the cube — at a match score as well as in a money game. That one does not describe the computation shown above it: the built-in evaluator does not model a ceiling, so the verdict is the one for a free cube. That is precisely why the badge is there: a capped cube is the one visible reason blunderDB and eXtreme Gammon can announce two different verdicts on the same position.
The regime badge, the evaluation depth, the link to the engine and the Challenge box form a separate strip, right-aligned above the tables.
The player on roll and the cube position are edited directly on the board, as in edit mode: clicking a player’s bearoff/score rectangle gives that player the roll; clicking the cube cycles centred → owned bottom → owned top (right click cycles the other way). The cube value stays pinned — in money game the equities are expressed in units of the current cube, only its owner matters. The analysis is recomputed immediately. In the estimated regime, the badge itself is clickable and opens the Bearoff tab of the settings directly; its tooltip explains why (cube verdict not estimable, ADR-0009) and how to widen the exact domain.
The score is also edited directly on the board, as in edit mode: left click on a player’s score rectangle decrements their number of points to go, right click increments it. Leaving the money score (-1, -1) by editing one side alone automatically aligns the other side on the same value rather than leaving an inconsistent score. On a bearoff position in the exact regime, moving from a money score to a match score leaves the winning probability as it is (a database lookup, valid whatever the frame of reference) but switches the displayed equity and cube verdict to those of the evaluated regime — the exact table being money by construction, it cannot answer the question asked at the score. The badge then becomes composite (“exact (win) · evaluated (cube)”) to say so explicitly.
The dice, finally, are edited the same way, and they are what decides the question being asked: dice on the board make a checker decision (the list of candidate moves), no dice a cube decision. Left-clicking a die raises its value (6 wraps to 1), right-clicking lowers it (1 wraps to 6); clicking a die on a board that has none puts down two at once — a single die would be neither a checker decision nor a cube decision. Clicking a player’s rectangle removes the dice to ask a cube question, and the next click on a die puts them back as they were.
BACKSPACE, or a double-click outside the board, clears the position: empty board, money score (-1, -1), no dice showing — values specific to the Eval panel, different from those used in edit mode (7 everywhere, dice 3-1), to stay consistent with what the panel shows by default.
Cube matrix
A cube decision is not a property of the board. The same checkers, the same pip count, are a double at 2-away/4-away and a no-double at 4-away/2-away; a player who has learnt the money answer has learnt one cell of a grid. The Eval panel shows the cell the position carries; the cube matrix shows the whole grid.
The cm command opens it on the position on screen. Each cell gives the verdict at one score: the row is the number of points the player on roll still needs, the column the number the opponent still needs. The four verdicts read ND (no double), DT (double, take), DP (double, pass) and TG (too good); a cell the engine refuses carries a question mark and says why on hover, which also gives the cell’s three equities. Three match lengths are offered: 5, 7 and 9 points.
The cell of the score the position actually carries is framed, and its row and column headers underlined: reading starts there, “my cell, and what surrounds it”. It is framed as soon as both of the position’s away scores fit in the displayed grid; changing the length moves the frame or removes it. A money position, the Crawford game, or an away beyond the grid designate none: there is no cell to show, and showing an approaching one would be false.
The position’s own score is replaced by each cell’s; its cube is kept. The grid answers “at what score would I turn this cube”, not what a centred position would do. It is post-Crawford throughout: during the Crawford game the cube is not in play, and a column of “you may not double” would say nothing about the position.
Every cell is its own search. The engine is match-aware — it does not play the same game at 2-away as at 7-away — so a single search read through different match equities would be wrong exactly where the score matters. The grid arrives at 0-ply first, then recomputes at the configured display depth once the window is at rest: the same escalation as the rest of the panel, for a 9-point grid costing about a second and a half.
The same grid is computed outside the interface, with the command line’s cubematrix command.
Bringing a position into the Eval panel
The panel opens by default on a bearoff position, but a study most often starts from a position already at hand. Two gestures bring it there:
Right click on the board, in an analysis panel or while navigating a match, then Evaluate this position: the Eval panel opens directly on that position, as displayed. The context menu does not appear in the Eval panel or in the Search panel, where the right button already serves to place checkers of the other colour.
CTRL-C then CTRL-V: copy the position from the analysis panel, then paste it once in the Eval panel. Pasting also accepts an identifier from elsewhere — an XGID (eXtreme Gammon, GNU Backgammon, another instance of blunderDB) or an OGID (OpenGammon): it only has to be in the clipboard.
The command
import XGID=…(orimport OGID=…) for when the identifier is not in the clipboard but in a message, on a forum read in a terminal, or produced by a script. It is the same verb as plainimport: with no argument it opens a file picker, with one it reads the identifier. The path is then identical to pasting — same reading, same deduplication, same opening of the imported position.
An OGID carries a position and nothing else: no evaluation, no comment. The position therefore arrives without an analysis, exactly like a bare XGID, and the built-in evaluator can fill the gap afterwards.
In an OGID, the Crawford game is read from the C that follows the match length (7C): without it, a player one point from the goal is past the Crawford game.
The Eval panel’s board is a draft: the position arrives there without its database identifier, so that no change made here can rewrite the record it came from. All the usual board edits remain available there (checkers, cube, dice, score), and the evaluation follows every change.
In the other direction, CTRL-C copies the Eval panel’s board to the clipboard, with an XGID recomputed from the checkers on the board — hence pasteable directly into eXtreme Gammon or into another instance of blunderDB. Only the position travels: the evaluation shown by the panel is not a database record and does not accompany the copy.
On leaving the Eval panel, the position previously viewed is restored: the draft is never saved on its own.
When the position is a pure bearoff (all checkers of both players in their home board) and no dice are showing, the cube decision shows, for the player on roll:
in the exact regime: the money equities (cubeless, no double, double/take, double/pass) and the money cube verdict (no double, double/take, double/pass or too good to double) — outside a match score, see above for the case of the score,
in the evaluated regime: the same equities and the same four-valued verdict, but played out by gammonNet (search + Janowski cube model) rather than read from a table — available even at a match score, which the estimated regime could never offer;
in the estimated regime: the cube verdict is then deliberately not shown — only the winning probability, in the facts table, along with its error margin, remains available.
As soon as dice are showing on a race position, this before the roll cube decision disappears — the board then calls for a checker decision, not a cube one — but the winning probability, for its part, remains a fact of the position, not a decision: it joins the before the roll row at the head of the move list, next to the EPC which, for its part, stays displayed just to the left.
A badge indicates the regime: exact (value read from a two-sided database), evaluated · <depth> (played out by gammonNet — the depth shown is the one that actually produced the figure shown), estimated ± margin, or, at a match score within the exact domain, exact (win) · evaluated (cube) — see above. The exact regime wins wherever it is available; otherwise the evaluated regime is displayed as soon as it has finished computing, replacing in place the estimated regime shown while waiting. See Methodology and assumptions of the Eval panel for the precise definition of the three regimes and their assumptions.
Widening the exact domain. The table computed on first launch covers 6 chequers a side. Two ways to go further, in the configuration’s Bearoff tab:
compute a wider two-sided table — up to TS-06-15 if the machine has the memory for it. The tab states the size, the memory and the time on this machine before starting, and the computation pauses and resumes. A cancelled computation leaves a
.partfile which is never read as a table;point to any two-sided gnubg
.bdfile. The database with the widest domain automatically wins.
The panel’s board is a scratch board, and it is remembered. Leaving the Eval panel and coming back finds the position it was left on, not the default bearoff board: that one is only served the first time the panel is opened in a session. Sending a position from the database to the panel wins over that memory, and BACKSPACE hands back the default board at any time. Nothing is written to the database along the way — the scratch board has no position identity, and its evaluation is recomputed on arrival rather than carried over.
Challenge mode. The Challenge box, in the badge strip, enables a training mode: on every change to the position, the values of three zones are masked (replaced by “···”); clicking a zone reveals that zone only. Without dice, these are the bottom player’s row, the top player’s row and the cube decision — the Δ row only appears once both player rows are revealed. The decision block then keeps its three rows: it is its values, its verdict and the highlighting of the best option that disappear, failing which the exercise would be solved by looking for the bold row. With dice showing on a race position, each player’s EPC row is masked as before, but the third zone then covers the before the roll row and the move list together: the list being sorted from best move to worst, revealing it partially would already give the answer away. With dice showing outside a race position, that same single zone alone covers everything the panel displays. One can thus practise estimating each side’s EPC, then deciding on the cube or on the move to play, before checking. The setting is remembered.
To close the Eval panel, press CTRL-E or switch to another tab.
Methodology and assumptions of the Eval panel
Every value displayed by the panel rests on precise assumptions, stated here exhaustively.
Domain. The race zone — winning probability and cube verdict — covers pure bearoffs only: every remaining chequer of both players in their home board. The position is evaluated before the roll; any dice set on it are ignored.
The EPC blocks, on the other hand, go further: a side gets its EPC as soon as its farthest chequer fits in the loaded one-sided table. With the default table (six points) that is the old home-board rule; with an eight-point table, computed from the Bearoff tab, a side with a chequer on the 8-point is treated like any other. Nothing is extrapolated: a chequer one point too far simply has no EPC, exactly as a chequer on the 7-point had none before. When the table that answered is not the six-point one, its name appears in the corner of the race block (“OS-08”) — without it one would read “six” by default and believe the side entirely home.
EPC blocks (always exact). The EPC, the average number of rolls and the standard deviation come from the exact distribution of the number of rolls needed to bear every chequer off, read from GNUbg’s one-sided database (6 to 10 points, 15 chequers, computed on the machine). EPC = average rolls × 49/6 (49/6 ≈ 8.167 is the exact average of pips per roll, doubles counted four times); wastage = EPC − pip count. The only idealisation is one-sided optimal play: each player minimises their own rolls, ignoring the opponent — that is the standard definition of the EPC.
Winning probability, exact regime. Direct lookup in the widest available two-sided database (TS-06-06 computed on first launch, an external file, or TS-06-11 computed from the Bearoff tab). These databases result from a complete retrograde analysis under optimal two-sided play by both sides: no additional assumption, error limited to quantisation (< 0.002%).
Winning probability, estimated regime. Outside the database’s domain: the probability is obtained by convolving the two one-sided distributions (the player on roll wins if their number of rolls is less than or equal to the opponent’s), then applying a frozen polynomial correction, calibrated offline against the TS-06-11 database. Three assumptions:
independence of the two bearoff processes — structural in a race, with no contact there is no interaction whatsoever;
optimal one-sided play by both sides — this is the approximation: in reality the trailing player deviates to play for variance and the leader for safety. The measured effect is an antisymmetric bias (the convolution overstates the leader’s advantage) which the correction absorbs statistically;
the correction was calibrated and validated on the oracle’s domain (up to 11 checkers per player). Measured residual error: standard deviation 0.05%, 99th percentile 0.17%, observed maximum 0.9% (in winning-probability points). Beyond 11 checkers per player, this bound is extrapolated — the trend is monotonic but no oracle certifies it.
Equities and cube verdict (exact regime only). The displayed equities are those of the money game, without Jacoby, the reference framework of the bearoff literature. Within the ≤ 11 checkers per player domain, gammons are impossible (each side has already borne off at least 4 checkers): this is not an approximation. The verdict (no double / double, take / double, pass) is reconstructed exactly from the stored equities, following GNUbg’s rule, validated verdict for verdict against its analysis.
Note
The cubeful equities assume optimal cube play by both sides all the way to the end: future recubes are fully valued (complete retrograde analysis). In the very volatile races at the end of the game, the cascade of recubes eats up almost all of the advantage of the side on roll — the “no double” and “double/take” equities can then be close to zero where an engine such as XG, whose cube model does not value this cascade, shows values close to the dead cube (for instance 2 checkers on the 3 point against 2 checkers on the 2 point: 62% winning chances, exact D/T +0.006 versus +0.475 for XG). The displayed decision, however, coincides with the engines’.
Winning probability and verdict, evaluated regime. Outside the exact domain, the winning probability comes from gammonNet’s raw output (0- or 2-ply search depending on the gesture, never read from a table), and the verdict from a Janowski “Decide” applied to that output — the search plays out the trajectory instead of summarising a snapshot of it, which is precisely what the estimated regime could not do (see below) and allows, alone among the three regimes together with the exact one, a verdict at the match score.
This regime was measured, not merely assumed, against the built-in two-sided table (TestEvalMeasure, 4000 sampled money decisions, canonical parameters 2-ply k=12): money verdict agreement 93.4% (3735/4000), broken down by distance to gammonNet’s take point — 61.1% within 1% of the take point (the zone most sensitive to a coin toss), 88.3% between 1 and 5%, 91.5% between 5 and 10%, 94.0% between 10 and 20%, 94.4% beyond. Winning-probability gap: mean 0.85%, median 0.44%, 95th percentile 3.21%, maximum 8.30%. Cubeful-equity gap: mean 0.039, median 0.018, 95th percentile 0.151, maximum 0.406. The shape is the expected one: most of the disagreement concentrates exactly at the take point, where two legitimately different methods diverge most on a close decision — not a diffuse error that would cost equity everywhere.
This measurement covers money decisions, in a race. The match-score verdict — which only this regime can render — and contact positions have no published measurement: none of the above carries over to those cases.
Why not deeper than 2-ply? Because the measurement says it buys nothing. A checker decision costs 99 ms at 2-ply and 8.4 s at 3-ply on the same machine — eighty-five times more. Over forty real decisions replayed at both depths, the deeper search changed its mind twice, and both times the gain it claimed for itself was at most 0.0005 normalised equity: two orders of magnitude below 0.020, the threshold at which eXtreme Gammon calls a decision an error at all. Per decision, all cases together, the gain is 0.0000.
The setting is therefore not offered. This does not say 3-ply is worthless in general, only that on this network, at the canonical filter, it does not pay for the wait of someone sitting in front of a panel. The measurement is reproducible (TestThreePlyMeasure) and the conclusion is re-decidable if the network changes.
Why is there no estimated verdict? What follows targets specifically the convolution method (estimated regime), not the evaluated regime above: cubeful equity is a trajectory problem (when to double) that no statistical summary of the position captures — the best static model measured leaves a residual error (standard deviation 0.016 of equity, maximum 0.20) large enough to flip every close decision. Likewise, converting the verdict to the match score through a match-equity table was measured to be insufficient (12% of disagreements with GNUbg’s 2-ply analysis, including genuine blunders). Since a wrong verdict displayed with confidence is worse than no verdict, the convolution was never allowed to display a verdict — it is a search that plays out the trajectory, not a statistical summary, that fills this hole.
Note
The bearoff databases are immutable mathematical tables. blunderDB computes them itself, identically to GNUbg’s makebearoff tool — byte for byte — in the Bearoff tab of the configuration or with blunderdb bearoff generate.
Anki Panel
The Anki panel (CTRL-K) allows studying positions with spaced repetition using the FSRS algorithm. Users can create decks from collections or search results.
Creating decks: Click New Deck to create a deck from a collection or the current search results. Search-based decks sync automatically when the Anki tab is opened.
A deck of score sheets. The third source, Score sheets, asks for nothing but a name: blunderDB fills the deck with the 36 unordered scores from 2 to 9 away, and the card of a score is the sheet the Scores exercise displays — take points and gammon values, both faces. That deck exists only if you create it: 36 cards due on the first day are a review debt, and it is contracted on purpose. The sync button regenerates it.
The two places do not do the same work. The Scores exercise makes you retrieve those numbers against the clock and measures the speed; the deck makes them last over time and measures none of it. The two histories stay apart: the Training journal ignores Anki reviews, and Anki’s statistics ignore Training sessions.
Reviewing: Select a deck then click Study (or double-click a deck) to start reviewing due cards. Each card shows the corresponding position on the board. Rate your recall with keys 1 (Again), 2 (Hard), 3 (Good), or 4 (Easy). Press Esc to stop and return to the deck list.
Cube decisions make two cards, chained. A cube decision is two questions — “double?”, then “take?” — and blunderDB has always stored them as two positions. A deck that selects only one half gets the other: the decision is completed, not enlarged. And when both are due, the second comes immediately after the first.
Each keeps its own grade and its own schedule: these are not two stages of one card, they are two cards. Chaining advances no due date — it orders the cards already due, nothing more. Both being born together, they are due together the first time, and that is where it serves.
Showing the answer: The card asks a question — which move to play, or which cube action. Think, then press SPACE (or click the masked area) to reveal the answer: the recorded analysis of the position, as the Analysis tab presents it. It appears below the rating buttons, which stay in place and within reach. Clicking a move in the list shows it on the board.
Nothing forces you to reveal the answer in order to rate: if you are sure of yourself, the 1 to 4 keys stay active. The answer is masked again on the next card, but not if you simply switch tabs — go and consult the Eval panel or the position’s comment, it will be waiting for you when you return.
A position without a recorded analysis says so directly, with no masked area.
Limiting the session. By default a review session runs through every card that is due. You can cap it at a number of cards, per deck, in the Settings: tick Limit session and give how many cards a session should serve. When the limit is reached the session stops and says so — the message tells “limit reached, so many cards still due” apart from a queue that is genuinely empty. To carry on anyway, free drill is there: it serves other positions without changing anything in the schedule.
A limit of 0 serves no card at all: it is a state in its own right, useful to freeze a deck while preparing for a tournament, and it is not the same thing as “no limit”. The Study button is then disabled.
The limit applies to the session, not to the day. A blunderDB deck is built on a collection or on a search: it is a finite corpus, introduced over a few sessions, whose daily volume is already bounded by its size. A daily cap would never bite, or else would build a backlog on a deck that fitted in a single session.
Free drill (cram): The Cram button, next to Study, starts a free-drill session: random positions from the deck are shown to you regardless of the FSRS schedule. This mode never alters the spaced-repetition plan — ideal for warming up before a tournament or intensively reviewing a themed deck without disturbing its ordering. A Cram badge replaces the card state and a Next button (keys 1 to 4) cycles through the positions. Esc returns to the list without saving an interrupted session.
Setting a card aside, without grading it. During a review, a right-click on the card’s header offers three gestures that take it out of the session without telling the scheduler anything:
Suspend — the card keeps its schedule and never comes up again while suspended. It is how a card that is wrong, or not useful yet, is set aside without losing the history attached to it.
Bury — the card disappears until the next day. Unlike suspending, this says nothing about its worth: it is for the one you have just seen elsewhere, or would rather not meet twice in an evening.
Remove — the card leaves the deck, after confirmation. The position itself stays in the database: a deck is a study list over the library, never a copy of it.
None of these three records a grade: a card set aside is not a card answered, and it does not count towards the session’s total.
Review log. In a deck’s Settings, the Review log button shows what the scheduler was told — date, position, grade, state, granted interval — as opposed to what it plans. It is the only place a grade entered by mistake can be seen. It cannot be corrected there: the schedule stays out of reach, and that rule is precisely what makes the log useful — the past cannot be rewritten, but it can be known.
Pause/Resume: You can interrupt a review session at any time with Esc. The button changes to Resume and shows your progress. Click it to pick up where you left off.
Deck management: Use the action buttons to rename, synchronise, reset or delete decks (a confirmation is asked for the last two). The FSRS parameters (target retention, maximum interval, fuzz) can be set per deck in the Settings (gear icon).
Retention: the target and the measurement. The target retention is your own choice on the trade-off between workload and quality of recall: the higher it is, the shorter the intervals and the more you review. Alongside it, the Settings show the measured retention over your own reviews — information, never a control loop: blunderDB does not change your target to chase your success rate. Below some twenty reviews the measurement is not shown: it would read as a fact when it is only noise.
Changing the retention is not retroactive: each card takes up the new pace at its next review, and the due dates already set do not move. The effect is therefore gradual, and invisible on the day itself.
The maximum interval bounds the spacing. A recently created deck starts at one year: a position the algorithm would push back by several years has left the deck without you deciding so, and your own game changes faster than that. Older decks keep the value they had.
Training Panel
The Anki panel reviews what is retained; the Training panel drills what is calculated, against the clock. It opens with CTRL-J, with the toolbar button placed right after « Position aléatoire », or with the train command. The score sheet belongs to both: it is calculated here and retained in a deck of score sheets.
At rest, the panel shows the launcher and the summary of past sessions.
The launcher
Three choices, then « Démarrer »:
the exercise — Scores, Pions (pips), Bearoff, Évaluation or Décision;
the source of the question, when the exercise has several — Vivier (canonical shapes of the exercise), Plateau (the position as it stands) or Base (a position of the browsed list);
the limit per question — none, 15, 30 or 60 seconds.
The chosen source is remembered for each exercise, from one session to the next.
train scores, train pips, train bearoff, train evaluation and train decision open the panel and start straight away; train tp and train takepoint are synonyms of train scores, train epc of train bearoff, train quiz of train decision.
The five exercises
Scores draws one of the 36 unordered scores from 2 to 9 away and shows a score card: two columns — Vous (you) and L’adversaire (the opponent) — and seven rows — the take point at cube 2 then at cube 4, each for a long race and for the last roll, then the gammon value at cubes 1, 2 and 4.
Each column carries only the cells the reference tables — those the tp2_live, tp2_last, tp4_live, tp4_last, gv1, gv2 and gv4 commands display — define for its face: three numbers at 2a-2a, fourteen at most, and a single column at a level score. A row neither face defines does not appear on the card — so there is no « n/a » cell to guess. Both faces are there because a cube decision at a score needs both: the corrected take point combines both players’ gammon values, and it is the opponent’s take point that says whether your double passes.
Pions (pips) asks for the pip count of both sides. The board’s pip count is hidden while the question is open; « Révéler » shows it — even if you had hidden the pip count with p, since the answer would otherwise stay invisible and the exercise unverifiable. It is a mask and not a setting: your own choice is not changed, and it takes over again at the next question. The Plateau source asks one question about the position shown, and only one; the Base source draws a new position for every question and brings it onto the board.
Bearoff asks for the EPC of both sides — the effective pip count, the one that adds to the pip count the wastage of the chequers that come off with pips to spare. It is the domain where the engine is exact, and the one where the EPC really differs from the pip count.
Every question is generated: the engine starts from a seed and plays a few rolls, and it is the snapshot that is put to you. A random placement would not have the gaps, the low stacks and the asymmetries of a real bear-off. The seed comes from the Vivier (a completed bear-in, then zero to ten plies), from the Plateau (the position on screen, then one to four plies — never zero, since you have just seen it) or from the Base (a position of the browsed list, as it is: it is already real).
The exercise’s domain: both sides entirely in their home board, 4 to 15 chequers a side and the rest borne off, cube centred, money play. A seed that does not fit is refused by name, and nothing starts — no silent adaptation: playing on until contact breaks would hand you a position you did not choose. An empty board is the exception: the question then comes from the pool, and the panel says why.
The exercise needs the one-sided bear-off table; while it is still being generated in the background (see Configuration), it says so rather than asking a question with no answer.
Évaluation asks what a position is worth: the win chance of the player on roll, as a percentage, and the cube action — Pas de double, Double, prend or Double, passe. These are the two numbers the Eval panel shows, asked before they are shown. The domain is any position: a race as well as a contact position, in money play.
As for Bearoff, the question is generated: the seed comes from the Vivier (a position where contact has just broken, then zero to ten plies played by the engine), from the Plateau (the position displayed, then one to four plies; the question is asked in money play with the cube centred, whatever the seed’s score) or from the Base (a position of the browsed list, as it is). A library position qualifies only if it is a money-play cube decision — no dice, the cube centred or held by the player on roll —; otherwise the draw moves on to the next one, and when none qualifies, the exercise says so. A board that is not a game position — not fifteen chequers a side, or a finished game — is refused with a sentence that says so; an empty board makes the question come from the pool.
The truth is the engine’s: the two-sided bear-off database when the position is in it, gammonNet at its canonical depth everywhere else, and the panel says which one answered. Nothing is estimated: a position the engine does not evaluate is not asked.
Décision asks a decision that is already analysed: a position of the browsed list — its only source — with the decision it carries, a checker play or a cube action, and the stored analysis is the judge. A position without an analysis asks no question, and a position once asked does not come back in the session; when the list is exhausted, the panel says so. With no database open, or with no analysed position in the list, the exercise refuses and says why, and nothing starts.
While an Évaluation or Décision question awaits its answer, the Analysis panel is masked: it carries the answer.
Answering
The answer mode is a property of the exercise, never a setting: what is counted or recalled is declared, what is estimated is entered — because there, the size of the error is the lesson.
Scores and Pions are declared: you work it out in your head, you click « Révéler », and the truth appears. Every number is then right by default — you click the one you got wrong to mark it a fault (Tab then Space does the same from the keyboard), and a second click clears the mark. Nothing is typed: a pip count or a table cell is right or wrong, and writing it teaches nothing reading it does not.
Bearoff is entered: you write the two EPCs, « Valider » grades them to within half a pip — the granularity at which the EPC changes a race decision — and the truth appears next to what you wrote. The application judges, there is nothing to tick. The deviation is recorded with its sign: overestimating is not underestimating, and it is the summary that makes an average of it.
Évaluation mixes both gestures in a single question. The win chance is entered and graded to within five points, signed deviation included; the cube action is chosen — the click keeps the button without grading anything, and « Valider » grades both at once. The cube has no tolerance: only the button the engine’s verdict makes right is right, and a position too good to double is answered Pas de double. Enter in the field leads to the cube action while it is not chosen, then validates. After the answer, the panel shows the truth — the verdict in four outcomes —, its source, and the EPC of both sides when the position has an exact one; the EPC is never asked here, it has its own exercise. The journal counts the two numbers apart: one can estimate a position well and misread its cube.
Décision is chosen. On a checker decision, play the move on the board: click the source point then the destination, or drag the checker, once per die. The board offers only what can be played — a click no legal move allows moves nothing. In the panel, « Annuler le pas » goes back one die, « Recommencer » restores the position as the question poses it (a double-click outside the board does the same), and « Valider », enabled once the move is complete, has it graded. On a cube decision, click No double, Double, take or Double, pass: the click is the answer.
The correction keeps three outcomes apart, and collapsing them would lie. An illegal move is not a badly chosen move — it is a rules mistake. A legal move the engine never ranked is not an error of judgement: it simply has no price, and costs nothing. A ranked move costs what the analysis says it costs, in millipoints. Only a ranked move with no cost is right; the best move is shown in every case.
The clock starts when the question appears and stops at « Révéler », at « Valider » or at the click of a Décision cube action; the next question is prepared while you answer, so it is never timed with yours. Ticking faults is not timed either. With a limit, a question still unanswered at the deadline reveals itself and counts out of time: every one of its numbers is wrong, and its time does not enter the median — one does not measure an answer that was not given. A decision out of time shows the best move, and does not enter the session’s PR.
« Suivante » records the question and asks another. The session has no fixed length: it runs until « Terminer », which writes it to the journal, or « Quitter », which discards it. Every button is in the panel; the board shows the question and its answer, it carries no control.
While a question is set on the board, revealed or not, the keys that browse the list do not scroll it: the question keeps the board until « Suivante », « Terminer » or « Quitter ».
The journal and the summary
Finished sessions are kept in the library itself — so they travel with the file — and without any cap. At rest, the panel shows one line per exercise: the number of sessions, the fault rate, the median time and, from ten sessions on, the trend, that is the gap between the fault rate of the last ten sessions and that of all of them — negative, you are improving.
For Décision, the line also gives the PR of the last session, computed by the formula the statistics apply to real play — 500 × mean error in normalised equity, over the graded decisions. A training PR of 6 and a match PR of 6 measure the same thing on the same scale.
Clicking the exercise’s name unfolds the detail by number type: « Point de prise 4 · dernier lancer, 6 / 9 ». That detail is what makes the journal worth keeping, and it counts by type and not by face: the same cell of the same table, seen from either side, is one single weakness.
Metadata Panel
The Metadata panel displays general information about the current database: name, description, number of positions, matches and games, schema version. Accessible via the meta command.
It also shows the database’s origin when there is one — see Handing out a database: origin and password. An ordinary database does not show that section.
Handing out a database: origin and password
A teacher handing out a database of positions has two mechanisms, independent of each other, both optional and both chosen at export time: marking the file with its origin, and protecting it with a password.
Note
Neither tracks what becomes of the file. blunderDB records nothing on the recipient’s side: opening a marked database is exactly like opening any other, and nothing anywhere logs who opened it, when, or where its contents came from.
Marking a database with its origin
The export dialog fits on a single screen: the form, then a progress overlay laid over it while the file is written. It closes by itself when finished, and the result appears in the status bar.
Three points deserve attention:
The export covers the positions currently displayed, not the whole database. After a search, only the results go out — the dialog says so at the top.
A collection whose positions are not all in the selection arrives truncated. The list therefore shows, for each collection, how much of it is covered (“12/40”), in red when it is partial.
Tournaments can only be exported together with matches: without them the tournament–match link does not exist and the tournament would arrive empty. The box stays disabled until “include matches” is ticked.
The User, Description and Date fields describe the file being produced; they are pre-filled from the source database. The My saved filters box is kept apart from the others: it exports not content but your own saved searches, which are of no use in someone else’s database.
Ticking Mark this file with its origin reveals two fields:
Origin — what this file is and where it comes from, in your own words: “Jean Dupont’s lesson — 12 March 2026”. This field is required: while it is empty the export button stays disabled.
Note, optional — terms of use, a contact address, a request not to pass the file on.
The mark is signed with your issuer identity. It is therefore tamper-evident and unforgeable: nobody can alter it, nor fabricate one in your name. It is however not unremovable — the distributed file is an ordinary SQLite database, and blunderDB is free software. It prevents nothing: it says where the file came from.
Issuer identity
Marks are signed with your issuer identity, created by itself the first time you mark a file; there is nothing to set up. It belongs to a person rather than to a database: every file you mark carries the same public fingerprint, of the form A3F1-9C24-7B05-E1D8.
You can give that fingerprint to your recipients so they can check that a file really comes from you. The identity moves from one machine to another as a single file (extension .bdbid), optionally protected by a passphrase. That file lets anyone holding it sign in your name: do not share it.
In the preferences (the gear icon in the toolbar), the Issuer identity tab shows your name and fingerprint, and offers Save identity…, Load identity… and Regenerate….
Warning
Regenerating revokes nothing. A watermark embeds the public key that signed it, so it verifies for ever, on its own. If your identity file has leaked, whoever holds it can keep signing under your old fingerprint, and those marks stay valid.
What protects you after a leak is not software: it is publishing your new fingerprint and disowning the old one to your recipients.
Regenerating overwrites the current key; blunderDB offers to save it before replacing it.
Protecting a database with a password
The password is typed masked, here as when opening a protected file; the eye icon reveals it while it is held down, and masks it again as soon as it is released.
Ticking Protect this file with a password produces a file with the .dbx extension — even if you chose a .db name in the save dialog, which opens before the password is asked for. To open it, use the usual open-database action: the file chooser accepts both .db and .dbx. blunderDB then asks for the password and installs an ordinary database beside it; nothing is asked afterwards.
The dialog offers to delete the protected file once opened: without that you keep the same content under two names. The box is not ticked by default — the protected file is yours to keep if you mean to pass it on — and the deletion only happens after a successful open.
Warning
The password protects the file in transit, not the database. It stops a stranger opening a file left in a downloads folder or an attachment forwarded by mistake. It does not protect you from whoever you gave the password to.
The password is checked on every open, including when the file has already been opened on this machine before.
Technically, the database is encrypted with AES-256 in GCM mode, with the key derived from the password by Argon2id (64 MiB of memory, 3 passes, 4 lanes) and a random salt unique to each file. GCM authenticates the whole payload: a wrong password is detected as such, and so is any tampering with the encrypted file — you never silently end up with a corrupt database.
The protected file’s header stays in the clear: its origin remains readable without the password.
Reading a file’s origin
In the application, open the file and show the Metadata panel (the meta command). An Origin section appears at the top of the panel, read-only, stating what was written, by whom, when, and how the signature checks out:
“✓ signature verified — marked by you”: the file carries your mark, intact;
“✓ signature verified”: the mark is intact and comes from another key — compare its fingerprint with the one the producer gave you;
“⚠ invalid signature”: the document has been altered or forged.
This section does not appear on an ordinary database.
From the command line, blunderdb info --db file.db shows the origin and the state of the signature, without ever writing to the file. It works on a protected file too, without the password. See CLI_USAGE.md for export’s --watermark and --password options, and for identity and open.
Publishing a database for others
A marked database is distributed like any other file — email, a personal site, a USB stick. blunderDB provides no service: no repository, no hosted catalogue, no account. That follows directly from its design: nothing is ever recorded on the side of whoever receives a file, so there would be nothing to report to a service even if one existed.
What makes a published database usable by someone else comes down to four fields, all of them already there:
User — who built it, under the name you want cited.
Description — what the database holds, in one sentence that fits in a list: “240 cube decisions at a score, commented, intermediate level”.
Origin (of the watermark) — what this file is and who it was produced for. It is the first thing the recipient reads in the Metadata panel.
Issuer fingerprint — publish it beside the file, not inside it: comparing it is how the recipient checks the file comes from you and not from someone who took your name.
A database published without a watermark stays perfectly usable; it is simply anonymous, and the Metadata panel then shows no Origin section.
To make a database known, the Show and tell category of the repository discussions serves as a directory: it is a list kept by those who publish, not a service blunderDB renders. Announcing one there takes the link, the four fields above and the fingerprint.