2. Manuale
2.1. Introduzione
blunderDB è un software per creare database di posizioni di backgammon. Il suo punto di forza principale è fornire un luogo unico in cui aggregare le posizioni che un giocatore ha incontrato (online, in torneo) e poterle riesaminare filtrandole secondo vari filtri combinabili arbitrariamente. blunderDB può anche essere usato per creare cataloghi di posizioni di riferimento.
Le posizioni sono memorizzate in un database rappresentato da un file .db.
2.2. Interazioni principali
Le principali interazioni possibili con blunderDB sono:
aggiungere una nuova posizione,
modificare una posizione esistente,
copiare l’immagine del board negli appunti (PNG) tramite Ctrl+X, oppure con l’analisi completa tramite Ctrl+X Ctrl+X,
eliminare una posizione esistente,
cercare una o più posizioni,
importare match da diverse fonti (XG, GNUbg, BGBlitz, Jellyfish), compresi i commenti dai file XG,
navigare tra le mosse di un match importato,
organizzare le posizioni in raccolte,
organizzare i match in tornei.
L’utente può etichettare liberamente le posizioni con tag e annotarle tramite commenti.
2.3. Descrizione dell’interfaccia
L’interfaccia di blunderDB è composta, dall’alto verso il basso, da:
[in alto] la barra degli strumenti, che raccoglie tutte le principali operazioni eseguibili sul database,
[al centro] l’area di visualizzazione principale, che permette di visualizzare o modificare posizioni di backgammon,
[in basso] la barra di stato, che presenta diverse informazioni sul database o sulla posizione corrente e integra la riga di comando.
Possono essere visualizzati dei pannelli per:
visualizzare i dati di analisi associati alla posizione corrente provenienti da eXtreme Gammon (XG), GNUbg o BGBlitz,
visualizzare, aggiungere o modificare commenti,
cercare e filtrare posizioni secondo criteri combinabili,
visualizzare e gestire le raccolte di posizioni (pannello raccolte),
visualizzare l’elenco dei match importati e navigare tra le mosse di un match (pannello match),
visualizzare e gestire i tornei (pannello tornei),
visualizzare le statistiche di performance (pannello Stats),
calcolare l’EPC (Effective Pip Count) di una posizione di bearoff (pannello EPC),
studiare le posizioni tramite ripetizione dilazionata (pannello Anki),
visualizzare i metadati del database (pannello metadati),
visualizzare il registro delle operazioni (pannello registro).
Possono comparire finestre modali per:
visualizzare la guida di blunderDB,
visualizzare il catalogo delle visite guidate (vedi Visite guidate e database di esempio),
configurare le impostazioni di esportazione del database,
configurare blunderDB, in particolare la lingua dell’interfaccia (vedi Configurazione).
L’area di visualizzazione principale mette a disposizione dell’utente:
un board per visualizzare o modificare una posizione di backgammon,
il livello e il proprietario del cubo,
il pip count di ciascun giocatore,
il punteggio di ciascun giocatore,
i dadi da giocare. Se sui dadi non è mostrato alcun valore, la posizione dei dadi indica quale giocatore ha il turno e che la posizione è una decisione di cubo. Quando la decisione di cubo è una risposta a un raddoppio (prendi/passa), il cubo proposto è mostrato al centro del board, al valore offerto.
La barra di stato è strutturata da sinistra a destra con le seguenti informazioni:
la riga di comando, accessibile premendo il tasto SPAZIO,
un messaggio informativo relativo a un’operazione eseguita dall’utente,
l’indice della posizione corrente, seguito dal numero di posizioni nella libreria corrente (oppure le informazioni di mossa/partita durante la navigazione in un match).
Nota
Nel caso di posizioni derivanti da una ricerca dell’utente, il numero di posizioni indicato nella barra di stato corrisponde al numero di posizioni filtrate.
2.4. Configurazione
Il pulsante di configurazione (icona a forma di ingranaggio) situato nella barra degli strumenti, a sinistra del pulsante di aiuto, apre la finestra di configurazione di blunderDB.
Essa permette di scegliere la lingua dell’interfaccia tra inglese, francese, tedesco, italiano, spagnolo, finlandese, giapponese, greco e russo. L’intera interfaccia (barra degli strumenti, pannelli, messaggi, guida) viene tradotta nella lingua selezionata. La scelta della lingua viene salvata e mantenuta da una sessione all’altra.
La finestra delle impostazioni permette inoltre di personalizzare i colori del board. Ogni elemento dispone del proprio selettore di colore: lo sfondo, il bordo, le punte chiare e scure, le pedine del giocatore 1 e del giocatore 2, i dadi, i punti dei dadi e il cubo. Il pulsante Ripristina riporta tutti i colori ai valori predefiniti. Come la lingua, i colori scelti vengono conservati da una sessione all’altra.
La finestra di configurazione raggruppa anche alcune impostazioni di visualizzazione dell’interfaccia. Un cursore di scala dell’interfaccia consente di ingrandire o ridurre l’insieme degli elementi, il che è utile sugli schermi ad alta densità o per migliorare la leggibilità. Un menu posizione dei pannelli determina la collocazione dei pannelli (ricerca, match, analisi) rispetto al tavoliere: in basso, di lato o automatica (il lato viene allora scelto sugli schermi larghi per sfruttare meglio lo spazio disponibile). Come le altre impostazioni, queste scelte vengono conservate da una sessione all’altra.
2.5. Visite guidate e database di esempio
Per facilitare i primi passi, blunderDB propone delle visite guidate dell’interfaccia. Il catalogo delle visite si apre dalla barra degli strumenti o con il comando tour (alias tutorial). Sono disponibili quattro visite: una visita generale dell’interfaccia e visite dedicate alla ricerca di posizioni, alla revisione delle partite e alla revisione dei tornei. Ogni visita evidenzia gli elementi interessati dell’interfaccia, passo dopo passo, e può essere ripetuta in qualsiasi momento. Al primo avvio, la visita generale viene proposta automaticamente.
Il comando demo carica un database di esempio (partite, un torneo e analisi) che permette di scoprire le funzionalità dello strumento senza importare le proprie partite. Le visite guidate si appoggiano a questo database quando nessun database è aperto.
2.7. Modifica delle posizioni
La pressione del tasto TAB apre il pannello di ricerca e permette di modificare una posizione sul board per aggiungerla al database o per definire una struttura di posizione da cercare. La distribuzione delle pedine, il cubo, il punteggio e il turno possono essere modificati con il mouse (vedi Modificare una posizione).
Suggerimento
Fare riferimento a Scorciatoie da tastiera per le scorciatoie disponibili.
2.8. La riga di comando
La riga di comando, integrata nella barra di stato, permette di eseguire tutte le funzionalità di blunderDB disponibili nell’interfaccia grafica: operazioni generali sul database, navigazione delle posizioni, visualizzazione dell’analisi e/o dei commenti, ricerca di posizioni secondo filtri… Dopo aver preso confidenza con l’interfaccia, si raccomanda di utilizzare progressivamente la riga di comando, che consente un uso potente e fluido di blunderDB, in particolare per le funzionalità di ricerca delle posizioni.
Per aprire la riga di comando, premere il tasto SPAZIO. Per inviare una richiesta e chiudere la riga di comando, premere il tasto INVIO.
blunderDB esegue le richieste inviate dall’utente a condizione che siano valide e modifica immediatamente lo stato del database se necessario. Non sono richieste azioni di salvataggio esplicite da parte dell’utente.
Suggerimento
Fare riferimento a Sezione 4 per l’elenco dei comandi disponibili nella riga di comando.
2.9. Pannello Analisi
Il pannello Analisi (CTRL-L) visualizza i dati di analisi della posizione corrente importati da eXtreme Gammon (XG), GNUbg o BGBlitz. Mostra le migliori alternative (mosse di pedine o decisioni di cubo) con i relativi valori di equity e gli errori corrispondenti. Il tasto d alterna tra l’analisi delle mosse di pedine e l’analisi del cubo. Durante la navigazione in un match, la mossa effettivamente giocata viene evidenziata nell’elenco delle alternative. Premere CTRL-L o eseguire il comando list per mostrare o nascondere il pannello.
2.10. Pannello Commenti
Il pannello Commenti (CTRL-P) visualizza, aggiunge e modifica i commenti associati alla posizione corrente. I commenti importati dai file XG vengono automaticamente associati alle posizioni corrispondenti. Premere CTRL-P o eseguire il comando comment per mostrare o nascondere il pannello.
2.11. Pannello Ricerca
Il pannello Ricerca (CTRL-F o TAB) permette di filtrare le posizioni secondo criteri liberamente combinabili: struttura delle pedine, tipo di decisione di cubo, magnitudo dell’errore, date, tag, ecc. Il tasto TAB apre contemporaneamente il pannello di ricerca e l’editor di posizione, consentendo di definire una struttura di pedine da cercare direttamente sul board.
Per affinare una ricerca tra le posizioni attualmente filtrate, usare il comando ss seguito da filtri (es.: ss nc, ss E>40). Il pannello di ricerca offre anche una casella di spunta Search in current results per la stessa funzionalità.
Il pannello offre un controllo esplicito del tipo di decisione ricercato: Indifferente (nessun filtro), Pedine (decisioni di mossa) o Cubo (decisioni di cubo). Quando è selezionato Cubo, un secondo elenco precisa il sotto-tipo: Tutti, Raddoppio / No raddoppio (il giocatore di turno deve decidere se raddoppiare) o Accetta / Passa (risposta a un raddoppio avversario). Il controllo è sincronizzato con il board: modificare i dadi o il cubo sul board aggiorna il tipo di decisione, e viceversa. In modalità Accetta / Passa, il cubo è mostrato al centro del board al valore offerto; tale valore resta modificabile.
Suggerimento
Fare riferimento a Sezione 4 per l’elenco dei filtri disponibili.
2.12. Pannello Raccolte
Il pannello Raccolte (CTRL-B) permette di gestire raccolte di posizioni. Le raccolte possono essere create, rinominate ed eliminate. Le posizioni possono esservi aggiunte o rimosse. Fare doppio clic su una raccolta per scorrere le sue posizioni con i tasti SINISTRA e DESTRA. L’ordine delle raccolte e delle posizioni al loro interno può essere modificato tramite trascinamento. Premere CTRL-B o eseguire il comando collection per mostrare o nascondere il pannello.
2.13. Pannello Match
Il pannello Match (CTRL-Tab) elenca i match importati. Fare doppio clic su un match (o premere INVIO) per navigare tra le sue mosse. Il comando m riprende la navigazione nell’ultimo match visitato.
L’utente può:
scorrere le mosse di un match usando i tasti SINISTRA e DESTRA,
passare da una partita all’altra con i tasti PageUp e PageDown,
visualizzare l’analisi delle mosse (pedine e cubo) premendo CTRL-L,
alternare tra l’analisi delle mosse di pedine e quella del cubo con il tasto d,
vedere la mossa effettivamente giocata evidenziata nell’analisi.
L’ultima posizione visitata in ciascun match viene memorizzata e ripristinata automaticamente. Premere CTRL-Tab o eseguire il comando match per mostrare o nascondere il pannello.
Quando un match è aperto, una barra delle informazioni appare sopra il tavoliere: ricorda i giocatori coinvolti (giocatore 1 contro giocatore 2) nonché il contesto del match (evento, luogo, turno, data e lunghezza del match, quando queste informazioni sono disponibili).
All’apertura di un database contenente match, il pannello Match viene mostrato subito e la revisione inizia direttamente sulla prima posizione, così da cominciare immediatamente la navigazione.
Suggerimento
Fare riferimento a Scorciatoie da tastiera per le scorciatoie disponibili.
2.14. Pannello Tornei
Il pannello Tornei (CTRL-Y) permette di raggruppare i match in tornei per un monitoraggio organizzato e un’analisi statistica per evento. I tornei possono essere creati, rinominati ed eliminati; i match possono essere assegnati ad essi. Le statistiche del pannello Stats possono essere filtrate per torneo. Premere CTRL-Y per mostrare o nascondere il pannello.
2.15. Pannello Stats
2.15.1. Introduzione
Il pannello Stats permette di analizzare il proprio livello di gioco e di seguire la propria progressione nel tempo a partire dalle posizioni importate nel database. Calcola e visualizza gli indicatori PR (Performance Rate) e MWC cost (Match Winning Chance cost) per l’insieme delle posizioni o per un sottoinsieme filtrato.
Il pannello Stats è particolarmente utile per:
valutare il proprio livello rispetto alle soglie di riferimento (world-class, esperto, avanzato…) grazie al PR globale;
seguire la propria progressione torneo dopo torneo o match dopo match grazie ai grafici della scheda Progressione;
individuare i propri punti deboli: la scheda Errori mostra la ripartizione tra mosse di pedine e decisioni di cubo e la distribuzione delle magnitudo d’errore;
accedere direttamente alle posizioni interessate cliccando su qualsiasi indicatore (drill-down).
2.15.2. Apertura del pannello
Per aprire il pannello Stats:
Premere CTRL-D.
Digitare il comando
:statso:stnella riga di comando.
Nota
Il pannello si aggiorna automaticamente a ogni modifica del filtro. Non ricalcola le statistiche in caso di semplice passaggio PR ↔ MWC: entrambe le metriche vengono calcolate simultaneamente dal backend.
2.15.3. Barra dei filtri
La barra dei filtri, in alto nel pannello, permette di limitare il calcolo a un sottoinsieme di posizioni.
2.15.3.1. Prospettiva del giocatore
Il menu a discesa Giocatore permette di filtrare le statistiche in base al giocatore analizzato. blunderDB seleziona automaticamente il giocatore il cui nome compare più spesso nel database — modificabile in qualsiasi momento.
Suggerimento
Cambiare giocatore non comporta alcuna perdita di dati; è sufficiente riselezionare il giocatore precedente dall’elenco.
2.15.3.2. Filtri disponibili
Torneo(i) — restrizione a uno o più tornei. È possibile selezionare più tornei contemporaneamente.
Date — intervallo temporale (Da … A). Se viene indicata solo la data di inizio, vengono incluse le posizioni più recenti.
Tipo di decisione — Tutti / Mosse di pedine / Decisioni di cubo.
Lunghezza del match — restrizione a lunghezze di match specifiche (1, 3, 5, 7, 9, 11, 13, 15, 21 punti). È possibile combinare più lunghezze.
Un pulsante Reset azzera tutti i filtri (tranne il giocatore rilevato automaticamente).
Nota
I filtri vengono salvati nella configurazione di blunderDB (config.yaml) e ripristinati all’avvio successivo.
2.15.4. Commutazione PR / MWC
Il pulsante PR / MWC in alto nel pannello commuta la metrica visualizzata in tutte le schede.
PR (Performance Rate)
Misura la qualità di gioco money-game: somma degli errori in millesimi di punto, divisa per il numero di decisioni. Indipendente dal punteggio del match.
Soglie di riferimento approssimative:
Livello
PR
World-class
< 3
Esperto
3 – 5
Avanzato
5 – 8
Intermedio
8 – 12
Principiante
> 12
MWC cost (Match Winning Chance cost)
Probabilità cumulata di vittoria del match persa a causa degli errori, sull’intero set di dati filtrato. Calcolata a partire dalla MET Kazaross-XG2 integrata in blunderDB.
Attenzione
Il MWC cost non è applicabile alle posizioni money-game (senza posta di match). Queste posizioni sono escluse dal calcolo MWC. I valori MWC dipendono dalla MET utilizzata; non sono direttamente confrontabili tra software che usano MET diverse.
La commutazione PR ↔ MWC è istantanea: non viene eseguito alcun ricalcolo da parte del backend.
2.15.5. Scheda Dashboard
La scheda Dashboard offre una visione sintetica degli indicatori chiave.
2.15.5.1. Schede di livello
Tre schede visualizzano il PR (o MWC) per:
All — tutte le decisioni (pedine + cubo);
Checker — solo mosse di pedine;
Cube — solo decisioni di cubo.
Cliccando su una scheda si caricano nel pannello di analisi le posizioni del sottoinsieme corrispondente (drill-down).
Nota
Il numero totale di decisioni viene visualizzato in fondo a ciascuna scheda al passaggio del mouse.
2.15.5.2. PR mobile sulle ultime N decisioni
Una riga di valori PR (o MWC) calcolati sulle ultime N decisioni (N = 5, 10, 50, 100, 250, 500, 1000) permette di misurare la tendenza recente. I valori in grigio corrispondono a un N superiore al numero di decisioni disponibili.
Cliccando su un valore si caricano le ultime N posizioni corrispondenti.
2.15.5.3. Top blunder
L’elenco dei 10 errori peggiori (o MWC cost), ordinati per magnitudo decrescente. Cliccando su una riga si carica la posizione interessata nel pannello di analisi.
2.15.6. Scheda Progressione
La scheda Progressione presenta l’evoluzione del livello nel tempo.
2.15.6.1. Grafico a linee per torneo
Un grafico a linee visualizza il PR (o MWC) per ciascun torneo (asse X: ordine dei tornei, asse Y: valore della metrica). Bande colorate evidenziano le soglie di livello.
Cliccando su un punto del grafico si apre un menu contestuale con due opzioni:
Open tournament — apre il torneo nel pannello Tornei.
Open positions — carica tutte le posizioni del torneo nel pannello di analisi.
2.15.6.2. Scatter plot per match
Un grafico a dispersione rappresenta ciascun match (asse X: data, asse Y: PR o MWC). La dimensione del punto è proporzionale al numero di decisioni nel match.
Cliccando su un punto si apre un menu contestuale:
Open match — apre il match nel pannello Match.
Open positions — carica tutte le posizioni del match nel pannello di analisi.
2.15.7. Scheda Errori
La scheda Errori scompone le fonti di errore.
2.15.7.1. Ripartizione per azione di cubo
Un diagramma a barre visualizza il PR (o MWC) per ciascun tipo di decisione di cubo: NoDouble, DoubleTake, DoublePass, TooGood. Ogni barra indica inoltre il numero di decisioni e il tasso di blunder in un suggerimento.
Cliccando su una barra si caricano le posizioni corrispondenti a quell’azione di cubo, solo quelle con un errore (drill-down).
2.15.7.2. Confronto Checker / Cube
Un diagramma comparativo affianca il PR delle mosse di pedine e quello delle decisioni di cubo. Cliccando su una barra si caricano le posizioni del sottoinsieme con errore.
2.15.7.3. Istogramma delle magnitudo d’errore
Un istogramma distribuisce gli errori in base alla loro magnitudo in millesimi di punto (fasce: 0–5, 5–10, 10–25, 25–50, 50–100, ≥ 100). Cliccando su una barra si caricano le posizioni della fascia.
2.15.8. Regola di aggregazione
Importante
Il PR di un torneo (o di un qualsiasi sottoinsieme) è calcolato con la regola somma/somma — mai come media dei PR individuali dei match.
Formula:
Esempio: un giocatore disputa due match in un torneo —
Match A: 10 decisioni, errore totale 50 mp → PR = 5,0
Match B: 90 decisioni, errore totale 270 mp → PR = 3,0
Media ingenua dei PR: (5,0 + 3,0) / 2 = 4,0 (errato)
Regola somma/somma: (50 + 270) / (10 + 90) = 320 / 100 = 3,2 (corretto)
La regola somma/somma è l’unica che gestisce correttamente la variazione di lunghezza dei match (un match a 21 punti pesa più di un match a 1 punto).
2.15.9. MWC: limitazioni
Il MWC cost è calcolato a partire dalla MET Kazaross-XG2, tabella di riferimento di fatto nel backgammon agonistico. I risultati non sono direttamente confrontabili con software che usano altre MET.
Le posizioni money-game (senza punteggio di match) sono escluse dal calcolo MWC. Se il database contiene molte posizioni money-game, il MWC cost potrebbe essere sottostimato o non disponibile.
Il MWC cost è cumulativo sull’intero set di dati filtrato — non è un indicatore per singola decisione. Misura l’impatto totale dei tuoi errori sulle tue probabilità di vittoria.
2.16. Pannello EPC
Il pannello EPC (CTRL-E) calcola l’EPC (Effective Pip Count) di una posizione di bearoff. Si attiva premendo CTRL-E, cliccando sulla scheda EPC nel pannello inferiore o eseguendo il comando epc.
In questo pannello, l’utente modifica la posizione delle pedine nella casa (gli ultimi 6 punti) e le seguenti informazioni vengono visualizzate in tempo reale per ciascun giocatore:
l’EPC (Effective Pip Count),
il numero medio di lanci necessari (Mean Rolls),
la deviazione standard (Standard Deviation),
il pip count,
il wastage (differenza tra l’EPC e il pip count).
Quando entrambi i giocatori hanno pedine nella propria casa, una sezione di confronto mostra le differenze di EPC e di pip count.
Per chiudere il pannello EPC, premere CTRL-E o passare a un’altra scheda.
Nota
Il calcolo si basa sul database interno di bearoff a 6 punti di GNUbg.
2.17. Pannello Anki
Il pannello Anki (CTRL-K) permette di studiare le posizioni tramite ripetizione dilazionata utilizzando l’algoritmo FSRS. L’utente può creare mazzi a partire da raccolte o risultati di ricerca.
Creazione di mazzi: Cliccare su New Deck per creare un mazzo a partire da una raccolta o dai risultati di ricerca correnti. I mazzi basati su una ricerca si sincronizzano automaticamente all’apertura della scheda Anki.
Revisione: Selezionare un mazzo e poi cliccare su Study (oppure fare doppio clic su un mazzo) per iniziare la revisione delle carte in scadenza. Ogni carta mostra la posizione corrispondente sul board. Valutare il proprio richiamo con i tasti 1 (Da rivedere), 2 (Difficile), 3 (Bene) o 4 (Facile). Premere Esc per interrompere e tornare all’elenco dei mazzi.
Allenamento libero (cram): Il pulsante Cram, accanto a Study, avvia una sessione di allenamento libero: ti vengono mostrate posizioni casuali del mazzo senza tenere conto della pianificazione FSRS. Questa modalità non modifica mai il piano di ripetizione dilazionata — ideale per scaldarsi prima di un torneo o per ripassare intensamente un mazzo tematico senza alterarne l’ordine. Un’etichetta Cram sostituisce lo stato della carta e un pulsante Avanti (tasti 1–4) scorre le posizioni. Esc torna all’elenco senza salvare una sessione interrotta.
Interruzione/Ripresa: È possibile interrompere una sessione di revisione in qualsiasi momento con Esc. Il pulsante cambia in Resume e mostra la tua progressione. Cliccarci sopra per riprendere da dove ci si era fermati.
Gestione dei mazzi: Usare i pulsanti di azione per rinominare, sincronizzare, reimpostare o eliminare i mazzi. I parametri FSRS (ritenzione obiettivo, intervallo massimo, fattore di casualità) possono essere configurati per mazzo nelle Impostazioni (icona a ingranaggio).
2.18. Pannello Metadati
Il pannello Metadati visualizza le informazioni generali del database corrente: nome, descrizione, numero di posizioni, numero di match e di partite, versione dello schema. Accessibile tramite il comando meta.
2.19. Pannello Registro
Il pannello Registro visualizza il registro delle operazioni recenti: importazioni, esportazioni e operazioni sul database, con i relativi risultati e marche temporali. È utile per diagnosticare gli errori di importazione.