2. Manual
2.1. 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.
2.2. 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.
2.3. 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 (EPC panel),
study positions with spaced repetition (Anki panel),
display the database metadata (metadata panel),
display the operation log (log 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 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).
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.
2.4. Configuration
The configuration button (gear-shaped icon) located in the toolbar, to the left of the help button, opens the blunderDB configuration window.
It lets you choose the interface 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 across sessions.
The configuration window also lets you customise the board 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 doubling cube. The Reset button restores all the default colours. Like the language, the chosen colours are kept from one session to the next.
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.
2.5. 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). Four tours are available: a general tour of the interface, and tours dedicated to searching positions, reviewing matches and reviewing tournaments. Each tour highlights the relevant interface elements, step by step, and can be replayed at any time. On first launch, the general tour is offered automatically.
The demo command loads a sample database (matches, a tournament and analyses) that lets you explore the tool’s features without importing your own games. The guided tours rely on this database when no database is open.
2.7. 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.
2.8. 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 Section 4 for the list of available commands in the command line.
2.9. 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.
2.10. Comments Panel
The Comments panel (CTRL-P) displays, adds, and edits comments associated with the current position. Comments imported from XG files are automatically associated with the corresponding positions. Press CTRL-P or run the comment command to show or hide the panel.
2.11. 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.
To refine a search among the currently filtered positions, use the ss command followed by filters (e.g.: ss nc, ss E>40). The search panel also offers a Search in current results checkbox for the same functionality.
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 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.
Tip
Refer to Section 4 for the list of available filters.
2.12. Collections Panel
The Collections panel (CTRL-B) manages collections of positions. Collections can be created, renamed, and deleted. Positions can be added to or removed from them. Double-click a collection to browse its positions using the LEFT and RIGHT keys. The order of collections and positions within them can be changed by drag and drop. Press CTRL-B or run the collection command to show or hide the panel.
2.13. 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.
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.
When a match is open, an information bar appears above the board: it shows the players involved (player 1 versus player 2) along with the match context (event, location, round, date and match length, when this information is available).
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.
Tip
Refer to Keyboard shortcuts for available shortcuts.
2.14. Tournaments Panel
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.
2.15. Stats Panel
2.15.1. 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 Rate) 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 reference thresholds (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;
navigating directly to the relevant positions by clicking any indicator (drill-down).
2.15.2. Opening the panel
To open the Stats panel:
Press CTRL-D.
Type the command
:statsor:stin 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.
2.15.3. Filter bar
The filter bar at the top of the panel restricts the computation to a subset of positions.
2.15.3.1. 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.
2.15.3.2. 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.
2.15.4. PR / MWC toggle
The PR / MWC button at the top of the panel toggles the metric displayed across all tabs.
PR (Performance Rate)
Measures money-game play quality: sum of errors in milli-points, divided by the number of decisions. Independent of match score.
Approximate reference thresholds:
Level
PR
World-class
< 3
Expert
3 – 5
Advanced
5 – 8
Intermediate
8 – 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.
2.15.5. Dashboard tab
The Dashboard tab gives a summary view of key indicators.
2.15.5.1. Level cards
Three cards display the PR (or MWC) for:
All — all decisions (checker + cube);
Checker — checker plays only;
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.
2.15.5.2. 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.
2.15.5.3. 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.
2.15.6. Progression tab
The Progression tab shows how your level evolves over time.
2.15.6.1. 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.
2.15.6.2. 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.
2.15.7. Errors tab
The Errors tab breaks down error sources.
2.15.7.1. 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).
2.15.7.2. 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.
2.15.7.3. Error magnitude histogram
A histogram distributes errors by magnitude in milli-points (buckets: 0–5, 5–10, 10–25, 25–50, 50–100, ≥ 100). Clicking a bar loads the positions in the bucket.
2.15.8. 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, total error 50 mp → PR = 5.0
Match B: 90 decisions, total error 270 mp → PR = 3.0
Naive average of PRs: (5.0 + 3.0) / 2 = 4.0 (incorrect)
Sum/sum rule: (50 + 270) / (10 + 90) = 320 / 100 = 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).
2.15.9. MWC: limitations
The MWC cost is computed using the Kazaross-XG2 MET, the de facto reference table in competitive backgammon. Results are not directly comparable with software using other METs.
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.
2.16. EPC Panel
The EPC panel (CTRL-E) computes the EPC (Effective Pip Count) of a bearoff position. It is activated by pressing CTRL-E, clicking the EPC tab in the bottom panel, or running the epc command.
In this panel, the user edits the checker positions in the home board (last 6 points) and the following information is displayed in real time for each player:
the EPC (Effective Pip Count),
the average number of rolls needed (Mean Rolls),
the standard deviation,
the pip count,
the wastage (difference between the EPC and the pip count).
When both players have checkers in their home board, a comparison section shows the EPC and pip count differences.
To close the EPC panel, press CTRL-E or switch to another tab.
Note
The computation relies on the built-in 6-point bearoff database from GNUbg.
2.17. 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.
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.
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.
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, sync, reset, or delete decks. FSRS parameters (target retention, maximum interval, fuzz factor) can be configured per deck in the Settings (gear icon).
2.18. 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.
2.19. Log Panel
The Log panel displays the log of recent operations: imports, exports and database operations, with their results and timestamps. It is useful for diagnosing import errors.