Vai al contenuto
← Tutti gli articoli

Pubblicato il 6 min di lettura

Classifiche anti-cheat: il server rigioca la partita

Come Hamlet Guard verifica le classifiche: simulazione deterministica, replay fatto di seme e comandi, ri-simulazione su GitHub Actions con un ruolo DB minimo.

Progetto collegato: Hamlet Guard

Una classifica in un gioco web vale quanto la fiducia che si può avere nei punteggi. Nel browser il punteggio è un numero che il client invia al server, e chiunque apra gli strumenti per sviluppatori può inviarne uno a piacere. Per Hamlet Guard, il tower defense in pixel art che sto sviluppando, ho scelto di non fidarmi del numero ma della partita: il server rigioca la partita e accetta il punteggio solo se il risultato torna identico.

Il vincolo che ha deciso l'architettura

Rigiocare una partita costa CPU. Nei documenti di progetto ho misurato in Node, su un PC di sviluppo, tra 17 e 37 ms per partita vinta, con il bot greedy dei test di bilanciamento. Il piano gratuito dei Cloudflare Workers concede 10 ms di CPU per richiesta: la verifica nel Worker richiederebbe un piano a pagamento. Ho scelto di restare gratis e di spostare la verifica in modo differito su GitHub Actions. Il giocatore non aspetta: il punteggio arriva al server con stato pending e viene giudicato dopo.

Una simulazione che dà sempre lo stesso risultato

Perché la ri-simulazione abbia senso, packages/sim deve essere deterministico: stesso seme e stessi comandi devono dare lo stesso stato a ogni tick, su qualunque motore JavaScript. Il pacchetto è headless, senza Pixi, React o DOM, e l'ESLint del monorepo fa rispettare le regole. Il problema sono le funzioni matematiche: Math.sin, Math.exp o Math.pow non sono garantite bit per bit tra motori diversi, e Math.random o Date.now non si riproducono affatto. Per questo il motore le vieta:

// eslint.config.js (estratto, semplificato)
const NON_DETERMINISTIC_MATH = ['random', 'sin', 'cos', 'atan2', 'exp', 'log', 'pow'].map(
  (property) => ({
    object: 'Math',
    property,
    message: 'Non deterministico tra motori JS: vietato in packages/sim (usa Math.sqrt o tabelle).',
  }),
);

Ai valori di gioco ho dato tipo intero: oro, vite, danno, costi, punteggio e tick. Posizioni, velocità e distanze restano float, perché il movimento lungo il percorso è continuo. Il determinismo quindi non nasce dal "tutto intero", ma da due scelte: usare solo operazioni che IEEE 754 arrotonda in modo identico ovunque (somma, moltiplicazione, divisione, radice quadrata) e calcolare l'hash sui bit esatti dei float. Un errore di un solo bit cambia l'hash. Anche il generatore casuale, mulberry32, usa soltanto operazioni su interi a 32 bit e parte dal seme della partita. Lo stato del mondo vive in un ECS, bitECS 0.4: i componenti sono array tipizzati (Float64Array, Int32Array) creati per ogni simulazione, così due partite non condividono memoria.

Il replay: seme, comandi e checkpoint

Un replay non contiene lo stato della partita, ma quanto basta per ricrearla: il seme, il livello, le versioni di contenuto e simulazione, la difficoltà, le abilità scelte e la lista dei comandi con il tick in cui sono stati applicati. Ogni 300 tick, cioè ogni 10 secondi a 30 Hz, la sessione registra un checkpoint con l'hash FNV-1a dello stato:

advance(): void {
  if (state.status !== 'playing') { pending.length = 0; return; }
  for (const command of pending) applyAndRecord(state, replay, command);
  pending.length = 0;
  step(state);
  replay.endTick = state.tick;
  if (state.tick % CHECKPOINT_INTERVAL_TICKS === 0 || state.status !== 'playing') {
    replay.checkpoints.push({ tick: state.tick, hash: hashState(state) });
  }
}

Un comando rifiutato non cambia nulla e non viene registrato, quindi un replay non si riempie di tocchi inutili. Durante la ri-simulazione il server ricalcola ogni hash: al primo checkpoint diverso il replay è rifiutato come diverged, con il tick in cui la storia si è separata.

Il verificatore

Il Worker riceve POST /api/scores, controlla solo la forma del payload (non importa la simulazione, per restare leggero), salva il punteggio come pending e risponde 202. In background, con waitUntil, chiede a GitHub di avviare il workflow verify-scores.yml: al massimo una volta ogni due minuti e trenta volte al giorno. Il workflow gira anche ogni notte. Il contatore dei lanci sta nel database, perché deve valere per tutte le istanze del Worker insieme.

Lo script di verifica applica una sequenza di controlli: contenuto noto, livello noto, versione della simulazione, abilità legali, divergenza dai checkpoint, partita vinta, punteggio uguale a quello dichiarato. Ogni rifiuto ha un motivo registrato. Così distinguo un bug del gioco da un tentativo di barare, e posso rigiudicare i punteggi quando arriva una nuova versione dei contenuti.

Il workflow scrive sul database con un ruolo dedicato, td_verifier, che ha privilegi minimi:

REVOKE ALL ON scores, remote_config, saves, season_content FROM td_verifier;
REVOKE ALL (status, reason, verified_at) ON scores FROM td_verifier;
GRANT SELECT ON scores, remote_config, saves TO td_verifier;
-- Scrittura: solo l'esito. Niente DELETE, niente INSERT, niente UPDATE di score o di altre colonne.
GRANT UPDATE (status, reason, verified_at) ON scores TO td_verifier;

Se qualcuno ottenesse la password di questo ruolo potrebbe leggere alcune tabelle e cambiare l'esito di una verifica, ma non inventare un punteggio né cancellarne uno.

Il test che protegge il determinismo

Il test più importante non verifica una funzione, ma la stabilità di un risultato. Per un seme e una sequenza di comandi fissi, determinism.test.ts si aspetta un finalHash preciso: se una modifica cambia il comportamento della simulazione, il test fallisce. Quando il cambiamento è voluto, si aggiorna il valore e si incrementa SIM_VERSION, oggi 7. I replay vecchi vengono così rifiutati come stale_sim invece di essere giudicati con regole che non avevano quando sono stati giocati.

Cosa finisce in classifica

Verificare un punteggio non basta: bisogna decidere che cosa conta. In classifica entrano solo le vittorie, e per ogni giocatore vale il miglior punteggio verificato, separato per livello, difficoltà e versione della simulazione. La classifica appartiene alla stagione in corso: quando una stagione si chiude, la sua classifica resta archiviata e quella nuova parte da zero. A parità di punteggio vince chi è arrivato prima.

Le versioni dei contenuti restano nella stessa classifica, perché un ritocco di bilanciamento non deve azzerarla. La versione della simulazione invece separa, perché cambia il significato stesso dei replay: un punteggio ottenuto con regole diverse non è confrontabile.

Cosa farei diversamente

Il salvataggio cloud, da cui il verificatore legge le abilità possedute, è scritto dal client. Chi bara deve falsificare anche lui, e il controllo non può impedirlo: lo considero un limite noto, non una garanzia. Vorrei inoltre eseguire i test golden anche nei browser reali, non solo in Node, perché è lì che si vedono le differenze tra motori. E la verifica differita significa che un punteggio resta in attesa finché il workflow non gira: per una beta va bene, per un torneo dal vivo no.

Puoi provare Hamlet Guard su hamletguard.it.

  • anti-cheat
  • simulazione deterministica
  • Cloudflare Workers
  • GitHub Actions
  • TypeScript

Hai un progetto simile? Parliamone

Se stai affrontando una sfida simile, scrivimi: ti dico come la affronterei.

Parliamone