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,
configure database export settings.
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 displayed on the dice, the position of the dice indicates which player has the turn and that the position is a cube decision.
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.5. 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.6. 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.7. 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.8. 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.9. 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.
Tip
Refer to Section 4 for the list of available filters.
2.10. 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.11. 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.
Tip
Refer to Keyboard shortcuts for available shortcuts.
2.12. 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.13. Stats Panel
2.13.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.13.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.13.3. Filter bar
The filter bar at the top of the panel restricts the computation to a subset of positions.
2.13.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.13.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.13.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.13.5. Dashboard tab
The Dashboard tab gives a summary view of key indicators.
2.13.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.13.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.13.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.13.6. Progression tab
The Progression tab shows how your level evolves over time.
2.13.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.13.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.13.7. Errors tab
The Errors tab breaks down error sources.
2.13.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.13.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.13.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.13.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.13.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.14. 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.15. 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.
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.16. 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.17. 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.