Blog
Upkeep, il gestionale dei tornei di Pauperwave
Cover illustration: Whiskerquill Scribe by Matt Stewart
DevelopmentNuxtVueSide projectsNov 6, 2026 (updated Nov 12, 2026) — 16 min read

Upkeep, il gestionale dei tornei di Pauperwave

Una serata di torneo di Magic, dall'inizio alla fine: iscrizioni, banco del check-in, accoppiamenti svizzeri e Commander, il timer sul telefono, i risultati da Telegram, il punteggio e la distribuzione dei premi, con le decisioni dietro ogni passaggio.

Emanuele Nardi

Emanuele Nardi

In Magic l'upkeep è la sottofase di mantenimento all'inizio del turno, quella in cui paghi per tenere in gioco quello che hai. Per il gestionale di Pauperwave mi è sembrato il nome adatto: tiene in ordine soci, tessere, tornei, classifiche e conti, e ha un bot Telegram per i giocatori.

La storia del progetto, e quanto si è allontanato dal piano iniziale, l'ho raccontata nell'articolo sulla migrazione del blog di Pauperwave. Qui seguo una serata di torneo, dalle iscrizioni alla consegna delle buste di carte in premio, che è la parte più difficile e quella su cui ho messo più di me. Dietro ogni passaggio c'è una decisione scritta nel repository come ADR (Architecture Decision Record); al momento sono 71.

Prima del torneo: regole e iscrizioni

Durata e numero dei round stanno nelle impostazioni dell'associazione, divise per famiglia di formato. Un round 1 contro 1 dura 50 minuti, il tempo consigliato dalle Magic Tournament Rules per Constructed (ognuno porta il proprio mazzo) e Limited (il mazzo si costruisce sul posto con carte aperte al momento); uno di Commander ne dura 75. Se si cambia un valore, vale per i tornei creati da lì in poi, e sul singolo torneo la durata resta modificabile.

Ci si iscrive dal bot con /iscriviti, anche a torneo iniziato: il torneo è alle 20:30, alle 20:35 arriva qualcuno di corsa. Il bot gli dice quanti round sono già partiti e lo mette nel round successivo, senza toccare gli abbinamenti già fatti. Nell'anteprima dei tavoli il suo nome ha il bordo giallo e il badge "Iscritto in ritardo", solo nel round in cui entra, perché l'organizzatore se ne accorga.

Il banco del check-in

La sera del torneo il passo "Accettazione" ha una sola tabella di iscritti, con i filtri Tutti, Da pagare e Accettati. Chi arriva senza iscrizione si cerca tra i soci e si aggiunge da lì. La ricerca mostra solo le tessere attive, e lo stato della tessera lo calcola una vista dalla data dell'ultimo rinnovo: quando una tessera scade, il socio sparisce dalla lista senza che nessuno debba fare niente.

Il pagamento si registra con un pulsante per riga (contanti, POS, omaggio), ed è il pagamento ad accettare il giocatore: la riga diventa verde e resta al suo posto. All'inizio c'era un pulsante "Accetta" e il pagamento si segnava dopo, al contrario di come lavora chi sta al banco, dove chi paga entra nel torneo. Ogni click scrive una riga nei conti con il nome di chi stava al banco, che si sceglie una volta per serata. Chiederlo a ogni giocatore avrebbe aggiunto un menu a una serata già abbastanza caotica.

Il round 1 e gli accoppiamenti

Gli algoritmi di accoppiamento sono due. Nello svizzero si gioca uno contro uno e chi ha gli stessi punti si incontra. Il Commander è un formato multigiocatore, in cui ognuno ha un mazzo guidato da una creatura leggendaria, il comandante: si gioca in tre o quattro allo stesso tavolo, e lì l'obiettivo è comporre tavoli equilibrati. Il round 1 parte per entrambi da un sorteggio con un seed, un codice come SEC-123 che si può leggere ad alta voce e ridigitare per ricostruire gli stessi tavoli.

Svizzera, uno contro uno

La usano i formati Constructed del club (Pauper, solo carte comuni; Premodern e Old School, solo carte stampate entro una certa epoca del gioco) e quelli Limited: Sealed, dove ognuno costruisce il mazzo con le buste che apre, e Cubo Vintage, una raccolta fissa di carte potenti da cui si costruiscono i mazzi. Anche il Draft, dove si siede in gruppi, i pod, e ci si passano le carte scegliendone una alla volta. Al round 1 si gioca contro qualcuno del proprio pod, come prevedono le regole, e il sorteggio mescola solo dentro i pod; dal secondo round si torna allo svizzero su tutto il torneo.

Il punteggio è quello ufficiale e non si può configurare: 3 punti per una vittoria, 1 per un pareggio, 0 per una sconfitta. Gli spareggi sono, in ordine, la percentuale di vittorie degli avversari, la propria percentuale di partite vinte e quella degli avversari, ognuna con un minimo di 0,33. Nella prima versione avevo messo 1/3, andando a memoria; poi ho letto l'Appendice C delle regole e l'ho corretto. La classifica si ricalcola dai risultati appena ne arriva uno nuovo, senza essere salvata, così non c'è niente che possa andare fuori sincrono.

Dal secondo round i giocatori sono ordinati per punti e spareggi e accoppiati in sequenza, evitando i rematch. Per quanto ne so, il software ufficiale di Wizards of the Coast raggruppa per punteggio ma mescola a caso l'ordine dentro ogni fascia. Io ho preferito un ordine deterministico, e il motivo è un bug. Guardando l'anteprima mi ero annotato «la sensazione è che le coppie siano ancora random», e in effetti a ogni apertura i giocatori venivano rimescolati. Con un ordine casuale dentro le fasce avrei avuto lo stesso effetto un livello più in basso, e per una lega non sanzionata, cioè fuori dal circuito ufficiale dei tornei, imitare il software ufficiale non mi dava niente. Adesso l'anteprima spiega l'algoritmo per esteso, e chi vuole mescolare ha il pulsante "Mescola".

Il bye va al giocatore più in basso in classifica che non ne ha ancora avuto uno. Qui le regole non aiutano: dicono solo quanto vale un bye, cioè una vittoria 2-0, e il resto è la prassi dei software da torneo.

Un testo incollato in una chat citava la "MTR 2.5" come fonte della regola sul bye. La 2.5 parla di concessioni e pareggi intenzionali. Da allora controllo sempre il regolamento.

Commander, tavoli da tre o quattro

Dal secondo round i tavoli li compone un ottimizzatore che ho portato dal vecchio gestore delle leghe. Dà un punteggio a ogni disposizione e premia:

  • tavoli equilibrati, senza i primi e gli ultimi della classifica tutti insieme;
  • giocatori che non si sono ancora incontrati (chi si è già trovato allo stesso tavolo pesa in negativo);
  • la rotazione dei tavoli da tre, perché non tocchino sempre agli stessi;
  • la preferenza tra tavoli da quattro e da tre.

Il codice è arrivato intero, ma per ora Upkeep gli passa solo la classifica. Lo storico degli incontri e dei tavoli da tre non è ancora collegato, quindi quei due criteri oggi valgono zero per tutti; ci torno nella parte sul tavolo da tre.

Le coppie di giocatori da tenere separati sono un vincolo rigido: una disposizione che le mette allo stesso tavolo viene scartata. L'ottimizzatore parte da tre ordinamenti (per classifica, per chi deve uscire dai tavoli da tre, per punti), riempie i tavoli uno alla volta con una ricerca greedy (golosa: a ogni passo la scelta migliore sul momento) e poi scambia giocatori tra tavoli finché trova miglioramenti, entro qualche centinaio di millisecondi. Dei tre risultati tiene il migliore. L'organizzatore vede il punteggio di ogni tavolo nell'anteprima e può sempre spostare i giocatori a mano.

Ogni passaggio è tutto o niente

Avviare il torneo, passare al round successivo, tornare indietro di un round, azzerare un tavolo: ognuna di queste transizioni è una route del server che controlla i permessi e poi chiama una sola funzione Postgres atomica. Se qualcosa si rompe a metà, non resta un round mezzo creato o un tavolo senza giocatori.

Azzerare un tavolo del Commander, per esempio, cancella piazzamenti, uccisioni e voti e lascia il tavolo con i suoi giocatori, pronto per ricominciare:

reset_commander_pairing.sql
create function public.reset_commander_pairing(
  p_pairing_uuid uuid
)
returns void
language plpgsql
set search_path to 'public'
as $function$
begin
  delete from tournament_round_results where pairing_uuid = p_pairing_uuid;
  delete from tournament_kills where pairing_uuid = p_pairing_uuid;
  delete from tournament_votes where pairing_uuid = p_pairing_uuid;
end;
$function$;

Una funzione plpgsql gira in un'unica transazione. Se la terza delete fallisce, Postgres annulla anche le prime due, e il tavolo non resta con i voti ma senza piazzamenti.

L'interfaccia segue la stessa idea. Lo stepper del torneo mostra tutti i passi, ma quelli non ancora raggiunti sono disabilitati: si va avanti solo con pulsanti come "Avvia torneo" o "Prossimo round", e un link che punta a un passo futuro viene ignorato.

Il timer sincronizzato

All'inizio il conto alla rovescia del round viveva solo nel browser dell'organizzatore, e il server non ne sapeva niente. Adesso ogni azione sul timer (avvio, pausa, salto di fase, minuti aggiunti, reset) la esegue il server, che legge la propria ora e scrive il nuovo stato in una tabella: il browser dell'organizzatore manda solo il nome dell'azione, mai un istante. Il timer parte da solo anche quando annuncio i tavoli. La Mini App dei turni su Telegram legge da lì, dopo aver verificato la firma che Telegram allega a ogni apertura, e mostra a ogni giocatore il suo tavolo e il tempo che resta.

Gli aggiornamenti passano da Supabase Realtime, che uso solo come campanello: quando arriva un messaggio, la Mini App rilegge lo stato dal server senza fidarsi del contenuto. Lo stesso fanno le pagine dell'organizzatore. Il timer cambia solo quando l'organizzatore preme un pulsante: aprire la pagina legge soltanto lo stato. Se due dispositivi agiscono insieme, il secondo riceve un errore e riprova sullo stato aggiornato, così uno schermo rimasto indietro non sovrascrive il timer in corso.

Tre secondi di ritardo

Poi è arrivata una segnalazione: «3 secondi di ritardo nel timer» tra lo schermo dell'organizzatore e i telefoni. Il tempo si può perdere in tre punti.

  • Gli orologi. Quello del telefono non coincide con quello del server, per questo il server risponde anche con la sua ora e la Mini App calcola la differenza. La prima versione la confrontava con l'istante in cui arrivava la risposta, e con una rete lenta il timer restava indietro di metà del viaggio. Adesso usa il punto a metà tra richiesta e risposta, come fanno i protocolli che sincronizzano gli orologi.
  • La pubblicazione. Nella prima versione il timer dell'organizzatore mandava i secondi trascorsi interi, perdendo fino a quasi un secondo, e il server leggeva la sua ora solo dopo aver controllato i permessi, spostando in avanti l'istante di partenza. Questo punto l'ho già corretto: il server legge l'ora prima di qualsiasi controllo e calcola lui gli istanti, senza l'orologio del dispositivo dell'organizzatore.
  • Il giro di Realtime. Tra la scrittura nel database, l'avviso e la nuova lettura passa altro tempo.

Il ritardo non sono ancora riuscito a riprodurlo. Nel frattempo la Mini App scrive nella console del browser, a ogni lettura, il viaggio di andata e ritorno e le due stime della differenza tra gli orologi, e a ogni avviso il tempo fino allo schermo. Alla prossima serata guardo quale dei due punti ancora aperti pesa davvero, e solo dopo decido dove intervenire.

I risultati arrivano da Telegram

Anche qui svizzero e Commander vanno per strade diverse. Nello svizzero c'è un solo numero da comunicare, il punteggio del match; nel Commander ogni giocatore racconta la propria partita.

In entrambi chi vuole lasciare il torneo (il drop) usa /drop, dopo aver inserito il risultato del round: quel round conta, il drop vale dal successivo. Per i soci senza Telegram c'è un'indicazione sul profilo, così l'organizzatore sa per chi inserire i dati a mano.

Svizzera, uno contro uno

All'annuncio dei tavoli ogni giocatore riceve un messaggio con il numero del tavolo e l'avversario, lo stesso che risponde a /tavolo. A fine match uno dei due tocca "Inserisci risultato", sceglie il punteggio in game, cioè le singole partite del match (2-0, 2-1, 1-1, 1-2, 0-2), controlla il riepilogo e invia.

All'inizio il risultato restava in attesa finché l'avversario non lo confermava. L'ho cambiato: adesso si scrive subito, come se l'avesse inserito l'organizzatore, con un badge "Inserito da" e l'orario. L'avversario riceve lo stesso il punteggio visto dalla sua parte, con i pulsanti per confermare o contestare. Una contestazione lascia il risultato dov'è e avvisa l'organizzatore, che decide. Se l'avversario non ha collegato Telegram, il bot lo dice a chi ha inviato: un eventuale errore lo correggerà l'organizzatore.

  1. All’annuncio dei tavoli, o con il comando /tavolo, arriva il messaggio del tavolo, con l’avversario
  2. "Inserisci risultato" chiede quanti game hai vinto: 2-0, 2-1, 1-1, 1-2 o 0-2
  3. Il riepilogo: "Modifica" torna alla scelta, "Invia" registra il risultato subito, come se l’avesse inserito l’organizzatore
  4. Se l’avversario ha Telegram gli arriva il risultato con due pulsanti: "Confermo" lo conferma con l’orario, "Non è corretto" lo segnala all’organizzatore, che decide
  5. Se non ha Telegram, un risultato sbagliato lo corregge l’organizzatore
A sinistra chi inserisce il risultato, a destra il suo avversario.

Commander, tre o quattro al tavolo

Qui il bot fa le domande una dopo l'altra: comandante (anche due, per le carte che permettono di averne una coppia), posizione al tavolo, uccisioni, voti. Ogni risposta viene salvata appena si tocca il pulsante, quindi il riepilogo finale non scrive niente, e "Modifica" riporta alla domanda sulla posizione.

I punti di un piazzamento si assegnano solo quando tutti quelli arrivati prima hanno inserito il proprio risultato. Senza questa regola succedeva una cosa assurda: un giocatore arrivato quarto, l'unico ad aver inserito il risultato, risultava primo.

  1. Il comando /tavolo apre il messaggio del tavolo
  2. "Imposta comandante" cerca prima tra i comandanti già giocati, poi su Scryfall
  3. Se il comandante può averne un secondo: un "Partner with" si compila da solo, per Partner, Background e le altre coppie si cerca tra i soli compatibili
  4. Salvato il comandante, si torna al messaggio del tavolo
  5. "Inserisci risultato" chiede la posizione al tavolo
  6. Poi le uccisioni, il voto del mazzo e il voto della giocata
  7. Il riepilogo: "Modifica" torna alla posizione, "Conferma" invia il risultato
  8. Se non è l’ultimo round, il bot chiede se si vuole lasciare il torneo, con /drop
  9. Quando tutto il tavolo ha finito arrivano i voti ricevuti e il punteggio, altrimenti chi manca ancora, con "Aggiorna" per ricontrollare
Dal comandante si torna al messaggio del tavolo, e "Modifica" riporta alla posizione.

Un altro caso è il tavolo finito senza uccisioni. Restava segnato come "uccisioni mancanti", perché zero righe nel database volevano dire sia "nessuna" sia "non ancora inserite". Adesso l'organizzatore lo dichiara esplicitamente, e il server rifiuta la dichiarazione su un tavolo che ha già delle uccisioni.

Il punteggio del Commander

Le regole del Commander sono dell'associazione: stanno in un regolamento, e se ne può creare un altro con valori diversi. Nel regolamento base ogni tavolo dà punti per piazzamento, uccisioni e voti:

CosaPunti nel regolamento base
Piazzamento: 1°, 2°, 3°, 4°8, 6, 4, 2
Ogni uccisione1
Ogni voto al mazzo ricevuto2
Ogni voto alla giocata ricevuto1

Chi arriva primo con due uccisioni e un voto al mazzo fa 8 + 2 + 2 = 12 punti. Il massimo a un tavolo da quattro è vincere, eliminare tutti e tre gli avversari e ricevere da ognuno sia il voto al mazzo sia quello alla giocata: 8 + 3 + 6 + 3 = 20.

Con i pari merito i punti si dividono. Le posizioni si salvano "dense": due primi a pari merito e poi gli altri diventano 1, 1, 2, 3. Per i punti però conta quanti giocatori stanno sopra, e chi viene dopo due primi è di fatto terzo. I due primi si dividono i punti del primo e del secondo posto, (8 + 6) / 2 = 7 a testa (arrotondato per difetto quando non è intero), e il successivo prende i 4 del terzo. Se tutto il tavolo finisce primo senza uccisioni è una "patta": i punti si dividono allo stesso modo e la vittoria non va a nessuno.

La classifica finale è la somma dei tavoli. A parità di punti contano, in ordine, vittorie, uccisioni, voti al mazzo e voti alla giocata. Anche questo ordine viene dal vecchio gestore delle leghe. Vittorie e uccisioni sono fatti, i voti invece li danno gli altri giocatori, e in una lega piccola, dove ci si ritrova sempre tra le stesse persone, il voto di cortesia tra amici capita davvero. Per questo i voti vengono per ultimi.

Il tavolo da tre

I tavoli sono da quattro finché si può, da tre solo quanto basta. Per sapere quanti ne servono basta il resto della divisione per quattro. Un tavolo da tre ha un posto in meno di uno da quattro, quindi se dopo aver riempito i tavoli da quattro avanzano r giocatori, servono (4 − r) tavoli da tre, e nessuno se il resto è zero:

GiocatoriResto della divisione per 4Tavoli da treTavoli da quattro
12003
13131
14222
15313

Sono due operazioni, con 8 giocatori come con 80. Gli unici numeri che non funzionano sono 5, che non si divide in tavoli da tre e da quattro, e quelli sotto i 3:

useCommanderPods.ts
const IDEAL_POD_SIZE = 4
const MIN_POD_SIZE = 3

function calculatePods(playerCount: number): CommanderPodSplit {
  if (playerCount < MIN_POD_SIZE || playerCount === 5) {
    return { canPlay: false, tableCount: 0, tableSizes: [] }
  }

  const smallTables = (IDEAL_POD_SIZE - (playerCount % IDEAL_POD_SIZE)) % IDEAL_POD_SIZE
  const idealTables = (playerCount - smallTables * MIN_POD_SIZE) / IDEAL_POD_SIZE

  const tableSizes = [
    ...Array.from({ length: idealTables }, () => IDEAL_POD_SIZE),
    ...Array.from({ length: smallTables }, () => MIN_POD_SIZE)
  ]

  return { canPlay: true, tableCount: tableSizes.length, tableSizes }
}

Il secondo % IDEAL_POD_SIZE serve per il resto zero: senza, con 12 giocatori uscirebbero quattro tavoli da tre. La stessa formula è anche nelle funzioni Postgres che avviano e fanno avanzare i round, per quando l'organizzatore non ha cambiato a mano la composizione dei tavoli.

Il punteggio, invece, non cambia con la dimensione del tavolo: a un tavolo da tre manca semplicemente il quarto posto. Le conseguenze:

  • l'ultimo a un tavolo da tre prende 4 punti, quelli del terzo posto, contro i 2 dell'ultimo a un tavolo da quattro;
  • i punti di piazzamento in palio sono 18 su tre giocatori invece di 20 su quattro, 6 a testa in media invece di 5;
  • gli avversari da eliminare sono due, quindi al massimo due uccisioni;
  • i voti in media non cambiano: ognuno ne dà uno al mazzo e uno alla giocata, e in media ne riceve uno per tipo.

Rifacendo gli esempi di prima, il primo con due uccisioni e un voto al mazzo fa sempre 12 punti, ma qui due uccisioni vogliono dire aver eliminato tutti. Il massimo scende a 8 + 2 + 4 + 2 = 16.

Per compensare ci sono state un paio di idee. Nel vecchio regolamento chi sedeva a un tavolo da tre poteva dare due voti alla giocata, così in palio c'erano tanti voti quanti a un tavolo da quattro. In pratica, per par condicio, i giocatori davano un punto a ciascun avversario, e il voto aveva smesso di essere un giudizio. In Upkeep ognuno dà un voto per tipo, a qualunque tavolo. L'altra idea era moltiplicare per 1,5 i voti ricevuti a un tavolo da tre: è stata provata sui dati di un torneo vero, dove spostava il terzo posto, ma per ora è rimasta una proposta.

Si può anche far girare il tavolo da tre. Il vecchio gestore contava, su tutti i tornei della lega, quante volte ogni giocatore ci era finito, e l'ottimizzatore ci mandava già dal primo turno chi ci era stato meno. In Upkeep il criterio esiste ma lo storico non è collegato, quindi il primo turno è un sorteggio e quel conteggio vale zero per tutti.

Una soluzione davvero equa non l'ho ancora trovata.

A fine serata: classifica e buste

L'ultimo passo è dividere le buste in premio secondo la classifica. Il programma propone una distribuzione senza salvarla: l'organizzatore sposta le quote, guarda il grafico e consegna. I vincoli sono pochi. Una posizione più bassa non riceve mai più buste di una più alta, e chi resta fuori dai premi principali non riceve mai più del minimo garantito a chi è dentro: se i primi otto hanno almeno tre buste, dal nono in giù se ne danno al massimo tre. Le buste si spostano intere, una alla volta, così nessun arrotondamento ne perde una per strada.

Nel Commander ci sono anche i premi della serata, che vengono da uccisioni e voti: La Vittima (chi è stato eliminato più volte), Il Carnefice (chi ha eliminato di più), Master Brewer (chi ha preso più voti al mazzo) e Il Player (chi ha preso più voti alla giocata).

Quello che non ho ancora provato dal vivo

Alcune cose passano i test ma non hanno ancora visto un torneo vero: l'iscrizione tardiva, il Draft con il round 1 dentro i pod e i round svizzeri dopo, e la verifica della firma di Telegram con dati reali. Sono segnate anche nella documentazione del progetto, così non me ne dimentico.

Cosa mi porto via

Rileggendo gli ADR uno dopo l'altro, la scelta che torna più spesso è calcolare un dato invece di salvarlo. La classifica viene dai risultati, lo stato della tessera dalla data dell'ultimo rinnovo, le date di un evento dai suoi tornei, e i premi sono una proposta. Un dato salvato in due posti prima o poi diverge, e durante un torneo non ho tempo di capire quale dei due è giusto.

Una parte degli ADR del torneo porta la nota "ricostruito il 2026-09-20". Li ho scritti dopo, partendo dai messaggi dei commit e dai commenti nel codice, perché sul momento non l'avevo fatto. Se i commit si fossero chiamati "fix" e "update" non ci sarei riuscito.

build 635 • 9c68990

© 2026 Emanuele Nardi